إدارة الفهارس في Cloud Firestore

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

إنشاء فهرس مفقود من خلال رسالة خطأ

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

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

الأدوار والأذونات

قبل أن تتمكن من إنشاء فهرس في 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:

صورة لواجهة فهرسة Firestore في وحدة تحكم Firebase

  1. انتقل إلى قسم Cloud Firestore في وحدة تحكم Firebase .
  2. انتقل إلى علامة التبويب "الفهارس" وانقر فوق "إضافة فهرس" .
  3. أدخل اسم المجموعة وقم بتعيين الحقول التي تريد ترتيب الفهرس وفقًا لها.
  4. انقر فوق إنشاء .

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

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

إزالة الفهارس

لحذف فهرس:

  1. انتقل إلى قسم Cloud Firestore في وحدة تحكم Firebase .
  2. انقر فوق علامة التبويب الفهارس .
  3. قم بالتمرير فوق الفهرس الذي تريد حذفه وحدد حذف من قائمة السياق.
  4. أكد رغبتك في حذفه بالنقر فوق "حذف" من التنبيه.

استخدم Firebase CLI

يمكنك أيضًا نشر الفهارس باستخدام Firebase CLI . للبدء، قم بتشغيل firebase init firestore في دليل مشروعك. أثناء الإعداد، تقوم واجهة سطر أوامر Firebase بإنشاء ملف JSON يحتوي على الفهارس الافتراضية بالتنسيق الصحيح. قم بتحرير الملف لإضافة المزيد من الفهارس ونشره باستخدام أمر firebase deploy .

لنشر فهارس وقواعد Cloud Firestore فقط، أضف علامة --only firestore .

إذا أجريت تعديلات على الفهارس باستخدام وحدة تحكم Firebase، فتأكد من تحديث ملف الفهارس المحلي أيضًا. ارجع إلى مرجع تعريف فهرس JSON .

وقت بناء الفهرس

لإنشاء فهرس، يجب على Cloud Firestore إعداد الفهرس ثم إعادة ملء الفهرس بالبيانات الموجودة. وقت إنشاء الفهرس هو مجموع وقت الإعداد ووقت التعبئة:

  • يستغرق إعداد الفهرس بضع دقائق. الحد الأدنى لوقت إنشاء الفهرس هو بضع دقائق، حتى بالنسبة لقاعدة بيانات فارغة.

  • يعتمد وقت إعادة التعبئة على مقدار البيانات الموجودة في الفهرس الجديد. كلما زاد عدد قيم الحقول التي تطابق تعريف الفهرس، كلما استغرقت إعادة ملء الفهرس وقتًا أطول.

تعتبر عمليات إنشاء الفهرس بمثابة عمليات طويلة الأمد .

بعد بدء إنشاء الفهرس، يقوم Cloud Firestore بتعيين اسم فريد للعملية. أسماء العمليات مسبوقة projects/[PROJECT_ID]/databases/(default)/operations/ ، على سبيل المثال:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

ومع ذلك، يمكنك ترك البادئة عند تحديد اسم العملية لأمر describe .

سرد كافة العمليات طويلة الأمد

لسرد العمليات طويلة الأمد، استخدم أمر قائمة عمليات gcloud firestore . يسرد هذا الأمر العمليات الجارية والمكتملة مؤخرًا. يتم إدراج العمليات لبضعة أيام بعد الانتهاء:

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 مشكلة في البيانات التي يقوم بفهرستها. في أغلب الأحيان، هذا يعني أنك وصلت إلى حد الفهرس . على سبيل المثال، قد تكون العملية قد وصلت إلى الحد الأقصى لعدد إدخالات الفهرس لكل مستند.

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