-- cap the number of rows
```
مثال بسيط، إيرادات البيع الإضافي ومعدل القبول اليومي لآخر 30 يومًا:
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue, accept_rate
GROUP BY date
SINCE last_30d
GRAIN day
```
الكلمات المفتاحية غير حساسة لحالة الأحرف (`SELECT` و`select` كلاهما يعمل) ولا تنتهي العبارات بفاصلة منقوطة. تُحاط القيم النصية بعلامات اقتباس مزدوجة؛ أما الأرقام والقوائم فلا.
### SELECT وGROUP BY
* **`SELECT`** يسرد المقاييس المراد قياسها، مفصولة بفواصل، على سبيل المثال `SELECT revenue, impressions, accept_rate`.
* **`GROUP BY`** يفصّل تلك المقاييس حسب بُعد واحد أو أكثر، مثل `date` أو `device` أو `surface` أو `funnel`. بدون `GROUP BY`، تحصل على إجمالي واحد للفترة بأكملها.
### التصفية باستخدام WHERE
يضيّق `WHERE` نطاق البيانات قبل قياسها. اجمع الشروط باستخدام `AND`.
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue
WHERE device = "mobile"
GROUP BY date
SINCE last_month
GRAIN day
```
**لا يمكن** تصفية `impressions` و`accept_rate` و`rpv` أو تجميعها حسب الجهاز أو المسار أو الموضع أو المنتج؛ إذ لا يحتوي التجميع المصدر لها على مثل هذا العمود. إضافة `WHERE device = "mobile"` إلى استعلام يختار أيًا منها تُرفض مع الرسالة `metric "impressions" cannot be filtered by "device"`.
المقارنات المدعومة هي `=` و`!=` و`IN` و`NOT IN` و`>` و`<` و`>=` و`<=`. استخدم قائمة مع `IN` لمطابقة عدة قيم:
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
WHERE surface IN ["PPU", "Checkout"]
```
`experiment` **ليس** حقلًا قابلًا للتصفية؛ إذ لا يوجد له مصدر تجميع، لذا يُرفض `WHERE experiment IN [...]` مع الرسالة `filters on "experiment" are not supported.`
يدعم عامل تصفية **funnel** التحديد المتعدد: **is one of** (`IN`) يتضمن المسارات المحددة فقط، و**is not one of** (`NOT IN`) يستبعدها. عند التجميع حسب **Funnel** وتطبيق عامل تصفية **is one of**، يعرض المخطط خطًا واحدًا لكل مسار محدد، دون دمج في "Other".
### النطاقات الزمنية والمقارنات
يحتاج كل استعلام إلى نطاق زمني، يُحدَّد باستخدام `SINCE`:
| الشكل | مثال | المعنى |
| - | - | - |
| إعداد مسبق | `SINCE last_30d` | نافذة متحركة تنتهي **بالأمس** (UTC). يُستبعد اليوم الحالي الجاري عمدًا، لذا فإن `last_1d` تعني الأمس فقط، و`this_month` تمتد من اليوم الأول إلى الأمس. |
| نافذة مخصصة | `SINCE 2026-07-02 UNTIL 2026-07-05` | نطاق ثابت، باستخدام تواريخ ISO (`YYYY-MM-DD`). |
الإعدادات المسبقة المتاحة: `last_1d` و`last_7d` و`last_30d` و`last_90d` و`this_month` و`last_month` و`this_year`.
* **`GRAIN`** يحدد حجم الفترة للسلاسل الزمنية: `day` أو `week` أو `month`. (يتم تحليل `hour` لكن لا يوجد تجميع يوفّر بيانات بالساعة، لذا يُرفض مثل هذا الاستعلام مع الرسالة `group_by / time_grain combination is not supported.`)
* **`COMPARE`** يضيف فترة ثانية فوق الأولى. استخدم `previous_period`، وهي النافذة المساوية في الطول التي تسبقها مباشرةً. `previous_year` مخفية من أداة اختيار Compare لأن مستودع البيانات لا يحتوي على بيانات قبل فبراير 2026؛ وتبقى قابلة للكتابة في AQL فقط حتى يستمر تحليل الاستعلامات المحفوظة سابقًا.
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- A four-day sale vs the four days immediately before it
SELECT revenue, impressions, accept_rate
GROUP BY date
SINCE 2026-07-02 UNTIL 2026-07-05
GRAIN day
COMPARE previous_period
```
تبدأ بيانات التقارير في **فبراير 2026**، لذا فإن أي نافذة أقدم من ذلك تُرجع نتائج فارغة لكلتا الفترتين.
### اختيار المخطط
* **`CHART`** يحدد طريقة عرض النتيجة: `scorecard` أو `line_chart` أو `bar_chart` أو `area_chart` أو `funnel_chart` أو `table`.
* **`TIMEZONE`** يحدد المنطقة الزمنية المستخدمة لتجميع التواريخ، كاسم IANA بين علامتي اقتباس، على سبيل المثال `TIMEZONE "America/New_York"`. القيمة الافتراضية هي UTC (انظر [المناطق الزمنية](#timezones)).
لنوع `funnel_chart` متطلبات محددة:
* **وضع الموضع.** جمّع حسب `placement` واختر مقياسًا واحدًا. تُرتَّب المراحل وفق تسلسل المواضع القياسي (البيع الإضافي الافتراضي، ثم البيع البديل، ثم عروض البيع الإضافي الإضافية). يُرسم المقياس الأول فقط؛ ويُشار إلى المقاييس الإضافية في حاشية.
* **وضع المقاييس.** اختر مقياسين أو أكثر دون `GROUP BY`. يصبح كل مقياس مرحلة في المسار بترتيب الاستعلام (على سبيل المثال، `SELECT impressions, conversions` يعرض الانخفاض من مرات الظهور إلى التحويلات). يجب أن تشترك جميع المقاييس في الوحدة نفسها.
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Placement funnel: conversion drop-off across placements
SELECT conversions
GROUP BY placement
SINCE last_30d
CHART funnel_chart
```
يحتاج وضع الموضع إلى مقياس يمكن تفصيله حسب الموضع. لا يمكن ذلك مع `impressions` و`accept_rate` و`rpv`؛ إذ يعرض مخطط المسار الرسالة "These metrics can't be grouped by placement" لها.
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Metric funnel: impressions to conversions drop-off
SELECT impressions, conversions
SINCE last_30d
CHART funnel_chart
```
### الفرز والتقييد
* **`ORDER BY`** يفرز النتائج حسب مقياس أو بُعد، مع `ASC` أو `DESC`.
* **`LIMIT`** يحدد الحد الأقصى لعدد الصفوف المُرجعة، وهو مفيد لأسئلة "أفضل N".
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Top 20 products by upsell revenue this month
SELECT revenue, conversions, avg_conversion_value
GROUP BY product
SINCE this_month
ORDER BY revenue DESC
LIMIT 20
```
### المزيد من الأمثلة
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Daily performance vs the previous period
SELECT revenue, impressions, conversions, accept_rate
GROUP BY date
SINCE last_30d
GRAIN day
COMPARE previous_period
```
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Mobile vs desktop revenue over the last 90 days
SELECT revenue
GROUP BY device
SINCE last_90d
ORDER BY revenue DESC
```
لا يمكن تفصيل `impressions` و`accept_rate` و`rpv` حسب الجهاز؛ فتجميعها هو المتجر × السطح × اليوم، دون عمود للجهاز. استخدم `revenue` (أو مقياسًا آخر مصدره التحويلات) لمقارنات الأجهزة.
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Which surface is driving the most revenue?
SELECT revenue, impressions, accept_rate
GROUP BY surface
SINCE last_30d
ORDER BY revenue DESC
```
## المناطق الزمنية
افتراضيًا، تعمل الاستعلامات بتوقيت UTC. يمكنك تجاوز المنطقة الزمنية بحيث تعكس النتائج المجمّعة حسب التاريخ التوقيت المحلي (انظر [تعيين منطقة زمنية](/ar/aftersell/reports_explorer#setting-a-timezone) لخطوات شريط الأدوات).
الاستعلامات التي تتضمن **Impressions** أو **Accept Rate** أو **Revenue Per Visit** تجمّع التواريخ دائمًا بتوقيت UTC، بغض النظر عن المنطقة الزمنية التي تختارها، لأن مصدرها تجميع يومي يُبلغ عنه بأيام UTC. إذا جمع استعلام أحد هذه المقاييس مع مقاييس أخرى، فإن مجموعة النتائج بأكملها تعود إلى UTC حتى تبقى فترات التواريخ متوافقة.
### عبارة TIMEZONE
حدد منطقة زمنية مباشرةً في AQL باستخدام عبارة `TIMEZONE`، التي تظهر بين `CHART` و`ORDER BY`:
```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT ...
CHART ...
TIMEZONE "Asia/Tokyo"
ORDER BY ...
```
عند وجودها، تتجاوز العبارة التحديد في شريط الأدوات لهذا الاستعلام، وتُحفظ عند الحفظ وإعادة التحميل.
### المناطق الزمنية المتاحة
تقبل أداة الاختيار (وعبارة `TIMEZONE`) مجموعة مغلقة من عشر مناطق. تُرفض أي منطقة زمنية أخرى من IANA باعتبارها غير مدعومة.
| المنطقة الزمنية | مثال على الموقع |
| - | - |
| UTC | التوقيت العالمي المنسق |
| America/New\_York | نيويورك (ET) |
| America/Chicago | شيكاغو (CT) |
| America/Denver | دنفر (MT) |
| America/Los\_Angeles | لوس أنجلوس (PT) |
| Europe/London | لندن (GMT/BST) |
| Europe/Paris | باريس (CET/CEST) |
| Asia/Tokyo | طوكيو (JST) |
| Asia/Singapore | سنغافورة (SGT) |
| Australia/Sydney | سيدني (AEST/AEDT) |
### الإعداد الافتراضي للحساب وكيف تؤثر المنطقة الزمنية على النتائج
إذا كان **Lock reporting timezone** مفعّلًا في إعدادات التحليلات، فإن اختيار **Account default** يستخدم تلك المنطقة الزمنية المقفلة (يعرض شريط الأدوات المنطقة المحددة، على سبيل المثال **Timezone: Account default (Paris (CET))**). تقبل صفحة إعدادات التحليلات قائمة IANA الكاملة، لكن Reports تلتزم فقط بالمناطق العشر المذكورة أعلاه؛ وإذا لم تكن منطقتك المقفلة إحداها، فإن **Account default** تتحول بصمت إلى UTC. إذا لم يكن **Lock reporting timezone** مفعّلًا، فإن **Account default** تعود إلى UTC.
عند تعيين منطقة زمنية، يستخدم تجميع التواريخ التوقيت المحلي بدلًا من UTC. على سبيل المثال، الحدث الذي يقع في `2026-03-29T01:30:00Z` يقع في 28 مارس في نيويورك (ET) لكنه يقع في 29 مارس في باريس (CET). الاستعلامات التي لا تحتوي على منطقة زمنية، بما في ذلك المحفوظة سابقًا، تستمر في العمل بتوقيت UTC.