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 הם תלויי אותיות רישיות:
| אופרטורים | תלות באותיות רישיות (Case sensitivity) |
|---|---|
| = או != | תלוי רישיות |
| (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 נדרש בשאילתות ביצועים.
אפשר לסנן לפי כל השדות של segments, ולפי שדות נוספים של metrics אם מציינים אותם בסעיף 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 מאפשר לציין את מספר התוצאות שיוחזרו.
הנה דוגמה שמחזירה רק 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
כאן מופיעה הרשימה המלאה של טווחי התאריכים היחסיים שאפשר להשתמש בהם.