بدء استخدام مقاييس BigQuery Graph

1. نظرة عامة

معظم أخطاء SQL التي تنجو من مراجعة الرمز البرمجي هي أخطاء تجميع. يكون الرقم صحيحًا في الجدول الذي يتضمّنه، وتعمل عملية الربط على نسخه، ويكون المجموع غير صحيح.

تتيح لك ميزة BigQuery Graph وصف طريقة ربط جداولك مرة واحدة، وذلك كرسومات بيانية للعلاقات، ثم طلب البحث عن عمليات الربط. تضيف مقاييس الرسم البياني عنصرًا آخر إلى هذا الوصف، وهو التجميع نفسه. يمكنك تعريف MEASURE(SUM(streams)) على العقدة التي تتضمّن الرقم، ويحصل كل طلب بحث يقرأ الرسم البياني على الإجمالي الصحيح بالمستوى المناسب من التفصيل، بدون أي حيلة GROUP BY أو تعبير جدول مشترك (CTE) يجب تذكّره.

في هذا الدرس العملي، ستنشئ فهرسًا موسيقيًا من خمسة جداول، وتضع مقياسًا واحدًا عليه، وستشاهد السؤال نفسه يعرض إجابتَين مختلفتَين: 12.6 مليار باستخدام SUM، و5.1 مليار باستخدام AGG. الفجوة هي شكل الكتالوج، فالأغنية التي تظهر في أربع قوائم تشغيل تصبح أربعة صفوف عند تسوية الرسم البياني، ويضيف SUM الصفوف الأربعة. بعد ذلك، ستتعرّف على القواعد التي تجعل الجملة الثانية صحيحة.

المكان الذي ستكتب فيه

يستخدم هذا التمرين المعملي مكانَين بالضبط، بهذا الترتيب:

	أين	ماذا تفعل هناك؟
1	وحدة طرفية Cloud Shell	عدد قليل من الأوامر، في خطوة الإعداد فقط
2	وحدة تحكّم BigQuery	كل ما عدا ذلك: لصق طلبات البحث في محرِّر طلبات البحث، والنقر على أداة تصميم الرسومات البيانية، والتحدّث مع وكيل

يتم وضع علامة على كل تعليمات حتى تعرف دائمًا ما تعنيه:

• 👉💻 Cloud Shell: اكتب هذا الأمر في نافذة Cloud Shell.
• 👉📋 محرِّر الطلبات: الصِق هذا الرمز في محرِّر طلبات BigQuery وانقر على تنفيذ.
• 👉🌐 وحدة التحكّم: يمكنك النقر في وحدة تحكّم BigQuery. لا حاجة إلى كتابة أي شيء ما لم تنص الخطوة على ذلك.
• ‫👀 — اطّلِع على النتيجة.

أهداف الدورة التعليمية

• كيفية تعريف مقياس في جدول عقدة، سواء في أداة تصميم الرسومات البيانية المرئية أو في SQL
• طريقة تحويل GRAPH_EXPAND رسم بياني إلى جدول واحد عريض
• لماذا AGG هي الدالة الوحيدة التي يمكنها قراءة مقياس، وماذا تقول كل محاولة أخرى؟
• العمليات الحسابية التي يمكن إجراؤها على المقاييس الستة التي يدعمها أحد المقاييس
• كيف تجيب إحدى المقاييس عن سؤال تم تجميعه بشكل مختلف بدون أي تغييرات
• اختياري: كيف تجيب GQL وعلامة التبويب "الرسم البياني" عن سؤال لا يمكن إجابته باستخدام الإجمالي، وكيف يستخدم وكيل بيانات BigQuery مقاييسك بدون إخباره بها

المتطلبات

• حساب Google يتضمّن خدمة الفوترة ومتصفّح لا تحتاج إلى مشروع على Google Cloud في البداية، لأنّ عملية الإعداد تنشئ مشروعًا لك.
• في خطوة المحادثة الاختيارية فقط: يجب تفعيل واجهة برمجة التطبيقات Gemini Data Analytics API، وتوفُّر دور منشئ وكيل Gemini Data Analytics Data Agent.

لا يلزم تثبيت أي شيء على جهازك. يتم تنفيذ كل شيء في Cloud Shell ووحدة تحكّم BigQuery.

حالة المنتج وتكلفته

تتوفّر BigQuery Graph للجميع. تتوفّر مقاييس الرسوم البيانية وأداة تصميم الرسوم البيانية المرئية وتصوّر الرسوم البيانية واستخدام الرسم البياني كمصدر معرفة لوكيل البيانات في معاينة، ويتم تناولها في "بنود العروض الترويجية لمرحلة ما قبل التوفّر للجمهور العام".

يتم تشغيل الفئتين GRAPH_EXPAND وAGG بموجب الأسعار المتاحة عند الطلب. تتطلّب طلبات البحث بلغة GQL (خطوة المسار الاختيارية) حجزًا يستخدم إصدار Enterprise أو Enterprise Plus، وفقًا للمستندات، وهذا هو السبب في أنّ هذه الخطوة اختيارية.

حجم مجموعة البيانات بضعة كيلوبايت. بموجب التسعير عند الطلب، يتم تحصيل رسوم كل طلب بحث عند الحد الأدنى البالغ 10 ميغابايت، لذا فإنّ تكلفة هذا الدرس العملي لا تتجاوز جزءًا من السنت.

البيانات وهمية. لا وجود لشركة Cymbal Records وNorthwind Audio والفنّانين والأغاني وقوائم التشغيل. تم تقريب الأرقام عمدًا، حتى تتمكّن من التحقّق من كل نتيجة في ذهنك.

2. الإعداد

هذه هي الخطوة الوحيدة التي تستخدم Cloud Shell. تنشئ هذه الميزة مشروعًا وتضيف إليه معلومات الفوترة وتنشئ الجداول الأولية. يمكنك بعد ذلك تشغيل الرسم البياني والمقياس وكل طلب بحث في وحدة تحكّم BigQuery.

هناك أمر واحد لا يمكن أن يوفّره لك هذا المختبر، وهو مشروع Google Cloud يتضمّن الفوترة. تتيح لك الخطوة 1 الحصول على حساب يمكنه الدفع مقابل المشروع، بينما تحوّل الخطوة 4 هذا الحساب إلى مشروع. نفِّذها بهذا الترتيب، لأنّ كل خطوة بعد الخطوة 4 تقرأ المشروع الذي تنشئه الخطوة 4.

‫1 · الحصول على حساب يتضمّن إمكانية الفوترة (حوالى دقيقة واحدة)

👉🌐 يجب إجراء ذلك قبل أي شيء آخر. سجِّل الدخول باستخدام حساب Google مفعَّلة فيه ميزة الفوترة. يمكن استخدام أي حساب من هذا النوع. إذا لم يكن لديك حساب فوترة، يمكنك بدء فترة تجريبية مجانية، إذ تمنحك حساب فوترة، وهو كل ما تحتاجه الخطوة 4.

لا يزال BigQuery يتطلّب إعداد الفوترة. يبلغ حجم مجموعة بيانات music بضعة كيلوبايت، ويتم تحصيل رسوم عن كل طلب بحث في هذا المختبر بمعدل 10 ميغابايت كحد أدنى عند الطلب، ولكن لن تنفّذ BigQuery أي طلب بحث لمشروع ليس لديه حساب فوترة مرتبط.

‫2 · فتح Cloud Shell (حوالى دقيقة واحدة)

👉🌐 وحدة التحكّم: انقر على تفعيل Cloud Shell في أعلى Google Cloud Console، وهو الرمز الذي يشبه شكل الجهاز الطرفي في العنوان. يتم فتح نافذة محطة طرفية في أسفل الصفحة.

👉🌐 وحدة التحكّم: إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على منح الإذن للمتابعة.

