أنواع الفهرس في Cloud Firestore

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

توضّح هذه الصفحة نوعَي الفهارس اللذين تستخدمهما Cloud Firestore، وهما الفهارس التلقائية والفهارس اليدوية.

تعريف الفهرس وبنيته

يتم تحديد الفهرس في قائمة حقول مستند معيّن، مع وضع فهرسة مقابل لكل حقل.

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

يتم ترتيب الفهرس حسب قيم الحقول، بالترتيب المحدّد في تعريف الفهرس.

فهرس لكل طلب بحث

إذا لم يكن هناك فهرس لطلب بحث، فإن معظم قواعد البيانات تزحف عبر محتوياتها عنصرًا تلو الآخر، وهي عملية بطيئة تتباطأ أكثر مع نمو قاعدة البيانات. يساعد Cloud Firestore في توفير أداء عالٍ لطلبات البحث باستخدام الفهارس لجميع طلبات البحث. نتيجةً لذلك، يعتمد أداء طلب البحث على حجم مجموعة النتائج وليس على عدد العناصر في قاعدة البيانات.

إدارة أقل للفهرس، وتطوير أكثر للتطبيقات

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

أنواع الفهارس

يستخدم Cloud Firestore نوعَين من الفهارس: تلقائية ويدوية. تختلف الفهارس اليدوية والتلقائية في كيفية إدارتها.

الفهارس التلقائية

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

الإعدادات التلقائية للفهرس التلقائي

يستخدم Cloud Firestore الإعدادات التلقائية التالية للفهارس التلقائية:

• بالنسبة إلى كل حقل غير مصفوفة وغير خريطة، يحدّد Cloud Firestore فهرسَين على مستوى المجموعة، أحدهما في الوضع التصاعدي والآخر في الوضع التنازلي.

• بالنسبة إلى كل حقل خريطة، ينشئ Cloud Firestore ما يلي:

  • فهرس تصاعدي واحد على مستوى المجموعة لكل حقل فرعي ليس مصفوفة أو خريطة.
  • فهرس تنازلي واحد على مستوى المجموعة لكل حقل فرعي ليس مصفوفة أو خريطة.
  • فهرس تصاعدي واحد على مستوى المجموعة لقيمة الخريطة بالكامل
  • فهرس تنازلي واحد على مستوى المجموعة لقيمة الخريطة بالكامل
  • فهرس واحد على مستوى المجموعة من النوع "يحتوي على مصفوفة" لكل حقل فرعي في المصفوفة.
  • تُفهرس Cloud Firestore كل حقل فرعي في الخريطة بشكل متكرر.

• بالنسبة إلى كل حقل مصفوفة في مستند، ينشئ Cloud Firestore ما يلي:

  • فهرس تصاعدي واحد على مستوى المجموعة لقيمة الصفيف بالكامل
  • فهرس تنازلي واحد على مستوى المجموعة لقيمة الصفيف بالكامل
  • فهرس واحد على مستوى المجموعة من النوع array-contains

• لا تتم صيانة الفهارس التلقائية التي تندرج ضمن نطاق مجموعة المجموعات تلقائيًا.

استثناءات الفهرسة التلقائية

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

استخدِم قيمة مسار الحقل * لإضافة استثناءات الفهرس على مستوى المجموعة في جميع الحقول في مجموعة المجموعات. على سبيل المثال، بالنسبة إلى مجموعة المجموعات comments، اضبط مسار الحقل على * لمطابقة جميع الحقول في مجموعة المجموعات comments و أوقِف فهرسة جميع الحقول ضمن مجموعة المجموعات. يمكنك بعد ذلك إضافة إعفاءات لفهرسة الحقول المطلوبة لطلبات البحث فقط. يؤدي تقليل عدد الحقول المفهرَسة إلى خفض تكاليف التخزين ويمكن أن يحسّن أداء الكتابة.

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

لإنشاء استثناءات الفهرسة التلقائية وإدارتها، يُرجى الاطّلاع على إدارة الفهارس.

الفهارس اليدوية

يخزّن الفهرس اليدوي عملية ربط مرتّبة لجميع المستندات في مجموعة، استنادًا إلى قائمة مرتبة من الحقول المطلوب فهرستها.

يستخدم Cloud Firestore الفهارس اليدوية لإتاحة طلبات البحث غير المتاحة من خلال الفهارس التلقائية.

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

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

