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

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