Cloud Firestore با الزام به ایجاد یک شاخص برای هر پرس‌وجو، عملکرد پرس‌وجو را تضمین می‌کند. شاخص‌های مورد نیاز برای ابتدایی‌ترین پرس‌وجوها به‌طور خودکار برای شما ایجاد می‌شوند. هنگام استفاده و آزمایش برنامه، Cloud Firestore پیام‌های خطایی ایجاد می‌کند که به شما در ایجاد شاخص‌های اضافی مورد نیاز برنامه‌تان کمک می‌کند. این صفحه نحوه مدیریت شاخص‌های تک‌فیلدی ، ترکیبی و برداری شما را شرح می‌دهد.
ایجاد یک اندیس از دست رفته از طریق یک پیام خطا
اگر یک کوئری ترکیبی با عبارت range که به یک اندیس موجود نگاشت نمی‌شود، اجرا کنید، با خطا مواجه خواهید شد. پیام خطا شامل یک لینک مستقیم برای ایجاد اندیس از دست رفته در کنسول Firebase است.
لینک ایجاد شده را به کنسول Firebase دنبال کنید، اطلاعات خودکار وارد شده را بررسی کنید و روی Create کلیک کنید.
در صورتی که به یک شاخص برداری نیاز باشد، پیام خطا شامل یک دستور 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:
- به بخش Cloud Firestore در کنسول Firebase بروید.
- به برگه «فهرست‌ها» بروید و روی «افزودن فهرست» کلیک کنید.
- نام مجموعه را وارد کنید و فیلدهایی را که می‌خواهید فهرست بر اساس آنها مرتب شود، تنظیم کنید.
- روی ایجاد کلیک کنید.
فیلدهای شاخص باید با محدودیت‌های مسیرهای فیلد مطابقت داشته باشند.
بسته به اندازه پرس و جو، ساخت ایندکس‌ها می‌تواند چند دقیقه طول بکشد. پس از ایجاد آنها، می‌توانید ایندکس‌های خود و وضعیت آنها را در بخش Composite Indexes مشاهده کنید. اگر هنوز در حال ساخت باشند، کنسول Firebase شامل یک نوار وضعیت ساخت است.
حذف ایندکس‌ها
برای حذف یک ایندکس:
- به بخش Cloud Firestore در کنسول Firebase بروید.
- روی برگه Indexes کلیک کنید.
- ماوس را روی فهرستی که می‌خواهید حذف کنید ببرید و از منوی زمینه، گزینه «حذف» را انتخاب کنید.
- با کلیک روی «حذف از هشدار»، تأیید کنید که می‌خواهید آن را حذف کنید.
از رابط خط فرمان فایربیس استفاده کنید
همچنین می‌توانید ایندکس‌ها را با استفاده از رابط خط فرمان فایربیس (Firebase CLI) مستقر کنید. برای شروع، دستور firebase init firestore در دایرکتوری پروژه خود اجرا کنید. در طول راه‌اندازی، رابط خط فرمان فایربیس یک فایل JSON با ایندکس‌های پیش‌فرض در قالب صحیح ایجاد می‌کند. فایل را ویرایش کنید تا ایندکس‌های بیشتری اضافه کنید و آن را با دستور firebase deploy مستقر کنید.
برای استقرار فقط شاخص‌ها و قوانین Cloud Firestore ، پرچم --only firestore را اضافه کنید.
اگر با استفاده از کنسول Firebase ویرایش‌هایی در ایندکس‌ها انجام می‌دهید، مطمئن شوید که فایل ایندکس‌های محلی خود را نیز به‌روزرسانی می‌کنید. به مرجع تعریف ایندکس JSON مراجعه کنید.
از Terraform استفاده کنید
ایجاد ایندکس‌ها در پایگاه داده
پایگاه‌های داده Cloud Firestore می‌توانند شامل هر دو شاخص تک فیلدی و ترکیبی باشند. شما می‌توانید فایل پیکربندی Terraform را ویرایش کنید تا یک شاخص برای پایگاه داده خود ایجاد کنید. شاخص‌های تک فیلدی و ترکیبی از انواع منابع Terraform متمایز ( google_firestore_index و google_firestore_field ) استفاده می‌کنند.
فهرست تک فیلدی
فایل پیکربندی Terraform در مثال زیر، یک اندیس تک فیلدی روی فیلد name در مجموعه chatrooms ایجاد می‌کند:
فروشگاه آتش نشانی.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 ایجاد می‌کند:
فروشگاه آتش نشانی.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 ایجاد می‌کند:
فروشگاه آتش نشانی.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 با داده‌هایی که شاخص‌گذاری می‌کند، مشکلی داشته باشد، عملیات شاخص‌گذاری می‌تواند با شکست مواجه شود. معمولاً این بدان معناست که شما به محدودیت شاخص‌گذاری رسیده‌اید. به عنوان مثال، ممکن است عملیات به حداکثر تعداد ورودی‌های شاخص‌گذاری در هر سند رسیده باشد.
اگر ایجاد شاخص با شکست مواجه شود، پیام خطا را در کنسول مشاهده خواهید کرد. پس از تأیید اینکه به هیچ محدودیت شاخصی برخورد نمی‌کنید، عملیات شاخص‌گذاری خود را دوباره امتحان کنید.