Paginação por dados da tabela

Este documento descreve como percorrer os dados da tabela usando a API REST do BigQuery.

Como fazer paginação de resultados usando a API

Em todos os métodos collection.list, são retornadas páginas de resultados 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.	100.000	100.000
Todos os outros métodos `collection.list`	Páginas de resultados são retornadas quando há mais de `maxResults` linhas.	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 com base no valor máximo.

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

O método bigquery.tabledata.list, usado para fazer a paginação dos dados da tabela, usa um valor de ajuste de linha ou token de página. Para saber mais informações, consulte Dados da tabela de navegação.

Os exemplos a seguir demonstram paginação por meio de dados da tabela bigquery.

C#

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

Ver no GitHub Feedback


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 este exemplo, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API BigQuery Java.

Ver no GitHub Feedback

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 este exemplo, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API BigQuery Go.

Na biblioteca de cliente do Google Cloud para Go, a paginação dos resultados é feita automaticamente por padrão, por isso, não é necessário implementá-la, por exemplo:

Ver no GitHub Feedback

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 guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API BigQuery Node.js.

Na biblioteca de cliente do Google Cloud para Node.js, a paginação dos resultados é feita automaticamente por padrão, por isso, não é necessário implementá-la. Por exemplo:

Ver no GitHub Feedback


// 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

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

A paginação é feita automaticamente na biblioteca de cliente do Google Cloud para PHP com o uso da função geradora rows. A função busca a próxima página de resultados durante a iteração.

Ver no GitHub Feedback

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 Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API BigQuery Python.

Na biblioteca de cliente do Google Cloud para Python, a paginação dos resultados é feita automaticamente por padrão, por isso, não é necessário implementá-la. Por exemplo:

Ver no GitHub Feedback

# 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 este exemplo, siga as instruções de configuração do Ruby no Guia de 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.

A paginação é feita automaticamente na biblioteca de cliente do Google Cloud para Ruby com o uso do Table#data e Data#next.

Ver no GitHub Feedback

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 hash dos resultados da página que pode ser usado para verificar se a página sofreu alteração desde a última solicitação. Quando você faz uma solicitaçã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. É possível usar ETags para ajudar a evitar chamadas redundantes de lista das seguintes maneiras:

Para retornar valores da lista, em caso de alteração:
Para retornar uma página de valores de lista se os valores tiverem sido alterados, 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 corresponder à ETag no servidor, será 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. Um exemplo disso seria uma página da Web que os usuários periodicamente preenchem com informações armazenadas no BigQuery. É possível evitar que sejam feitas 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 valores de listas apenas se os valores não tiverem sido mudados:
Para retornar uma página de valores de lista se os valores não tiverem sido mudados, 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: as ETags são uma boa maneira de evitar chamadas redundantes de lista, mas é possível aplicar esses 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:

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.

Última atualização: Outubro 14, 2019.

Paginação por dados da tabela

Como fazer paginação de resultados usando a API

C#

Java

Go

Node.js

PHP

Python

Ruby

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

Enviar comentários sobre…