Paginação por dados da tabela
Este documento descreve como percorrer os dados da tabela e os resultados da consulta usando a API REST do BigQuery.
Analisar os resultados usando a API
Em todos os métodos *collection*.list
são retornadas páginas de resultados sob certas circunstâncias. A propriedade maxResults
limita o número de resultados por página.
Método | Critérios de paginação | Valor padrão de maxResults |
Valor máximo de maxResults |
Valor máximo de maxFieldValues |
---|---|---|---|---|
tabledata.list |
Retorna resultados paginados se o tamanho da resposta tiver mais que
10 MB1 de dados ou mais que maxResults
linhas. |
Ilimitado | Ilimitado | Ilimitado |
Todos os outros métodos *collection*.list |
Retorna resultados paginados se a resposta tiver mais do que
maxResults linhas e também menos que os limites máximos. |
10.000 | Ilimitado | 300.000 |
Se o resultado for maior que o limite de bytes ou campos, o resultado será
cortado para se ajustar ao limite. Se uma linha for maior que o limite de bytes ou campos,
tabledata.list
pode retornar até 100 MB de dados1,
o que é consistente com o limite máximo de tamanho de linha para os resultados da consulta.
1O tamanho da linha é aproximado, porque ele é baseado na representação interna dos dados da linha. Esse limite é aplicado durante determinados estágios da execução do job de consulta.
jobs.getQueryResult
pode retornar 20 MB de dados, a menos que seja explicitamente
solicitado mais do que isso pelo suporte.
Cada página é um subconjunto do número total de linhas. Quando os resultados são compostos por
mais de uma página de dados, eles têm uma propriedade
pageToken
. 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 tabledata.list
,
usado para fazer a paginação dos dados da tabela, usa um valor de ajuste de linha ou
token de página. Consulte Como procurar dados da tabela
para mais informações.
Os exemplos a seguir demonstram paginação por meio de dados da Tabela do 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 mais informações, consulte a documentação de referência da API BigQuery em C#.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java 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 em Java.
Go
Antes de testar esta amostra, siga as instruções de configuração do Go 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 em Go.
Nas bibliotecas de cliente do Google Cloud para Go, a paginação dos resultados é feita automaticamente por padrão. Portanto, não é necessário implementá-la. Por exemplo:
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 mais informações, consulte a documentação de referência da API BigQuery Node.js.
Nas bibliotecas de cliente do Google Cloud para Node.js, a paginação dos resultados é feita automaticamente por padrão. Portanto, não é necessário implementá-la. Por exemplo:
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 mais informações, consulte a documentação de referência da API BigQuery PHP.
A paginação acontece automaticamente nas bibliotecas de cliente do Cloud para PHP
usando a função do gerador rows
, que busca a próxima página de
resultados durante a iteração.
Python
Antes de testar esta amostra, siga as instruções de configuração para Python 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 em Python.
Nas bibliotecas de cliente do Google Cloud para Python, a paginação dos resultados é feita automaticamente por padrão. Portanto, não é necessário implementá-la. Por exemplo:
Ruby
Antes de testar esta amostra, siga as instruções de configuração para 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 Ruby.
A paginação acontece automaticamente nas bibliotecas de cliente do Cloud para Ruby
usando Table#data
e Data#next
.
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
.
Cada 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 foi alterada desde a última
solicitação. Quando você fizer uma solicitação ao BigQuery com um valor de
ETag, o BigQuery compara o valor de ETag com o valor de ETag retornado pela
API e responde com base na correspondência dos valores de ETag. É possível usar ETags
para evitar chamadas de lista redundantes da seguinte maneira:
Para retornar valores de lista se os valores tiverem sido alterados.
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 corresponderem, o BigQuery retornará um código de status
HTTP 304 Not Modified
e nenhum valor. Um exemplo disso seria uma página da Web que os usuários periodicamente preenchem com informações armazenadas no BigQuery. Se não houver alterações nos seus dados, será possível evitar chamadas redundantes de lista ao BigQuery usando o cabeçalho if-none-match com ETags.Para retornar valores de lista se os valores não tiverem sido alterados.
Para retornar uma página de valores de lista se os valores não tiverem sido mudados, use o cabeçalho HTTP "if-match". O BigQuery fará a comparação dos 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.
Ver os resultados da consulta
Cada consulta é gravada em uma tabela de destino. Se nenhuma tabela de destino for fornecida, a API do BigQuery preencherá automaticamente a propriedade da tabela de destino com uma referência a uma tabela anônima temporária.
API
Leia o campo jobs.config.query.destinationTable
para determinar a tabela na qual os resultados da consulta foram gravados.
Chame tabledata.list
para ler os resultados da consulta.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java 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 em Java.
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 mais informações, consulte a documentação de referência da API BigQuery Node.js.
Python
O método QueryJob.result
retorna um iterável dos resultados da consulta. Como alternativa:
- Leia a propriedade
QueryJob.destination
. Se essa propriedade não estiver configurada, ela será definida pela API como uma referência a uma tabela anônima temporária. - Receba o esquema da tabela com o método
Client.get_table
. - Crie um iterável em todas as linhas na tabela de destino com o método
Client.list_rows
.
Antes de testar essa amostra, siga as instruções de configuração para Python 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 em Python.