שאילתות NDB

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

סקירה כללית

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

from google.appengine.ext import ndb
... 
class Greeting(ndb.Model):
    """Models an individual Guestbook entry with content and date."""
    content = ndb.StringProperty()
    date = ndb.DateTimeProperty(auto_now_add=True)

    @classmethod
    def query_book(cls, ancestor_key):
        return cls.query(ancestor=ancestor_key).order(-cls.date)

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

ה-Datastore של App Engine תומך באופן מובנה במסננים של התאמות מדויקות (האופרטור ==) ושל השוואות (האופרטורים <, <=, > ו->=). הוא תומך בשילוב של כמה מסננים באמצעות פעולת AND בוליאנית, עם כמה מגבלות (מפורטות בהמשך).

בנוסף לאופרטורים המובנים, ה-API תומך באופרטור !=, שמשלב קבוצות של מסננים באמצעות הפעולה הבוליאנית OR, ובפעולה IN, שבודקת שוויון לאחד מהערכים האפשריים ברשימה (כמו האופרטור in של Python). הפעולות האלה לא ממופות 1:1 לפעולות המקוריות של Datastore, ולכן הן קצת מוזרות ואיטיות יחסית. הם מיושמים באמצעות מיזוג בזיכרון של זרמי תוצאות. שימו לב שהתנאי p != v מיושם כ-p < v OR p > v. (הדבר חשוב לגבי נכסים שחוזרים על עצמם).

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

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

סינון לפי ערכי מאפיינים

נזכרים במחלקה Account מתוך NDB Properties: 

class Account(ndb.Model):
    username = ndb.StringProperty()
    userid = ndb.IntegerProperty()
    email = ndb.StringProperty()

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

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

query = Account.query(Account.userid == 42)

(אם אתם בטוחים שהיה רק Account אחד עם userid, יכול להיות שתעדיפו להשתמש ב-userid כמפתח. Account.get_by_id(...) מהיר יותר מ-Account.query(...).get().)

‫NDB תומך בפעולות הבאות:

property == value
property < value
property <= value
property > value
property >= value
property != value
property.IN([value1, value2])

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

query = Account.query(Account.userid >= 40)

הפעולה הזו מוצאת את כל ישויות החשבון שערך המאפיין userid שלהן גדול מ-40 או שווה לו.

שתיים מהפעולות האלה, != ו-IN, מיושמות כשילוב של הפעולות האחרות, והן קצת מוזרות כמו שמתואר במאמר != ו-IN.

אפשר לציין כמה מסננים: 

query = Account.query(Account.userid >= 40, Account.userid < 50)

הפונקציה הזו משלבת את ארגומנטי המסנן שצוינו ומחזירה את כל ישויות Account שהערך של userid שלהן גדול מ-40 או שווה לו וקטן מ-50.

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

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

query1 = Account.query()  # Retrieve all Account entitites
query2 = query1.filter(Account.userid >= 40)  # Filter on userid >= 40
query3 = query2.filter(Account.userid < 50)  # Filter on userid < 50 too

‫query3 שווה למשתנה query מהדוגמה הקודמת. הערה: אובייקטים של שאילתות הם בלתי ניתנים לשינוי, ולכן יצירת query2 לא משפיעה על query1, ויצירת query3 לא משפיעה על query1 או על query2.

הפעולות != ו-IN

שליפת המחלקה Article מתוך NDB Properties: 

class Article(ndb.Model):
    title = ndb.StringProperty()
    stars = ndb.IntegerProperty()
    tags = ndb.StringProperty(repeated=True)

הפעולות != (לא שווה) ו-IN (חברות) מיושמות על ידי שילוב של מסננים אחרים באמצעות הפעולה OR. הראשון מביניהם, 

property != value

מוטמע כ 

(property < value) OR (property > value)

לדוגמה, 

query = Article.query(Article.tags != 'perl')

שווה ערך ל- 

query = Article.query(ndb.OR(Article.tags < 'perl',
                             Article.tags > 'perl'))

הערה: יכול להיות שתופתעו, אבל השאילתה הזו לא מחפשת ישויות Article שלא כוללות את התג perl! במקום זאת, הוא מוצא את כל הישויות עם תג אחד לפחות שלא שווה ל-perl. לדוגמה, הישות הבאה תיכלל בתוצאות,

גם אם התג שלה הוא perl:

