نظرة عامة على الفهرس

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

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

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

يتألف الفهرس مما يلي:

• معرّف مجموعة
• قائمة بالحقول في المجموعة المحدّدة
• وضع فهرسة لكل حقل، إما تصاعدي أو تنازلي أو array-contains

يمكن أن يفعّل الفهرس أيضًا خيارات التناثر أو الفريدة.

ترتيب الفهرس

يحدّد ترتيب كل حقل واتجاه الفرز فيه الفهرس بشكل فريد. على سبيل المثال، الفهرسان التاليان هما فهرسان مختلفان ولا يمكن التبديل بينهما:

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

كثافة الفهرس

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

الفهارس المتفرّقة

يفهرس الفهرس المتناثر المستندات في المجموعة التي تحتوي على قيمة (بما في ذلك القيمة الفارغة) لحقل واحد على الأقل من الحقول المفهرسة. يقلّل الفهرس المتناثر من تكاليف التخزين ويمكن أن يحسّن الأداء.

فهارس Array-contains

لتحسين أداء طلب البحث عند البحث في حقل مصفوفة باستخدام array-contains أو array-contains-any، يمكنك فهرسة الحقل في وضع array-contains. يمكن أن يحتوي الفهرس على حقل واحد كحد أقصى في الوضع array-contains.

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

لفهرسة حقل مصفوفة، يجب أن يستوفي الحقل المتطلبات التالية:

• شرط الصفيف غير الفارغ: لا يتم إنشاء إدخال فهرس إلا إذا كان حقل الصفيف موجودًا في المستند وكان صفيفًا غير فارغ. لا تتم فهرسة المستندات التي تحتوي على حقول مفقودة أو غير مصفوفة أو فارغة.

كيفية ارتباط الكثافة بفهارس array-contains

بالنسبة إلى الفهارس التي تتضمّن حقل array-contains، تنطبق قواعد كثافة الفهرس على الحقول المفهرَسة المرتبة فقط. إذا تم استيفاء شرط المصفوفة غير الفارغة، تنطبق قواعد الكثافة على الحقول المفهرسة المتبقية في الفهرس:

• الفهرس غير المتناثر (DENSE): يتم إنشاء إدخال فهرس للمستند. يتم تخزين أي حقول مفهرَسة مرتبة مفقودة في الفهرس على شكل null في إدخال الفهرس.
• الفهرس المتناثر (SPARSE): يتم إنشاء إدخال فهرس فقط في حال توفّر حقل واحد على الأقل من الحقول المفهرَسة المرتبة في المستند.

مثال: إنشاء إدخال فهرس

لنفترض أنّ الفهرس هو users (tags[*], status ASC):

مثال على طلب البحث

// Query for users where 'tags' contains 'news' and 'status' is 'active'
const query = db.collection("users")
  .where("tags", "array-contains", "news")
  .where("status", "==", "active");

// Documents returned by the query:
// [
//   {
//     "id": "alice",
//     "tags": ["news", "tech"],
//     "status": "active"
//   }
// ]

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

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

الحقول غير المتوفّرة في فهرس فريد

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

على سبيل المثال، باستخدام هذا الفهرس:

إذا أضفت المستند {"abbreviation": "LA"} إلى المجموعة، سينشئ الفهرس الفريد إدخالاً مع ضبط name على null. إذا حاولت بعد ذلك إضافة المستند {"abbreviation": "NYC"}، ستفشل العملية لأنّ الإدخال الناتج للفهرس الفريد هو نفسه.

ينطبق السلوك نفسه على الفهارس الفريدة التي تحتوي على حقول متعددة. When creating or updating a document, missing indexed fields are set to null and the resulting index entry must be unique in the index.

الفهارس الفريدة في قيم الصفائف

يمنع فهرس array-contains الفريد المستندات التي تحتوي على عناصر مصفوفة متداخلة.

هذا النوع من الفهارس لا يفرض أن يحتوي الصفيف على قيم فريدة ضمن مستند واحد.

على سبيل المثال، مع فهرس فريد في حقل باسم tags:

المستند التالي، doc1، صالح للإدراج:

{
  "tags": [ "news", "tech", "news", "music" ]
}

يسمح الفهرس بالقيم المكرّرة ("news") ضمن الصفيفة نفسها في مستند واحد.

إذا حاولت إدراج مستند ثانٍ، doc2، مع عنصر مكرر، فستفشل العملية:

{
  "tags": [ "sports", "music" ]
}

ستفشل العملية لأنّ "music" متوفّر في مصفوفة doc1 وتم ربطه في الفهرس.

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

المصفوفات الفارغة والحقول غير المتوفّرة والقيم الفارغة

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

• المصفوفات الفارغة والحقول غير المتوفّرة والقيم الفارغة المستقلة: إذا كان حقل المصفوفة فارغًا أو غير متوفّر بالكامل أو يحتوي على قيمة null مستقلة (ليست داخل مصفوفة)، لن يتم إنشاء مفاتيح فهرسة للمستند. لذلك، يمكن أن تحتوي مستندات متعددة على حقول فارغة أو قيم null مستقلة بدون ظهور أخطاء المفاتيح المكرّرة.
• عناصر فارغة داخل مصفوفة: إذا كانت المصفوفة تحتوي على قيمة null كعنصر (على سبيل المثال، ["news", null])، تتم فهرسة العنصر null. أي مستند لاحق يحتوي على عنصر null في حقل المصفوفة المفهرسة سيتعذّر إرساله مع ظهور خطأ مفتاح مكرر.

تحديد مشاكل أخطاء إنشاء الفهرس وحلّها

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

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

الخطوات التالية

كيفية إنشاء الفهارس وإدارتها