ניהול אינדקסים ב-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. במסוף Firebase, עוברים אל Databases & Storage (מסדי נתונים ואחסון) >‏ Firestore.
  2. בכרטיסייה אינדקסים, לוחצים על הוספת אינדקס.
  3. מזינים את שם האוסף ומגדירים את השדות שלפיהם רוצים למיין את האינדקס.
  4. לוחצים על יצירה.

שדות האינדקס חייבים לעמוד במגבלות על נתיבי שדות.

יצירת האינדקסים יכולה להימשך כמה דקות, בהתאם לגודל השאילתה. אחרי שיוצרים את האינדקסים, אפשר לראות אותם ואת הסטטוס שלהם בקטע Composite Indexes. אם הם עדיין בבנייה, במסוף Firebase מוצג סרגל סטטוס של הבנייה.

הסרת אינדקסים

כדי למחוק אינדקס:

  1. במסוף Firebase, עוברים אל Databases & Storage (מסדי נתונים ואחסון) >‏ Firestore.
  2. בכרטיסייה אינדקסים, מעבירים את העכבר מעל האינדקס שרוצים למחוק ובוחרים באפשרות מחיקה בתפריט ההקשר.
  3. לוחצים על מחיקה בהתראה כדי לאשר את המחיקה.

שימוש ב-Firebase CLI

אפשר גם לפרוס אינדקסים באמצעות Firebase CLI. כדי להתחיל, מריצים את הפקודה firebase init firestore בספריית הפרויקט. במהלך ההגדרה, Firebase CLI יוצר קובץ JSON עם האינדקסים שמוגדרים כברירת מחדל בפורמט הנכון. עורכים את הקובץ כדי להוסיף עוד אינדקסים ומפעילים אותו באמצעות הפקודה firebase deploy.

כדי לפרוס רק את האינדקסים והכללים של Cloud Firestore, מוסיפים את הדגל --only firestore.

אם מבצעים שינויים באינדקסים באמצעות Firebase Console, צריך לוודא שמעדכנים גם את קובץ האינדקסים המקומי. אפשר לעיין בהפניה להגדרת אינדקס 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 צריך להגדיר את האינדקס ואז למלא אותו בנתונים קיימים. משך זמן של תהליך build של אינדקס הוא סכום הזמן של ההגדרה ושל מילוי החוסרים:

  • ההגדרה של אינדקס נמשכת כמה דקות. זמן הבנייה המינימלי של אינדקס הוא כמה דקות, גם אם מדובר במסד נתונים ריק.

  • משך הזמן של מילוי החוסרים תלוי בכמות הנתונים הקיימים שצריך להוסיף לאינדקס החדש. ככל שיש יותר ערכים בשדה שתואמים להגדרת האינדקס, כך ייקח יותר זמן למלא את האינדקס.

בניית אינדקסים היא פעולה ממושכת.

אחרי שמתחילים ליצור אינדקס, 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 נתקלת בבעיה בנתונים שהיא יוצרת להם אינדקס. ברוב המקרים, זה אומר שהגעתם למגבלת אינדקס. לדוגמה, יכול להיות שהפעולה הגיעה למספר המקסימלי של רשומות אינדקס לכל מסמך.

אם יצירת האינדקס נכשלת, הודעת השגיאה מוצגת במסוף. אחרי שמוודאים שלא חורגים ממגבלות האינדקס, מנסים שוב לבצע את פעולת האינדקס.