👉💻 Cloud Shell: تحقَّق من الحساب الذي تم تسجيل الدخول إليه في Cloud Shell:

gcloud auth list

👀 توقَّع أن يتم تمييز حسابك بالرمز *، ويجب أن يكون الحساب نفسه الذي سجّلت الدخول إليه في الخطوة 1. إذا لم يكن كذلك، شغِّل gcloud auth login واختَر الحساب الصحيح.

هل تريد وحدة طرفية أكثر اتساعًا؟ انقر على فتح المحرِّر (رمز المجلد المفتوح مع قلم رصاص) لفتح Cloud Shell Editor، ثم افتح وحدة طرفية داخله باستخدام عرض → الوحدة الطرفية. لا يتطلّب هذا الدرس التطبيقي استخدام المحرِّر، إذ لن تعدّل أي ملف، ولكن من الأسهل قراءة ناتج الإعداد في نافذة طرفية بملء الشاشة.

‫3. الحصول على المختبر (حوالى دقيقة واحدة)

👉💻 Cloud Shell: استنساخ المستودع:

cd ~
rm -rf ~/bq-graph-measures-lab
git clone https://github.com/cuppibla/bq-graph-measures-lab.git
cd ~/bq-graph-measures-lab

لماذا rm -rf أولاً؟ يبقى دليل Cloud Shell الرئيسي متاحًا بين الجلسات، لذا ستؤدي المحاولة الثانية لهذا الدرس التطبيقي إلى ظهور fatal: destination path ... already exists. تؤدي إزالة المجلد أولاً إلى جعل هذا المكوّن آمنًا لتشغيله مرتين. ولا يتضمّن أي محتوى خاص بك.

‫4 · إنشاء مشروعك (حوالى دقيقتان)

👉💻 Cloud Shell: يعثر نص برمجي واحد على حساب الفوترة الخاص بك، وينشئ مشروعًا عليه، ويوجّه Cloud Shell إلى هذا المشروع:

cd ~/bq-graph-measures-lab
./setup_project.sh

👀 توقَّع الحصول على ✓ لحساب الفوترة الذي اختاره، و✓ للمشروع الذي أنشأه، ونهاية مثل:

Project ready: bq-graph-4271
  Next:  ./setup.sh

bq-graph-4271 هو رقم تعريف مشروعك، وسيكون مختلفًا لديك. تحدث أربعة أشياء في هذه المرحلة:

الفوترة	يتم استخدام أحدث حساب [YYYY-MM-DD] GDP Credit: إذا كان لديك حساب، وأي حساب فوترة آخر مفتوح في حال عدم توفّر حساب.
المشروع	ينشئ bq-graph-XXXX ويربط حساب الفوترة هذا به
اختيارات	يكتب المعرّف في ~/project_id.txt ويشغّل gcloud config set project، لذا لن يُطلب منك كتابته بعد ذلك
waits	الاستطلاعات إلى أن يُسمح فعليًا بعرض المشروع الجديد تمامًا، لمدة تصل إلى دقيقتَين

‫🌐 أصبح المشروع نفسه الآن في وحدة التحكّم، ويظهر رقم تعريفه في بطاقة معلومات المشروع على لوحة البيانات:

لماذا يبقى في نهاية قائمة الانتظار؟ لا يُسمح بعرض مشروع Google Cloud الذي تم إنشاؤه قبل ثوانٍ بعد، لأنّ سياسة إدارة الهوية وإمكانية الوصول لا تزال قيد الانتشار، وتعود الطلبات بقيمة 403 IAM_PERMISSION_DENIED. هذا هو الشيء الوحيد الذي من المرجّح أن يحدث خطأ في عملية الإعداد هذه، وهو ليس مشكلة في الفوترة أو الأذونات، فقد أثبتت الأسطر أعلاه أنّ المشروع متوفّر وأنّ الفوترة مرتبطة به. يمتص النص البرمجي فترة الانتظار هذه، لذا لا يواجه ./setup.sh أي مشاكل.

يمكن إعادة تشغيلها بأمان. إذا حدث أي خطأ، ما عليك سوى تشغيل ./setup_project.sh مرة أخرى. يتم قراءة ~/project_id.txt أولاً واستئناف هذا المشروع طالما أنّه لا يزال موجودًا، مع ربط الفوترة به إذا كان هذا هو الجزء الذي لم يكتمل، وبالتالي لن يؤدي التشغيل الثاني إلى إنشاء مشروع ثانٍ بدون علمك.

No open billing account؟ يتوقف النص البرمجي عند هذا الحدّ، قبل أن يغيّر أي شيء آخر، ويعرض الخطوات التي يجب اتّخاذها. في معظم الحالات، يتم تسجيل الدخول إلى Cloud Shell باستخدام حساب مختلف عن الحساب الذي يتم تحصيل الرسوم منه. قارِن gcloud auth list بالخطوة 1.

Could not create a project؟ لا يُسمح لبعض الحسابات، وخاصةً حسابات الشركات، بإنشاء مشاريع، ولكل حساب حصة من المشاريع. يطبع النص البرمجي تعليمات وحدة التحكّم لإنشاء مشروع يدويًا. بعد إنشائه، ضَع رقم التعريف في ~/project_id.txt وأعِد تشغيل ./setup_project.sh وسيتم استخدام هذا المشروع بدلاً من المشروع التلقائي.

هل لديك مشروع تريد استخدامه؟ تخطّي النص البرمجي نفِّذ الأمر gcloud config set project YOUR_PROJECT_ID بدلاً من ذلك، وتحقّق من تنفيذه باستخدام الأمر gcloud config get-value project، ثم انتقِل مباشرةً إلى الخطوة 5. يجب أن يكون لديك دور مشرف BigQuery فيه.

‫5 · إنشاء مجموعة البيانات (حوالى 3 دقائق)

👉💻 Cloud Shell: ينشئ نص برمجي آخر الجداول:

cd ~/bq-graph-measures-lab
./setup.sh

يطبع النص البرمجي كل خطوة أثناء تنفيذها. في ما يلي وظيفة هذا الإجراء:

المشروع	يقرأ المشروع من gcloud config ويرفض المتابعة بدون واحد
واجهة برمجة التطبيقات	تفعيل bigquery.googleapis.com
مجموعة البيانات	ينشئ مجموعة بيانات music في المنطقة المتعددة في الولايات المتحدة وخمسة جداول، يحتوي كل منها على PRIMARY KEY ... NOT ENFORCED
check	تحسب الصفوف في كل جدول وتتوقف إذا كان أي عدد غير صحيح

👀 نتوقّع:

BigQuery Graph Measures · setup
  ✓ project: bq-graph-4271
  ✓ BigQuery API enabled

Creating dataset music (US) and five tables...
  ✓ music.Labels              2 rows
  ✓ music.Artists             3 rows
  ✓ music.Songs               5 rows
  ✓ music.Playlists           4 rows
  ✓ music.PlaylistEntries    10 rows

🎉 ready — open BigQuery Studio: https://console.cloud.google.com/bigquery?project=bq-graph-4271

لقد انتهيت من استخدام Cloud Shell. يمكنك إغلاقها.

كل طلب بحث في هذا المختبر هو أيضًا ملف في هذا المستودع. sql/01_... إلى sql/09_...، ويتم ترقيمها حسب الخطوة. إذا كنت تفضّل تشغيل أمر من الوحدة الطرفية بدلاً من لصقه في وحدة التحكّم: bq query --nouse_legacy_sql < sql/02_sum_vs_agg.sql.

‫6 · افتح BigQuery ومحرِّر طلبات

👉🌐 وحدة التحكّم: انقر على الرابط في نهاية الناتج، أو افتح BigQuery من قائمة التنقّل. في جزء المستكشف على يمين الصفحة، وسِّع مشروعك: مجموعة بيانات music تحتوي على خمسة جداول.

