הגדרת אינדקסים של Datastore באמצעות index.yaml

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

דוגמה index.yaml

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

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

indexes:

- kind: Cat
  ancestor: no
  properties:
  - name: name
  - name: age
    direction: desc

- kind: Cat
  properties:
  - name: name
    direction: asc
  - name: whiskers
    direction: desc

- kind: Store
  ancestor: yes
  properties:
  - name: business
    direction: asc
  - name: owner
    direction: asc

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

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

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

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

kind
שדה חובה. סוג הישות של השאילתה.
properties

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

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

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

ancestor
‫
yes אם לשאילתה יש פסקה של ישות אב (או Query.ancestor() או פסקה של GQL ANCESTOR IS). ערך ברירת המחדל הוא no.

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

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

כשאתם מבצעים בדיקות בסביבה המקומית, אתם יכולים להשתמש בפקודה gcloud emulator כדי להפעיל שירות שמדמה את Datastore לפני שאתם מריצים את האפליקציה:

gcloud beta emulators datastore start --data-dir DATA-DIR

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

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

# AUTOGENERATED

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

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

פריסת קובץ תצורת האינדקס

כדי לפרוס את קובץ התצורה index.yaml, מריצים את הפקודה הבאה:

gcloud app deploy index.yaml

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

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

כשאתם בטוחים שאין יותר צורך באינדקסים ישנים, אתם יכולים למחוק אותם מ-App Engine באופן הבא:

gcloud datastore indexes cleanup index.yaml