שימוש בהחלפה בין דפים ב-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.
כל שיטה collection.list (חוץ מ-Tabledata) מחזירה מאפיין etag בתוצאה. המאפיין הזה הוא גיבוב של תוצאות הדף, שאפשר להשתמש בו כדי לוודא שהדף לא השתנה מאז הבקשה האחרונה. כששולחים בקשה ל-BigQuery עם ערך ETag, BigQuery משווה את ערך ה-ETag לערך ה-ETag שמוחזר על ידי ה-API ומגיב בהתאם להתאמה בין ערכי ה-ETag. אפשר להשתמש ב-ETag כדי להימנע מקריאות מיותרות לרשימה, באופן הבא:
- כדי להחזיר ערכים רק אם הם השתנו, צריך לבצע קריאה של רשימה עם ETag שאוחסן בעבר באמצעות הכותרת
If-None-Matchשל HTTP. אם ה-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גודל השורה הוא משוער, כי הגודל מבוסס על הייצוג הפנימי של נתוני השורה. מגבלת הגודל המקסימלית של שורה נאכפת בשלבים מסוימים של ביצוע משימת שאילתה.