👉🌐 وحدة التحكّم: في أعلى BigQuery Studio، في صف إنشاء جديد، انقر على طلب بحث SQL. سيتم فتح علامة تبويب فارغة في المحرِّر.

الاحتفاظ بعلامة التبويب هذه يجب وضع كلّ كتلة 👉📋 في هذا المختبر هنا: اختَر أي محتوى في المحرّر، والصِق الكتلة الجديدة فوقه، ثم انقر على تشغيل. تظهر النتيجة في اللوحة أدناه.

التعرّف على الجداول

هناك أمران مهمان بشأن هذه الجداول سنتحدّث عنهما لاحقًا. يجب أن يحدّد كل جدول مفتاحه الأساسي على النحو التالي: NOT ENFORCED. لا يتحقّق BigQuery من ذلك، ولكن الرسم البياني للسمات الذي ستنشئه يحتاج إلى مفتاح صريح لمعرفة ما يحدّد الصف. أما الجدول الأخير، PlaylistEntries، فهو جدول ربط: إذا كانت أغنية مدرَجة في أربع قوائم تشغيل، سيكون لها أربعة صفوف في هذا الجدول. في هذا الجدول، تحدث القصة بأكملها.

يتم ربط الجداول معًا على النحو التالي: تتعاقد شركة الإنتاج مع فنّانين، ويصدر الفنّان أغاني، ويتم وضع الأغنية في قوائم التشغيل من خلال PlaylistEntries. تمتلك شركة Cymbal Records الفنانتين Ava Sterling وMina Okafor، ومن خلالهما أربع أغانٍ. تمتلك شركة Northwind Audio أغنية واحدة هي "Midnight Drive"، كما تمتلك حقوق نشر أعمال الفنان "كاي ناكامورا".

جدول	صفوف	مفتاح	ما يحتويه
التصنيفات	2	label_id	الاسم، الميزانية التسويقية
الفنانون	3	artist_id	الاسم، التصنيف
الأغاني	5	song_id	العنوان، اسم الفنان، عدد مرات التشغيل
قوائم التشغيل	4	playlist_id	الاسم، عدد المتابعين
PlaylistEntries	10	entry_id	أي أغنية مدرَجة في أي قائمة تشغيل؟

✅ نقطة التحقّق: 🎉 ready في Cloud Shell، وخمسة جداول ضمن music في "المستكشف"، وعلامة تبويب فارغة لمحرّر طلبات البحث مفتوحة.

3- إنشاء الرسم البياني: الخيار أ، أداة تصميم النماذج المرئية

الرسم البياني للخصائص هو وصف لطريقة ربط الجداول. يمكنك النقر عليه معًا في أداة تصميم الرسوم البيانية المرئية (هذه الخطوة، كل النقرات) أو كتابته كاستعلام SQL (الخطوة التالية، عملية لصق واحدة). ينتج كلاهما العنصر نفسه، لذا استخدِم أحدهما فقط.

هل أنت معتاد على استخدام DDL؟ انتقِل إلى الخطوة التالية والصِق الرمز. يمكنك العودة وفتح أداة تصميم النماذج بعد ذلك، إذ تعرض أي رسم بياني، بغض النظر عن طريقة إنشائه.

1. إنشاء هيكل الرسم البياني

👉🌐 وحدة التحكّم: في BigQuery Studio، في صف إنشاء جديد، افتح قائمة الذكاء الاصطناعي والمعرفة وانقر على الرسم البياني.

👉🌐 Console: أدخِل MusicGraph في حقل اسم الرسم البياني وmusic في حقل وجهة الرسم البياني في مجموعة البيانات. يتم ملء المنطقة من مجموعة البيانات (الولايات المتحدة).

👉🌐 Console: ضمن مصادر البيانات، اختَر الجداول الخمسة: "الفنانون" و"شركات الإنتاج" و"إدخالات قائمة التشغيل" و"قوائم التشغيل" و"الأغاني"، ثم انقر على إنشاء.

👀 يتم فتح لوحة العرض بخمس عقد ملونة وبدون خطوط بينها. تعرض لوحة التفاصيل على يسار الشاشة العُقد (5) والحواف (0). تحمل كل عقدة المفتاح الأساسي للجدول وجميع أعمدته كسمات، ويمكنك النقر على أي عقدة للاطّلاع عليها.

2. رسم الحواف الأربع

الحافة هي مفتاح خارجي، ويتم رسمها. ينتقل كل مفتاح من الجدول الذي يحتوي على المفتاح إلى الجدول الذي يشير إليه.

👉🌐 وحدة التحكّم: انقر على حافة جديدة. في مربّع الحوار اختيار جدول، اختَر PlaylistEntries وانقر على إضافة. في لوحة إضافة حافة:

1. اضبط الاسم على EntryToSong.
2. انقر على إضافة مفتاح أساسي واقبل entry_id.
3. ضمن المصدر، اضبط عقدة المصدر على PlaylistEntries، ثم استخدِم إضافة الأعمدة المشار إليها إلى العقدة وإضافة الأعمدة المشار إليها على الحافة لاختيار entry_id لكليهما.
4. ضمن الاستهداف، اضبط عقدة الاستهداف على "الأغاني"، ثم اختَر song_id لكلّ من الأعمدة المشار إليها في العقدة والأعمدة المشار إليها على الحافة.
5. انقر على تم.

👉🌐 وحدة التحكّم — كرِّر هذه الخطوة ثلاث مرات أخرى:

اسم الحافة	جدول	عقدة المصدر → عقدة الوجهة	العمود الذي سيتم اختياره على كلا الجانبين
EntryToPlaylist	PlaylistEntries	PlaylistEntries → Playlists	المصدر entry_id، الهدف playlist_id
SongToArtist	الأغاني	الأغاني → الفنانون	المصدر song_id، الهدف artist_id
ArtistToLabel	الفنانون	الفنّانون → شركات الإنتاج	المصدر artist_id، الهدف label_id

اترك كل حافة بدون خصائص إضافية.

👀 تعرض لوحة "التفاصيل" الآن العناصر المرتبطة (4)، وتعرض لوحة العرض السلسلة التالية: التصنيفات ← الفنانون ← الأغاني ← عناصر قائمة التشغيل → قوائم التشغيل.

3- إضافة المقياس

👉🌐 Console: انقر على عقدة الأغاني (Songs)، ثم على رمز التعديل (edit) (قلم الرصاص) في أعلى لوحة "التفاصيل" (Details). ضمن خصائص التصنيف، انقر على إضافة خاصية، ثم على إضافة حقل.

👉🌐 Console: أدخِل total_streams في اسم الحقل، واكتب ما يلي في مربّع التعبير:

MEASURE(SUM(streams))

👉🌐 وحدة التحكّم: انقر على إضافة، ثم على تم.

4. قراءة الرمز البرمجي الذي كتبته، ثم نشره

👉🌐 وحدة التحكّم: افتح علامة التبويب الرمز في اللوحة اليسرى. كتب مصمّم النماذج بيان CREATE PROPERTY GRAPH نيابةً عنك. انتقِلوا إلى عُقدة "الأغاني": تنتهي قائمة السمات الآن بـ

MEASURE(SUM(streams)) AS `total_streams`

هذه هي الميزة الكاملة، في سطر واحد. بعد هذه الخطوة، يصبح كل شيء مرتبطًا بما يفعله هذا السطر.

👉🌐 وحدة التحكّم: انقر على نشر.

يحدّد الخيار "ب" بعض المقاييس الإضافية، مثل عدد الأغاني والميزانيات والمتابعين ومواضع الإعلانات. تعيد الخطوة كل عملية تجميع يدعمها مقياس إنشاء الرسم البياني مع كل هذه العمليات في SQL، لذلك لا حاجة إلى إضافتها يدويًا هنا.

