تمت ترجمة هذه الصفحة بواسطة 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.

استخدام Terraform

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

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

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