لغة طلب البحث في 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 حسّاسة لحالة الأحرف:
| المشغِّلون | الحساسية لحالة الأحرف |
|---|---|
| = أو != | حساس لحالة الأحرف |
| (NOT) IN | حساس لحالة الأحرف |
| (NOT) LIKE | حساس لحالة الأحرف |
| CONTAINS (...) | حساس لحالة الأحرف |
| REGEXP_MATCH | كلاهما (اختياري) |
البنود
في ما يلي البنود التي يمكنك الاستعلام عنها باستخدام MCQL:
SELECT
تتطلّب عبارة SELECT قائمة قيم مفصولة بفاصلة للحقول المطلوب استردادها.
يمكنك اختيار أي حقل من طريقة العرض التي تستخدمها. في ما يلي بعض الأمثلة على الحقول التي يمكنك اختيارها:
يمكنك الاستعلام عن أنواع حقول متعددة في طلب واحد. وفي ما يلي مثال لذلك:
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
يمكنك الاطّلاع على القواعد النحوية للحصول على القائمة الكاملة للنطاقات الزمنية النسبية المتاحة.