✅ نقطة التحقّق: في "المستكشف"، يحتوي music الآن على مجلد الرسوم البيانية الذي يتضمّن MusicGraph. انقر عليه: خمس عُقد وأربع حواف والخط MEASURE(SUM(streams)) في علامة التبويب "الرمز". تخطَّ الخطوة التالية وانتقِل إلى دالتا SUM وAGG جنبًا إلى جنب.

4. إنشاء الرسم البياني - الخيار ب: SQL

يمكنك تخطّي هذه الخطوة إذا أنشأت الرسم البياني في أداة تصميم النماذج.

👉📋 أداة تعديل طلب البحث: الصِق النص، ثم انقر على تشغيل:

CREATE OR REPLACE PROPERTY GRAPH music.MusicGraph
  NODE TABLES (
    music.Labels KEY (label_id)
      PROPERTIES (label_id, label_name, marketing_budget,
        MEASURE(SUM(marketing_budget)) AS total_budget),
    music.Artists KEY (artist_id)
      PROPERTIES (artist_id, artist_name, label_id,
        MEASURE(COUNT(artist_id)) AS artist_count),
    music.Songs KEY (song_id)
      PROPERTIES (song_id, title, artist_id, streams,
        MEASURE(SUM(streams))   AS total_streams,
        MEASURE(COUNT(song_id)) AS song_count),
    music.Playlists KEY (playlist_id)
      PROPERTIES (playlist_id, playlist_name, followers,
        MEASURE(SUM(followers)) AS total_followers),
    music.PlaylistEntries KEY (entry_id)
      PROPERTIES (entry_id, playlist_id, song_id,
        MEASURE(COUNT(entry_id)) AS placement_count)
  )
  EDGE TABLES (
    music.PlaylistEntries AS EntryToSong
      SOURCE KEY (entry_id) REFERENCES PlaylistEntries(entry_id)
      DESTINATION KEY (song_id) REFERENCES Songs(song_id) NO PROPERTIES,
    music.PlaylistEntries AS EntryToPlaylist
      SOURCE KEY (entry_id) REFERENCES PlaylistEntries(entry_id)
      DESTINATION KEY (playlist_id) REFERENCES Playlists(playlist_id) NO PROPERTIES,
    music.Songs AS SongToArtist
      SOURCE KEY (song_id) REFERENCES Songs(song_id)
      DESTINATION KEY (artist_id) REFERENCES Artists(artist_id) NO PROPERTIES,
    music.Artists AS ArtistToLabel
      SOURCE KEY (artist_id) REFERENCES Artists(artist_id)
      DESTINATION KEY (label_id) REFERENCES Labels(label_id) NO PROPERTIES
  )

‫👀 تشير لوحة النتائج إلى أنّه تم إنشاء الرسم البياني للمواقع.

قراءتها مرة واحدة

يحتوي الرسم البياني على خمسة جداول عقد وأربعة جداول حواف. تسمّي كل عقدة جدول KEY وتدرج PROPERTIES. الأسطر التي تبدأ بـ MEASURE هي الجزء الجديد: يلتف كل سطر حول إحدى عمليات التجميع المتوافقة ويمنحها اسمًا مستعارًا، وهو أمر مطلوب.

كل جدول حافة هو مفتاح خارجي، ويتم توضيحه على النحو التالي: SOURCE KEY في الجدول الذي يحتوي على المفتاح، وDESTINATION KEY في الجدول الذي يشير إليه. يعني NO PROPERTIES أنّ الحافة لا تحمل أي شيء خاص بها.

لاحظ أنّ PlaylistEntries يظهر ثلاث مرات: مرة واحدة كجدول عقدة، ومرتين أخريين كجدول فعلي خلف الحافتين EntryToSong وEntryToPlaylist. هذا الإجراء متعمّد، وسنشرح السبب لاحقًا.

الاطّلاع على ما أنشأته

👉🌐 Console: في لوحة Explorer، وسِّع music، ثم Graphs، وانقر على MusicGraph. تفتح صفحة الرسم البياني على لوحة عرض تحتوي على خمس عُقد وأربع حواف. انقر على عقدة للاطّلاع على خصائصها، وسيتم إدراج المقاييس مع إجماليها. افتح علامة التبويب الرمز للاطّلاع على البيان الذي يظهر خلف الصورة.

✅ نقطة التحقّق: يحتوي music على مجلد رسومات بيانية يتضمّن MusicGraph، وتعرض علامة التبويب "الرمز" MEASURE(SUM(streams)) AS total_streams.

5- SUM وAGG جنبًا إلى جنب

هذا هو الدرس التطبيقي الكامل في طلب بحث واحد. يحاول كلا العمودين الإجابة عن السؤال نفسه، وهو إجمالي عمليات البث لكل شركة إنتاج، من الجدول نفسه.

هذا الجدول هو ما ينتجه GRAPH_EXPAND. يؤدي ذلك إلى تسوية الرسم البياني: يبدأ بجدول واحد ويتتبّع كل حافة إلى الخارج كـ LEFT JOIN، إلى أن يصبح كل جدول مرتبط بجانب بعضه البعض في نتيجة واحدة عريضة. يجب أن يتضمّن كل صف موضع إعلان واحدًا، وليس أغنية واحدة، ويجب أن يحمل كل عمود الاسم TableLabel_property. يجب الاطّلاع على البيانات قبل طلبها.

👉📋 أداة تعديل طلب البحث: الصِق النص، ثم انقر على تشغيل:

SELECT Labels_label_name, Songs_title, Songs_streams, Playlists_playlist_name
FROM GRAPH_EXPAND("music.MusicGraph")
ORDER BY Songs_title, Playlists_playlist_name

👀 توقَّع 10 صفوف، صف واحد لكل موضع إعلان في PlaylistEntries، وهو ما تم تحميله بالضبط في "الإعداد". تحتلّ أغنية Neon Summer أربعة من هذه المواضع، أي موضع واحد لكل قائمة تشغيل تظهر فيها، ويبلغ عدد مرات تشغيلها Songs_streams 2,000,000,000 في كل موضع. لا يوجد أي خطأ في هذه الصفوف، فقوائم التشغيل هي بالفعل أربع. ولكن يتم الآن تكرار عمود ينتمي إلى أغنية في الصفوف التي تنتمي إلى مواضع الإعلانات، وهذه هي المشكلة الكاملة التي يقيسها طلب البحث التالي.

والآن، لننتقل إلى المقارنة.

👉📋 أداة تعديل طلب البحث: الصِق النص، ثم انقر على تشغيل:

SELECT
  Labels_label_name,
  SUM(Songs_streams)       AS with_sum,
  AGG(Songs_total_streams) AS with_agg
FROM GRAPH_EXPAND("music.MusicGraph")
GROUP BY 1 ORDER BY 1

👀 النتيجة:

Labels_label_name	with_sum	with_agg
Cymbal Records	‫12,600,000,000	‫5,100,000,000
Northwind Audio	‫9,000,000,000	‫4,500,000,000

يمكنك التحقّق من ذلك يدويًا. حققت أغاني Cymbal الأربع 2.0 مليار و1.5 مليار و1.2 مليار و0.4 مليار استماع. هذا يعني 5.1 مليار. AGG هو الصحيح. حجم الملف SUM أكبر بمرتين ونصف، وتضاعف عدد الأغاني في Northwind.

ثلاثة أجزاء جديدة من بناء الجملة

• GRAPH_EXPAND("music.MusicGraph") هي دالة ذات قيمة جدولية تحوّل الرسم البياني إلى جدول واحد عريض، وذلك باتّباع كل حافة كـ LEFT JOIN. تمت تسمية كل عمود TableLabel_property، لذا فإنّ Songs_streams هو العمود الأوّلي من جدول "الأغاني" وSongs_total_streams هو المقياس الذي حدّدته.
• ‫SUM(Songs_streams) هو SQL عادي على هذا الجدول الواسع، ويرث كل تكرار ناتج عن التسوية.
• تُقيّم الدالة AGG(Songs_total_streams) المقياس بالطريقة التي تم تحديدها بها: SUM(streams) مرة واحدة لكل song_id، بغض النظر عن عدد الصفوف التي تشغلها الأغنية في الجدول الواسع.