يمكنك أيضًا تحديد الفهارس وإدارتها يدويًا باستخدام وحدة التحكّم أو باستخدام Firebase CLI. لمزيد من المعلومات حول إنشاء الفهارس اليدوية وإدارتها، يُرجى الاطّلاع على إدارة الفهارس.

أوضاع الفهرسة ونطاقات طلبات البحث

يمكنك ضبط الفهارس التلقائية واليدوية بشكل مختلف، ولكن يتطلب كلاهما ضبط أوضاع الفهرس ونطاقات طلبات البحث للفهارس.

أوضاع الفهرسة

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

نطاقات طلب البحث

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

نطاق جمع البيانات

تنشئ

Cloud Firestore فهارس بنطاق المجموعة تلقائيًا. تتيح هذه الفهارس تنفيذ طلبات البحث التي تعرض نتائج من مجموعة واحدة.

نطاق مجموعة المجموعات

تتضمّن مجموعة المجموعات كل المجموعات التي لها معرّف المجموعة نفسه. لتشغيل طلب بحث لمجموعة يعرض نتائج مفلترة أو مرتّبة من مجموعة، يجب إنشاء فهرس مطابق مع نطاق المجموعة.

الترتيب التلقائي والحقل __name__

بالإضافة إلى ترتيب المستندات حسب أوضاع الفهرسة المحدّدة لكل حقل (تصاعديًا أو تنازليًا)، تطبّق الفهارس ترتيبًا نهائيًا حسب حقل __name__ لكل مستند. يتم ضبط قيمة الحقل __name__ على مسار المستند الكامل. هذا يعني أنّ المستندات في مجموعة النتائج التي تتضمّن قيم الحقول نفسها يتم ترتيبها حسب مسار المستند.

يتم تلقائيًا ترتيب الحقل __name__ في الاتجاه نفسه لآخر حقل تم ترتيبه في تعريف الفهرس. على سبيل المثال:

لترتيب النتائج حسب اتجاه __name__ غير التلقائي، عليك إنشاء هذا الفهرس.

خصائص الفهرس

يتم تحديد الفهرس الذي يسمح بتنفيذ طلب البحث بأكبر قدر من الكفاءة من خلال السمات التالية:

• الحقول المستخدَمة في فلاتر المساواة
• الحقول المستخدَمة في أنظمة الترتيب
• الحقول المستخدَمة في فلاتر النطاق وعدم المساواة (غير المضمّنة في أنظمة الترتيب)
• الحقول المستخدَمة في عمليات التجميع (غير المضمّنة في أنظمة الترتيب وفلاتر النطاقات وفلاتر عدم المساواة)

تحسب Cloud Firestore نتائج طلبات البحث على النحو التالي:

1. يحدّد الفهرس المقابل لمجموعة طلب البحث وخصائص الفلتر وعوامل تشغيل الفلتر وأنظمة الترتيب.
2. يحدّد موضع الفهرس الذي يبدأ منه الفحص. يتم إلحاق موضع البداية بفلاتر المساواة في طلب البحث وينتهي بفلاتر النطاق وعدم المساواة في حقل orderBy الأول.
3. يبدأ فحص الفهرس، ويعرض كل مستند يستوفي جميع الفلاتر، إلى أن ينفّذ الفحص أحد الإجراءات التالية:
   • يواجه مستندًا لا يستوفي شروط الفلتر ويؤكّد أنّ أي مستند لاحق لن يستوفي شروط الفلتر بالكامل.
   • يصل إلى نهاية الفهرس.
   • تجمع هذه الدالة الحد الأقصى لعدد النتائج التي يطلبها طلب البحث.

مثال على الفهرسة

من خلال إنشاء فهارس أحادية الحقل تلقائيًا، تتيح Cloud Firestore لتطبيقك إمكانية دعم طلبات البحث الأساسية في قاعدة البيانات بسرعة. تتيح لك الفهارس ذات الحقل الواحد إجراء طلبات بحث بسيطة استنادًا إلى قيم الحقول والمقارنات < و<= و== و>= و> وin. بالنسبة إلى حقول الصفائف، تتيح لك هذه الفلاتر إجراء طلبات بحث array-contains وarray-contains-any.

للتوضيح، افحص الأمثلة التالية من وجهة نظر إنشاء الفهرس. ينشئ المقتطف التالي بعض مستندات city في مجموعة cities ويضبط حقول name وstate وcountry وcapital وpopulation وregions لكل مستند:

