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	حساس لحالة الأحرف
(ليس) LIKE	حساس لحالة الأحرف
CONTAINS (...)	حساس لحالة الأحرف
REGEXP_MATCH	كلاهما اختياري

نقطة رئيسية: REGEXP_MATCH وNOT REGEXP_MATCH حساسان لحالة الأحرف تلقائيًا، ولكن يمكنك تضمين (?i) كما هو موضّح في بنية RE2 لجعلهما غير حساسَين لحالة الأحرف.

العبارات

في ما يلي العبارات التي يمكنك طلب البحث عنها باستخدام MCQL:

SELECT

تأخذ عبارة 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 في طلبات البحث المتعلقة بالأداء. يمكنك الفلترة حسب جميع حقول الشرائح، وحسب حقول المقاييس الإضافية إذا حدّدتها في عبارة 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

اطّلِع على قواعد اللغة للحصول على القائمة الكاملة بنطاقات التواريخ النسبية المتاحة.