Merchant Center Query Language

Merchant Center Query Language (MCQL)‎ یک زبان پُرسمان مشابه SQL است. می‌توانید از MCQL با Merchant Reports API استفاده کنید تا داده‌های عملکرد محصولاتتان و بازاری را که در آن رقابت می‌کنند بازیابی کنید.

دستور زبان

در اینجا مرجع دستور زبان MCQL (در نماد عبارت باقاعده) آمده است:

Query            -> SelectClause FromClause? WhereClause? OrderByClause? LimitClause?
SelectClause     -> SELECT FieldName (, FieldName)*
FromClause       -> FROM TableName
WhereClause      -> WHERE Condition (AND Condition)*
OrderByClause    -> ORDER BY Ordering (, Ordering)*
LimitClause      -> LIMIT PositiveInteger

Condition        -> FieldName Operator Value | FieldName BETWEEN Value AND Value
Operator         -> = | != | > | >= | < | <= | <> | IN | NOT IN |
                    CONTAINS ANY | CONTAINS ALL | CONTAINS NONE | DURING |
                    LIKE | NOT LIKE | REGEXP_MATCH | NOT REGEXP_MATCH
Value            -> Number | NumberList | String | StringList | Function
Ordering         -> FieldName (ASC | DESC)?

FieldName        -> [a-z] ([a-zA-Z0-9._])*
TableName        -> [A-Z] ([a-zA-Z_])*

StringList       -> ( String (, String)* )
NumberList       -> ( Number (, Number)* )

PositiveInteger  -> [1-9] ([0-9])*
Number           -> -? [0-9]+ (. [0-9] [0-9]*)?
String           -> (' Char* ') | (" Char* ")
Function         -> LAST_14_DAYS | LAST_30_DAYS | LAST_7_DAYS |
                    LAST_BUSINESS_WEEK | LAST_MONTH | LAST_WEEK_MON_SUN |
                    LAST_WEEK_SUN_SAT | THIS_MONTH | THIS_WEEK_MON_TODAY |
                    THIS_WEEK_SUN_TODAY | TODAY | YESTERDAY

می‌توانید از نمادهای زیر استفاده کنید:

  • ?نشان‌دهنده عنصر اختیاری است.
  • * یعنی صفر یا بیشتر؛ + یعنی یک یا بیشتر.
  • ‫(xxxxxx) نشان‌دهنده گروه‌بندی است.
  • [a-z0-9] نشان‌دهنده محدوده نویسه است.
  • | به‌معنی «یا» است.

حروف‌حساس

اکثر عملگرهای MCQL به حروف بزرگ و کوچک حساس هستند:

اپراتورها حروف‌حساس
= یا ≠ حروف‌حساس
(NOT) IN حروف‌حساس
(NOT) LIKE حروف‌حساس
شامل (...) حروف‌حساس
REGEXP_MATCH اختیاری هر دو

بندها

عبارت‌هایی که می‌توانید با MCQL پُرسمان کنید در اینجا آمده است:

انتخاب

عبارت SELECT فهرستی از فیلدهای جداشده با کاما را برای بازیابی دریافت می‌کند.

می‌توانید هر فیلدی را از نمایی که استفاده می‌کنید انتخاب کنید. در اینجا چند نمونه از فیلدهایی که می‌توانید انتخاب کنید آورده شده است:

می‌توانید چندین نوع فیلد را در یک درخواست پُرسمان کنید. مثالی در اینجا ارائه شده است:

SELECT
  date,
  marketing_method,
  impressions,
  clicks
FROM product_performance_view
WHERE date BETWEEN '2023-08-01' AND '2023-08-31'

فرستنده

بند FROM جدولی را که داده‌ها باید از آن واکشی شود در درخواست مشخص می‌کند. فقط می‌توانید یک فیلد را در عبارت FROM مشخص کنید. عبارت FROM برای همه پُرسمان‌ها لازم است.

WHERE

از عبارت WHERE برای فیلتر کردن داده‌های درخواستتان استفاده کنید. بند WHERE برای پرس‌وجوهای عملکرد لازم است. می‌توانید براساس همه فیلدهای بخش‌ها و براساس فیلدهای سنجه‌های تکمیلی فیلتر کنید، به‌شرطی که آن‌ها را در عبارت SELECT مشخص کنید.

