تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إدارة الفهارس في 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

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

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

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

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

لحذف فهرس:

انتقِل إلى قسم Cloud Firestore في وحدة تحكُّم Firebase.
انقر على علامة التبويب المؤشرات.
مرِّر مؤشر الماوس فوق الفهرس الذي تريد حذفه واختَر حذف من قائمة السياق.
أكِّد أنّك تريد حذفها بالنقر على حذف من التنبيه.

استخدام واجهة سطر الأوامر في Firebase

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

لنشر فهارس وقواعد Cloud Firestore فقط، يُرجى إضافة علامة --only firestore.

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

استخدام شكل ثلاثي الأبعاد

إنشاء فهارس في قاعدة البيانات

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

فهرس أحادي الحقل

في ما يلي مثال على ملف إعداد 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 بمعرّف قاعدة البيانات.

وقت إنشاء الفهرس

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

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

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

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

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

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

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

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

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