אובייקט Query מייצג שאילתת NDB, בקשה לרשימה מסוננת וממוינת של ישויות.
בדף הזה מופיע מסמך עזר. לדיון כללי בשאילתות NDB, אפשר לעיין במאמר בנושא שאילתות.
אפשרויות שאילתה
הרבה שיטות לשאילתות מקבלות קבוצה סטנדרטית של אפשרויות נוספות, או בצורה של ארגומנטים של מילות מפתח כמו keys_only=True, או כאובייקט QueryOptions שמועבר עם options=QueryOptions(...).
יש מגוון אפשרויות הגדרה לשאילתות.
מציינים אותן באמצעות ארגומנטים של מילות מפתח לשיטות Query:
| ארגומנט | סוג | ברירת מחדל | תיאור |
|---|---|---|---|
| keys_only | bool | False | כל הפעולות מחזירות מפתחות במקום ישויות. |
| היטל | tuple (או רשימה) של מאפיינים (או מחרוזות) | None
| הפעולות מחזירות ישויות שמוגדרות בהן רק המאפיינים שצוינו.
projection=[Article.title, Article.date]
או projection=['title', 'date']
מאחזר ישויות שמוגדרים בהן רק שני השדות האלה.
(לעיון בשאילתות של תחזיות).
|
| לקזז | int | 0 | מספר תוצאות השאילתה שיש לדלג עליהן. |
| הגבלה | int | אין מגבלה | מספר התוצאות המקסימלי של שאילתה שיוחזרו. |
| batch_size | int | 20 | גודל האצווה. משפיע רק על יעילות השאילתות. אצוות גדולות יותר משתמשות ביותר זיכרון, אבל מבצעות פחות קריאות RPC. |
| prefetch_size | int | None | הפונקציה מחליפה את גודל האצווה עבור האצווה הראשונה שמוחזרת. |
| produce_cursors | bool | False
| יצירת סמני מיקום משאילתה (ראו Query Iterators). סמני מיקום של שאילתות). |
| start_cursor | Cursor | None
| נקודת התחלה לחיפוש (ראו סמני מיקום של שאילתות). |
| end_cursor | Cursor | None
| נקודת הסיום של החיפוש (ראו סמני מיקום של שאילתות). |
| מועד אחרון | int | תלוי ב-Context
| עוקף את מועד היעד של RPC (שברירת המחדל שלו היא 5 שניות אם הוא לא נעקף כשיוצרים את Context)
|
| read_policy | ndb.EVENTUAL_CONSISTENCY
| מדיניות הקריאה. הגדרה ל-ndb.EVENTUAL_CONSISTENCY מאפשרת לקבל תוצאות מהר יותר, בלי לחכות שמאגר הנתונים יחיל שינויים בהמתנה על כל הרשומות שמוחזרות.
|
כדי להריץ שאילתה עם קבוצה ספציפית של אפשרויות, מעבירים את ארגומנטי מילות המפתח לשיטה הרלוונטית:
qry = Employee.query().filter(...).order(...) # Create a query for acct in qry.fetch(10, offset=20): # Skip the first 20 print acct
לפעמים כדאי לשמור קבוצה של אפשרויות שאילתה ולהשתמש בהן במקומות שונים. אפשר פשוט לשמור אותן במילון ולהעביר את המילון הזה לשיטות באמצעות **kwds, אבל אפשר גם ליצור אובייקט QueryOptions ולהעביר אותו באמצעות ארגומנט מילת המפתח options.
שתי הדוגמאות הבאות שקולות:
qo = ndb.QueryOptions(keys_only=True, offset=20) results = qry.fetch(10, options=qo) results = qry.fetch(10, keys_only=True, offset=20)
Constructor
בדרך כלל, אפליקציה יוצרת Query על ידי קריאה ל-Model.query(). אבל אפשר גם להתקשר אל ndb.Query().
ארגומנטים
- kind
- מחרוזת אופציונלית של סוג. בדרך כלל השם של מחלקת ישויות.
- ancestor
- מפתח ישות אב אופציונלי.
- מסננים
- צומת אופציונלי שמייצג עץ של ביטויי סינון.
- הזמנות
- אובייקט אופציונלי
datastore_query.Order. - אפליקציה
- מזהה אפליקציה אופציונלי.
- namespace
- מרחב שמות אופציונלי. אם לא מציינים מרחב שמות, המערכת תשתמש במרחב השמות שמוגדר כברירת מחדל בזמן ההפעלה של השאילתה.
- projection
- רשימה או טאפל אופציונליים של נכסים להצגה.
- group_by
- רשימה או טאפל אופציונליים של מאפיינים לקיבוץ לפי.
- default_options
- אופציונלי
אובייקט
QueryOptionsשמכיל אפשרויות ברירת מחדל לשאילתה, שישמשו להרצת השאילתה.
Instance Methods
- filter(filter1, filter2, ...)
- מחזירה
Queryחדש עם מסננים נוספים שהוחלו. מקבלת ארגומנטים של מסננים כפי שמתואר בשאילתות.qry.filter(filter1).filter(filter2)שווה ל-qry.filter(filter1, filter2) - get(**q_options)
- מחזירה את תוצאת השאילתה הראשונה, אם יש כזו (אחרת
None). הפונקציה הזו דומה לקריאה שלq.fetch(1)ולהחזרה של הפריט הראשון ברשימת התוצאות.ארגומנטים
- **q_options
- כל הארגומנטים של מילות המפתח של אפשרויות השאילתה נתמכים.
- order(order1, order2, ...)
- מחזירה
Queryחדש עם סדר מיון נוסף. מקבלת ארגומנט אחד או יותר שהם מאפיינים או מאפיינים 'שליליים'. לדוגמה, כדי למיין משתמשים לפי גיל ולמיין משתמשים עם אותו גיל לפי שם, אפשר להשתמש במשהו כמוqry.order(-Account.birthday, Account.name) - bind(...values...)
- This function is for use with GQL queries that use parameter
bindings (
:1,:2, etc.) or named bindings (:foo,:bar, etc.). הוא מקשר את הערכים המועברים לפרמטרים.כדי לקשר פרמטרים, יכול להיות שתקראו למשהו כמו
qry.bind("USA", 49). כדי לקשר פרמטרים עם שמות, אפשר להפעיל פקודה כמוqry.bind(region = "USA", threshold = 49).הפונקציה מחזירה אובייקט
Queryחדש עם ערכי הפרמטרים שנקשרו. - count(limit=None, **q_options)
- הפונקציה מחזירה את מספר תוצאות השאילתה, עד למגבלה מסוימת.
הפונקציה מחזירה את אותה תוצאה כמו
len(q.fetch(limit)), אבל בצורה יעילה יותר.ארגומנטים
- limit
- מספר התוצאות המקסימלי שרוצים לספור
- **q_options
- כל האפשרויות של שאילתות, ארגומנטים של מילות מפתח ואפשרויות של הקשר נתמכות.
- count_async(limit, **q_options)
- סופרת באופן אסינכרוני את מספר תוצאות השאילתה, עד למגבלה מסוימת;
היא מחזירה
Futureשהתוצאה שלה היא מספר. זוהי הגרסה האסינכרונית של count(). - fetch(limit, **q_options)
- אחזור רשימה של תוצאות שאילתה, עד למגבלה מסוימת.
ארגומנטים
- limit
- מספר התוצאות המקסימלי שרוצים לספור
- **q_options
- כל הארגומנטים של מילות המפתח של אפשרויות השאילתה נתמכים.
- fetch_async(limit, **q_options)
- שליפת רשימה של תוצאות שאילתה באופן אסינכרוני, עד למגבלה מסוימת.
מחזירה
Futureשהתוצאה שלו היא רשימה של תוצאות. זוהי הגרסה האסינכרונית של fetch(). - fetch_page(page_size, **q_options)
- אחזור של 'דף' תוצאות. זו שיטה מיוחדת לשימוש בממשקי משתמש של דפדוף.
ארגומנטים
- page_size
- המספר המקסימלי של התוצאות שיוחזרו.
- **q_options
- כל הארגומנטים של מילות המפתח של אפשרויות השאילתה נתמכים.
(results, cursor, more):- results רשימה של תוצאות השאילתה
- cursor סמן שאילתה שמצביע על קבוצת התוצאות הבאה. אם אין יותר תוצאות, יכול להיות שהסמן יהיה
None. - more
boolשמציין אם יש (כנראה) תוצאות נוספות אחרי קבוצת התוצאות הזו. אםFalse, אין עוד תוצאות; אםTrue, כנראה שיש עוד תוצאות.
כדי לאחזר את הדף הבא, צריך להעביר את הסמן שמוחזר מקריאה אחת לקריאה הבאה באמצעות
start_cursor=cursor. דרך נפוצה היא להעביר את הסמן ללקוח באמצעותcursor.urlsafe()ולשחזר את הסמן הזה בבקשה הבאה באמצעותCursor(urlsafe=string). - fetch_page_async(page_size, **q_options)
- אחזור אסינכרוני של 'דף' תוצאות. זו הגרסה האסינכרונית של fetch_page().
- get_async(**q_options)
- מחזירה באופן אסינכרוני את תוצאת השאילתה הראשונה, אם יש כזו (אחרת
None). זו הגרסה האסינכרונית של get(). - iter(**q_options)
- Constructs and returns an iterator over the query.
ארגומנטים
- **q_options
- כל הארגומנטים של מילות המפתח של אפשרויות השאילתה נתמכים.
מחזירה אובייקט QueryIterator.
- map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- מיפוי של פונקציית קריאה חוזרת או של tasklet על תוצאות השאילתה. כלומר,
הפונקציה (או ה-tasklet) מוחלת על כל ישות בתוצאות השאילתה.
ארגומנטים
- callback
- פונקציה או tasklet שיחולו על כל תוצאה.
- pass_batch_into_callback
- אם
True, מתבצעת קריאה חוזרת עם ארגומנטים של פרטי אצווה, כמו שמתואר בהמשך. - merge_future
- מחלקת משנה
Futureאופציונלית; מידע נוסף מופיע בהמשך. - **q_options
- כל הארגומנטים של מילות המפתח של אפשרויות השאילתה נתמכים.
חתימת הקריאה החוזרת בדרך כלל מתבצעת קריאה חוזרת עם ישות כארגומנט. עם זאת, אם מצוין
keys_only=True, מתבצעת קריאה חוזרת עם Key. אם מצויןpass_batch_into_callback=True, מתבצעת קריאה חוזרת עם שלושה ארגומנטים: האצווה הנוכחית, האינדקס בתוך האצווה והישות אוKeyבאינדקס הזה. הקריאה החוזרת יכולה להחזיר כל מה שרוצים. אם הקריאה החוזרת היאNone, מניחים שמדובר בקריאה חוזרת פשוטה שמחזירה רק את הישות או המפתח שהועברו.אופציונלי
merge_futureהארגומנטmerge_futureהוא ארגומנט מתקדם שאפשר להשתמש בו כדי לשנות את האופן שבו תוצאות הקריאה החוזרת משולבות בערך ההחזרה הכולל שלmap(). כברירת מחדל, נוצרת רשימה של ערכי החזרה של הקריאה החוזרת. אפשר להחליף את ברירת המחדל באחת מכמה חלופות מיוחדות כדי לשנות את האופן שבו הערכים משולבים. אפשר לעיין בקוד המקור שלtasklets.MultiFutureכדי לראות את יישום ברירת המחדל ותיאור של הפרוטוקול שאובייקטmerge_futureצריך ליישם. חלופות מאותו מודול כוללות אתQueueFuture,SerialQueueFutureו-ReducingFuture.מחזירה רשימה של תוצאות כל הקריאות החוזרות. (אבל כדאי לעיין ב 'אופציונלי
merge_future' למעלה). היא מחזירה כשהשאילתה הסתיימה וכל הקריאות החוזרות הוחזרו. - map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- מיפוי אסינכרוני של פונקציית קריאה חוזרת או של tasklet על תוצאות השאילתה. זו הגרסה האסינכרונית של map().