שפת השאילתות של 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 הם תלויי-רישיות:
| אופרטורים | תלות באותיות רישיות |
|---|---|
| = או != | תלוי רישיות |
| (NOT) IN | תלוי רישיות |
| (NOT) LIKE | תלוי רישיות |
| CONTAINS (...) | תלוי רישיות |
| REGEXP_MATCH | אופציונלי: גם וגם |
סעיפים
אלה הסעיפים שאפשר לשלוח לגביהם שאילתות באמצעות MCQL:
SELECT
הפסקה SELECT מקבלת רשימה של שדות שמופרדים בפסיקים.
אפשר לבחור כל שדה מהתצוגה שבה אתם משתמשים. ריכזנו כאן כמה דוגמאות לשדות שאפשר לבחור:
אפשר לשלוח שאילתה לגבי כמה סוגים של שדות בבקשה אחת. לדוגמה:
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. אפשר להשתמש בפונקציה order רק עם שדות שצוינו בסעיף 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
כאן אפשר לראות את הרשימה המלאה של טווחי התאריכים היחסיים שזמינים.