Article(title='Perl + Python = Parrot',
        stars=5,
        tags=['python', 'perl'])

אבל כתובת ה-URL הזו לא תיכלל:

Article(title='Introduction to Perl',
        stars=3,
        tags=['perl'])

אין אפשרות לשלוח שאילתה לגבי ישויות שלא כוללות תג ששווה ל-perl.

באופן דומה, הפעולה IN 

property IN [value1, value2, ...]

שבודקת אם ערך מסוים כלול ברשימה של ערכים אפשריים, מיושמת כ 

(property == value1) OR (property == value2) OR ...

לדוגמה, 

query = Article.query(Article.tags.IN(['python', 'ruby', 'php']))

שווה ערך ל- 

query = Article.query(ndb.OR(Article.tags == 'python',
                             Article.tags == 'ruby',
                             Article.tags == 'php'))

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

שאילתות לגבי נכסים חוזרים

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

Article.tags == 'python'

משתמש בערך יחיד, למרות ש-Article.tags הוא מאפיין חוזר. אי אפשר להשוות מאפיינים חוזרים לאובייקטים של רשימה (Datastore לא יבין את זה), ומסנן כמו 

Article.tags.IN(['python', 'ruby', 'php'])

הפעולה שמתבצעת שונה לחלוטין מחיפוש של ישויות Article שהערך של התגים שלהן הוא הרשימה ['python', 'ruby', 'php']: החיפוש מתבצע אחר ישויות שהערך tags שלהן (שנחשב לרשימה) מכיל לפחות אחד מהערכים האלה.

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

שילוב של פעולות AND ו-OR

אפשר לקנן פעולות של AND ו-OR באופן שרירותי. לדוגמה: 

query = Article.query(ndb.AND(Article.tags == 'python',
                              ndb.OR(Article.tags.IN(['ruby', 'jruby']),
                                     ndb.AND(Article.tags == 'php',
                                             Article.tags != 'perl'))))

עם זאת, בגלל ההטמעה של OR, שאילתה מהסוג הזה שהיא מורכבת מדי עלולה להיכשל עם חריגה. כדי להגביר את הבטיחות, כדאי לנרמל את המסננים האלה כך שיהיה (לכל היותר) פעולת OR אחת בחלק העליון של עץ הביטויים, ורמה אחת של פעולות AND מתחתיה.

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

  1. מרחיבים את האופרטורים != ו-IN לצורה הפרימיטיבית שלהם, כאשר != הופך לבדיקה אם המאפיין הוא < או > מהערך, ו- IN הופך לבדיקה אם המאפיין הוא == לערך הראשון או לערך השני או...עד הערך האחרון ברשימה.
  2. ‫AND עם OR בתוכו שווה ל-OR של כמה ANDs שמוחל על האופרנדים המקוריים של AND, עם אופרנד יחיד של OR במקום האופרנד המקורי של AND.OR לדוגמה: AND(a, b, OR(c, d)) שווה ל- OR(AND(a, b, c), AND(a, b, d))
  3. אפשר לשלב אופרנדים של AND מוטמע בתוך AND שמכיל אותו.ANDAND לדוגמה, AND(a, b, AND(c, d)) שווה ל- AND(a, b, c, d)
  4. אפשר לשלב אופרנדים של OR מקונן בתוך OR שמכיל אותו, אם האופרנד של OR הוא בעצמו פעולת OR. לדוגמה, OR(a, b, OR(c, d)) שווה ל- OR(a, b, c, d)

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

  1. שימוש בכלל מספר 1 באופרטורים IN ו-!=: 
    AND(tags == 'python',
  OR(tags == 'ruby',
     tags == 'jruby',
     AND(tags == 'php',
         OR(tags < 'perl', tags > 'perl'))))
  2. שימוש בכלל מספר 2 ב-OR הפנימי ביותר שמוטמע בתוך AND: 
    AND(tags == 'python',
  OR(tags == 'ruby',
     tags == 'jruby',
     OR(AND(tags == 'php', tags < 'perl'),
        AND(tags == 'php', tags > 'perl'))))
  3. שימוש בכלל מספר 4 ב-OR שמוטמע בתוך OR אחר: 
    AND(tags == 'python',
  OR(tags == 'ruby',
     tags == 'jruby',
     AND(tags == 'php', tags < 'perl'),
     AND(tags == 'php', tags > 'perl')))
  4. שימוש בכלל מספר 2 ב-OR שנותרו בתוך AND: 
    OR(AND(tags == 'python', tags == 'ruby'),
   AND(tags == 'python', tags == 'jruby'),
   AND(tags == 'python', AND(tags == 'php', tags < 'perl')),
   AND(tags == 'python', AND(tags == 'php', tags > 'perl')))
  5. שימוש בכלל מספר 3 כדי לכווץ את תגי ה-AND שנותרו: 
    OR(AND(tags == 'python', tags == 'ruby'),
   AND(tags == 'python', tags == 'jruby'),
   AND(tags == 'python', tags == 'php', tags < 'perl'),
   AND(tags == 'python', tags == 'php', tags > 'perl'))