لا تلاحظ النتائج المخزّنة مؤقتًا أي تغييرات في الرسم البياني. يتم تخزين نتائج طلبات البحث التي تستدعي GRAPH_EXPAND مؤقتًا مثل أي طلبات بحث أخرى، ولا يؤدي تغيير الرسم البياني إلى إبطال تلك الذاكرة المؤقتة. عند إعادة تشغيل طلب بحث بعد تغيير الرسم البياني، افتح المزيد → إعدادات طلب البحث في محرِّر طلب البحث وأزِل العلامة من المربّع بجانب استخدام النتائج المخزّنة مؤقتًا.

✅ نقطة التحقّق: تصنيفان وعمودان، وتتطابق أرقام with_agg مع عدد الأصابع.

6. لماذا تحتسب الدالة SUM عددًا أكبر من اللازم؟

استمع إلى أغنية واحدة وشاهِد تأثير عمليات الدمج هذه عليها.

👉📋 أداة تعديل طلب البحث: الصِق النص، ثم انقر على تشغيل:

SELECT 'BEFORE - the Songs table' AS step, title, streams, CAST(NULL AS STRING) AS playlist
FROM music.Songs WHERE title = 'Neon Summer'
UNION ALL
SELECT 'AFTER - joined to playlists', s.title, s.streams, pl.playlist_name
FROM music.Songs s
LEFT JOIN music.PlaylistEntries e ON e.song_id = s.song_id
LEFT JOIN music.Playlists pl ON pl.playlist_id = e.playlist_id
WHERE s.title = 'Neon Summer'
ORDER BY step DESC, playlist

👀 النتيجة:

بخطوة	title	مجموعات بث	قائمة تشغيل
BEFORE - the Songs table	صيف النيون	2,000,000,000	قيمة فارغة
AFTER - joined to playlists	صيف النيون	2,000,000,000	Gym Pump
AFTER - joined to playlists	صيف النيون	2,000,000,000	المحتوى الرائج حاليًا
AFTER - joined to playlists	صيف النيون	2,000,000,000	أغاني بوب صاعدة
AFTER - joined to playlists	صيف النيون	2,000,000,000	رحلة برية

تحوّل صف واحد إلى أربعة صفوف. لم يتغيّر عدد مصادر البيانات، بل تم نسخه. إليك مجموع عدد مرات الاستماع إلى أغاني Cymbal Records: أغنية Neon Summer 2.0 مليار مرة في أربع قوائم تشغيل، أي 8.0، وأغنية Paper Crown 1.5 مليار مرة في قائمتَي تشغيل، أي 3.0، وأغنية Double Shot 1.2 مليار مرة في قائمة تشغيل واحدة، وأغنية Slow Arrow 0.4 مليار مرة في قائمة تشغيل واحدة. وهذا يساوي 12.6 مليار، وهو الرقم SUM الذي تم عرضه. تظهر أغنية Northwind's Midnight Drive في قائمتَي تشغيل، لذا تحوّل الرقم 4.5 مليار إلى 9.0 مليار.

يُعرف ذلك باسم التوزيع الموسَّع، وهو ليس خطأ في عملية الربط. صفوف قوائم التشغيل حقيقية. الخطأ هو جمع رقم يخصّ أغنية معيّنة في صفوف تخصّ مواضع الإعلانات.

يتم إصلاح الخطأ في المقياس لأنّه تم تعريفه في عقدة "الأغاني" مع KEY (song_id). المهم هو الحبوب. عندما تقيّم الدالة AGG السمة total_streams، يتم تجميعها مرة واحدة لكل مفتاح أغنية، وبعد ذلك يتم تجميعها حسب أي شيء تم تجميعه.

أوجه التغيير

كنت تكتب	باستخدام مقياس
SUM(streams) في كل طلب بحث يحتاج إلى ذلك	MEASURE(SUM(streams)) مرة واحدة في الرسم البياني
SUM(...) لقراءتها	AGG(...) لقراءتها، وAGG فقط
ثلاث JOINات	‫GRAPH_EXPAND()، جدول مسطّح واحد
تعبير جدول شائع يجمع البيانات قبل الانضمام	لا شيء. يحدّد KEY مستوى التحبب

✅ نقطة التحقّق: خمسة صفوف، صف واحد قبل التغيير وأربعة بعده، ويمكنك إعادة إنشاء 12.6 مليار من هذه الصفوف.

7. القاعدة: لا يمكن لـ AGG قراءة مقياس إلا إذا كان

للمقاييس نوعها الخاص، MEASURE، وتقبلها دالة واحدة فقط. إنّ الاستعلامات الأربعة أدناه معطّلة عمدًا، لذا شغِّل كل استعلام واقرأ الخطأ الأحمر. هذه هي الطرق الأربع التي يجربها الجميع أولاً، ومعرفة ما تعنيه توفّر الوقت لاحقًا.

👉📋 محرّر طلبات البحث — AGG في عمود عادي:

SELECT AGG(Songs_streams) FROM GRAPH_EXPAND("music.MusicGraph")

👀 No matching signature for aggregate function AGG ... Argument 1: expected MEASURE, found INT64

👉📋 محرِّر طلبات البحث: عمود مقياس بدون AGG:

SELECT Songs_total_streams FROM GRAPH_EXPAND("music.MusicGraph") LIMIT 1

👀 Returning expressions of type MEASURE is not allowed

👉📋 محرّر طلبات البحث: مقياس يُشار إليه في لغة طلبات البحث الخاصة بالرسوم البيانية (GQL)، ولا يرى المقاييس على الإطلاق (هذا المقياس هو طلب بحث بلغة طلبات البحث الخاصة بالرسوم البيانية، راجِع ملاحظة الإصدار في النظرة العامة):

GRAPH music.MusicGraph
MATCH (s:Songs)
RETURN s.total_streams
LIMIT 1

👀 total_streams is not exposed by element type GRAPH_NODE(...)

👉📋 محرّر طلبات البحث — SUM فوق عمود مقياس، وهو العمود الجذّاب:

SELECT Labels_label_name, SUM(Songs_total_streams)
FROM GRAPH_EXPAND("music.MusicGraph")
GROUP BY 1

👀 MEASURE-typed arguments are only permitted in the AGG function

وبالتالي، يفرض نظام الأنواع القاعدة نيابةً عنك. لا يمكن الاطّلاع على مقياس إلا من خلال GRAPH_EXPAND، ولا يمكن قراءته إلا من خلال AGG. إنّ الرقم الذي تم احتسابه بشكل زائد والبالغ 12.6 مليار دولار أمريكي من قبل لا يمكن أن يكون ناتجًا إلا عن جمع العمود الأولي، وليس عن سوء التعامل مع المقياس.

✅ نقطة التحقّق: أربعة أخطاء باللون الأحمر، ويمكنك تحديد القاعدة التي يفرضها كل خطأ.

8. كل عملية تجميع تتوافق مع مقياس

تتضمّن السمة MEASURE() أحد الأنواع المجمّعة الستة التالية: SUM وAVG وMIN وMAX وCOUNT وCOUNT(DISTINCT). أعِد إنشاء الرسم البياني مع كل الأغاني الست على عقدة "الأغاني". تبقى الحواف NO PROPERTIES، وهي أفضل الممارسات الموثّقة عندما تشارك الحافة جدولها الفعلي مع عقدة.

👉📋 أداة تعديل طلب البحث: الصِق النص، ثم انقر على تشغيل:

