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

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

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

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

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

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

אם נדרש אינדקס וקטורי, הודעת השגיאה תכלול פקודה של Google Cloud CLI ליצירת האינדקס הווקטורי החסר. מריצים את הפקודה כדי ליצור את האינדקס החסר.

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

כדי ליצור אינדקס במהדורת Firestore Standard, צריך לוודא שהוקצה לכם אחד מהתפקידים הבאים:

  • 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

שימוש במסוף Google Cloud

במסוף Google Cloud אפשר לנהל את הפטורים מהוספה אוטומטית לאינדקס ואת האינדקסים הידניים.

יצירת אינדקס ידני

כדי ליצור ידנית אינדקס חדש מ Google Cloud המסוף:

  1. נכנסים לדף Databases במסוף Google Cloud .

    מעבר אל Databases

  2. בוחרים את מסד הנתונים הרצוי מתוך רשימת מסדי הנתונים.

  3. בתפריט הניווט, לוחצים על אינדקסים ואז על הכרטיסייה ידני.

  4. לוחצים על יצירת אינדקס.

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

  5. מזינים מזהה אוסף. מוסיפים את שמות השדות שרוצים ליצור להם אינדקס ואת מצב האינדקס לכל שדה.

    באינדקסים של וקטורים, מזינים את הנתיב של שדה הווקטור ואת מספר הממדים של הטמעת הווקטור.

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

האינדקס החדש יופיע ברשימת האינדקסים הידניים, ו-Firestore Standard edition יתחיל ליצור את האינדקס. כשהאינדקס יסיים את היצירה, יופיע סימן וי ירוק לצד האינדקס.

מחיקת אינדקס ידני

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

  1. נכנסים לדף Databases במסוף Google Cloud .

    מעבר אל Databases

  2. בוחרים את מסד הנתונים הרצוי מתוך רשימת מסדי הנתונים.

  3. בתפריט הניווט, לוחצים על אינדקסים ואז על הכרטיסייה ידני.

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

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

הוספת פטור אוטומטי מהוספה לאינדקס

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

  1. נכנסים לדף Databases במסוף Google Cloud .

    מעבר אל Databases

  2. בוחרים את מסד הנתונים הרצוי מתוך רשימת מסדי הנתונים.

  3. בתפריט הניווט, לוחצים על אינדקסים ואז על הכרטיסייה אוטומטי.

  4. לוחצים על הוספת פטור.

  5. מזינים מזהה אוסף ונתיב שדה.

  6. בוחרים הגדרות חדשות ליצירת אינדקס בשדה הזה. הפעלה או השבתה של אינדקסים של שדה יחיד מסוג array-contains, ‏ ascending ו-descending, שמתעדכנים אוטומטית בשדה הזה.

  7. לוחצים על שמירת הפטור.

הוספת פטור ברמת הקולקציה

כדי להגדיר פטור ממדד של שדה יחיד שחל על כל השדות במזהה אוסף:

  1. לוחצים על הוספת פטור.

  2. מזינים מזהה אוסף לקבוצת האוספים ומגדירים את נתיב השדה כ-*.

    בחירת שדה להחרגה

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

  4. לוחצים על שמירת הפטור.

מחיקת חריגה מהוספה אוטומטית לאינדקס

כדי למחוק חריגה מהוספה אוטומטית לאינדקס:

  1. נכנסים לדף Databases במסוף Google Cloud .

    מעבר אל Databases

  2. בוחרים את מסד הנתונים הרצוי מתוך רשימת מסדי הנתונים.

  3. בתפריט הניווט, לוחצים על אינדקסים ואז על הכרטיסייה אוטומטי.

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

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

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

שימוש ב-Firebase CLI

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

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

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

שימוש ב-Terraform

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

מסדי נתונים במהדורת Standard של Firestore יכולים לכלול אינדקסים של שדה יחיד (אוטומטיים) ואינדקסים מורכבים (ידניים). אפשר לערוך את קובץ ההגדרות של Terraform כדי ליצור אינדקס למסד הנתונים. אינדקסים אוטומטיים וידניים משתמשים בסוגים שונים של משאבי Terraform (google_firestore_index ו-google_firestore_field).

יש תמיכה באינדקסים של מצב Native ושל מצב Datastore.

אינדקס של שדה יחיד (אוטומטי)

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

אינדקסים במצב Datastore

אפשר גם ליצור אינדקסים במצב Datastore באמצעות Terraform.

datastore.tf

resource "google_firestore_index" "datastore-mode-index" {
  project = "project-id"
  database = "database-id"

  collection = "chatrooms"

  fields {
    field_path = "name"
    order      = "ASCENDING"
  }

  fields {
    field_path = "description"
    order      = "DESCENDING"
  }

  query_scope = "COLLECTION_GROUP"
  api_scope   = "DATASTORE_MODE_API"
}
העברה מ-google_datastore_index

