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

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