Execute uma consulta
Este documento mostra como executar uma consulta no BigQuery e compreender a quantidade de dados que a consulta vai processar antes da execução através de uma execução de teste.
Tipos de consultas
Pode consultar dados do BigQuery usando um dos seguintes tipos de tarefas de consulta:
Tarefas de consulta interativas. Por predefinição, o BigQuery executa consultas como tarefas de consulta interativas, que se destinam a começar a ser executadas o mais rapidamente possível.
Tarefas de consulta em lote. As consultas em lote têm uma prioridade inferior à das consultas interativas. Quando um projeto ou uma reserva usa todos os recursos de computação disponíveis, é mais provável que as consultas em lote sejam colocadas em fila e permaneçam na fila. Depois de iniciar uma consulta em lote, esta é executada da mesma forma que uma consulta interativa. Para mais informações, consulte filas de consultas.
Tarefas de consulta contínuas. Com estes trabalhos, a consulta é executada continuamente, o que lhe permite analisar os dados recebidos no BigQuery em tempo real e, em seguida, escrever os resultados numa tabela do BigQuery ou exportá-los para o Bigtable ou o Pub/Sub. Pode usar esta capacidade para realizar tarefas sensíveis ao tempo, como criar e agir imediatamente com base em estatísticas, aplicar inferência de aprendizagem automática (AA) em tempo real e criar pipelines de dados orientados por eventos.
Pode executar tarefas de consulta através dos seguintes métodos:
- Componha e execute uma consulta na Google Cloud consola.
- Execute o comando
bq queryna ferramenta de linhas de comando bq. - Chame programaticamente o método
jobs.queryoujobs.insertna API REST do BigQuery. - Use as bibliotecas cliente do BigQuery.
O BigQuery guarda os resultados da consulta numa tabela temporária (predefinição) ou numa tabela permanente. Quando especifica uma tabela permanente como a tabela de destino dos resultados, pode escolher se quer acrescentar ou substituir uma tabela existente, ou criar uma nova tabela com um nome único.
Funções necessárias
Para receber as autorizações de que precisa para executar uma tarefa de consulta, peça ao seu administrador para lhe conceder as seguintes funções de IAM:
-
Utilizador de tarefas do BigQuery (
roles/bigquery.jobUser) no projeto. -
Visualizador de dados do BigQuery (
roles/bigquery.dataViewer) em todas as tabelas e vistas a que a sua consulta faz referência. Para consultar visualizações, também precisa desta função em todas as tabelas e visualizações subjacentes. Se estiver a usar vistas autorizadas ou conjuntos de dados autorizados, não precisa de acesso aos dados de origem subjacentes.
Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.
Estas funções predefinidas contêm as autorizações necessárias para executar uma tarefa de consulta. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:
Autorizações necessárias
São necessárias as seguintes autorizações para executar uma tarefa de consulta:
-
bigquery.jobs.createno projeto a partir do qual a consulta está a ser executada, independentemente de onde os dados estão armazenados. -
bigquery.tables.getDataem todas as tabelas e vistas a que a sua consulta faz referência. Para consultar visualizações, também precisa desta autorização em todas as tabelas e visualizações subjacentes. Se estiver a usar vistas autorizadas ou conjuntos de dados autorizados, não precisa de acesso aos dados de origem subjacentes.
Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.
Resolução de problemas
Access Denied: Project [project_id]: User does not have bigquery.jobs.create
permission in project [project_id].
Este erro ocorre quando um principal não tem autorização para criar tarefas de consulta no projeto.
Resolução: um administrador tem de lhe conceder a autorização bigquery.jobs.create no projeto que está a consultar. Esta autorização é necessária
além de qualquer autorização necessária para aceder aos dados consultados.
Para mais informações sobre as autorizações do BigQuery, consulte o artigo Controlo de acesso com a IAM.
Execute uma consulta interativa
Para executar uma consulta interativa, selecione uma das seguintes opções:
Consola
Aceda à página do BigQuery.
Clique em Consulta SQL.
No editor de consultas, introduza uma consulta GoogleSQL válida.
Por exemplo, consulte o conjunto de dados públicos do BigQuery
usa_namespara determinar os nomes mais comuns nos Estados Unidos entre os anos de 1910 e 2013:SELECT name, gender, SUM(number) AS total FROM `bigquery-public-data.usa_names.usa_1910_2013` GROUP BY name, gender ORDER BY total DESC LIMIT 10;Em alternativa, pode usar o painel de referência para criar novas consultas.
Opcional: para apresentar automaticamente sugestões de código quando escreve uma consulta, clique em Mais e, em seguida, selecione Preenchimento automático de SQL. Se não precisar de sugestões de preenchimento automático, desmarque a opção Preenchimento automático de SQL. Esta ação também desativa as sugestões de preenchimento automático do nome do projeto.
Opcional: para selecionar definições de consulta adicionais, clique em Mais e, de seguida, clique em Definições de consulta.
Clique em Executar.
Se não especificar uma tabela de destino, a tarefa de consulta escreve o resultado numa tabela temporária (cache).
Agora, pode explorar os resultados da consulta no separador Resultados do painel Resultados da consulta.
Opcional: para ordenar os resultados da consulta por coluna, clique em Abrir menu de ordenação junto ao nome da coluna e selecione uma ordem de ordenação. Se os bytes estimados processados para a ordenação forem superiores a zero, o número de bytes é apresentado na parte superior do menu.
Opcional: para ver a visualização dos resultados da consulta, aceda ao separador Visualização. Pode aumentar ou diminuir o zoom do gráfico, transferir o gráfico como um ficheiro PNG ou ativar/desativar a visibilidade da legenda.
No painel Configuração da visualização, pode alterar o tipo de visualização e configurar as métricas e as dimensões da visualização. Os campos neste painel são pré-preenchidos com a configuração inicial inferida do esquema da tabela de destino da consulta. A configuração é preservada entre as execuções de consultas seguintes no mesmo editor de consultas.
Para visualizações de linhas, barras ou dispersão, as dimensões suportadas são os tipos de dados
INT64,FLOAT64,NUMERIC,BIGNUMERIC,TIMESTAMP,DATE,DATETIME,TIMEeSTRING, enquanto as medidas suportadas são os tipos de dadosINT64,FLOAT64,NUMERICeBIGNUMERIC.Se os resultados da sua consulta incluírem o tipo
GEOGRAPHY, o tipo de visualização predefinido é Mapa, que lhe permite visualizar os resultados num mapa interativo.Opcional: no separador JSON, pode explorar os resultados da consulta no formato JSON, em que a chave é o nome da coluna e o valor é o resultado dessa coluna.
bq
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Use o comando
bq query. No exemplo seguinte, a flag--use_legacy_sql=falsepermite-lhe usar a sintaxe do GoogleSQL.bq query \ --use_legacy_sql=false \ 'QUERY'
Substitua QUERY por uma consulta GoogleSQL válida. Por exemplo, consulte o conjunto de dados público do BigQuery
usa_namespara determinar os nomes mais comuns nos Estados Unidos entre 1910 e 2013:bq query \ --use_legacy_sql=false \ 'SELECT name, gender, SUM(number) AS total FROM `bigquery-public-data.usa_names.usa_1910_2013` GROUP BY name, gender ORDER BY total DESC LIMIT 10;'A tarefa de consulta escreve o resultado numa tabela temporária (cache).
Opcionalmente, pode especificar a tabela de destino e a localização para os resultados da consulta. Para escrever os resultados numa tabela existente, inclua a flag adequada para anexar (
--append_table=true) ou substituir (--replace=true) a tabela.bq query \ --location=LOCATION \ --destination_table=TABLE \ --use_legacy_sql=false \ 'QUERY'
Substitua o seguinte:
LOCATION: a região ou a multirregião da tabela de destinos, por exemplo,
USNeste exemplo, o conjunto de dados
usa_namesé armazenado na localização multirregional dos EUA. Se especificar uma tabela de destino para esta consulta, o conjunto de dados que contém a tabela de destino também tem de estar na multirregião dos EUA. Não pode consultar um conjunto de dados numa localização e escrever os resultados numa tabela noutra localização.Pode definir um valor predefinido para a localização através do ficheiro.bigqueryrc.
TABLE: um nome para a tabela de destino, por exemplo,
myDataset.myTableSe a tabela de destino for uma tabela nova, o BigQuery cria a tabela quando executa a consulta. No entanto, tem de especificar um conjunto de dados existente.
Se a tabela não estiver no seu projeto atual, adicione o Google Cloud ID do projeto usando o formato
PROJECT_ID:DATASET.TABLE, por exemplo,myProject:myDataset.myTable. Se--destination_tablenão for especificado, é gerada uma tarefa de consulta que escreve o resultado numa tabela temporária.
- Inicie o Cloud Shell.
-
Defina o Google Cloud projeto predefinido onde quer aplicar as suas configurações do Terraform.
Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
As variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.
-
No Cloud Shell, crie um diretório e um novo ficheiro nesse diretório. O nome do ficheiro tem de ter a extensão
.tf, por exemplo,main.tf. Neste tutorial, o ficheiro é denominadomain.tf.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
Se estiver a seguir um tutorial, pode copiar o código de exemplo em cada secção ou passo.
Copie o exemplo de código para o ficheiro
main.tfcriado recentemente.Opcionalmente, copie o código do GitHub. Isto é recomendado quando o fragmento do Terraform faz parte de uma solução completa.
- Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
- Guarde as alterações.
-
Inicialize o Terraform. Só tem de fazer isto uma vez por diretório.
terraform init
Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção
-upgrade:terraform init -upgrade
-
Reveja a configuração e verifique se os recursos que o Terraform vai criar ou
atualizar correspondem às suas expetativas:
terraform plan
Faça correções à configuração conforme necessário.
-
Aplique a configuração do Terraform executando o seguinte comando e introduzindo
yesno comando:terraform apply
Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).
- Abra o seu Google Cloud projeto para ver os resultados. Na Google Cloud consola, navegue para os seus recursos na IU para se certificar de que o Terraform os criou ou atualizou.
Terraform
Use o
google_bigquery_job recurso.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
O exemplo seguinte executa uma consulta. Pode obter os resultados da consulta vendo os detalhes da tarefa:
Para aplicar a configuração do Terraform num Google Cloud projeto, conclua os passos nas secções seguintes.
Prepare o Cloud Shell
Prepare o diretório
Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz).
Aplique as alterações
API
Para executar uma consulta através da API, insira uma nova tarefa
e preencha a propriedade de configuração da tarefa query. Opcionalmente, especifique a sua localização na propriedade location na secção jobReference do recurso de trabalho.
Sonde os resultados chamando
getQueryResults.
A sondagem até jobComplete é igual a true. Verifique se existem erros e avisos na
errors lista.
C#
Antes de experimentar este exemplo, siga as C#instruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API C# BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Ir
Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Java
Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Para executar uma consulta com um proxy, consulte o artigo Configurar um proxy.
Node.js
Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
PHP
Antes de experimentar este exemplo, siga as PHPinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API PHP BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Python
Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Ruby
Antes de experimentar este exemplo, siga as Rubyinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Ruby BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Execute uma consulta em lote
Para executar uma consulta em lote, selecione uma das seguintes opções:
Consola
Aceda à página do BigQuery.
Clique em Consulta SQL.
No editor de consultas, introduza uma consulta GoogleSQL válida.
Por exemplo, consulte o conjunto de dados públicos do BigQuery
usa_namespara determinar os nomes mais comuns nos Estados Unidos entre os anos de 1910 e 2013:SELECT name, gender, SUM(number) AS total FROM `bigquery-public-data.usa_names.usa_1910_2013` GROUP BY name, gender ORDER BY total DESC LIMIT 10;Clique em Mais e, de seguida, clique em Definições de consulta.
Na secção Gestão de recursos, selecione Lote.
Opcional: ajuste as definições de consulta.
Clique em Guardar.
Clique em Executar.
Se não especificar uma tabela de destino, a tarefa de consulta escreve o resultado numa tabela temporária (cache).
bq
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Use o comando
bq querye especifique a flag--batch. No exemplo seguinte, a flag--use_legacy_sql=falsepermite-lhe usar a sintaxe do GoogleSQL.bq query \ --batch \ --use_legacy_sql=false \ 'QUERY'
Substitua QUERY por uma consulta GoogleSQL válida. Por exemplo, consulte o conjunto de dados público do BigQuery
usa_namespara determinar os nomes mais comuns nos Estados Unidos entre 1910 e 2013:bq query \ --batch \ --use_legacy_sql=false \ 'SELECT name, gender, SUM(number) AS total FROM `bigquery-public-data.usa_names.usa_1910_2013` GROUP BY name, gender ORDER BY total DESC LIMIT 10;'A tarefa de consulta escreve o resultado numa tabela temporária (cache).
Opcionalmente, pode especificar a tabela de destino e a localização para os resultados da consulta. Para escrever os resultados numa tabela existente, inclua a flag adequada para anexar (
--append_table=true) ou substituir (--replace=true) a tabela.bq query \ --batch \ --location=LOCATION \ --destination_table=TABLE \ --use_legacy_sql=false \ 'QUERY'
Substitua o seguinte:
LOCATION: a região ou a multirregião da tabela de destinos, por exemplo,
USNeste exemplo, o conjunto de dados
usa_namesé armazenado na localização multirregional dos EUA. Se especificar uma tabela de destino para esta consulta, o conjunto de dados que contém a tabela de destino também tem de estar na multirregião dos EUA. Não pode consultar um conjunto de dados numa localização e escrever os resultados numa tabela noutra localização.Pode definir um valor predefinido para a localização através do ficheiro.bigqueryrc.
TABLE: um nome para a tabela de destino, por exemplo,
myDataset.myTableSe a tabela de destino for uma tabela nova, o BigQuery cria a tabela quando executa a consulta. No entanto, tem de especificar um conjunto de dados existente.
Se a tabela não estiver no seu projeto atual, adicione o Google Cloud ID do projeto no formato
PROJECT_ID:DATASET.TABLE, por exemplo,myProject:myDataset.myTable. Se--destination_tablenão for especificado, é gerada uma tarefa de consulta que escreve o resultado numa tabela temporária.
API
Para executar uma consulta através da API, insira uma nova tarefa
e preencha a propriedade de configuração da tarefa query. Opcionalmente, especifique a sua localização na propriedade location na secção jobReference do recurso de trabalho.
Quando preencher as propriedades da tarefa de consulta, inclua a propriedade configuration.query.priority e defina o valor como BATCH.
Sonde os resultados chamando
getQueryResults.
A sondagem até jobComplete é igual a true. Verifique se existem erros e avisos na
errors lista.
Ir
Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.
Java
Para executar uma consulta em lote, defina a prioridade da consulta como QueryJobConfiguration.Priority.BATCH quando criar uma QueryJobConfiguration.
Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.
Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.