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

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

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

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

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

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

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

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