逐頁瀏覽查詢結果

本文說明如何使用 BigQuery REST API 逐頁瀏覽查詢結果。

使用 API 逐頁瀏覽結果

在某些情況下,所有 collection.list 方法都會傳回分頁結果。每頁的結果數由 maxResults 屬性控管。

方法 分頁條件 maxResults 的預設值 maxResults 的上限值
Tabledata.list 如果回應大小超過 10 MB 的序列化 JSON 或超過 maxResults 個資料列,就會傳回分成數頁的結果。 100,000 100,000
所有其他 collection.list 方法 如果回應超過 maxResults 個資料列就傳回分成數頁的結果。 50 1,000

如果您將 maxResults 設為大於上述上限值,結果就會根據上限值分成數頁。

頁面是總資料列數的子集。如果您的結果有超過一頁的資料,結果資料就會有 pageToken 這個屬性。如要擷取下一頁的結果,請再次發出 list 呼叫,並加入憑證值做為名為「pageToken」的網址參數。

bigquery.tabledata.list 方法可用來分頁資料表資料,並使用資料列的偏移值或網頁憑證。如要瞭解詳細資訊,請參閱瀏覽資料表資料

下列範例示範分頁 bigquery 結果。

C#

在試行此示例之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 C# 設定說明進行操作。詳情請參閱 BigQuery C# API 參考說明文件

using Google.Api.Gax;
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
using System.Linq;

public class BigQueryBrowseTable
{
    public void BrowseTable(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        TableReference tableReference = new TableReference()
        {
            TableId = "shakespeare",
            DatasetId = "samples",
            ProjectId = "bigquery-public-data"
        };
        // Load all rows from a table
        PagedEnumerable<TableDataList, BigQueryRow> result = client.ListRows(
            tableReference: tableReference,
            schema: null
        );
        // Print the first 10 rows
        foreach (BigQueryRow row in result.Take(10))
        {
            Console.WriteLine($"{row["corpus"]}: {row["word_count"]}");
        }
    }
}

Java

在試行此示例之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件

TableId tableIdObject = TableId.of(datasetName, tableName);
// This example reads the result 100 rows per RPC call. If there's no need to limit the number,
// simply omit the option.
TableResult tableData =
    bigquery.listTableData(tableIdObject, TableDataListOption.pageSize(100));
for (FieldValueList row : tableData.iterateAll()) {
  // do something with the row
}

Go

在試行此示例之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件

根據預設,Go 專用的 Google Cloud 用戶端程式庫會自動進行分頁,因此您無須自行導入分頁程序,例如:

table := client.Dataset(datasetID).Table(tableID)
it := table.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Node.js

在試行此示例之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件

根據預設,Node.js 專用的 Google Cloud 用戶端程式庫會自動進行分頁,因此您無須自行導入分頁程序,例如:

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const datasetId = "my_dataset";
// const tableId = "my_table";

async function browseRows() {
  // Displays rows from "my_table" in "my_dataset".

  // Create a client
  const bigqueryClient = new BigQuery();

  // List rows in the table
  const [rows] = await bigqueryClient
    .dataset(datasetId)
    .table(tableId)
    .getRows();

  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

browseRows();

PHP

在試行此示例之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 PHP 設定說明進行操作。詳情請參閱 BigQuery PHP API 參考說明文件

PHP 適用的 Google Cloud 用戶端程式庫會透過產生器函式 rows 在疊代作業期間擷取下頁結果,藉此自動進行分頁。

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId   = 'The BigQuery table ID';
// $maxResults = 10;

$maxResults = 10;
$startIndex = 0;

$options = [
    'maxResults' => $maxResults,
    'startIndex' => $startIndex
];
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
$numRows = 0;
foreach ($table->rows($options) as $row) {
    print('---');
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, $value);
    }
    $numRows++;
}

Python

在試行此示例之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件

根據預設,Phthon 專用的 Google Cloud 用戶端程式庫會自動進行分頁,因此您無須自行導入分頁程序,例如:

# from google.cloud import bigquery
# client = bigquery.Client()

dataset_ref = client.dataset("samples", project="bigquery-public-data")
table_ref = dataset_ref.table("shakespeare")
table = client.get_table(table_ref)  # API call

# Load all rows from a table
rows = client.list_rows(table)
assert len(list(rows)) == table.num_rows

# Load the first 10 rows
rows = client.list_rows(table, max_results=10)
assert len(list(rows)) == 10

# Specify selected fields to limit the results to certain columns
fields = table.schema[:2]  # first two columns
rows = client.list_rows(table, selected_fields=fields, max_results=10)
assert len(rows.schema) == 2
assert len(list(rows)) == 10

# Use the start index to load an arbitrary portion of the table
rows = client.list_rows(table, start_index=10, max_results=10)

# Print row data in tabular format
format_string = "{!s:<16} " * len(rows.schema)
field_names = [field.name for field in rows.schema]
print(format_string.format(*field_names))  # prints column headers
for row in rows:
    print(format_string.format(*row))  # prints row data

Ruby

在試行此示例之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Ruby 設定說明進行操作。詳情請參閱 BigQuery Ruby API 參考說明文件

Ruby 適用的 Google Cloud 用戶端程式庫會透過 Table#dataData#next 自動進行分頁。

require "google/cloud/bigquery"

def browse_table
  bigquery = Google::Cloud::Bigquery.new project_id: "bigquery-public-data"
  dataset  = bigquery.dataset "samples"
  table    = dataset.table "shakespeare"

  # Load all rows from a table
  rows = table.data

  # Load the first 10 rows
  rows = table.data max: 10

  # Print row data
  rows.each { |row| puts row }
end

要求任意頁面,並避免多餘的清單呼叫作業

當您使用快取的「pageToken」值往前翻頁或跳到任意頁面時,頁面內的資料就有可能會因為最近瀏覽過而變更,不過這不一定會發生。為了避免發生這種情況,您可以使用 Etag 屬性。

每一個 collection.list 方法 (Tabledata 除外) 都會在結果內傳回「Etag」屬性。這個屬性是頁面的雜湊值,可用來驗證網頁在上次要求過後是否有變更。當您使用 Etag 值對 BigQuery 進行要求時,BigQuery 會將這個 Etag 值和 API 傳回的 ETag 值進行比較,如果這兩個 ETag 值相符的話,BigQuery 就會回應。您可以使用 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」結果。

備註:雖然 ETag 是避免進行多餘清單呼叫的好方法,不過您可以採用同樣方式來確定是否有任何已變更的物件。例如,您可以針對特定資料表執行 Get 要求,並使用 ETag 判斷資料表在傳回完整回應前是否有變更過。


本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