使用分頁功能透過 BigQuery API 讀取資料
本文說明如何使用分頁功能,透過 BigQuery API 讀取資料表資料和查詢結果。
使用 API 逐頁瀏覽結果
在某些情況下,所有 *collection*.list
方法都會傳回分頁結果。maxResults
屬性會限制每頁的結果數。
方法 | 分頁條件 | 預設 maxResults 值 |
最大的 maxResults 值 |
最大的 maxFieldValues 值 |
---|---|---|---|---|
tabledata.list |
如果回應大小超過 10 MB1 的資料或超過 maxResults 個資料列,就會傳回分成數頁的結果。 |
無限制 | 無限制 | 無限制 |
所有其他 *collection*.list 方法 |
如果回應超過 maxResults 個資料列,但未達上限,就會傳回分成數頁的結果。 |
10,000 | 無限制 | 300,000 |
如果結果大於位元組或欄位限制,系統會將結果修剪至符合限制。如果某個資料列超過位元組或欄位限制,tabledata.list
最多可傳回 100 MB 的資料1,這與查詢結果的資料列大小上限一致。每頁沒有大小下限,有些頁面可能會傳回的資料列比其他頁面多。
1資料列大小為約略值,因為此大小是根據資料列資料的內部呈現方式而定。系統會在查詢工作執行作業的某些階段對資料列大小設定上限。
jobs.getQueryResults
最多可傳回 20 MB 的資料,除非您透過支援服務明確要求更多資料。
頁面是總列數的子集。如果您的結果有超過一頁的資料,結果資料就會有「pageToken」pageToken
這個屬性。如要擷取下一頁的結果,請再次發出 list
呼叫,並透過網址參數「pageToken」pageToken
提供代碼值。
tabledata.list
方法可用來將資料表資料分頁,並使用資料列的偏移值或網頁憑證。如要瞭解詳細資訊,請參閱瀏覽資料表資料一文。
疊代用戶端程式庫結果
Cloud 用戶端程式庫會處理 API 分頁的低階詳細資料,並提供類似迭代器的體驗,簡化與網頁回應中個別元素的互動。
下列範例示範如何逐頁瀏覽 BigQuery 資料表資料。
C#
在試行這個範例之前,請先按照 BigQuery 快速入門導覽課程:使用用戶端程式庫中的 C# 設定說明進行操作。詳情請參閱 BigQuery C# API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
在試行這個範例之前,請先按照 BigQuery 快速入門導覽課程:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
Go
在試行這個範例之前,請先按照 BigQuery 快速入門導覽課程:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
根據預設, Go 專用的 Cloud 用戶端程式庫會自動進行分頁,因此您無須自行實作分頁程序,例如:
Node.js
在試行這個範例之前,請先按照 BigQuery 快速入門導覽課程:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
根據預設,Node.js 適用的 Cloud 用戶端程式庫會自動進行分頁,因此您無須自行實作分頁程序,例如:
PHP
在試行這個範例之前,請先按照 BigQuery 快速入門導覽課程:使用用戶端程式庫中的 PHP 設定說明進行操作。詳情請參閱 BigQuery PHP API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
PHP 適用的 Cloud 用戶端程式庫會透過產生器函式 rows
在疊代作業期間擷取下一頁的結果,藉此自動進行分頁。
Python
在試行這個範例之前,請先按照 BigQuery 快速入門導覽課程:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
根據預設,Python 專用的 Cloud 用戶端程式庫會自動進行分頁,因此您無須自行實作分頁程序,例如:
Ruby
在試行這個範例之前,請先按照 BigQuery 快速入門導覽課程:使用用戶端程式庫中的 Ruby 設定說明進行操作。詳情請參閱 BigQuery Ruby API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
Ruby 適用的 Cloud 用戶端程式庫會透過 Table#data
和 Data#next
自動進行分頁。
要求任意頁面,並避免多餘的清單呼叫作業
當您使用快取的 pageToken
值往前翻頁或跳到任意頁面時,頁面內的資料就有可能會因為最近瀏覽過而變更,不過這不一定會發生。為了避免發生這種情況,您可以使用 etag
屬性。
每個 collection.list
方法 (Tabledata 除外) 都會在結果中傳回 etag
屬性。這個屬性是頁面結果的雜湊值,可用來驗證網頁在上次要求過後是否有變更。當您使用 ETag 值對 BigQuery 提出要求時,BigQuery 會將這個 ETag 值和 API 傳回的 ETag 值進行比較,並依這兩個 ETag 值是否相符來進行回應。您可以透過下列方式使用 ETag,避免進行多餘的清單呼叫:
在值有變更的情況下傳回清單值。
如果您只是想要在值有變更的情況下傳回一頁清單值,可以使用 HTTP "if-none-match" 標頭,藉由先前儲存的 ETag 進行清單呼叫。如果您提供的 ETag 與伺服器上的 ETag 不符,BigQuery 就會傳回一頁新的清單值。如果 ETag 相符,BigQuery 就會傳回
HTTP 304 Not Modified
狀態碼,而且不會傳回任何值。舉例來說,使用者可能會定期在某個網頁上輸入儲存在 BigQuery 內的資訊,這種情況就會發生。如果資料沒有變更,您可以使用 if-non-match 標頭和 ETag 來避免對 BigQuery 進行多餘的清單呼叫。在數值沒有變更的情況下傳回清單值。
如果您只是想要在清單值沒有變更的情況下傳回一頁清單值,可以使用 HTTP "if-match" 標頭。假使結果未曾變更,BigQuery 就會比對 ETag 值並傳回結果頁面,如果頁面已變更過,就會傳回 412「Precondition Failed」的結果。
逐頁瀏覽查詢結果
每項查詢都會寫入目的地資料表。如果未提供目的地資料表,BigQuery API 會自動在目的地資料表屬性中填入匿名暫時資料表的參照。
API
讀取 jobs.config.query.destinationTable
欄位,判斷查詢結果寫入的資料表。呼叫 tabledata.list
讀取查詢結果。
Java
在試行這個範例之前,請先按照 BigQuery 快速入門導覽課程:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
如要設定每頁傳回的資料列數量,請使用 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 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
QueryJob.result
方法會傳回查詢結果的可疊代項目。或者
- 請參閱
QueryJob.destination
屬性。如果未設定這項屬性,API 會將其設為臨時匿名資料表的參照。 - 使用
Client.get_table
方法取得資料表結構定義。 - 使用
Client.list_rows
方法,在目的地資料表的所有資料列中建立可疊代的項目。
在試行這個範例之前,請先按照 BigQuery 快速入門導覽課程:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。