فهرست ها را در 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. به بخش Cloud Firestore کنسول Firebase بروید.
  2. به تب Indexes بروید و روی Add Index کلیک کنید.
  3. نام مجموعه را وارد کنید و فیلدهایی را که می خواهید فهرست را بر اساس آن مرتب کنید، تنظیم کنید.
  4. روی ایجاد کلیک کنید.

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

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

فهرست ها را حذف کنید

برای حذف یک فهرست:

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

از Firebase CLI استفاده کنید

همچنین می توانید با Firebase CLI ایندکس ها را مستقر کنید. برای شروع، firebase init firestore در فهرست پروژه خود اجرا کنید. در طول راه اندازی، Firebase CLI یک فایل 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 عملیات لیست استفاده کنید. این دستور عملیات در حال انجام و اخیراً تکمیل شده را فهرست می کند. عملیات برای چند روز پس از اتمام فهرست شده است:

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

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