使用 BigQuery API 進行分頁
本文說明如何使用 BigQuery API 搭配分頁功能,讀取大型資料集中的資料表資料和查詢結果。
BigQuery 會使用分頁功能,將大型資料集分成較小的區塊,稱為「頁面」。對大多數使用者而言,Cloud 用戶端程式庫會自動處理這項程序,但您也可以手動控制分頁,適用於網頁應用程式等特定用途。
使用自動分頁功能
Cloud 用戶端程式庫會處理 API 分頁的低階詳細資料,並提供類似迭代器的體驗。當您逐一查看結果時,程式庫會在需要時自動擷取下一頁資料。
下列範例示範如何自動逐一查看 BigQuery 資料表資料。
C#
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 C# 設定說明操作。詳情請參閱 BigQuery C# API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
Go
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 BigQuery Go API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
Java
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
Node.js
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Node.js 設定說明操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
PHP
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 PHP 設定說明操作。詳情請參閱 BigQuery PHP API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
Ruby
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Ruby 設定說明操作。詳情請參閱 BigQuery Ruby API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
控制頁面大小
您可以設定網頁大小,指定每個網路要求傳回的資料列數量上限。設定頁面大小有助於最佳化網路用量,或將資料放入記憶體。
在大多數用戶端程式庫中,呼叫 list_rows 或 query 等方法時,可以使用 max_results 或 page_size 參數。
使用網頁權杖手動分頁
手動分頁功能適用於無狀態應用程式,例如使用者點選「下一步」即可查看下一組結果的網路服務。在這個情境中,伺服器不會在要求之間維護有效的疊代器。
請改用網頁權杖,如下所示:
- 要求網頁。呼叫 API 並接收
pageToken參數和資料列。 - 繼續。在下一個要求中,將相同的
pageToken參數傳回 BigQuery,即可擷取下一個資料區塊。
下列範例說明如何擷取分頁符記,並用來擷取下一頁的查詢結果。
API
讀取 jobs.config.query.destinationTable 欄位,判斷查詢結果寫入的資料表。呼叫 tabledata.list 讀取查詢結果。
Java
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
如要設定每頁傳回的資料列數量,請使用 GetQueryResults 工作,並設定您傳入的 QueryResultsOption 物件的 pageSize 選項,如下列範例所示:
TableResult result = job.getQueryResults();
QueryResultsOption queryResultsOption = QueryResultsOption.pageSize(20);
TableResult result = job.getQueryResults(queryResultsOption);
Node.js
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Node.js 設定說明操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
Python
QueryJob.result 方法會傳回查詢結果的可疊代項目。或者
- 讀取
QueryJob.destination屬性。如果未設定這項屬性,API 會將其設為臨時匿名資料表的參照。 - 使用
Client.get_table方法取得資料表結構定義。 - 使用
Client.list_rows方法,在目的地資料表中的所有資料列上建立可疊代物件。
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
使用 ETag 進行最佳化
當您使用快取的 pageToken 值往前翻頁或跳到任意頁面時,頁面內的資料就有可能會因為最近瀏覽過而變更,為避免發生這種情況,您可以使用 etag 屬性。
每個 collection.list 方法 (Tabledata 除外) 都會在結果中傳回 etag 屬性。這個屬性是頁面結果的雜湊值,可用於驗證頁面自上次要求後是否有所變更。當您使用 ETag 值對 BigQuery 進行要求時,BigQuery 會將這個 ETag 值和 API 傳回的 ETag 值進行比較,並依這兩個 ETag 值是否相符來進行回應。您可以按照下列方式使用 ETag,避免多餘的清單呼叫:
- 如要只在值有變更時傳回值,請使用 HTTP
If-None-Match標頭,藉由先前儲存的 ETag 進行清單呼叫。如果 ETag 相符,BigQuery 會傳回HTTP 304 Not Modified狀態碼,且不會傳回任何資料,節省頻寬。 - 如要只在值未變更時傳回值,請使用 HTTP
If-Match標頭。如果頁面已變更,BigQuery 會傳回412 Precondition Failed。
參考資料:API 限制和條件
在某些情況下,所有 *collection*.list 方法都會傳回分頁結果。maxResults 屬性會限制每頁的結果數。
| 方法 | 分頁條件 | 預設 maxResults 限制 |
最多只能有 maxResults 個捷徑 |
最多只能有 maxFieldValues 個捷徑 |
|---|---|---|---|---|
tabledata.list |
如果回應大小超過 10 MB1 的資料或超過 maxResults 個資料列,就會傳回分成數頁的結果。 |
無限制 | 無限制 | 無限制 |
所有其他 *collection*.list 方法 |
如果回應超過 maxResults 個資料列,但未達上限,就會傳回分成數頁的結果。 |
10,000 | 無限制 | 300,000 |
如果結果超出位元組或欄位限制,系統會將結果截斷,以符合限制。如果單一資料列超出位元組或欄位限制,tabledata.list 方法最多可傳回 100 MB 的資料1,這與查詢結果的資料列大小上限一致。每個頁面沒有大小下限,因此部分頁面可能會傳回的資料列比其他頁面多。
除非您透過支援服務明確要求更多資料,否則 jobs.getQueryResults REST API 方法最多只會傳回 20 MB 的資料。
1資料列大小為約略值,因為此大小是根據資料列資料的內部呈現方式而定。系統會在查詢工作執行作業的某些階段對資料列大小設定上限。