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

يضمن 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":

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

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

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

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

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

لحذف فهرس:

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

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

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