var citiesRef = db.collection("cities");

citiesRef.doc("SF").set({
    name: "San Francisco", state: "CA", country: "USA",
    capital: false, population: 860000,
    regions: ["west_coast", "norcal"] });
citiesRef.doc("LA").set({
    name: "Los Angeles", state: "CA", country: "USA",
    capital: false, population: 3900000,
    regions: ["west_coast", "socal"] });
citiesRef.doc("DC").set({
    name: "Washington, D.C.", state: null, country: "USA",
    capital: true, population: 680000,
    regions: ["east_coast"] });
citiesRef.doc("TOK").set({
    name: "Tokyo", state: null, country: "Japan",
    capital: true, population: 9000000,
    regions: ["kanto", "honshu"] });
citiesRef.doc("BJ").set({
    name: "Beijing", state: null, country: "China",
    capital: true, population: 21500000,
    regions: ["jingjinji", "hebei"] });
test.firestore.js

بافتراض إعدادات الفهرسة التلقائية، يحدّث Cloud Firestore فهرسًا تصاعديًا واحدًا لكل حقل، وفهرسًا تنازليًا واحدًا لكل حقل، وفهرسًا واحدًا من نوع array-contains لكل حقل مصفوفة. يمثّل كل صف في الجدول التالي إدخالاً في فهرس حقل واحد:

طلبات البحث المتوافقة مع الفهارس ذات الحقل الواحد

باستخدام هذه الفهارس ذات الحقل الواحد التي يتم إنشاؤها تلقائيًا، يمكنك تشغيل طلبات بحث بسيطة مثل ما يلي:

const stateQuery = citiesRef.where("state", "==", "CA");
const populationQuery = citiesRef.where("population", "<", 100000);
const nameQuery = citiesRef.where("name", ">=", "San Francisco");
test.firestore.js

يمكنك أيضًا إنشاء طلبات بحث in وطلبات بحث مركّبة عن المساواة (==):

citiesRef.where('country', 'in', ["USA", "Japan", "China"])

// Compound equality queries
citiesRef.where("state", "==", "CO").where("name", "==", "Denver")
citiesRef.where("country", "==", "USA")
         .where("capital", "==", false)
         .where("state", "==", "CA")
         .where("population", "==", 860000)

إذا كنت بحاجة إلى تشغيل طلب بحث مركّب يستخدم مقارنة نطاق (< أو <= أو > أو >=) أو إذا كنت بحاجة إلى الترتيب حسب حقل مختلف، يجب إنشاء فهرس يدوي لطلب البحث هذا.

يتيح لك فهرس array-contains طلب البحث في حقل مصفوفة regions:

citiesRef.where("regions", "array-contains", "west_coast")
// array-contains-any and array-contains use the same indexes
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])

طلبات البحث المتوافقة مع الفهارس اليدوية

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

citiesRef.where("country", "==", "USA").orderBy("population", "asc")
citiesRef.where("country", "==", "USA").where("population", "<", 3800000)
citiesRef.where("country", "==", "USA").where("population", ">", 690000)
// in and == clauses use the same index
citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)

تتطلّب طلبات البحث هذه الفهرس التالي. بما أنّ طلب البحث يستخدم عامل مساواة (== أو in) للحقل country، يمكنك استخدام وضع فهرسة تصاعدي أو تنازلي لهذا الحقل. بشكل تلقائي، تطبّق عبارات عدم المساواة نظام ترتيب تصاعدي استنادًا إلى الحقل في عبارة عدم المساواة.

لتشغيل طلبات البحث نفسها ولكن بنظام ترتيب تنازلي، تحتاج إلى فهرس إضافي في الاتجاه التنازلي لـ population:

citiesRef.where("country", "==", "USA").orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", "<", 3800000)
         .orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", ">", 690000)
         .orderBy("population", "desc")

citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)
         .orderBy("population", "desc")

لتجنُّب انخفاض الأداء الناتج عن دمج الفهارس، ننصحك بإنشاء فهرس لدمج طلب بحث array-contains أو array-contains-any مع عبارات إضافية:

citiesRef.where("regions", "array-contains", "east_coast")
         .where("capital", "==", true)

// array-contains-any and array-contains use the same index
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])
         .where("capital", "==", true)

طلبات البحث المتوافقة مع فهارس مجموعة المجموعات

لتوضيح فهرس بنطاق مجموعة المجموعات، أضِف مجموعة فرعية باسم landmarks إلى بعض مستندات city:

