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

تضمن Cloud Firestore أداء طلبات البحث من خلال طلب فهرس لكل طلب البحث. يتم تلقائيًا تنفيذ الفهارس المطلوبة لطلبات البحث الأساسية. التي أنشأتها لك. أثناء استخدام التطبيق واختباره، ينشئ 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

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

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

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

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

لحذف فهرس:

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

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

ويمكنك أيضًا نشر الفهارس باستخدام واجهة سطر الأوامر في Firebase. للبدء، شغِّل "firebase init firestore" في دليل مشروعك. أثناء الإعداد، ينشئ واجهة سطر الأوامر في Firebase ملف JSON يتضمّن الإعدادات التلقائية الفهارس بالتنسيق الصحيح. عدِّل الملف لإضافة المزيد من الفهارس ونشره. باستخدام الأمر firebase deploy.

لنشر فهارس وقواعد Cloud Firestore فقط، يمكنك إضافة علم واحد (--only firestore)

وإذا أجريت تعديلات على الفهارس باستخدام وحدة تحكُّم Firebase، تأكَّد أيضًا من تعديل ملف الفهارس المحلية. ارجع إلى مرجع تعريف فهرس JSON.

استخدام شكل ثلاثي الأبعاد

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

يمكن أن تتضمن قاعدة بيانات Cloud Firestore فهرسًا أحادي الحقل أو فهرسًا مركبًا. يمكنك تحرير ملف تهيئة 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 الأمر. يسرد هذا الأمر العمليات الجارية والمكتملة مؤخرًا. يتم سرد العمليات لبضعة أيام بعد الاكتمال:

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

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