זהירות: במקרה של חלק מהמסננים, הנורמליזציה הזו עלולה לגרום לפיצוץ קומבינטורי. ניקח לדוגמה AND של 3 OR סעיפים, כשכל אחד מהם כולל 2 סעיפים בסיסיים. אחרי נרמול, זה הופך ל-OR של 8 סעיפים AND עם 3 סעיפים בסיסיים בכל אחד: כלומר, 6 מונחים הופכים ל-24.

ציון סדר המיון

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

query = Greeting.query().order(Greeting.content, -Greeting.date)

הפעולה הזו מאחזרת את כל ישויות Greeting, ממוינות לפי ערך עולה של מאפיין content שלהן. רצפים של ישויות עוקבות עם אותו מאפיין תוכן ימוינו לפי ערך יורד של המאפיין date שלהן. אפשר להשתמש בכמה קריאות order() כדי להשיג את אותה תוצאה: 

query = Greeting.query().order(Greeting.content).order(-Greeting.date)

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

שאילתות לגבי ישות אב

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

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

class Customer(ndb.Model):
    name = ndb.StringProperty()

class Purchase(ndb.Model):
    customer = ndb.KeyProperty(kind=Customer)
    price = ndb.IntegerProperty()

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

purchases = Purchase.query(
    Purchase.customer == customer_entity.key).fetch()

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

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

class Customer(ndb.Model):
    name = ndb.StringProperty()

class Purchase(ndb.Model):
    price = ndb.IntegerProperty()

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

purchase = Purchase(parent=customer_entity.key)

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

purchases = Purchase.query(ancestor=customer_entity.key).fetch()

מאפייני שאילתה

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

מאפיין סוג ברירת מחדל תיאור
סיווג str None שם הסוג (בדרך כלל שם הכיתה)
אב Key None ישות אב שצוינה לשאילתה
מסננים FilterNode None ביטוי סינון
הזמנות Order None מיון ההזמנות

הדפסה של אובייקט שאילתה (או קריאה של str() או repr()) יוצרת ייצוג מחרוזת בפורמט יפה: 

print(Employee.query())
# -> Query(kind='Employee')
print(Employee.query(ancestor=ndb.Key(Manager, 1)))
# -> Query(kind='Employee', ancestor=Key('Manager', 1))

סינון לפי ערכים של מאפיינים מובנים

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

query = Contact.query(Contact.addresses.city == 'Amsterdam')

אם משלבים כמה מסננים כאלה, יכול להיות שהמסננים יתאימו לישויות משנה שונות Address באותה ישות מסוג Contact. לדוגמה: 

query = Contact.query(Contact.addresses.city == 'Amsterdam',  # Beware!
                      Contact.addresses.street == 'Spear St')

יכול להיות שתמצאו אנשי קשר עם כתובת שהעיר שלה היא 'Amsterdam' וכתובת אחרת (שונה) שהרחוב שלה הוא 'Spear St'. עם זאת, לפחות לגבי מסנני שוויון, אפשר ליצור שאילתה שמחזירה רק תוצאות עם כמה ערכים בישות משנה אחת: 

query = Contact.query(Contact.addresses == Address(city='San Francisco',
                                                   street='Spear St'))

אם משתמשים בטכניקה הזו, המערכת מתעלמת בשאילתה ממאפיינים של ישות המשנה ששווים ל-None. אם למאפיין יש ערך ברירת מחדל, צריך להגדיר אותו במפורש ל-None כדי להתעלם ממנו בשאילתה. אחרת, השאילתה כוללת מסנן שדורש שערך המאפיין יהיה שווה לערך ברירת המחדל. לדוגמה, אם למודל Address יש מאפיין country עם הערך default='us', בדוגמה שלמעלה יוחזרו רק אנשי קשר עם מדינה ששווה ל-'us'. כדי להחזיר אנשי קשר עם ערכי מדינה אחרים, צריך לסנן לפי Address(city='San Francisco', street='Spear St', country=None).

