쿼리 결과 페이징

이 문서는 BigQuery REST API를 사용하여 쿼리 결과를 페이징하는 방법을 설명합니다.

API를 사용하여 결과 페이징

모든 collection.list 메소드는 특정한 상황에서 페이지를 매긴 결과를 반환합니다. 페이지당 결과 수는 maxResults 속성으로 제어됩니다.

메소드 페이지 매김 기준 maxResults 기본값 maxResults 최대값
Tabledata.list 응답 크기가 10MB의 직렬화된 JSON보다 크거나 maxResults 행보다 많은 경우, 페이지를 매긴 결과를 반환합니다. 100,000 100,000
다른 모든 collection.list 메소드 응답이 maxResults 행보다 많은 경우 페이지를 매긴 결과를 반환합니다. 50 1,000

maxResults를 위에 나열된 최대값보다 큰 값으로 설정하면 최대값을 기준으로 결과에 페이지가 매겨집니다.

페이지는 전체 행 수의 하위 집합입니다. 결과 데이터가 한 페이지를 넘는 경우 결과 데이터에 pageToken 속성이 생깁니다. 결과의 다음 페이지를 가져오려면 list를 다시 호출하고, 토큰 값을 pageToken 이름의 URL 매개변수로 포함합니다.

테이블 데이터에 페이지를 매기는 데 사용되는 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"]}");
        }
    }
}

자바

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 BigQuery 빠른 시작의 자바 설정 안내를 따르세요. 자세한 내용은 BigQuery 자바 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 클라이언트 라이브러리는 기본적으로 자동 페이지 매김을 수행하므로 사용자가 직접 페이지 매김을 구현할 필요가 없습니다. 예를 들면 다음과 같습니다.

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

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

// Creates a client
const bigquery = new BigQuery({
  projectId: projectId,
});

// Lists rows in the table
bigquery
  .dataset(datasetId)
  .table(tableId)
  .getRows()
  .then(results => {
    const rows = results[0];
    console.log('Rows:');
    rows.forEach(row => console.log(row));
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

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 참조 문서를 확인하세요.

# 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

임의 페이지 요청 및 list 중복 호출 방지

페이지를 뒤로 이동하거나 캐시된 pageToken 값을 사용하여 임의의 페이지로 건너뛸 경우, 페이지를 마지막으로 본 이후 데이터가 변경되었다는 명확한 징후는 없지만 페이지의 데이터가 변경되었을 수 있습니다. Etag 속성을 사용하여 이 문제를 완화할 수 있습니다.

모든 collection.list 메소드(Tabledata 제외)는 결과에 Etag 속성을 반환합니다. 이 속성은 마지막 요청 이후 페이지가 변경되었는지 여부를 확인하는 데 사용할 수 있는 페이지 결과의 해시입니다. Etag 값을 사용하여 BigQuery에 요청하면 BigQuery는 Etag 값을 API가 반환한 ETag 값과 비교하고 ETag 값의 일치 여부에 따라 응답합니다. ETag를 사용하면 다음과 같은 방법으로 list 중복 호출을 방지할 수 있습니다.

  • 값이 변경된 경우에만 list 값을 반환하려는 경우:

    값이 변경된 경우에만 한 페이지 분량의 list 값을 반환하려는 경우, HTTP 'if-none-match' 헤더를 사용하여 이전에 저장된 ETag로 list를 호출할 수 있습니다. 제공한 ETag가 서버의 ETag와 일치하지 않으면 BigQuery는 한 페이지 분량의 새로운 list 값을 반환합니다. ETag가 일치하면 BigQuery는 HTTP 304 'Not Modified(수정되지 않음)' 결과를 값 없이 반환합니다. 사용자가 BigQuery에 저장된 정보를 주기적으로 채울 수 있는 웹페이지가 이러한 예에 해당합니다. 데이터가 변경되지 않은 경우, ETag와 if-none-match 헤더를 사용하면 BigQuery에 대한 list 중복 호출을 방지할 수 있습니다.

  • 값이 변경되지 않은 경우에만 list 값을 반환하려는 경우:

    list 값이 변경되지 않은 경우에만 한 페이지 분량의 list 값을 반환하려는 경우, HTTP 'if-match' 헤더를 사용할 수 있습니다. BigQuery는 ETag 값을 비교하여 결과가 변경되지 않은 경우에 결과 페이지를 반환하고, 페이지가 변경된 경우에는 412 '전제 조건 미충족' 결과를 반환합니다.

참고: ETag는 list 중복 호출을 피할 수 있는 훌륭한 방법이며, 동일한 메소드를 적용하여 객체의 변경 여부도 확인할 수 있습니다. 예를 들어 특정 테이블에 대해 Get 요청을 수행하고 ETag를 사용하여 전체 응답을 반환하기 전에 테이블이 변경되었는지 확인할 수 있습니다.


이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

도움이 필요하시나요? 지원 페이지를 방문하세요.