Como usar a paginação com a API BigQuery
Neste documento, descrevemos como ler dados de tabela e resultados de consulta em grandes conjuntos de dados usando a paginação com a API BigQuery.
Com a paginação, o BigQuery divide um conjunto de dados grande em partes menores chamadas de páginas. Para a maioria dos usuários, as bibliotecas de cliente do Cloud processam esse processo automaticamente, mas também é possível controlar manualmente a paginação para casos de uso específicos, como aplicativos da Web.
Usar paginação automática
As bibliotecas de cliente do Cloud processam os detalhes de baixo nível da paginação da API e fornecem uma experiência semelhante à de iteração. Ao iterar pelos resultados, a biblioteca busca automaticamente a próxima página de dados quando necessário.
Os exemplos a seguir demonstram como iterar automaticamente pelos 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#.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
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.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
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.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
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 em Node.js.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
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 em PHP.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
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 mais informações, consulte a documentação de referência da API BigQuery em Python.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Ruby
Antes de testar esta amostra, 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 em Ruby.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Controlar o tamanho da página
É possível especificar o número máximo de linhas retornadas em cada solicitação de rede definindo um tamanho de página. Isso é útil para otimizar o uso da rede ou ajustar os dados à memória.
Na maioria das bibliotecas de cliente, é possível usar um parâmetro max_results ou page_size
ao chamar métodos como list_rows ou query.
Usar paginação manual com tokens de página
A paginação manual é útil para aplicativos sem estado, como um serviço da Web em que um usuário clica em Próxima para ver o próximo conjunto de resultados. Nesse cenário, o servidor não mantém um iterador ativo entre as solicitações.
Em vez disso, use um token de página da seguinte maneira:
- Solicite uma página.Chame a API e receba um parâmetro
pageTokenjunto com as linhas. - Retomar: na próxima solicitação, transmita o mesmo parâmetro
pageTokende volta ao BigQuery para recuperar o próximo bloco de dados.
Os exemplos a seguir mostram como recuperar um token de página e usá-lo para buscar a próxima página de resultados da consulta.
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.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Para definir o número de linhas retornadas em cada página, use um
job GetQueryResults e defina a
opção pageSize
do objeto QueryResultsOption que você transmite, conforme mostrado no
exemplo a seguir:
TableResult result = job.getQueryResults();
QueryResultsOption queryResultsOption = QueryResultsOption.pageSize(20);
TableResult result = job.getQueryResults(queryResultsOption);
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 em Node.js.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
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 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 mais informações, consulte a documentação de referência da API BigQuery em Python.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Antes de executar exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
Otimizar com ETags
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. Para evitar isso, use a propriedade etag.
Cada método collection.list (exceto 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 somente se eles tiverem sido alterados, faça uma chamada de lista com uma ETag armazenada anteriormente usando o cabeçalho HTTP
If-None-Match. Se as ETags coincidirem, o BigQuery retornará um código de statusHTTP 304 Not Modifiede nenhum dado, economizando largura de banda. - Para retornar valores somente se eles não tiverem sido alterados, use o cabeçalho HTTP
If-Match. O BigQuery retorna um412 Precondition Failedse a página tiver mudado.
Referência: limites e critérios da 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 | Limite padrão de maxResults |
Limite máximo de maxResults |
Limite 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,
o método 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.
Não há um tamanho mínimo por página, e algumas páginas podem retornar mais linhas do que outras.
O método jobs.getQueryResults da API REST pode retornar 20 MB de dados, a menos que você solicite mais explicitamente pelo suporte.
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.