Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

הגדרת אינדקס מורכב

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

דרישות מערכת

כדי להשתמש ב-gcloud CLI, צריך להתקין את Google Cloud CLI.

מידע על index.yaml

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

האמולטור של Datastore מוסיף פריטים לקובץ הזה באופן אוטומטי כשהאפליקציה מנסה להריץ שאילתה שצריכה אינדקס מורכב שאין לו רשומה מתאימה בקובץ התצורה. אפשר לערוך את הקובץ כדי לשנות את האינדקסים המורכבים או ליצור אינדקסים חדשים באופן ידני. הקובץ index.yaml נמצא בתיקייה <project-directory>/WEB-INF/. כברירת מחדל, ספריית הנתונים שמכילה את WEB-INF/appengine-generated/index.yaml היא ~/.config/gcloud/emulators/datastore/. פרטים נוספים זמינים במאמר ספריות פרויקטים של אמולטור Datastore.

דוגמה לקובץ index.yaml:

indexes:

- kind: Task
  ancestor: no
  properties:
  - name: done
  - name: priority
    direction: desc

- kind: Task
  properties:
  - name: collaborators
    direction: asc
  - name: created
    direction: desc

- kind: TaskList
  ancestor: yes
  properties:
  - name: percent_complete
    direction: asc
  - name: type
    direction: asc

התחביר של index.yaml הוא פורמט YAML. מידע נוסף על התחביר הזה זמין באתר YAML.

הגדרות של אינדקסים מורכבים

לרכיב index.yaml יש רכיב רשימה יחיד בשם indexes. כל רכיב ברשימה מייצג אינדקס מורכב של האפליקציה.

רכיב אינדקס יכול לכלול את הרכיבים הבאים:

kind

סוג הישות של השאילתה. חובה להוסיף את הרכיב הזה.

properties

רשימה של מאפיינים שייכללו כעמודות באינדקס המורכב, לפי הסדר שבו הם ימוינו: קודם המאפיינים שמשמשים לסינון לפי שוויון, אחר כך המאפיין שמשמש לסינון לפי אי-שוויון, ואז סדרי המיון והכיוונים שלהם.

כל רכיב ברשימה הזו כולל את הרכיבים הבאים:

name: השם של הנכס במצב Datastore.
direction: כיוון המיון, asc למיון בסדר עולה או desc למיון בסדר יורד. הדרישה הזו רלוונטית רק לנכסים שמשמשים בסדר מיון של השאילתה, והערך שלהם צריך להיות זהה לכיוון שמוגדר בשאילתה. ערך ברירת המחדל הוא asc.

ancestor

‫yes אם השאילתה מכילה פסקה לגבי ישות אב. ערך ברירת המחדל הוא no.

אינדקסים מורכבים אוטומטיים וידניים

כשסימולטור Datastore מוסיף הגדרה של אינדקס מורכב שנוצר ל-index.yaml, הוא עושה זאת מתחת לשורה הבאה, ומוסיף אותה אם צריך:

# AUTOGENERATED

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

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

עדכון אינדקסים מורכבים

הפקודה datastore indexes create בודקת את ההגדרה של האינדקס המורכב המקומי של Datastore (הקובץ index.yaml), ואם ההגדרה של האינדקס המורכב מגדירה אינדקס מורכב שעדיין לא קיים במסד הנתונים שלכם במצב Datastore בסביבת הייצור, מסד הנתונים יוצר את האינדקס המורכב החדש. דוגמה לשימוש ב-indexes create מופיעה במאמר תהליך העבודה של הפיתוח באמצעות ה-CLI של gcloud.

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

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

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

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

מחיקת אינדקסים מורכבים שלא בשימוש

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

אם אתם בטוחים שאין יותר צורך באינדקסים מורכבים ישנים, אתם יכולים למחוק אותם באמצעות הפקודה datastore indexes cleanup. הפקודה הזו מוחקת את כל האינדקסים המורכבים במופע של מצב Datastore בסביבת הייצור שלא מוזכרים בגרסה המקומית של index.yaml. במאמר תהליך הפיתוח באמצעות ה-CLI של gcloud מופיעה דוגמה לשימוש ב-indexes cleanup.

ארגומנטים בשורת הפקודה

פרטים על ארגומנטים של שורת הפקודה ליצירה ולניקוי של אינדקסים מורכבים מופיעים במאמרים datastore indexes create וdatastore indexes cleanup. פרטים על ארגומנטים של שורת הפקודה ב-CLI של gcloud זמינים במדריך העזר ל-CLI של gcloud.

