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] מייצג טווחי תווים.
• | הוא ראשי תיבות של 'או'.

נקודה חשובה: האופרטור REGEXP_MATCH משתמש ב-RE2 תחביר.

החשיבות של אותיות רישיות

רוב האופרטורים של MCQL הם תלויי אותיות רישיות:

אופרטורים	החשיבות של אותיות רישיות
= או !=	תלוי רישיות
(NOT) IN	תלוי רישיות
(לא) לייק	תלוי רישיות
CONTAINS (...)	תלוי רישיות
REGEXP_MATCH	אופציונלי: שניהם

נקודה חשובה: REGEXP_MATCH ו-NOT REGEXP_MATCH הם תלויי אותיות רישיות כברירת מחדל, אבל אפשר לכלול את (?i) כמו שמתואר ב-RE2 תחביר כדי ליצור אותם לא תלוי-רישיות.

סעיפים

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

בחירה

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

חשוב: התנאי SELECT נדרש לכל השאילתות. עליך לבחור בכתובת שדה מדד אחד לפחות בעמודה ביצועים השאילתות.

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

• מדדים

  • impressions
  • clicks

• פלחים

  • date
  • marketingMethod

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

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

FROM

הסעיף FROM מציין את הטבלה שממנה מאחזרים נתונים בבקשה. אפשר לציין רק שדה אחד בסעיף FROM. הסעיף FROM נדרש כדי כל השאילתות.

WHERE

אפשר להשתמש בתנאי 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. אופרטורים הם תלויי אותיות רישיות (case-sensitive). עבור את הרשימה המלאה של האופרטורים, ראו grammar.

ORDER BY (אופציונלי)

הסעיף 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'

אפשר להגדיר מחרוזות תאריך עם מירכאות בודדות (') או עם מירכאות כפולות (").

קרוב-משפחה

אפשר לציין טווח תאריכים יחסי, כמו LAST_30_DAYS או THIS_MONTH, באמצעות DURING במקום ב-BETWEEN וב-AND:

WHERE date DURING LAST_30_DAYS

בדקדוק מופיעה הרשימה המלאה של טווחי התאריכים היחסיים הזמינים.