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

ينطبق ذلك على إصدار Cloud Firestore Enterprise فقط.

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

قبل البدء

قبل أن تتمكّن من إنشاء فهرس في Cloud Firestore مع إمكانية التوافق مع MongoDB، تأكَّد من أنّك حصلت على أيّ من الأدوار التالية:

• roles/datastore.owner
• roles/datastore.indexAdmin
• roles/editor
• roles/owner

لمنح دور، يُرجى الاطّلاع على منح دور واحد. لمزيد من المعلومات عن أدوار Cloud Firestore والأذونات المرتبطة بها، يُرجى الاطّلاع على الأدوار المُحدَّدة مسبقًا.

إذا كنت قد حدّدت أدوارًا مخصّصة، عليك منح جميع الأذونات التالية لإنشاء الفهارس:

• datastore.indexes.create
• datastore.indexes.delete
• datastore.indexes.get
• datastore.indexes.list
• datastore.indexes.update

إنشاء فهرس

لإنشاء فهرس، أكمِل الخطوات التالية:

MongoDB API

استخدِم طريقة createIndex() لإنشاء فهرس. على سبيل المثال:

•   db.restaurants.createIndex({"cuisine" : 1})
    

•   db.restaurants.createIndex({"cuisine" : 1}, {sparse: true})
    