CREATE OR REPLACE PROPERTY GRAPH music.MusicGraph
  NODE TABLES (
    music.Labels KEY (label_id)
      PROPERTIES (label_id, label_name, marketing_budget,
        MEASURE(SUM(marketing_budget)) AS total_budget),
    music.Artists KEY (artist_id)
      PROPERTIES (artist_id, artist_name, label_id,
        MEASURE(COUNT(artist_id)) AS artist_count),
    music.Songs KEY (song_id)
      PROPERTIES (song_id, title, artist_id, streams,
        MEASURE(SUM(streams))              AS total_streams,
        MEASURE(AVG(streams))              AS avg_streams,
        MEASURE(MIN(streams))              AS min_streams,
        MEASURE(MAX(streams))              AS max_streams,
        MEASURE(COUNT(song_id))            AS song_count,
        MEASURE(COUNT(DISTINCT artist_id)) AS distinct_artists),
    music.Playlists KEY (playlist_id)
      PROPERTIES (playlist_id, playlist_name, followers,
        MEASURE(SUM(followers)) AS total_followers),
    music.PlaylistEntries KEY (entry_id)
      PROPERTIES (entry_id, playlist_id, song_id,
        MEASURE(COUNT(entry_id)) AS placement_count)
  )
  EDGE TABLES (
    music.PlaylistEntries AS EntryToSong
      SOURCE KEY (entry_id) REFERENCES PlaylistEntries(entry_id)
      DESTINATION KEY (song_id) REFERENCES Songs(song_id) NO PROPERTIES,
    music.PlaylistEntries AS EntryToPlaylist
      SOURCE KEY (entry_id) REFERENCES PlaylistEntries(entry_id)
      DESTINATION KEY (playlist_id) REFERENCES Playlists(playlist_id) NO PROPERTIES,
    music.Songs AS SongToArtist
      SOURCE KEY (song_id) REFERENCES Songs(song_id)
      DESTINATION KEY (artist_id) REFERENCES Artists(artist_id) NO PROPERTIES,
    music.Artists AS ArtistToLabel
      SOURCE KEY (artist_id) REFERENCES Artists(artist_id)
      DESTINATION KEY (label_id) REFERENCES Labels(label_id) NO PROPERTIES
  )

الآن، اقرأها كلها مرة أخرى. يمرّ كل مقياس بعملية AGG، ويعرض العمود الأخير أنّ نتائج AGG هي قيم عادية يمكنك إجراء عمليات حسابية عليها. لقد تغيّر الرسم البياني للتو، لذا عليك إلغاء تفعيل استخدام النتائج المخزّنة مؤقتًا أولاً (المزيد → إعدادات الاستعلام).

👉📋 أداة تعديل طلب البحث: الصِق النص، ثم انقر على تشغيل:

SELECT
  Labels_label_name,
  AGG(Songs_total_streams)    AS total_streams,
  AGG(Songs_avg_streams)      AS avg_streams,
  AGG(Songs_min_streams)      AS min_streams,
  AGG(Songs_max_streams)      AS max_streams,
  AGG(Songs_song_count)       AS songs,
  AGG(Songs_distinct_artists) AS artists,
  AGG(Songs_total_streams) / AGG(Songs_song_count) AS streams_per_song
FROM GRAPH_EXPAND("music.MusicGraph")
GROUP BY 1
ORDER BY 1

👀 النتيجة:

Labels_label_name	total_streams	avg_streams	min_streams	max_streams	أغنية	الفنانون	streams_per_song
Cymbal Records	‫5,100,000,000	1,275,000,000	400,000,000	2,000,000,000	4	2	1,275,000,000
Northwind Audio	‫4,500,000,000	‫4,500,000,000	‫4,500,000,000	‫4,500,000,000	1	1	‫4,500,000,000

يتم احتساب كل رقم على أربع أغانٍ في Cymbal وأغنية واحدة في Northwind، وليس على صفوف مواضع الإعلانات العشرة. كانت القيمة AVG على وجه الخصوص ستكون خاطئة في الاتجاه الآخر: إنّ حساب متوسط العمود الأولي على مستوى صفوف مواضع الإعلان يعطي 1.575 مليار دولار أمريكي لأغنية Cymbal، لأنّه يتم احتساب مبلغ 2 مليار دولار أمريكي لأغنية Neon Summer أربع مرات.

لذا، فإنّ "استبدال SUM بـ AGG" هو في الواقع قراران. عند تعريف المقياس، يمكنك اختيار أيّ من القيم المجمّعة الست. وعند قراءته، تكون الدالة دائمًا AGG.

تعمل المقاييس في جداول الحواف أيضًا، مع تطبيق قاعدة واحدة: لا يمكن أن يشير تعبير المقياس إلا إلى سمة تعلن عنها الحافة نفسها، لذا يجب إدراج السمة أولاً، ثم المقياس الذي يستخدمها.

✅ نقطة التحقّق: صف واحد لكل تصنيف، وسبعة أرقام لكل تصنيف، ويجب أن تكون قيمة streams_per_song مساوية لقيمة avg_streams.

9. تغيير التجميع، وليس المقياس

يجيب المقياس نفسه عن سؤال مختلف. يمكنك تجميع المحتوى حسب قائمة التشغيل بدلاً من التصنيف.

👉📋 أداة تعديل طلب البحث: الصِق النص، ثم انقر على تشغيل:

SELECT
  Playlists_playlist_name,
  AGG(Songs_total_streams) AS streams,
  AGG(Songs_song_count)    AS songs
FROM GRAPH_EXPAND("music.MusicGraph")
GROUP BY 1
ORDER BY 2 DESC

👀 النتيجة:

Playlists_playlist_name	مجموعات بث	أغنية
رحلة برية	‫6,900,000,000	3
Gym Pump	‫6,500,000,000	2
المحتوى الرائج حاليًا	‫4,700,000,000	3
أغاني بوب صاعدة	‫3,500,000,000	2

سطرا AGG هما سطرا SUM وAGG، جنبًا إلى جنب. تم نقل GROUP BY فقط. تتضمّن قائمة التشغيل "رحلة على الطريق" أغاني "صيف نيون" و"قيادة ليلية" و"سهم بطيء"، ويتم احتساب كل أغنية مرة واحدة داخل قائمة التشغيل هذه، وهذا هو المقصود بالضبط بعبارة "عمليات البث التي وصلت إلى قائمة التشغيل هذه".

يحدّد الشخص الذي كتب المقياس مستوى التفاصيل مرة واحدة. ويتم تطبيق هذا الإعداد على كل طلب بحث لاحق يرسله أي مستخدم.

‫✅ نقطة المراقبة: "رحلة على الطريق" في الصدارة مع 6.9 مليار.

10. الاطّلاع على ما يوفّره لك GRAPH_EXPAND

ليس عليك تشغيل GRAPH_EXPAND لمعرفة شكله. يكتب إجراء النظام BQ.SHOW_GRAPH_EXPAND_SCHEMA قائمة الأعمدة في متغيّر.

👉📋 محرّر طلبات البحث: الصِق الأسطر الثلاثة، ثم انقر على تنفيذ:

DECLARE schema STRING DEFAULT '';
CALL BQ.SHOW_GRAPH_EXPAND_SCHEMA('music.MusicGraph', schema);
SELECT schema;

👀 النتيجة هي سلسلة JSON واحدة. يحتوي كل حقل على اسم ونوع ووضع، ويحمل كل عمود مقياس "is_measure": true. بالنسبة إلى الرسم البياني الذي أنشأته للتو، ستحصل على ما يلي، من بين أمور أخرى:

الاسم	النوع	is_measure
Songs_title	سلسلة
Songs_streams	عدد صحيح
Songs_total_streams	عدد صحيح	صحيح
Songs_avg_streams	قيمة عائمة	صحيح
Songs_distinct_artists	عدد صحيح	صحيح
PlaylistEntries_placement_count	عدد صحيح	صحيح

