ניהול אינדקסים ב-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. עוברים לקטע Cloud Firestore במסוף Firebase.
  2. עוברים לכרטיסייה Indexes ולוחצים על Add Index.
  3. מזינים את שם האוסף ומגדירים את השדות שלפיהם רוצים למיין את האינדקס.
  4. לוחצים על יצירה.

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

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

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

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

  1. עוברים לקטע Cloud Firestore במסוף Firebase.
  2. לוחצים על הכרטיסייה Indexes.
  3. מעבירים את העכבר מעל המדד שרוצים למחוק ובוחרים באפשרות Delete (מחיקה) בתפריט ההקשר.
  4. לוחצים על מחיקה בהתראה כדי לאשר את המחיקה.

שימוש ב-Firebase CLI

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

זמן ה-build של האינדקס

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

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