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

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

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

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

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

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

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

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

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

التركيز على تطوير التطبيقات بدلاً من إدارة الفهرس

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

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

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

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

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

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

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

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

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

  • فهرس تصاعدي واحد على مستوى المجموعة لكل حقل فرعي غير مصفوفة وغير خريطة
  • فهرس واحد تنازلي بنطاق المجموعة لكل حقل فرعي غير مصفوفة وغير خريطة
  • فهرس تصاعدي بنطاق المجموعة لقيمة الخريطة بأكملها
  • فهرس واحد بترتيب تنازلي على مستوى المجموعة لقيمة الخريطة بأكملها
  • فهرس واحد من نوع array-contains على مستوى المجموعة لكل حقل فرعي من نوع مصفوفة.
  • تتم فهرسة كل حقل فرعي للخريطة بشكل متكرر باستخدام 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 فهرسًا واحدًا تصاعديًا بحقل واحد لكل حقل، وفهرسًا واحدًا تنازليًا بحقل واحد لكل حقل، وفهرسًا واحدًا بحقل واحد يتضمّن مصفوفة لحقل المصفوفة. يمثّل كل صف في الجدول التالي إدخالاً في فهرس ذي حقل واحد:

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

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

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
• أحياء ASC
• neighborhoods DESC
• درجات الحرارة ASC
• temperatures DESC
• درجات الحرارة.ASC الصيف
• temperatures.summer DESC
• temperatures.winter ASC
• temperatures.winter DESC
• تحتوي مصفوفة الأحياء على

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

• 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)، يُرجى الاطّلاع على صفحة تحديد المشاكل وحلّها.