يظهر هنا أيضًا أي وصف أو مرادفات تحدّدها لموقع معيّن. توضّح خطوة المحادثة الاختيارية هوية المستخدمين الذين يمكنهم قراءة هذه الرسائل.

✅ نقطة التحقّق: سلسلة JSON تتضمّن is_measure في كل عمود حدّدته باستخدام MEASURE.

11. ما الذي يحتاجه GRAPH_EXPAND من شكل الرسم البياني؟

لا يوجد أي شيء لتشغيله في هذه الخطوة، ما عليك سوى القراءة. تنشئ GRAPH_EXPAND جدولها الواسع باستخدام سلسلة من LEFT JOIN، بدءًا من جدول واحد واتّباع الحواف إلى الخارج. تنتج عن ذلك ثلاث قواعد، وتستوفي MusicGraph جميعها.

جدول عقدة جذر واحد بالضبط: الجذر هو جدول العُقد الذي لا يظهر مفتاحه في أي جدول آخر، أي الجدول الذي لا يشير إليه أيّ حدّ. في MusicGraph، يكون ذلك PlaylistEntries: مصدر حافتين وليس وجهة أي حافة. يحتوي الجدول الواسع على 10 صفوف، صف واحد لكل موضع إعلان.

كل حافة هي علاقة متعددة إلى واحد، من المصدر إلى الوجهة. يتضمّن كل إدخال أغنية واحدة وقائمة تشغيل واحدة، وكل أغنية تتضمّن فنانًا واحدًا، وكل فنان يتضمّن شركة إنتاج واحدة. لهذا السبب، لا يتوسّع الجدول العريض أبدًا إلى ما بعد صفوف الجذر. لا تظهر البيانات التي لا يمكن الوصول إليها من الجذر: لن تظهر أغنية بدون مواضع في الجدول الواسع.

تتحوّل علاقات المتعدّد إلى المتعدّد إلى عقدة. الأغاني وقوائم التشغيل هي علاقة متعددة إلى متعددة. إذا عرّفت جدول الربط على أنّه حافة واحدة من "الأغاني" إلى "قوائم التشغيل"، سيتجاهله GRAPH_EXPAND باعتباره غامضًا، وبما أنّه لن تبقى أي حواف قابلة للاستخدام، سيتعذّر تنفيذ الطلب. إنّ ترقية PlaylistEntries إلى جدول عقدة مع حافتين متعددتين إلى واحدة خارجها هو النمط الموثّق، وهو ما فعلته عند إنشاء الرسم البياني.

نصيحتان صغيرتان من أفضل الممارسات الواردة في المستندات: حدِّد عقدة وحوافها الصادرة في الجدول الفعلي نفسه، كما يفعل هذا الرسم البياني، واحتفظ بهذه الحواف NO PROPERTIES ما لم تحمل الحافة معلومات لا تحتوي عليها العقدة.

12. (اختياري) المسارات التي تتضمّن GQL

كانت الإجابة عن كل سؤال حتى الآن عبارة عن رقم. لا يتضمّن هذا التقرير هذه المعلومات. إلى أين تصل عمليات البث في Cymbal؟ هو سؤال حول المسارات عبر الرسم البياني، ولا يمكن أن يجيب عنه الإجمالي، لأنّه عند إجراء عملية الجمع، يكون المسار قد انتهى.

تتطلّب هذه الخطوة حجزًا. تتطلّب طلبات البحث في GQL حجزًا في إصدار Enterprise أو Enterprise Plus. إذا كان مشروعك يستخدِم التسعير عند الطلب، يمكنك الاطّلاع على كل نتيجة أدناه والانتقال إلى الخطوة التالية.

1. اسأل عن المكان الذي يتم فيه عرض أحداث البث المباشر

👉📋 أداة تعديل طلب البحث: الصِق النص، ثم انقر على تشغيل:

GRAPH music.MusicGraph
MATCH (l:Labels)<-[:ArtistToLabel]-(a:Artists)<-[:SongToArtist]-(s:Songs)
      <-[:EntryToSong]-(e:PlaylistEntries)-[:EntryToPlaylist]->(pl:Playlists)
WHERE l.label_name = 'Cymbal Records'
RETURN pl.playlist_name, pl.followers,
       SUM(s.streams) AS streams_reaching_this_playlist,
       STRING_AGG(s.title, ', ') AS songs
GROUP BY pl.playlist_name, pl.followers
ORDER BY streams_reaching_this_playlist DESC

👀 يمكنك توقّع أربع قوائم تشغيل:

pl.playlist_name	pl.followers	streams_reaching_this_playlist	أغنية
المحتوى الرائج حاليًا	35,000,000	‫4,700,000,000	Double Shot وNeon Summer وPaper Crown
أغاني بوب صاعدة	2,000,000	‫3,500,000,000	Neon Summer, Paper Crown
رحلة برية	5,000,000	2,400,000,000	Neon Summer, Slow Arrow
Gym Pump	3,000,000	2,000,000,000	صيف النيون

اقرأ السطر MATCH كجملة: ابدأ بتسمية، ثم ارجع إلى الفنانين، ثم إلى أغانيهم، ثم إلى إدخالات قائمة التشغيل التي تتضمّن هذه الأغاني، ثم تقدّم إلى قوائم التشغيل. تشير الأسهم إلى الطريقة التي تم بها تعريف الحواف، بينما يشير الرمز <- إلى الانتقال خطوة واحدة إلى الخلف.

الآن، اجمع أرقام العمود الثالث. 12.6 مليار: هو الرقم الذي حصلت عليه من SUM في الخطوة الرابعة، وهو الرقم الخاطئ.

ها هي الإجابة الصحيحة. في ذلك الوقت، كان السؤال هو مقدار المحتوى الذي تم بثه على Cymbal، وكان يتم احتساب الأغنية مرة واحدة بغض النظر عن عدد قوائم التشغيل التي تتضمّنها. هذا السؤال هو المكان الذي تصل إليه عمليات البث هذه، والأغنية المدرَجة في أربع قوائم تشغيل تصل إلى أربعة شرائح من الجمهور. إنّ التكرار الذي ينتج عن GRAPH_EXPAND هو خطأ لسؤال واحد وإجابة عن السؤال الآخر. لم يكن الهدف من AGG أبدًا هو إزالة المحتوى المكرّر، بل كان الهدف هو مطابقة العمليات الحسابية مع السؤال.

2. عرض المسارات نفسها

إزالة التجميع وطلب المسارات

👉📋 أداة تعديل طلب البحث: الصِق النص، ثم انقر على تشغيل:

GRAPH music.MusicGraph
MATCH p = (l:Labels)<-[:ArtistToLabel]-(a:Artists)<-[:SongToArtist]-(s:Songs)
          <-[:EntryToSong]-(e:PlaylistEntries)-[:EntryToPlaylist]->(pl:Playlists)
WHERE l.label_name = 'Cymbal Records'
RETURN TO_JSON(p) AS path

تسمّي p = المطابقة الكاملة، وتعرضها TO_JSON.

👀 توقَّع 8 صفوف وعمود path واحد. كل خلية هي مصفوفة JSON للعُقد والحواف على طول مسار واحد، وتحمل كل عقدة labels وproperties.

ثمانية صفوف لأربع أغانٍ، لأنّه يتوفّر مسار لكل موضع إعلان، وليس لكل أغنية.

3- فتح علامة التبويب "الرسم البياني"

👉🌐 Console: فوق النتائج، انقر على Graph.

لا تظهر علامة التبويب هذه إلا عندما تحتوي النتيجة على عناصر رسم بياني. أرجع الاستعلام السابق أرقامًا، لذا لم يكن يتضمّن علامة التبويب "رسم بياني"، بينما يرجع هذا الاستعلام مسارات، لذا يتضمّنها.