אם לישות משנה יש ערכי מאפיינים ששווים ל-None, המערכת מתעלמת מהם. לכן, אין טעם לסנן לפי ערך המאפיין של ישות המשנה None.

שימוש במאפיינים שנקראים על שם מחרוזת

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

Article.query(Article."tags" == "python") # does NOT work

אם המודל הוא Expando, המסנן יכול להשתמש ב-GenericProperty, המחלקה Expando משתמשת במאפיינים דינמיים: 

property_to_query = 'location'
query = FlexEmployee.query(ndb.GenericProperty(property_to_query) == 'SF')

אפשר להשתמש ב-GenericProperty גם אם המודל שלכם לא מבוסס על Expando, אבל אם אתם רוצים לוודא שאתם משתמשים רק בשמות מאפיינים מוגדרים, אתם יכולים להשתמש גם במאפיין המחלקה _properties 

query = Article.query(Article._properties[keyword] == value)

או להשתמש בgetattr() כדי לקבל אותו מהכיתה: 

query = Article.query(getattr(Article, keyword) == value)

ההבדל הוא שב-getattr() נעשה שימוש ב'שם Python' של המאפיין, ואילו ב-_properties נעשה אינדוקס לפי 'שם מאגר הנתונים' של המאפיין. הם שונים רק אם הנכס הוגדר עם משהו כמו 

class ArticleWithDifferentDatastoreName(ndb.Model):
    title = ndb.StringProperty('t')

בדוגמה הזו, השם ב-Python הוא title, אבל השם במאגר הנתונים הוא t.

הגישות האלה מתאימות גם לסידור תוצאות של שאילתות: 

expando_query = FlexEmployee.query().order(ndb.GenericProperty('location'))

property_query = Article.query().order(Article._properties[keyword])

Query Iterators

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

  • שימוש בפונקציה המובנית iter() של Python באובייקט Query
  • הפעלת השיטה iter() של האובייקט Query

הראשונה תומכת בשימוש בלולאת for Python (שקוראת באופן מרומז לפונקציה iter()) כדי לחזור על שאילתה. 

for greeting in greetings:
    self.response.out.write(
        '<blockquote>%s</blockquote>' % cgi.escape(greeting.content))

הדרך השנייה, באמצעות ה-method‏ iter() של האובייקט Query, מאפשרת להעביר אפשרויות לאיטרטור כדי להשפיע על ההתנהגות שלו. לדוגמה, כדי להשתמש בשאילתה של מפתחות בלבד בלולאה for, אפשר לכתוב את הקוד הבא: 

for key in query.iter(keys_only=True):
    print(key)

לאיטרטורים של שאילתות יש שיטות שימושיות נוספות:

‏Method תיאור
__iter__() חלק מפרוטוקול האיטרטור של Python.
next() מחזירה את התוצאה הבאה או מעלה את החריגה StopIteration אם אין תוצאה כזו.

has_next() הפונקציה מחזירה True אם קריאה עוקבת ל-next() תחזיר תוצאה, ו-False אם היא תגרום להפעלת StopIteration.

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

יכול להיות שהפונקציה תחזיר תוצאה חיובית שגויה (True כש-next() בעצם יחזיר StopIteration), אבל היא אף פעם לא תחזיר תוצאה שלילית שגויה (False כש-next() בעצם יחזיר תוצאה).
cursor_before() מחזירה סמן שאילתה שמייצג נקודה ממש לפני התוצאה האחרונה שהוחזרה.

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

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

סמני מיקום של שאילתות

סמן שאילתה הוא מבנה נתונים קטן ואטום שמייצג נקודת חידוש בשאילתה. האפשרות הזו שימושית כשרוצים להציג למשתמש דף תוצאות בכל פעם, וגם כשרוצים לטפל במשימות ארוכות שאולי צריך להפסיק ולהמשיך אותן. אחת הדרכים הנפוצות להשתמש בהם היא באמצעות השיטה fetch_page() של שאילתה. היא פועלת בדומה ל-fetch(), אבל היא מחזירה טריפלט (results, cursor, more). הדגל more שמוחזר מציין שכנראה יש עוד תוצאות. ממשק משתמש יכול להשתמש בדגל הזה, למשל, כדי להסתיר את הלחצן או הקישור 'הדף הבא'. כדי לבקש דפים עוקבים, מעבירים את הסמן שמוחזר על ידי קריאה אחת של fetch_page() לקריאה הבאה. אם מעבירים סמן לא תקין, נוצרת שגיאה BadArgumentError. שימו לב שהאימות בודק רק אם הערך מקודד בפורמט Base64. תצטרכו לבצע אימות נוסף אם יידרש.

