إدارة الفهارس في 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. أكِّد رغبتك في حذفها من خلال النقر على حذف من التنبيه.

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

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

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