إدارة الفهارس في 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. في وحدة تحكُّم Firebase، انتقِل إلى قواعد البيانات ومساحة التخزين > Firestore.
  2. في علامة التبويب الفهارس، انقر على إضافة فهرس.
  3. أدخِل اسم المجموعة واضبط الحقول التي تريد ترتيب الفهرس حسبها.
  4. انقر على إنشاء.

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

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

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

لحذف فهرس:

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

استخدام Firebase CLI

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

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