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

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

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

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

אופרטורים	התלות באותיות רישיות (Case sensitivity)
= או !=	תלות באותיות גדולות
(לא) בהודו	תלות באותיות גדולות
(לא) LIKE	תלות באותיות גדולות
CONTAINS (...)	תלות באותיות גדולות
REGEXP_MATCH	אופציונלי: שניהם

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

סעיפים

אלה הסעיפים שאפשר להריץ עליהם שאילתה ב-MCQL:

SELECT

התנאי 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 נדרש לשאילתות ביצועים. ניתן לך לסנן לפי כל שדות הפלחים, ולפי שדות metrics נוספים אם מציינים אותם בסעיף 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".

הנה דוגמה שמציגה את מספר הקליקים לכל מוצר, כאשר שיטת השיווק ADS קיבלה יותר מ-100 קליקים, במהלך חודש אוגוסט:

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

הסעיף WHERE לא תומך בOR. האופרטורים הם תלויי אותיות רישיות. לרשימת האופרטורים המלאה, ראו 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 מאפשר לציין את מספר התוצאות שיוחזרו.

הנה דוגמה שמחזירה רק 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

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