המשאב google_datastore_index הוצא משימוש ולא יהיה זמין בגרסה 6.0.0 ואילך של terraform-provider-google.

אם השתמשתם בעבר במשאב google_datastore_index, תוכלו לעבור אל google_firestore_index. כדי לבצע את ההעברה:

  1. תכתוב משאב google_firestore_index מקביל.
  2. מייבאים את האינדקס הקיים במצב Datastore למשאב החדש.
  3. מסירים את ההפניות למשאב הישן google_datastore_index.
  4. מסירים את המשאב הישן google_datastore_index מהמצב של Terraform.
  5. מריצים את הפקודה terraform apply כדי להחיל את השינויים.

בהמשך מפורטות הוראות נוספות:

  1. לכתוב google_firestore_index חלופי על סמך משאב google_datastore_index קיים. בהמשך מפורטים השינויים הנדרשים.

  2. קובעים את נתיב המשאב של האינדקס ב-Firestore:

    export INDEX_RESOURCE_PATH=$(echo '"projects/${google_datastore_index.datastore-index-resource-name.project}/databases/(default)/collectionGroups/${google_datastore_index.datastore-index-resource-name.kind}/indexes/${google_datastore_index.datastore-index-resource-name.index_id}"' | terraform console | tr -d '"')

    מחליפים את datastore-index-resource-name בשם Terraform של המשאב הקיים.

  3. מייבאים את האינדקס הקיים במצב Datastore למשאב google_firestore_index שיצרתם למעלה:

    terraform import google_firestore_index.firestore-index-resource-name $INDEX_RESOURCE_PATH

    מחליפים את firestore-index-resource-name בשם Terraform של המשאב הקיים.

    מידע נוסף על ייבוא משאבי אינדקס של Firestore זמין במאמרי העזרה בנושא google_firestore_index.

  4. מוחקים את המשאב הקיים google_datastore_index מקובץ התצורה של Terraform.

  5. מסירים את המשאב google_datastore_index הקיים ממצב Terraform:

    terraform state rm google_datastore_index.datastore-index-resource-name

    מידע נוסף על הסרת משאבים זמין בדף בנושא הסרת משאבים ב-Terraform.

  6. מריצים את terraform plan. בודקים את הפלט כדי לוודא שלא נוצרים ולא נהרסים משאבים.

    בודקים את הפלט כדי לוודא שהייבוא הושלם בהצלחה. אם הפלט מראה שיש שינויים בשדות, צריך לוודא שהשינויים האלה מכוונים. אם הפלט כולל שורה שדומה ל:

    google_firestore_index.firestore-index-resource-name must be replaced

    לאחר מכן בודקים את קובץ ההגדרות של Terraform כדי לראות אם היו טעויות.

  7. כשמרוצים מהפלט של תוכנית Terraform, מריצים את הפקודה:

    terraform apply

    8. תרגום האינדקס

    כדי לתרגם משאב google_datastore_index למשאב google_firestore_index ששווה לו, מעתיקים אותו ומבצעים את השינויים הבאים:

    • מחליפים את google_datastore_index ב-google_firestore_index.
    • מחליפים את שם הארגומנט kind ב-collection, אבל משאירים את ערך הארגומנט ללא שינוי.
    • מחליפים את שם הארגומנט ancestor ב-query_scope. מחליפים את ערך הארגומנט ALL_ANCESTORS ב-COLLECTION_RECURSIVE, ומחליפים כל ערך אחר ב-COLLECTION_GROUP. אם לא היה ארגומנט ancestor, מוסיפים ארגומנט query_scope עם הערך COLLECTION_GROUP.
    • מוסיפים את הארגומנט api_scope עם הערך DATASTORE_MODE_API.
    • לכל מופע של properties, מחליפים אותו במופע תואם של fields. מחליפים כל מופע של name ב-field_path וכל מופע של direction ב-order.

    לדוגמה, נניח שיש לכם משאב google_datastore_index:

    datastore.tf

    resource "google_datastore_index" "legacy" {
  kind = "foo"

  properties {
    name = "property_a"
    direction = "ASCENDING"
  }

  properties {
    name = "property_b"
    direction = "ASCENDING"
  }
}

    משאב google_firestore_index שווה ערך ייראה כך:

    resource "google_firestore_index" "new" {
  // note: defaults to the provider project
  project = project

  // note: defaults to the (default) database
  database = "(default)"

  collection = "foo"

  api_scope = "DATASTORE_MODE_API"

  // since there was no "ancestor" property set above, use COLLECTION_GROUP here
  query_scope = "COLLECTION_GROUP"

  fields {
    field_path = "property_a"
    order  = "ASCENDING"
  }

  fields {
    field_path = "property_b"
    order = "ASCENDING"
  }
}

    זמן בניית האינדקס

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

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

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

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

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

    שגיאות ביצירת אינדקס

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

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