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

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

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

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

עוקבים אחרי הקישור שנוצר למסוף Firebase, בודקים את המידע שנוסף באופן אוטומטי ולוחצים על Create (יצירה).

תפקידים והרשאות

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

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

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

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

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

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

שימוש ב-CLI של Firebase

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

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

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

שימוש ב-Terraform

יצירת אינדקסים במסד הנתונים

מסדי נתונים Cloud Firestore יכולים לכלול גם אינדקסים עם שדה יחיד וגם אינדקסים מורכבים. תוכלו לערוך את קובץ התצורה של Terraform כדי ליצור אינדקס למסד הנתונים שלכם. אינדקסים עם שדה יחיד ואינדקסים מורכבים משתמשים בסוגים שונים של משאבים של Terraform.

אינדקס שדה יחיד

בדוגמה הבאה לקובץ התצורה של 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 במזהה מסד הנתונים.

זמן יצירת האינדקס

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

  • הגדרת אינדקס לוקחת כמה דקות. גרסת ה-build המינימלית לאינדקס הוא כמה דקות, גם אם מסד הנתונים ריק.

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

גרסאות build של אינדקסות הן פעולות ממושכות.

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

לדוגמה, זהו סטטוס ההתקדמות של build של אינדקס:

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

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