var citiesRef = db.collection("cities");

citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Bridge",
    category : "bridge" });
citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Park",
    category : "park" });

citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Gallery of Art",
    category : "museum" });
citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Mall",
    category : "park" });

باستخدام الفهرس التالي للحقل الواحد مع نطاق المجموعة، يمكنك الاستعلام عن مجموعة landmarks لمدينة واحدة استنادًا إلى حقل category:

citiesRef.doc("SF").collection("landmarks").where("category", "==", "park")
citiesRef.doc("SF").collection("landmarks").where("category", "in", ["park", "museum"])

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

بعد تفعيل هذا الفهرس، يمكنك الاستعلام عن مجموعة المجموعات landmarks:

var landmarksGroupRef = db.collectionGroup("landmarks");

landmarksGroupRef.where("category", "==", "park")
landmarksGroupRef.where("category", "in", ["park", "museum"])

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

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

db.collectionGroup("landmarks").get()

إدخالات الفهرس

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

يوضّح المثال التالي إدخالات الفهرس لمستند.

مستند

/cities/SF

city_name : "San Francisco"
temperatures : {summer: 67, winter: 55}
neighborhoods : ["Mission", "Downtown", "Marina"]

الفهارس التلقائية

• city_name ASC
• city_name DESC
• neighborhoods ASC
• neighborhoods DESC
• درجات الحرارة تصاعديًا
• temperatures DESC
• temperatures.summer ASC
• temperatures.summer DESC
• temperatures.winter ASC
• temperatures.winter DESC
• neighborhoods Array Contains

الفهارس اليدوية

• city_name ASC, neighborhoods ARRAY
• city_name DESC, neighborhoods ARRAY

إدخالات الفهرس

ينتج عن إعداد الفهرسة هذا إدخالات الفهرس التالية للمستند:

المؤشرات والأسعار

تساهم الفهارس في تكاليف التخزين لتطبيقك. لمزيد من المعلومات حول كيفية احتساب حجم مساحة التخزين للفهارس، يُرجى الاطّلاع على حجم إدخال الفهرس.

استخدام دمج الفهارس

على الرغم من أنّ Cloud Firestore تستخدم فهرسًا لكل طلب بحث، فإنّها لا تتطلّب بالضرورة فهرسًا واحدًا لكل طلب بحث. بالنسبة إلى طلبات البحث التي تتضمّن عبارات مساواة (==) متعددة وعبارة orderBy اختيارية، يمكن لـ Cloud Firestore إعادة استخدام الفهارس الحالية. يمكن لـ "Cloud Firestore" دمج الفهارس لفلاتر المساواة البسيطة لإنشاء الفهارس اللازمة لطلبات البحث الأكبر التي تتضمّن مساواة.

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

• ‫collections_bookmark مطعم

  • ‫class burgerthyme

    name : "Burger Thyme"
category : "burgers"
city : "San Francisco"
editors_pick : true
star_rating : 4
    

يستخدم هذا التطبيق طلبات بحث مثل ما يلي. يستخدم التطبيق مجموعات من عبارات المساواة لـ category وcity وeditors_pick مع الفرز دائمًا حسب star_rating تصاعديًا:

db.collection("restaurants").where("category", "==", "burgers")
                            .orderBy("star_rating")

db.collection("restaurants").where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==", "San Francisco")
                            .where("editors_pick", "==", true )
                            .orderBy("star_rating")

يمكنك إنشاء فهرس لكل طلب بحث:

كحل أفضل، يمكنك تقليل عدد الفهارس من خلال الاستفادة من قدرة Cloud Firestore على دمج الفهارس لبنود المساواة:

لا تقتصر هذه المجموعة من الفهارس على كونها أصغر حجمًا، بل تتيح أيضًا طلبًا إضافيًا:

db.collection("restaurants").where("editors_pick", "==", true)
                            .orderBy("star_rating")

حدود الفهرسة

تنطبق الحدود التالية على الفهارس. لمزيد من المعلومات حول الحصص والحدود، يُرجى الاطّلاع على الحصص والحدود.

أفضل الممارسات المتعلقة بالفهرسة

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

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

لمزيد من المعلومات حول كيفية حلّ مشاكل الفهرسة (توزيع الفهرس، أخطاء INVALID_ARGUMENT)، يُرجى الاطّلاع على صفحة تحديد المشاكل وحلّها.