ניהול אינדקסים ב-Cloud Firestore

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

יצירת אינדקס חסר באמצעות הודעת שגיאה

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

כדי ליצור אינדקס חדש באופן ידני ממסוף Firebase:

תמונה של ממשק ההוספה לאינדקס של Firestore במסוף Firebase

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

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

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

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

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

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

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

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