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] تشير إلى نطاقات الأحرف.
• | تعني "أو".

الحساسية لحالة الأحرف

معظم مشغّلي MCQL حساسون لحالة الأحرف:

العبارات

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

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 لفلترة البيانات في طلبك. عبارة 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

للاطّلاع على القائمة الكاملة بالنطاقات الزمنية النسبية المتاحة، يُرجى مراجعة القواعد اللغوية.