يضمن Cloud Firestore أداء طلبات البحث من خلال طلب فهرس لكل طلب بحث. يتم تلقائيًا إنشاء الفهارس المطلوبة لطلبات البحث الأساسية. أثناء استخدام تطبيقك واختباره، يُنشئ Cloud Firestore رسائل خطأ تساعدك في إنشاء فهارس إضافية يحتاج إليها تطبيقك. توضّح هذه الصفحة كيفية إدارة فهارس الحقل الواحد والمركّبة والنطاقية.
إنشاء فهرس غير متوفّر من خلال رسالة خطأ
إذا حاولت تنفيذ طلب بحث مركّب باستخدام عبارة نطاق لا ترتبط بفهرس حالي، ستظهر لك رسالة خطأ. تتضمّن رسالة الخطأ رابطًا مباشرًا لإنشاء ملف الوسائط الذي يحتوي على فهرس مفقود في وحدة تحكّم Firebase.
اتّبِع الرابط الذي تم إنشاؤه للانتقال إلى وحدة تحكّم Firebase، راجِع المعلومات التي تمت تعبئتها تلقائيًا، ثم انقر على إنشاء.
في حال كان مطلوبًا إنشاء فهرس متّجه، ستتضمّن رسالة الخطأ الأمر Google Cloud CLI لإنشاء فهرس المتّجه غير المتوفّر. نفِّذ الأمر لمحاولة إنشاء الفهرس المفقود.
الأدوار والأذونات
لكي تتمكّن من إنشاء فهرس في Cloud Firestore، تأكَّد من أنّه تم إسناد أحد الدورَين التاليَين إليك:
roles/datastore.owner
roles/datastore.indexAdmin
roles/editor
roles/owner
إذا حدّدت أدوارًا مخصّصة، يمكنك منح جميع الأذونات التالية لإنشاء الفهارس:
datastore.indexes.create
datastore.indexes.delete
datastore.indexes.get
datastore.indexes.list
datastore.indexes.update
استخدام وحدة تحكُّم Firebase
لإنشاء فهرس جديد يدويًا من "وحدة تحكّم Firebase"، اتّبِع الخطوات التالية:
- انتقِل إلى قسم Cloud Firestore في وحدة تحكُّم Firebase.
- انتقِل إلى علامة التبويب الفهارس وانقر على إضافة فهرس.
- أدخِل اسم المجموعة وحدِّد الحقول التي تريد ترتيب الفهرس حسبها.
- انقر على إنشاء.
يجب أن تكون حقول الفهرس متوافقة مع القيود المفروضة على مسارات الحقول.
يمكن أن تستغرق عملية إنشاء الفهارس بضع دقائق، وذلك استنادًا إلى حجم طلب البحث. بعد إنشائها، يمكنك الاطّلاع على الفهارس وحالتها في القسم الفهارس المركبة. إذا كانت عملية الإنشاء لا تزال جارية، تتضمّن وحدة تحكّم Firebase شريط حالة الإنشاء.
إزالة الفهارس
لحذف فهرس:
- انتقِل إلى قسم Cloud Firestore في وحدة تحكُّم Firebase.
- انقر على علامة التبويب الفهارس.
- مرِّر مؤشر الماوس فوق الفهرس الذي تريد حذفه، ثم انقر على حذف من قائمة السياق.
- أكِّد رغبتك في حذفه بالنقر على حذف من التنبيه.
استخدام واجهة برمجة التطبيقات Firebase CLI
يمكنك أيضًا نشر الفهارس باستخدام واجهة برمجة تطبيقات Firebase.
للبدء، شغِّل firebase init firestore
في دليل مشروعك.
أثناء الإعداد، تُنشئ أداة Firebase CLI ملف JSON يتضمّن الفهرس default
بالتنسيق الصحيح. عدِّل الملف لإضافة المزيد من الفهارس ونشره
باستخدام الأمر firebase deploy
.
لنشر الفهارس والقواعد في Cloud Firestore فقط، أضِف العلامة
--only firestore
.
إذا أجريت تعديلات على الفهارس باستخدام وحدة تحكّم Firebase، تأكَّد من تعديل ملف الفهارس على الجهاز أيضًا. يُرجى الرجوع إلى مرجع تعريف فهرس JSON.
استخدام Terraform
إنشاء الفهارس في قاعدة البيانات
يمكن أن تتضمّن قواعد بيانات Cloud Firestore كلاً من الفهارس التي تتألف من حقل واحد والفهارس المركبة. يمكنك تعديل ملف إعدادات Terraform لإنشاء فهرس لقاعدة بياناتك.
تستخدِم الفهارس التي تتألف من حقل واحد والفهارس المركبة أنواعًا مختلفة من موارد Terraform
(google_firestore_index
وgoogle_firestore_field
).
فهرس حقل واحد
في المثال التالي لملف إعدادات Terraform، يتم إنشاء فهرس حقل واحد في الحقل name
في المجموعة chatrooms
:
firestore.tf
resource "random_id" "variable"{ byte_length = 8 } resource "google_firestore_field" "single-index" { project = "project-id" database = "database-id" collection = "chatrooms_${random_id.variable.hex}" field = "name" index_config { indexes { order = "ASCENDING" query_scope = "COLLECTION_GROUP" } indexes { array_config = "CONTAINS" } } ttl_config {} }
- استبدِل project-id برقم تعريف مشروعك. يجب أن تكون أرقام تعريف المشاريع فريدة.
- استبدِل database-id بمعرّف قاعدة بياناتك.
مؤشر مركّب
في المثال التالي لملف إعدادات Terraform، يتم إنشاء فهرس مركب لمجموعة من حقل name
وحقل description
في مجموعة chatrooms
:
firestore.tf
resource "google_firestore_index" "composite-index" { project = "project-id" database = "database-id" collection = "chatrooms" fields { field_path = "name" order = "ASCENDING" } fields { field_path = "description" order = "DESCENDING" } }
- استبدِل project-id برقم تعريف مشروعك. يجب أن تكون أرقام تعريف المشاريع فريدة.
- استبدِل database-id بمعرّف قاعدة بياناتك.
فهرس المتّجه
في المثال التالي لملف إعدادات Terraform، يتم إنشاء فهرس متّجه في حقل embedding
ضمن مجموعة chatrooms
:
firestore.tf
resource "google_firestore_index" "vector-index" { project = "project-id" database = "database-id" collection = "chatrooms" fields { field_path = "__name__" order = "ASCENDING" } fields { field_path = "embedding" vector_config { dimension = 128 flat {} } } }
- استبدِل project-id برقم تعريف مشروعك. يجب أن تكون أرقام تعريف المشاريع فريدة.
- استبدِل database-id بمعرّف قاعدة بياناتك.
مدة إنشاء الفهرس
لإنشاء فهرس، على Cloud Firestore إعداد الفهرس ثم إضافة البيانات الحالية إلى الفهرس. وقت إنشاء الفهرس هو مجموع وقت الإعداد ووقت إضافة البيانات السابقة:
يستغرق إعداد فهرس بضع دقائق. الحد الأدنى لوقت إنشاء فهرس هو بضع دقائق، حتى بالنسبة إلى قاعدة بيانات فارغة.
يعتمد وقت إضافة البيانات السابقة على مقدار البيانات الحالية التي تنتمي إلى الفهرس الجديد. كلما زاد عدد قيم الحقول التي تتطابق مع تعريف الفهرس، زادت المدة التي يستغرقها ملء الفهرس ببيانات سابقة.
إنّ عمليات إنشاء الفهارس هي عمليات تستغرق وقتًا طويلاً.
بعد بدء إنشاء فهرس، يحدّد Cloud Firestore اسمًا فريدًا
للعملية. تتم إضافة البادئة projects/[PROJECT_ID]/databases/(default)/operations/
إلى أسماء العمليات،
على سبيل المثال:
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
ومع ذلك، يمكنك حذف البادئة عند تحديد اسم عملية لسمة
describe
.
إدراج جميع العمليات التي تستغرق وقتًا طويلاً
لإدراج العمليات التي تستغرق وقتًا طويلاً، استخدِم الأمر gcloud firestore operations list. يسرد هذا الأمر العمليات الجارية والعمليات التي اكتملت مؤخرًا. يتم إدراج العمليات لبضعة أيام بعد اكتمالها:
gcloud firestore operations list
التحقّق من حالة العملية
بدلاً من إدراج جميع العمليات التي تستغرق وقتًا طويلاً، يمكنك إدراج تفاصيل عملية واحدة:
gcloud firestore operations describe operation-name
تقدير وقت الإنجاز
أثناء تنفيذ العملية، اطّلِع على قيمة حقل state
لمعرفة الحالة العامة للعملية.
يعرض طلب حالة عملية طويلة الأمد أيضًا المقياسين
workEstimated
وworkCompleted
. يتم عرض هذه المقاييس لعدد
المستندات. workEstimated
تعرِض إجمالي عدد المستندات المقدَّر الذي ستعالجه
العملية. workCompleted
يعرض عدد المستندات التي تمت معالجتها حتى الآن. بعد اكتمال العملية، يعرض الحقل
workCompleted
إجمالي عدد المستندات التي تمت
معالجتها فعليًا، وقد تختلف عن قيمة الحقلworkEstimated
.
اقسم workCompleted
على workEstimated
للحصول على تقدير تقريبي للتقدّم. قد يكون التقدير غير دقيق لأنّه يعتمد على جمع الإحصاءات المتأخرة.
على سبيل المثال، إليك حالة التقدّم في إنشاء فهرس:
{ "operations": [ { "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI", "metadata": { "@type": "type.googleapis.com/google.firestore.admin.v1.IndexOperationMetadata", "common": { "operationType": "CREATE_INDEX", "startTime": "2020-06-23T16:52:25.697539Z", "state": "PROCESSING" }, "progressDocuments": { "workCompleted": "219327", "workEstimated": "2198182" } }, }, ...
عند اكتمال عملية، سيحتوي وصف العملية على "done":
true
. اطّلِع على قيمة حقل state
لتحديد نتيجة العملية. إذا لم يتم ضبط الحقل done
في الاستجابة،
تكون قيمته false
. لا تعتمد على توفّر القيمة done
للعمليات الجارية.
أخطاء في إنشاء الفهرس
قد تواجه أخطاء في إنشاء الفهرس عند إدارة الفهارس المركبة و إعفاءات فهرس الحقول الفردية. يمكن أن تتعذّر عملية الفهرسة إذا واجهت Cloud Firestore مشكلة في البيانات التي يفهرسها. في معظم الحالات، يعني ذلك أنّك بلغت الحد الأقصى للفهرس. على سبيل المثال، قد تكون العملية قد بلغت الحد الأقصى لعدد إدخالات الفهرس لكل مستند.
إذا تعذّر إنشاء الفهرس، ستظهر لك رسالة الخطأ في وحدة التحكّم. بعد التأكّد من أنّك لا تتجاوز أي حدود فهرس، أعِد محاولة إجراء الفهرسة.