يتم رسم زاوية الرسم البياني في Cymbal كتصميم قسري، مع عدد العُقد والحواف في العرض وشريحة لكل تصنيف. اسحب عقدة لفصل التنسيق، وانقر على إحدى العقد لقراءة خصائصها.

✅ نقطة التحقّق: يبلغ مجموع العمود الثالث في الاستعلام الأول 12.6 مليار، ويعرض الاستعلام الثاني 8 مسارات، وترسم علامة التبويب "الرسم البياني" هذه المسارات.

13. (اختياري) الدردشة مع الرسم البياني

ما مِن SQL في هذه الخطوة. يمكن لوكلائنا المستندين إلى البيانات في BigQuery استخدام رسم بياني كمصدر للمعرفة، وتشير المستندات إلى أنّهم يستخدمون مقاييس للتجميع المتعدد المستويات. لنرى ما إذا كان ذلك صحيحًا.

قبل البدء: تتطلّب هذه الخطوة تفعيل Gemini Data Analytics API في المشروع وتوفُّر دور "منشئ وكيل بيانات Gemini Data Analytics". يتم تحصيل رسوم من طلبات البحث التي ينفّذها الوكيل وفقًا لأسعار الحوسبة في BigQuery، مثل أي طلب بحث آخر.

1. إنشاء الوكيل

👉🌐 وحدة التحكّم: في قائمة التنقّل في BigQuery على يمين الصفحة، انقر على الوكلاء، ثم على كتالوج الوكلاء، ثم على إنشاء وكيل.

👉🌐 وحدة التحكّم: اكتب Music graph agent في اسم الوكيل، واكتب ما يلي في وصف الوكيل:

Ask questions about labels, artists, songs and playlists in the music property graph.

👉🌐 Console: ضمن مصادر المعرفة، انقر على إضافة مصدر. في مربّع الحوار اختيار المصادر، وسِّع مشروعك، ثم وسِّع music، ثم وسِّع الرسومات البيانية، ثم ضَع علامة في المربّع بجانب MusicGraph، ثم انقر على تأكيد.

👀 يصبح الزر إضافة مصدر غير مفعّل. يمكن أن يحتوي الوكيل على رسم بياني واحد كحدّ أقصى، ولا يمكنه الجمع بين الرسوم البيانية والجداول.

👉🌐 وحدة التحكّم: اترُك المنطقة كما تم ضبطها من الموقع الجغرافي للرسم البياني. انقر على حفظ، ثمّ على نشر. في لوحة قنوات النشر، انقر على نشر الوكيل وأغلِق نافذة التأكيد.

2. طرح السؤال

👉🌐 وحدة التحكّم: انقر على إنشاء محادثة. سيتم فتح صفحة محادثة. اكتب ما يلي في مربّع طرح سؤال في أسفل الصفحة واضغط على Enter:

For each label, show total streams and how many playlists their songs are on

👀 يعرض الوكيل جدولاً وملخّصًا من جملة واحدة:

label_name	total_streams	playlist_placements
Cymbal Records	‫5,100,000,000	8
Northwind Audio	‫4,500,000,000	2

5.1 مليار لم يخبر أحد الوكيل بشأن التوزيع الموسَّع، ولم يقع في هذا الخطأ.

3- قراءة طلب البحث الذي كتبته

👉🌐 وحدة التحكّم: في قائمة التنقّل، انقر على مستكشف الوظائف ثم انقر على أحدث وظيفة. تتضمّن تصنيفاته ca-bq-job: true وdata-agent-id مع معرّف الوكيل، وطلب البحث هو:

SELECT
  Labels_label_name AS label_name,
  AGG(Songs_total_streams) AS total_streams,
  AGG(PlaylistEntries_placement_count) AS playlist_placements
FROM GRAPH_EXPAND("music.MusicGraph")
GROUP BY label_name
ORDER BY total_streams DESC

استخدمت GRAPH_EXPAND وAGG من تلقاء نفسها، لأنّ المقاييس كانت في المخطط الذي قرأته. لا يتضمّن وصف الوكيل أي إشارة إلى ذلك.

✅ نقطة التحقّق: 5.1 مليار في إجابة المحادثة، وAGG(...) في SQL الخاص بالوظيفة.

14. تَنظيم

👉💻 Cloud Shell — إسقاط مجموعة البيانات والجداول والرسم البياني للخصائص:

cd ~/bq-graph-measures-lab
./cleanup.sh

👀 نتوقّع ✓ dropped YOUR_PROJECT_ID.music (tables and graph).

إذا أنشأت وكيل البيانات الاختياري، احذفه في وحدة التحكّم ضمن الوكلاء → قائمة الوكلاء. وإذا ./setup_project.sh أنشأت مشروعًا لهذا التمرين المعملي فقط، فإنّ أفضل طريقة لتنظيف كل شيء هي إيقاف المشروع بأكمله، ويمكنك العثور على المعرّف في ~/project_id.txt.

15. تهانينا

لقد أضفت سطرًا واحدًا، MEASURE(SUM(streams))، ما أدّى إلى تغيير 12.6 مليار إلى 5.1 مليار، وذلك بالنسبة إليك ولكل طلب بحث يكتبه أي شخص في هذا الرسم البياني بعد ذلك، بما في ذلك طلبات البحث التي يكتبها أحد العملاء.

ما تعلّمته

• المقياس هو قيمة مجمّعة يتم تعريفها في عقدة، بجانب KEY الذي يحدّد مستوى التفصيل.
• تعمل السمة GRAPH_EXPAND على تسوية الرسم البياني في جدول عريض واحد يتضمّن TableLabel_property عمودًا.
• ‫AGG هي الدالة الوحيدة التي تقرأ مقياسًا، ويفرض نظام الأنواع ذلك بأربع طرق مختلفة.
• تتوفّر ستة عناصر مجمّعة، ونتائج AGG هي قيم عادية يمكنك تقسيمها.
• يؤدي تغيير GROUP BY إلى إعادة طرح السؤال بدون لمس المقياس.
• تريد "GRAPH_EXPAND" جذرًا واحدًا، وحوافًا متعددة إلى واحد، وتقاطعًا يتم ترقيته إلى عقدة.

جدول القرار

المشكلة	السبب	تعديل الإجابات
مجموع كبير جدًا	SUM فوق عمود موسّع	تحديد مقياس وقراءته باستخدام AGG
"expected MEASURE, found INT64"	‫AGG في عمود عادي	استخدام SUM أو تعريف المقياس
"لا يُسمح بإرجاع تعبيرات من النوع MEASURE"	عمود المقياس بدون AGG	تغليف الهدية: AGG(...)
"غير مكشوف حسب نوع العنصر"	المقياس المشار إليه في GQL	تقيس الوقت الذي يتأخر فيه البث المباشر عن GRAPH_EXPAND فقط
يتجاهل GRAPH_EXPAND حافة أو يتعذّر	تقاطع تم تصميمه كحافة	ترقية جدول الربط إلى عقدة
رقم قديم بعد تغيير الرسم البياني	نتيجة مخزّنة مؤقتًا	إلغاء تفعيل استخدام النتائج المخزَّنة مؤقتًا

المواضيع التي لم نتناولها (عن قصد)

الأوصاف والمرادفات في المواقع · طلبات البحث والقواميس التي تم التحقّق منها لوكلاء البيانات · GQL يتجاوز MATCH واحدًا · المقاييس على أكثر من رسم بياني واحد كلّ منها عبارة عن مختبر مستقل.

مزيد من المعلومات

• التعامل مع المقاييس
• إنشاء رسم بياني للعلاقات بين العناصر وتنفيذ طلب بحث فيه
• نظرة عامة على تحليلات المحادثات
• مستودع Lab: كل طلب بحث في هذا الدرس التطبيقي حول الترميز، مع ترقيم حسب الخطوة