إدارة الفهارس في 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 CLI. للبدء، شغِّل الأمر firebase init firestore في دليل مشروعك. أثناء الإعداد، ينشئ Firebase CLI ملف JSON يتضمّن الفهارس التلقائية بالتنسيق الصحيح. عدِّل الملف لإضافة المزيد من الفهارس وانشرها باستخدام الأمر 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 مشكلة في البيانات التي تتم فهرستها. يعني هذا في أغلب الأحيان أنّك بلغت حدًا للفهرس. على سبيل المثال، قد تكون العملية قد بلغت الحد الأقصى لعدد إدخالات الفهرس لكل مستند.

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