Merchant Center Query Language

שפת השאילתות של Merchant Center‏ (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 הם תלויי-רישיות:

סעיפים

אלה הסעיפים שאפשר להריץ עליהם שאילתות באמצעות MCQL:

‪SELECT

הפסקה SELECT מקבלת רשימה מופרדת בפסיקים של שדות לאחזור.

אתם יכולים לבחור כל שדה מהתצוגה שבה אתם משתמשים. הנה כמה דוגמאות לשדות שאתם יכולים לבחור:

• מדדים

  • impressions
  • clicks

• פלחים

  • date
  • marketing_method

אפשר לשלוח שאילתה לגבי כמה סוגי שדות בבקשה אחת. לדוגמה:

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

FROM

הפסקה 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".

דוגמה שמחזירה את מספר הקליקים לכל מבצע, אם יש יותר מ-100 קליקים, לשיטת השיווק 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

הסעיף LIMIT מאפשר לציין את מספר התוצאות שיוחזרו.

הנה דוגמה שמחזירה רק 50 תוצאות, גם אם יש עוד שורות זמינות.

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‏(YYYY-MM-DD) בפורמטים הבאים:

• 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

כאן אפשר לראות את הרשימה המלאה של טווחי התאריכים היחסיים שזמינים.