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 به حروف کوچک و بزرگ حساس هستند:

اپراتورها حساسیت به حروف کوچک
= یا != حساس به حروف کوچک و بزرگ
(نه) در حساس به حروف کوچک و بزرگ
(نه) لایک حساس به حروف کوچک و بزرگ
حاوی (...) حساس به حروف کوچک و بزرگ
REGEXP_MATCH اختیاری هر دو

بندها

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

انتخاب کنید

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

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

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

SELECT
  date,
  marketingMethod,
  impressions,
  clicks
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'

از

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

کجا

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

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

SELECT offerId, impressions
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'

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

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

SELECT offerId, clicks
FROM ProductPerformanceView
WHERE clicks > 100
  AND marketingMethod = 'ADS'
  AND date BETWEEN '2020-08-01' AND '2020-08-31'

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

سفارش بر اساس (اختیاری)

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

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

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

SELECT offerId, clicks
FROM ProductPerformanceView
WHERE date BETWEEN '2020-08-01' AND '2020-08-31'
ORDER BY clicks DESC

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

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

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

LIMIT

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

در اینجا یک مثال است که تنها 50 نتیجه را برمی گرداند، حتی اگر ردیف های بیشتری در دسترس باشد.

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

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

محدوده تاریخ

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

سفارشی

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

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

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

نسبی

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

WHERE date DURING LAST_30_DAYS

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