مدیریت نمایه‌ها در 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:

1. در کنسول Firebase، به پایگاه‌های داده و فضای ذخیره‌سازی > Firestore بروید.
2. در برگه نمایه‌ها، روی افزودن نمایه کلیک کنید.
3. نام مجموعه را وارد کنید و فیلدهایی را که می‌خواهید نمایه براساس آن‌ها مرتب شود تنظیم کنید.
4. روی ایجاد کردن کلیک کنید.

فیلدهای نمایه باید با محدودیت‌های مسیرهای فیلد مطابقت داشته باشند.

بسته به اندازه پُرسمان، ساختن نمایه‌ها ممکن است چند دقیقه طول بکشد. پس‌از ایجاد نمایه‌ها، می‌توانید آن‌ها و وضعیتشان را در بخش نمایه‌های ترکیبی ببینید. اگر هنوز درحال ساخت باشد، کنسول Firebase شامل نوار وضعیت ساخت است.

برداشتن نمایه‌ها

برای حذف نمایه:

1. در کنسول Firebase، به پایگاه‌های داده و فضای ذخیره‌سازی > Firestore بروید.
2. در برگه نمایه‌ها، نشانگر را روی نمایه‌ای که می‌خواهید حذف شود نگه دارید و حذف را از منوِ بافت انتخاب کنید.
3. با کلیک کردن روی حذف در هشدار، تأیید کنید که می‌خواهید آن را حذف کنید.

استفاده از واسط خط فرمان Firebase

همچنین می‌توانید نمایه‌ها را با واسط خط فرمان Firebase مستقر کنید. برای شروع، 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 با مشکلی در داده‌هایی که نمایه می‌کند مواجه شود، عملیات نمایه‌سازی ممکن است ناموفق باشد. معمولاً این یعنی به حد نمایه رسیده‌اید. برای مثال، ممکن است عملیات به حداکثر تعداد ورودی‌های نمایه برای هر سند رسیده باشد.

اگر ایجاد نمایه ناموفق باشد، پیام خطا را در کنسول می‌بینید. پس‌از اینکه مطمئن شدید به هیچ‌کدام از محدودیت‌های نمایه نرسیده‌اید، عملیات نمایه را دوباره امتحان کنید.