ניהול פעולות ממושכות

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

אחרי שמתחילים ליצור אינדקס מורכב, מצב Datastore מקצה לפעולה שם ייחודי. שמות הפעולות מתחילים בקידומת projects/[PROJECT_ID]/databases/(default)/operations/, לדוגמה:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

עם זאת, אפשר להשמיט את הקידומת כשמציינים שם פעולה לפקודה describe.

הצגת רשימה של כל הפעולות לטווח ארוך

כדי לראות את רשימת הפעולות הממושכות, משתמשים בפקודה gcloud datastore operations list. הפקודה הזו מציגה רשימה של פעולות שמתבצעות כרגע ופעולות שהושלמו לאחרונה. הפעולות מופיעות למשך כמה ימים אחרי שהן מסתיימות:

gcloud

gcloud datastore operations list

מנוחה

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫project-id: מזהה הפרויקט

ה-method של ה-HTTP וכתובת ה-URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations" | Select-Object -Expand Content

מידע על התשובה מופיע בהמשך.

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

{
  "operations": [
  {
    "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIGRiNTdiZDQNmE4YS0yMTVmNWUzZSQadGx1YWZlZAcSMXRzYWVzdS1yZXhlZG5pLW5pbWRhFQpWEg",
    "done": true,
    "metadata": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
      "common": {
        "endTime": "2020-06-23T16:55:29.923562Z",
        "operationType": "CREATE_INDEX",
        "startTime": "2020-06-23T16:55:10Z",
        "state": "SUCCESSFUL"
      },
      "indexId": "CICAJiUpoMK",
      "progressEntities": {
        "workCompleted": "2193027",
        "workEstimated": "2198182"
      }
    },
    "response": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.Index",
      "ancestor": "NONE",
      "indexId": "CICAJiUpoMK",
      "kind": "Task",
      "projectId": "project-id",
           "properties": [
        {
          "direction": "ASCENDING",
          "name": "priority"
        },
        {
          "direction": "ASCENDING",
          "name": "done"
        },
        {
          "direction": "DESCENDING",
          "name": "created"
        }
      ],
      "state": "READY"
    }
  },
  ]
}

תיאור של פעולה יחידה

במקום להציג רשימה של כל הפעולות ארוכות הטווח, אפשר להציג את הפרטים של פעולה אחת:

gcloud

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

gcloud datastore operations describe operation-name

מנוחה

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫project-id: מזהה הפרויקט

ה-method של ה-HTTP וכתובת ה-URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

מריצים את הפקודה הבאה:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations"

‎PowerShell (Windows)

מריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations" | Select-Object -Expand Content

מידע על התשובה מופיע בהמשך.

חישוב משוער של זמן ההשלמה

במהלך הפעולה, אפשר לראות את הערך של השדה state כדי לדעת מה הסטטוס הכולל של הפעולה.

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

כדי לקבל אומדן גס של ההתקדמות, מחלקים את workCompleted ב-workEstimated. יכול להיות שההערכה לא מדויקת כי היא מבוססת על איסוף נתונים סטטיסטיים עם עיכוב.

לדוגמה, הנה סטטוס ההתקדמות של בניית אינדקס מורכב:

{
  "operations": [
    {
      "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
        "common": {
          "operationType": "CREATE_INDEX",
          "startTime": "2020-06-23T16:52:25.697539Z",
          "state": "PROCESSING"
        },
        "progressEntities": {
          "workCompleted": "219327",
          "workEstimated": "2198182"
        }
       },
    },
    ...

כשפעולה מסתיימת, תיאור הפעולה יכיל את הערך "done": true. התוצאה של הפעולה מופיעה בערך של השדה state. אם השדה done לא מוגדר בתגובה, הערך שלו הוא false. אל תסתמכו על קיומו של הערך done בפעולות שנמצאות בתהליך.

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

דרישות מערכת

מידע על index.yaml

הגדרות של אינדקסים מורכבים

אינדקסים מורכבים אוטומטיים וידניים

עדכון אינדקסים מורכבים

מחיקת אינדקסים מורכבים שלא בשימוש

ארגומנטים בשורת הפקודה

ניהול פעולות ממושכות

הצגת רשימה של כל הפעולות לטווח ארוך

gcloud

מנוחה

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

תיאור של פעולה יחידה

gcloud

מנוחה

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

חישוב משוער של זמן ההשלמה

הגדרת אינדקס מורכב