לכן, כדי לאפשר למשתמש לראות את כל הישויות שתואמות לשאילתה, צריך לאחזר אותן דף אחרי דף. הקוד יכול להיראות כך: 

from google.appengine.datastore.datastore_query import Cursor
... 
class List(webapp2.RequestHandler):
    GREETINGS_PER_PAGE = 10

    def get(self):
        """Handles requests like /list?cursor=1234567."""
        cursor = Cursor(urlsafe=self.request.get('cursor'))
        greets, next_cursor, more = Greeting.query().fetch_page(
            self.GREETINGS_PER_PAGE, start_cursor=cursor)

        self.response.out.write('<html><body>')

        for greeting in greets:
            self.response.out.write(
                '<blockquote>%s</blockquote>' % cgi.escape(greeting.content))

        if more and next_cursor:
            self.response.out.write('<a href="/list?cursor=%s">More...</a>' %
                                    next_cursor.urlsafe())

        self.response.out.write('</body></html>')

שימו לב לשימוש ב-urlsafe() וב-Cursor(urlsafe=s) כדי לבצע סריאליזציה ודה-סריאליזציה של הסמן. כך אפשר להעביר סמן ללקוח באינטרנט בתגובה לבקשה אחת, ולקבל אותו בחזרה מהלקוח בבקשה מאוחרת יותר.

הערה: השיטה fetch_page() בדרך כלל מחזירה סמן גם אם אין יותר תוצאות, אבל זה לא מובטח: יכול להיות שערך הסמן שיוחזר יהיה None. חשוב גם לזכור שהדגל more מיושם באמצעות השיטה probably_has_next() של האיטרטור, ולכן בנסיבות נדירות הוא עשוי להחזיר True גם אם הדף הבא ריק.

חלק מהשאילתות של NDB לא תומכות בסמני מיקום של שאילתות, אבל אפשר לתקן אותן. אם שאילתה משתמשת ב-IN, ב-OR או ב-!=, תוצאות השאילתה לא יפעלו עם סמני מיקום אלא אם הן מסודרות לפי מפתח. אם אפליקציה לא מסדרת את התוצאות לפי מפתח וקוראת ל-fetch_page(), היא מקבלת BadArgumentError. אם מופיעה שגיאה ב- User.query(User.name.IN(['Joe', 'Jane'])).order(User.name).fetch_page(N) , משנים אותו ל- User.query(User.name.IN(['Joe', 'Jane'])).order(User.name, User.key).fetch_page(N)

במקום להשתמש בשיטת iter() של שאילתה כדי לקבל סמן בנקודה מדויקת, אפשר להשתמש בשיטה הזו כדי לעבור בין תוצאות של שאילתה. כדי לעשות את זה, מעבירים את produce_cursors=True אל iter(); כשהאיטרטור נמצא במקום הנכון, קוראים ל-cursor_after() שלו כדי לקבל סמן שנמצא מיד אחריו. (או, באופן דומה, קוראים ל-cursor_before() כדי לקבל סמן ממש לפני). שימו לב: קריאה ל-cursor_after() או ל-cursor_before() עשויה להפעיל קריאה חוסמת ל-מאגר נתונים, ולהפעיל מחדש חלק מהשאילתה כדי לחלץ סמן שמצביע על אמצע אצווה.

כדי להשתמש בסמן כדי לדפדף אחורה בתוצאות של שאילתה, יוצרים שאילתה הפוכה: 

# Set up.
q = Bar.query()
q_forward = q.order(Bar.key)
q_reverse = q.order(-Bar.key)

# Fetch a page going forward.
bars, cursor, more = q_forward.fetch_page(10)

# Fetch the same page going backward.
r_bars, r_cursor, r_more = q_reverse.fetch_page(10, start_cursor=cursor)

הפעלת פונקציה לכל ישות (מיפוי)

