אובייקט Query מייצג שאילתת NDB, בקשה לרשימה מסוננת וממוינת של ישויות.
הדף הזה מכיל מאמרי עזרה. לדיון כללי על שאילתות NDB, ראו Queries.
אפשרויות שאילתה
הרבה שיטות לשאילתות מקבלות קבוצה סטנדרטית של אפשרויות נוספות, או בצורה של ארגומנטים של מילות מפתח כמו 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)
- Asynchronously returns the first query result, if any
(otherwise
None). This is the asynchronous version of get(). - iter(**q_options)
- יוצר איטרטור על השאילתה ומחזיר אותו.
ארגומנטים
- **q_options
- כל הארגומנטים של מילות המפתח של אפשרויות השאילתה נתמכים.
מחזירה אובייקט QueryIterator.
- map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- מיפוי של פונקציית קריאה חוזרת או של tasklet על תוצאות השאילתה. כלומר,
הפונקציה (או ה-tasklet) מוחלת על כל ישות בתוצאות השאילתה.
ארגומנטים
- callback
- פונקציה או tasklet שיחולו על כל תוצאה.
- pass_batch_into_callback
- If
True, calls the callback with batch information arguments as described below. - merge_future
- אופציונלי
Futureמחלקת משנה; ראו בהמשך. - **q_options
- כל הארגומנטים של מילות המפתח של אפשרויות השאילתה נתמכים.
חתימת הקריאה החוזרת הקריאה החוזרת מופעלת בדרך כלל עם ישות כארגומנט. עם זאת, אם מצוין
keys_only=True, הפונקציה נקראת עם Key. אם מציינים אתpass_batch_into_callback=True, הקריאה החוזרת מתבצעת עם שלושה ארגומנטים: האצווה הנוכחית, האינדקס בתוך האצווה והישות אוKeyבאינדקס הזה. הפונקציה להחזרת קריאה יכולה להחזיר כל ערך שרוצים. אם הקריאה החוזרת היאNone, מניחים שמדובר בקריאה חוזרת פשוטה שמחזירה רק את הישות או המפתח שהועברו.אופציונלי
merge_futureהארגומנטmerge_futureהוא ארגומנט מתקדם שאפשר להשתמש בו כדי לשנות את אופן השילוב של תוצאות הקריאה החוזרת בערך ההחזרה הכוללmap(). כברירת מחדל, נוצרת רשימה של ערכים שמוחזרים מפונקציות callback. אפשר להחליף את אחת מתוך מספר קטן של חלופות מיוחדות כדי להסדיר את העניין. אפשר לעיין בקוד המקור שלtasklets.MultiFutureכדי לראות את הטמעת ברירת המחדל ואת תיאור הפרוטוקול שאובייקטmerge_futureצריך להטמיע. חלופות מאותו מודול כוללות אתQueueFuture,SerialQueueFutureו-ReducingFuture.הפונקציה מחזירה רשימה של התוצאות של כל הקריאות החוזרות (callback). (אבל אפשר לעיין בקטע 'אפשרויות
merge_future' למעלה). הפונקציה מחזירה ערך כשהשאילתה מסתיימת וכל הקריאות החוזרות מסתיימות. - map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- מיפוי אסינכרוני של פונקציית קריאה חוזרת או של tasklet על תוצאות השאילתה. זו הגרסה האסינכרונית של map().