Como paginar resultados da consulta

Este documento descreve como percorrer os resultados da consulta usando a API REST do BigQuery.

Como percorrer resultados usando a API

Todos os métodos collection.list retornam resultados paginados sob certas circunstâncias. O número de resultados por página é controlado pela propriedade maxResults.

Método Critérios de paginação Valor padrão de maxResults Valor máximo de maxResults
Tabledata.list Páginas de resultados são retornadas quando há mais de 10 MB de dados JSON serializados ou mais de maxResults linhas na resposta. 100.000 100.000
Todos os outros métodos collection.list Páginas de resultados são retornadas quando há mais de maxResults linhas na resposta. 50 1.000

Se você define maxResults como um valor maior do que o máximo listado acima, os resultados são exibidos em páginas respeitando o valor máximo.

Cada página é um subconjunto do número total de linhas. Quando há mais de uma página de resultados, é incluída a propriedade pageToken nos dados. Para recuperar a próxima página de resultados, faça outra chamada list e inclua o valor do token como um parâmetro de URL chamado pageToken.

No método bigquery.tabledata.list usado para percorrer os dados da tabela, há um valor de equidistância de linha ou token de página. Consulte Como procurar dados da tabela para mais informações.

Nos exemplos a seguir, vemos como percorrer resultados do BigQuery.

C#

Antes de testar esta amostra, siga as instruções de configuração do C# no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do BigQuery para C#.

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

Antes de testar esta amostra, siga as instruções de configuração do Java no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do BigQuery para Java.

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

Antes de testar esta amostra, siga as instruções de configuração do Go no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery para Go.

Na biblioteca de cliente do Google Cloud para Go, os resultados são percorridos automaticamente por padrão, então não é necessário implementar a paginação. Por exemplo:

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

Antes de testar esta amostra, siga as instruções de configuração do Node.js no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery para Node.js.

Na biblioteca de cliente do Google Cloud para Node.js, os resultados são percorridos automaticamente por padrão, então não é necessário implementar a paginação. Por exemplo:

// 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});

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

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

PHP

Antes de testar esta amostra, siga as instruções de configuração do PHP no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery para PHP.

Na biblioteca de cliente do Google Cloud para PHP, a paginação é automática com o uso da função geradora rows, que busca a próxima página de resultados durante a iteração.

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

Antes de testar esta amostra, siga as instruções de configuração do Python no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do BigQuery para Python.

Na biblioteca de cliente do Google Cloud para Python, os resultados são percorridos automaticamente por padrão, então não é necessário implementar a paginação. Por exemplo:

# 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

Antes de testar esta amostra, siga as instruções de configuração do Ruby no Início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery para Ruby.

Na biblioteca de cliente do Google Cloud para Ruby a paginação é automática com o uso de Table#data e Data#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

Como solicitar páginas arbitrárias e evitar chamadas de lista redundantes

Quando você volta ou avança para uma página arbitrária usando os valores de pageToken em cache, os dados exibidos nas suas páginas talvez não sejam os mesmos visualizados no último acesso, mas não há uma indicação clara disso. Para minimizar esse problema, use a propriedade Etag.

Todo método collection.list (exceto para Tabledata) retorna uma propriedade Etag no resultado. Essa propriedade é um resumo dos resultados da página que pode ser usado para verificar se a página sofreu alteração desde a última vez que você fez uma solicitação. Quando você faz uma requisição ao BigQuery com um valor de Etag, o BigQuery compara esse valor de Etag com a ETag retornado pela API e responde se os valores coincidem. Você pode usar ETags para ajudar a evitar chamadas redundantes de lista das seguintes maneiras:

  • Para retornar valores da lista, em caso de alteração:

    Faça uma chamada de lista com uma ETag armazenada anteriormente usando o cabeçalho HTTP "if-none-match". Se a ETag fornecida não corresponde à Etag no servidor, é retornada uma página dos novos valores da lista no BigQuery. Se as ETags coincidirem, o BigQuery retornará uma mensagem HTTP 304 "Não modificado" e nenhum valor na lista. Um exemplo disso seria uma página da Web que os usuários periodicamente preenchem com informações armazenadas no BigQuery. Você pode evitar fazer chamadas redundantes de lista ao BigQuery se não existirem alterações nos dados usando o cabeçalho if-none-match com ETags.

  • Para retornar listas apenas se os valores não tiverem mudado:

    Para retornar uma página de valores de lista apenas se os valores não tiverem mudado, use o cabeçalho HTTP "if-none-match". O BigQuery comparará os valores de ETag e retornará a página de resultados se os valores não tiverem mudado ou retornará um resultado 412 "Pré-requisito falhou" se a página tiver mudado.

Observação: embora as ETags sejam uma boa maneira de evitar chamadas redundantes de lista, você pode aplicar estes mesmos métodos para identificar se houve alteração em quaisquer objetos. Por exemplo, é possível realizar uma solicitação "Get" de uma tabela específica e usar ETags para determinar se a tabela foi modificada antes de retornar a resposta completa.


Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.