נניח שאתם צריכים לקבל את הישויות Account שמתאימות לישויות Message שהוחזרו על ידי שאילתה. אפשר לכתוב משהו כמו: 

message_account_pairs = []
for message in message_query:
    key = ndb.Key('Account', message.userid)
    account = key.get()
    message_account_pairs.append((message, account))

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

def callback(message):
    key = ndb.Key('Account', message.userid)
    account = key.get()
    return message, account

message_account_pairs = message_query.map(callback)
# Now message_account_pairs is a list of (message, account) tuples.

הגרסה הזו תפעל קצת יותר מהר מהלולאה הפשוטה for שמופיעה למעלה, כי אפשר לבצע בה כמה פעולות בו-זמנית. עם זאת, מכיוון שהקריאה get() call in callback() עדיין סינכרונית, השיפור לא משמעותי. כאן כדאי להשתמש בקבלת נתונים אסינכרונית.

GQL

‫GQL היא שפה דמוית SQL לאחזור ישויות או מפתחות מ-App Engine Datastore. התכונות של GQL שונות מאלה של שפת שאילתות למסד נתונים רלציוני מסורתי, אבל התחביר של GQL דומה לזה של SQL. התחביר של GQL מתואר בהפניה ל-GQL.

אפשר להשתמש ב-GQL כדי ליצור שאילתות. הפעולה הזו דומה ליצירת שאילתה עם Model.query(), אבל נעשה בה שימוש בתחביר GQL כדי להגדיר את מסנן השאילתה ואת הסדר. כדי להשתמש בו:

  • ndb.gql(querystring) מחזירה אובייקט Query (מאותו סוג שמוחזר על ידי Model.query()). כל השיטות הרגילות זמינות באובייקטים מסוג Query: fetch(), map_async(), filter(), וכו'.
  • ‫Model.gql(querystring) הוא קיצור של ndb.gql("SELECT * FROM Model " + querystring). בדרך כלל, querystring הוא נתיב כמו "WHERE prop1 > 0 AND prop2 = TRUE".
  • כדי להריץ שאילתות על מודלים שמכילים מאפיינים מובנים, אפשר להשתמש ב-foo.bar בתחביר GQL כדי להפנות למאפייני משנה.
  • ‫GQL תומכת בקישורי פרמטרים דומים ל-SQL. אפליקציה יכולה להגדיר שאילתה ואז לקשר אליה ערכים: 
    query = ndb.gql("SELECT * FROM Article WHERE stars > :1")
query2 = query.bind(3)
    או 
    query = ndb.gql("SELECT * FROM Article WHERE stars > :1", 3)

    הפעלת הפונקציה bind() של שאילתה מחזירה שאילתה חדשה, ולא משנה את השאילתה המקורית.

  • אם מחלקת המודל שלכם מבטלת את _get_kind() שיטת המחלקה, שאילתת ה-GQL שלכם צריכה להשתמש בסוג שמוחזר על ידי הפונקציה הזו, ולא בשם המחלקה.
  • אם מאפיין במודל שלכם מבטל את השם שלו (לדוגמה, foo = StringProperty('bar')), שאילתת GQL צריכה להשתמש בשם המאפיין שבוטל (בדוגמה, bar).

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

שגיאה מתרחשת כשמבצעים שאילתה לגבי מודל שלא יובא (או, באופן כללי יותר, שלא הוגדר).

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

ציון מגבלה או היסט בשאילתת fetch() מבטל את המגבלה או ההיסט שמוגדרים באמצעות הסעיפים OFFSET ו-LIMIT של GQL. אל תשלבו בין OFFSET ו-LIMIT של GQL לבין LIMIT. שימו לב שמגבלת 1,000 התוצאות שמוטלת על שאילתות ב-App Engine חלה גם על offset וגם על limit.fetch_page()

אם אתם רגילים ל-SQL, שימו לב לא להניח הנחות שגויות כשאתם משתמשים ב-GQL. שפת GQL מתורגמת ל-NDB's native query API. זה שונה ממיפוי אובייקטים יחסיים (ORM) רגיל (כמו SQLAlchemy או התמיכה במסד הנתונים של Django), שבו קריאות ה-API מתורגמות ל-SQL לפני שהן מועברות לשרת מסד הנתונים. שפת GQL לא תומכת בשינויים ב-Datastore (הוספות, מחיקות או עדכונים); היא תומכת רק בשאילתות.