أنواع الفهرس في 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 وtags لكل مستند:

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