שימוש בהחלפה בין דפים ב-BigQuery API
במאמר הזה מוסבר איך לקרוא נתונים בטבלה ותוצאות של שאילתות במערכי נתונים גדולים באמצעות חלוקה לעמודים עם BigQuery API.
באמצעות חלוקה לעמודים, מערכת BigQuery מחלקת מערך נתונים גדול לחלקים קטנים יותר שנקראים עמודים. ברוב המקרים, ספריות הלקוח של Cloud מטפלות בתהליך הזה באופן אוטומטי, אבל אפשר גם לשלוט ידנית על חלוקה לעמודים במקרים ספציפיים כמו אפליקציות אינטרנט.
שימוש במספור עמודים אוטומטי
ספריות הלקוח ב-Cloud מטפלות בפרטים ברמה הנמוכה של חלוקת ה-API לדפים, ומספקות חוויה שדומה לשימוש באיטרטור. כשמבצעים איטרציה על התוצאות, הספרייה מאחזרת באופן אוטומטי את דף הנתונים הבא כשצריך.
בדוגמאות הבאות מוסבר איך לבצע איטרציה אוטומטית על נתונים בטבלה ב-BigQuery.
C#
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי C#הוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery C# API.
כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.
לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.
המשך
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Goהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Go API.
כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.
לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.
Java
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Javaהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Java API.
כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.
לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.
Node.js
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Node.jsהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Node.js API.
כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.
לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.
PHP
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי PHPהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery PHP API.
כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.
לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.
Python
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Python API.
כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.
לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.
Ruby
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Rubyהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Ruby API.
כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.
לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.
שליטה בגודל הדף
אפשר לציין את המספר המקסימלי של השורות שמוחזרות בכל בקשה לאחזור מהרשת על ידי הגדרת גודל הדף. הגדרת גודל הדף שימושית לאופטימיזציה של השימוש ברשת או להתאמת נתונים לזיכרון.
ברוב ספריות הלקוח, אפשר להשתמש בפרמטר max_results או page_size כשמפעילים שיטות כמו list_rows או query.
שימוש בהחלפה ידנית של דפים באמצעות טוקנים של דפים
החלוקה לדפים באופן ידני שימושית באפליקציות בלי שמירת מצב, כמו שירות אינטרנט שבו המשתמש לוחץ על הבא כדי לראות את קבוצת התוצאות הבאה. בתרחיש הזה, השרת לא שומר על איטרטור פעיל בין הבקשות.
במקום זאת, משתמשים בטוקן דף באופן הבא:
- בקשה של דף קוראים ל-API ומקבלים פרמטר
pageTokenיחד עם השורות. - הפעלה מחדש. בבקשה הבאה, מעבירים את אותו פרמטר
pageTokenבחזרה ל-BigQuery כדי לאחזר את הנתח הבא של הנתונים.
בדוגמאות הבאות אפשר לראות איך מאחזרים אסימון דף ומשתמשים בו כדי לאחזר את הדף הבא של תוצאות השאילתה.
API
קוראים את השדה jobs.config.query.destinationTable כדי לדעת לאיזו טבלה נכתבו תוצאות השאילתה.
מתקשרים אל tabledata.list כדי להקריא את תוצאות השאילתה.
Java
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Javaהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Java API.
כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.
לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.
כדי להגדיר את מספר השורות שיוחזרו בכל דף, משתמשים בGetQueryResults job ומגדירים את האפשרות pageSize של האובייקט QueryResultsOption שמעבירים, כמו בדוגמה הבאה:
TableResult result = job.getQueryResults();
QueryResultsOption queryResultsOption = QueryResultsOption.pageSize(20);
TableResult result = job.getQueryResults(queryResultsOption);
Node.js
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Node.jsהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Node.js API.
כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.
לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.
Python
השיטה
QueryJob.result
מחזירה אובייקט שאפשר לחזור עליו של תוצאות השאילתה. לחלופין,
- מומלץ לקרוא את הנכס
QueryJob.destination. אם לא מגדירים את המאפיין הזה, ה-API מגדיר אותו כהפניה לטבלה זמנית אנונימית. - אפשר לקבל את סכימת הטבלה באמצעות השיטה
Client.get_table. - יוצרים אובייקט שאפשר לחזור עליו (iterable) בכל השורות בטבלת היעד באמצעות השיטה
Client.list_rows.
לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonהוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery Python API.
כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.
לפני שמריצים דוגמאות קוד, צריך להגדיר את משתנה הסביבה GOOGLE_CLOUD_UNIVERSE_DOMAIN לערך s3nsapis.fr.
אופטימיזציה באמצעות ETags
כשמדפדפים אחורה או קופצים לדפים שרירותיים באמצעות ערכים במטמון pageToken
יכול להיות שהנתונים בדפים השתנו מאז הצפייה האחרונה בהם. כדי למנוע את התוצאה הזו, אפשר להשתמש במאפיין etag.
כל method collection.list (חוץ מ-Tabledata) מחזירה את המאפיין etag בתוצאה. המאפיין הזה הוא גיבוב של תוצאות הדף, שאפשר להשתמש בו כדי לבדוק אם הדף השתנה מאז הבקשה האחרונה. כששולחים בקשה ל-BigQuery עם ערך ETag, המערכת משווה את הערך הזה לערך ETag שמוחזר על ידי ה-API, ומגיבה בהתאם לתוצאת ההשוואה. כדי להימנע מקריאות מיותרות לרשימה, אפשר להשתמש ב-ETags באופן הבא:
- כדי להחזיר ערכים רק אם הם השתנו, מבצעים קריאה לרשימה עם ETag שנשמר בעבר באמצעות הכותרת HTTP
If-None-Match. אם ערכי ה-ETag זהים, BigQuery מחזיר קוד סטטוסHTTP 304 Not Modifiedבלי נתונים, וכך חוסך רוחב פס. - כדי להחזיר ערכים רק אם הם לא השתנו, משתמשים בכותרת HTTP
If-Match. BigQuery מחזיר412 Precondition Failedאם הדף השתנה.
הפניה: מגבלות וקריטריונים של API
כל השיטות *collection*.list מחזירות תוצאות עם מספור דפים בנסיבות מסוימות. המאפיין maxResults מגביל את מספר התוצאות בכל דף.
| Method | קריטריונים לעימוד | מגבלת ברירת מחדל של maxResults |
מגבלת maxResults |
מגבלת maxFieldValues |
|---|---|---|---|---|
tabledata.list |
הפונקציה מחזירה תוצאות עם עימוד אם גודל התגובה הוא יותר מ-10 MB1 של נתונים או יותר מ-maxResults שורות. |
ללא הגבלה | ללא הגבלה | ללא הגבלה |
כל שאר השיטות של *collection*.list |
הפונקציה מחזירה תוצאות עם חלוקה לדפים אם התשובה מכילה יותר מ-maxResults שורות וגם פחות מהמגבלות המקסימליות. |
10,000 | ללא הגבלה | 300,000 |
אם התוצאה גדולה מהמגבלה של הבייט או השדה, התוצאה נחתכת כדי להתאים למגבלה. אם שורה אחת גדולה ממגבלת הבייטים או השדות,
השיטה tabledata.list יכולה להחזיר עד 100 MB של נתונים1, בהתאם למגבלת הגודל המקסימלי של שורה בתוצאות של שאילתה.
אין גודל מינימלי לכל דף, ויכול להיות שדפים מסוימים יחזירו יותר שורות מאחרים.
שיטת ה-API בארכיטקטורת REST jobs.getQueryResults יכולה להחזיר 20 MB של נתונים, אלא אם מבקשים במפורש יותר נתונים דרך התמיכה.
1גודל השורה הוא משוער, כי הגודל מבוסס על הייצוג הפנימי של נתוני השורה. מגבלת הגודל המקסימלי של שורה נאכפת בשלבים מסוימים של ביצוע משימת שאילתה.