در اینجا مثالی آورده شده است که از WHERE برای برگرداندن ظهورها فقط از یک دوره زمانی مشخص (ماه اوت) استفاده می‌کند:

SELECT offer_id, impressions
FROM product_performance_view
WHERE date BETWEEN '2023-08-01' AND '2023-08-31'

می‌توانید بااستفاده از عملگر AND، براساس چند شرط در یک پُرسمان فیلتر کنید. از AND بین شرایط کامل استفاده کنید، برای مثال: WHERE marketing_method != "ADS" AND marketing_method != "ORGANIC". نمی‌توانید از AND بین مقادیر در یک شرط استفاده کنید، برای مثال: WHERE marketing_method != "ADS" AND "ORGANIC".

در اینجا مثالی آورده شده است که تعداد کلیک‌ها را به‌ازای هر پیشنهاد ویژه برمی‌گرداند، که در آن بیش‌از ۱۰۰ کلیک برای روش بازاریابی ADS درطول ماه اوت وجود دارد:

SELECT offer_id, clicks
FROM product_performance_view
WHERE clicks > 100
  AND marketing_method = 'ADS'
  AND date BETWEEN '2023-08-01' AND '2023-08-31'

بند WHERE از OR پشتیبانی نمی‌کند. عملگرها حروف‌حساس هستند. برای فهرست کامل عملگرها، دستور زبان را ببینید.

ORDER BY (اختیاری)

بند ORDER BY به شما امکان می‌دهد نتایج را با ترتیب مشخصی بازیابی کنید.

ترتیب را با field_name، سپس ASC یا DESC مشخص کنید. فقط می‌توانید براساس فیلدهای مشخص‌شده در عبارت SELECT پُرسمانتان مرتب کنید. اگر مشخص نکنید، ORDER BY به‌طور پیش‌فرض روی ASC تنظیم می‌شود.

پرس‌وجو زیر ردیف‌های برگردانده‌شده را براساس تعداد کلیک‌ها، از بیشترین به کمترین، مرتب می‌کند:

SELECT offer_id, clicks
FROM product_performance_view
WHERE date BETWEEN '2023-08-01' AND '2023-08-31'
ORDER BY clicks DESC

می‌توانید چندین فیلد را در عبارت ORDER BY بااستفاده از فهرست جداشده با کاما مشخص کنید.

برای مثال، نتایج پُرسمان زیر به‌ترتیب صعودی براساس offer_id، سپس به‌ترتیب نزولی براساس تعداد ظهورها، و سپس به‌ترتیب نزولی براساس تعداد کلیک‌ها مرتب شده است:

SELECT offer_id, impressions, clicks
FROM product_performance_view
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY
  offer_id,
  impressions DESC,
  clicks DESC

محدودیت

بند LIMIT به شما امکان می‌دهد تعداد نتایج برگشتی را مشخص کنید.

در اینجا مثالی آورده شده است که فقط ۵۰ نتیجه را برمی‌گرداند، حتی اگر ردیف‌های بیشتری دردسترس باشد.

SELECT offer_id, impressions
FROM product_performance_view
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY impressions DESC
LIMIT 50

از فیلد pageSize برای مدیریت فهرست‌های طولانی نتایج استفاده کنید.

محدوده تاریخ

MCQL به شما امکان می‌دهد محدوده تاریخ سفارشی یا نسبی را مشخص کنید. باید از عبارت WHERE برای مشخص کردن محدوده date برای همه پرس‌وجوهای عملکرد استفاده کنید.

سفارشی

می‌توانید تاریخ‌های ISO 8601(سال-ماه-روز) را در قالب‌های زیر مشخص کنید:

  • date BETWEEN '2021-01-01' AND '2021-01-31'
  • date >= '2021-01-01' AND date <= '2021-01-31'

می‌توانید رشته‌های تاریخ را با علامت نقل‌قول تکی (') یا علامت نقل‌قول دوتایی (") تعریف کنید.

خویشاوند

می‌توانید محدوده تاریخ نسبی، مثل LAST_30_DAYS یا THIS_MONTH، را بااستفاده از DURING به‌جای BETWEEN و AND مشخص کنید:

WHERE date DURING LAST_30_DAYS

برای مشاهده فهرست کامل محدوده تاریخ‌های نسبی دردسترس، به دستور زبان مراجعه کنید.

قبلی
Analyze UCP agentic performance (Alpha)
بعدی
Paginate query results