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 حساسة لحالة الأحرف:

عوامل التشغيل	الحساسية لحالة الأحرف
= أو !=	حساس لحالة الأحرف
(ليس) الهند	حساس لحالة الأحرف
(ليس) أعجبني	حساس لحالة الأحرف
يحتوي على (...)	حساس لحالة الأحرف
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 مطلوبة من أجل الأداء طلبات البحث. يمكنك الفلترة حسب الكل الشرائح، ومن خلال حقول 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".

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

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

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