• يمكن أيضًا إنشاء الفهرس باستخدام db.runCommand() مع فهرس واحد على الأكثر.

    db.runCommand({"createIndexes":"restaurant", "index": [{"key": {"cuisine":1}, {"name": "cuisine_index"}]})
    

يُرجى ملاحظة القيود التالية:

• يمكنك إنشاء فهرس واحد فقط لكل طلب. ‫"db.collection.createIndexes()" غير متاح.
• تستخدِم سجلات التدقيق لإنشاء الفهرس باستخدام واجهة MongoDB API اسم الطريقة google.firestore.admin.v1.FirestoreAdmin.CreateIndex.
• للاطّلاع على خيارات الفهرسة المتوافقة، راجِع الفهارس وسمات الفهرسة.

Firebase وحدة التحكّم

1. في وحدة تحكّم Firebase، انتقِل إلى صفحة قاعدة بيانات Firestore.

   الانتقال إلى قاعدة بيانات Firestore

2. اختَر قاعدة بيانات من قائمة قواعد البيانات.
3. في علامة التبويب الفهارس، انقر على إنشاء فهرس.
4. أدخِل معرّف مجموعة.
5. أضِف مسار حقل واحدًا أو أكثر واختَر خيار فهرس لكل مسار.
6. اختَر خيارًا لوجود الحقل، إما غير متفرّق أو متفرّق.
7. يمكنك اختياريًا ضبط الخيار فهرس المفاتيح المتعدّدة.
8. انقر على إنشاء.
9. يتم عرض الفهرس الجديد في قائمة الفهارس، ويبدأ Cloud Firestore المتوافق مع MongoDB في إنشاء الفهرس. عند إنشاء الفهرس، ستظهر علامة اختيار خضراء بجانبه. إذا لم يتم إنشاء الفهرس، يمكنك الاطّلاع على أخطاء إنشاء الفهرس لمعرفة الأسباب المحتملة.

gcloud CLI

لإنشاء فهرس، استخدِم الأمر gcloud firestore indexes composite create. اضبط قيمة api-scope على mongodb-compatible-api.

gcloud firestore indexes composite create \
--database='DATABASE_ID' \
--collection-group=COLLECTION \
--field-config=FIELD_CONFIGURATION \
--query-scope=collection-group \
--density=dense \
--api-scope=mongodb-compatible-api

استبدِل ما يلي:

• ‫DATABASE_ID: رقم تعريف قاعدة البيانات
• COLLECTION: اسم مجموعة
• FIELD_CONFIGURATION: إعدادات الحقل لكل حقل، أضِف --field-config=field-path=. على سبيل المثال:

      --field-config=field-path=user-id,order=descending \
      --field-config=field-path=score,order=descending
      

  لمزيد من المعلومات حول كيفية ضبط هذه الحقول، يُرجى الاطّلاع على --field-config.

لإنشاء فهرس متفرّق، اضبط --density=sparse-any.

لإنشاء فهرس بمفاتيح متعدّدة، أضِف العلامة --multikey.

لإنشاء فهرس فريد، أضِف العلامة --unique.

Terraform

استخدِم مورد google_firestore_index واضبط api_scope على MONGODB_COMPATIBLE_API وquery_scope على COLLECTION_GROUP.

resource "google_firestore_index" "index" {
  database    = "DATABASE_ID"
  collection  = "COLLECTION"
  api_scope   = "MONGODB_COMPATIBLE_API"
  query_scope = "COLLECTION_GROUP"

  // You can include multiple field blocks
  fields {
    field_path = "FIELD_PATH"
    order      = "ORDER"
  }

  // Optional
  multikey = true
  density  = "DENSITY"
}

استبدِل ما يلي:

• DATABASE_ID: رقم تعريف قاعدة البيانات التي اخترتها
• COLLECTION: اسم المجموعة التي سيتم فهرسة محتواها
• ‫FIELD_PATH: اسم الحقل المطلوب فهرسته
• ORDER: إحدى القيمتين ASCENDING أو DESCENDING
• DENSITY: إحدى القيمتين SPARSE_ANY أو DENSE

حذف فهرس

لحذف فهرس، أكمِل الخطوات التالية:

MongoDB API

استخدِم طريقة dropIndex() لحذف فهرس. على سبيل المثال:

حذف فهرس باستخدام اسم الفهرس

db.restaurants.dropIndex("cuisine_index")

حذف فهرس باستخدام تعريف الفهرس

db.restaurants.dropIndex({"cuisine" : 1})

Firebase وحدة التحكّم

1. في وحدة تحكّم Firebase، انتقِل إلى صفحة قاعدة بيانات Firestore.

   الانتقال إلى قاعدة بيانات Firestore

2. اختَر قاعدة بيانات من قائمة قواعد البيانات.
3. انقر على علامة التبويب الفهارس.
4. في قائمة الفهارس، انقر على حذف من زر المزيد للفهرس الذي تريد حذفه.
5. انقر على حذف الفهرس.

gcloud CLI

1. للعثور على اسم الفهرس، استخدِم الأمر gcloud firestore indexes composite list.

   gcloud firestore indexes composite list \
   --database='DATABASE_ID'

   استبدِل DATABASE_ID بمعرّف قاعدة البيانات.

2. لحذف الفهرس، استخدِم الأمر gcloud firestore indexes composite delete.

   gcloud firestore indexes composite delete INDEX_NAME \
   --database='DATABASE_ID'

   استبدِل ما يلي:

   • ‫INDEX_NAME: اسم مؤشر
   • ‫DATABASE_ID: رقم تعريف قاعدة البيانات

مدة إنشاء الفهرس

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

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

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

إدارة العمليات الطويلة الأمد

إنّ عمليات إنشاء الفهرس هي عمليات تستغرق وقتًا طويلاً. توضّح الأقسام التالية كيفية التعامل مع العمليات الطويلة الأمد للفهارس.

المصطلح الأساسي: يتيح Cloud Firestore المتوافق مع MongoDB العديد من عمليات الإدارة التي قد تستغرق وقتًا طويلاً لإكمالها. تُسمّى هذه العمليات عمليات طويلة الأمد. تتضمّن Cloud Firestore المتوافقة مع MongoDB ميزات لتنفيذ العمليات الطويلة الأمد وإدارتها. تشمل عمليات التشغيل لفترة طويلة المتوافقة عمليات إنشاء الفهرس وعمليات التصدير.

بعد بدء إنشاء الفهرس، يمنح Cloud Firestore المتوافق مع MongoDB العملية اسمًا فريدًا. تتم إضافة البادئة projects/PROJECT_ID/databases/DATABASE_ID/operations/ إلى أسماء العمليات، على سبيل المثال:

projects/PROJECT_ID/databases/DATABASE_ID/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 في الرد، يعني ذلك أنّ العملية لم تكتمل.