將資料表中的資料分頁

本文說明如何使用 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 參考說明文件。

前往 GitHub 查看意見回饋


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 參考說明文件。

前往 GitHub 查看意見回饋

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 用戶端程式庫會自動進行分頁，因此您無須自行實作分頁程序，例如：

前往 GitHub 查看意見回饋

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 用戶端程式庫會自動進行分頁，因此您無須自行實作分頁程序，例如：

前往 GitHub 查看意見回饋


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

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

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

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

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

PHP

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

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

前往 GitHub 查看意見回饋

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 用戶端程式庫會自動進行分頁，因此您無須自行實作分頁程序，例如：

前往 GitHub 查看意見回饋

# 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#data 和 Data#next 自動進行分頁。

前往 GitHub 查看意見回饋

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 值是否相符來進行回應。您可以使用 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 判斷資料表在傳回完整回應前是否變更過。

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

上次更新：十月 14, 2019。

將資料表中的資料分頁

使用 API 逐頁瀏覽結果

C#

Java

Go

Node.js

PHP

Python

Ruby

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

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