שאילתות NDB

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

סקירה כללית

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

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 כדי לגלות מתי בניית האינדקסים הסתיימה.

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

בנוסף לאופרטורים המובנים, ה-API תומך באופרטור !=, שמשלב קבוצות של מסננים באמצעות הפעולה הבוליאנית OR, ובפעולה IN, שבודקת שוויון לאחד מהערכים האפשריים ברשימה (כמו האופרטור 'in' של Python). הפעולות האלה לא ממופות באופן ישיר לפעולות המקוריות של 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'])

אבל הדוגמה הזו לא תיכלל:

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 של כמה AND שמוחל על האופרנדים המקוריים של AND, עם אופרנד יחיד של OR שמוחלף באופרנד המקורי של OR. לדוגמה: AND(a, b, OR(c, d)) שווה ל- OR(AND(a, b, c), AND(a, b, d))
  3. אופרטור AND שיש לו אופרנד שהוא בעצמו פעולת AND יכול לכלול את האופרנדים של AND המקונן בתוך AND המקיף. לדוגמה, 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() עשויה להפעיל קריאה חוסמת ל-Datastore, ולהפעיל מחדש חלק מהשאילתה כדי לחלץ סמן שמצביע על אמצע אצווה.

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

# 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 לבין fetch_page() שימו לב שמגבלת 1,000 התוצאות שמוטלת על שאילתות ב-App Engine חלה גם על offset וגם על limit.

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