Como gravar resultados de consulta

Neste documento, descrevemos como gravar ou salvar resultados de consulta.

Tabelas temporárias e permanentes

O BigQuery salva todos os resultados de consulta em uma tabela, que pode ser permanente ou temporária:

  • Uma tabela temporária tem um nome aleatório e é armazenada em um conjunto de dados especial. As tabelas temporárias são usadas para armazenar em cache os resultados de consulta. Uma tabela temporária tem duração de aproximadamente 24 horas. As tabelas temporárias não estão disponíveis para compartilhamento e não são visíveis por nenhum método de lista padrão ou outros métodos de manipulação de tabela. Você não é cobrado pelo armazenamento de tabelas temporárias.

  • Uma tabela permanente pode ser uma tabela nova ou atual em qualquer conjunto de dados a que você tenha acesso. Se você gravar os resultados da consulta em uma tabela nova, será cobrado pelo armazenamento dos dados. Quando você grava os resultados da consulta em uma tabela permanente, as tabelas consultadas precisam estar no mesmo local que o conjunto de dados que contém a tabela de destino.

Como gravar resultados de consulta em uma tabela permanente

Ao gravar resultados de consulta em uma tabela permanente, é possível criar uma tabela nova, anexar os resultados a uma atual ou substituí-la. É possível gravar resultados de consulta em uma tabela permanente de uma das maneiras a seguir:

  • Use o Console do GCP ou a IU da Web clássica do BigQuery.
  • Use o comando bq query da ferramenta de linha de comando.
  • Chame o método da API jobs.insert e configure um job query.

Permissões exigidas

As permissões obrigatórias para gravar os resultados da consulta em uma tabela permanente dependem da disposição de gravação dos dados.

Permissões para gravar resultados de consulta em uma tabela nova

Se você estiver gravando resultados de consulta em uma tabela nova, será necessário ter o acesso de WRITER no nível do conjunto de dados ou um papel do IAM para envolvidos no projeto que inclua permissões bigquery.tables.create. Os seguintes papéis do IAM que são predefinidos e para envolvidos no projeto incluem permissões bigquery.tables.create:

Além disso, como o papel bigquery.user tem permissões bigquery.datasets.create, um usuário com o papel bigquery.user pode criar tabelas em qualquer conjunto de dados criados por ele. Quando um usuário com o papel bigquery.user cria um conjunto de dados, ele recebe acesso OWNER. Com o acesso OWNER, o usuário tem controle total sobre o conjunto de dados e todas as tabelas nele.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso. Para mais informações sobre os papéis no nível do conjunto de dados, consulte Papéis primários para conjuntos de dados.

Permissões para substituir ou anexar dados

Se você estiver usando resultados de consulta para substituir uma tabela atual ou anexar dados a ela, será necessário ter o acesso de WRITER no nível do conjunto de dados ou um papel do IAM para envolvidos no projeto que inclua permissões bigquery.tables.updateData. Os seguintes papéis do IAM que são predefinidos e para envolvidos no projeto incluem permissões bigquery.tables.updateData:

Além disso, como o papel bigquery.user tem permissões bigquery.datasets.create, um usuário com o papel bigquery.user pode substituir ou anexar dados em qualquer tabela criada por ele no conjunto de dados. Quando um usuário com o papel bigquery.user cria um conjunto de dados, ele recebe acesso OWNER. Com o acesso OWNER, o usuário tem controle total sobre o conjunto de dados e todas as tabelas nele.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Controle de acesso. Para mais informações sobre os papéis no nível do conjunto de dados, consulte Papéis primários para conjuntos de dados.

Como gravar resultados de consulta

Para gravar resultados de consulta em uma tabela permanente:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. No painel de navegação, localizado na seção Recursos, expanda seu projeto e selecione um conjunto de dados.

  3. Se o Editor de consultas estiver oculto, clique em Exibir editor no canto superior à direita da janela.

  4. Insira uma consulta SQL válida na área de texto do Editor de consultas.

  5. Clique em Mais abaixo do editor e selecione Configurações de consulta.

    Configurações de consulta

  6. Marque a caixa Definir uma tabela de destino para os resultados da consulta.

    Definir destino

  7. Na seção Destino, selecione o Nome do Projeto e o Nome do conjunto de dados em que a tabela será criada. Depois, escolha o Nome da tabela.

  8. Na seção Preferência de gravação na tabela de destino, escolha uma das seguintes opções:

    • Gravar apenas se a tabela estiver vazia: grava os resultados da consulta na tabela somente se ela estiver vazia.
    • Anexar à tabela: anexa os resultados da consulta a uma tabela atual.
    • Substituir tabela: usa os resultados da consulta para substituir uma tabela atual com o mesmo nome.

  9. (Opcional) Em Local de processamento, clique em Seleção automática e escolha o local dos seus dados.

  10. Clique em Executar consulta. Isso cria um job de consulta que grava os resultados da consulta na tabela que você especificou.

Como alternativa, se você esquecer de especificar uma tabela de destino antes de executar a consulta, será possível copiar a tabela temporária para uma permanente. Basta clicar no botão Salvar visualização abaixo do editor.

IU clássica

Opção 1: usar uma instrução DDL

Com as instruções de linguagem de definição de dados (DDL, na sigla em inglês), é possível criar e modificar tabelas usando a sintaxe de consulta do SQL padrão.

Para mais informações, consulte a página da instrução CREATE TABLE e o exemplo CREATE TABLE: Como criar uma nova tabela a partir de uma atual.

Opção 2: usar a IU clássica da Web

  1. Acesse a IU clássica da Web do BigQuery.
    Acesse a IU da Web clássica do BigQuery

  2. Clique no botão Escrever consulta.

  3. Insira uma consulta SQL válida na área de texto Nova consulta.

  4. Clique em Mostrar opções.

  5. Na seção Tabela de destino, clique em Selecionar tabela.

  6. Na caixa de diálogo Selecionar tabela de destino:

    1. Em Projeto, selecione o projeto em que a tabela de destino será criada.

    2. Em Conjunto de dados, selecione o conjunto de dados que armazenará a tabela.

    3. No campo Código da tabela, insira um nome de tabela. Ele precisa ser exclusivo no conjunto de dados de destino. O nome da tabela pode conter até 1.024 caracteres, sendo eles a-z, A-Z, 0-9 ou _ (caractere de sublinhado).

    4. Clique em OK.

  7. Na seção Tabela de destino, em Preferência de gravação, escolha uma das seguintes opções:

    • Gravar apenas se a tabela estiver vazia: grava os resultados da consulta na tabela somente se ela estiver vazia.
    • Anexar à tabela: anexa os resultados da consulta a uma tabela atual.
    • Substituir tabela: usa os resultados da consulta para substituir uma tabela atual com o mesmo nome.

  8. (Opcional) Em Local de processamento, clique em Não especificado e escolha o local dos dados.

  9. Clique em Executar consulta. Isso cria um job de consulta que grava os resultados da consulta na tabela que você especificou.

Como alternativa, se você esquecer de especificar uma tabela de destino antes de executar a consulta, será possível copiar a tabela temporária para uma permanente. Basta clicar no botão Salvar como tabela na janela de resultados.

CLI

Digite o comando bq query e especifique a sinalização --destination_table para criar uma tabela permanente com base nos resultados da consulta. Especifique a sinalização use_legacy_sql=false para usar a sintaxe SQL padrão. Para gravar os resultados da consulta em uma tabela que não esteja no projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

Forneça a sinalização --location e defina o valor como o local.

Para controlar a disposição de gravação de uma tabela de destino atual, especifique uma das seguintes sinalizações opcionais:

  • --append_table: se a tabela de destino existir, os resultados da consulta serão anexados a ela.

  • --replace: se a tabela de destino existir, ela será substituída pelos resultados da consulta.

    bq --location=[LOCATION] query --destination_table [PROJECT_ID]:[DATASET].[TABLE] --use_legacy_sql=false '[QUERY]'

Em que:

  • [LOCATION] é o nome do local usado para processar a consulta. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região Tokyo, será possível definir o valor da sinalização como asia-northeast1. Defina um valor padrão para o local usando o arquivo .bigqueryrc;
  • [PROJECT_ID] é o ID do projeto;
  • [DATASET] é o nome do conjunto de dados que contém a tabela em que você está gravando os resultados da consulta;
  • [TABLE] é o nome da tabela em que você está gravando os resultados da consulta;
  • [QUERY] é uma consulta na sintaxe SQL padrão.

Se nenhuma sinalização de disposição de gravação for especificada, o comportamento padrão será gravar os resultados na tabela somente se ela estiver vazia. Se a tabela existir e não estiver vazia, o seguinte erro será retornado: BigQuery error in query operation: Error processing job '[PROJECT_ID]:bqjob_123abc456789_00000e1234f_1': Already Exists: Table [PROJECT_ID]:[DATASET].[TABLE].

Exemplos:

Digite o comando a seguir para gravar os resultados da consulta em uma tabela de destino chamada mytable em mydataset. O conjunto de dados está no projeto padrão. Como nenhuma sinalização de disposição de gravação está especificada no comando, a tabela precisa ser nova ou estar vazia. Caso contrário, um erro Already exists é retornado. A consulta recupera dados do conjunto de dados público USA Name Data.

bq --location=US query --destination_table mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Digite o comando a seguir para usar os resultados da consulta a fim de substituir uma tabela de destino chamada mytable em mydataset. O conjunto de dados está no projeto padrão. O comando usa a sinalização --replace para substituir a tabela de destino.

bq --location=US query --destination_table mydataset.mytable --replace --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Digite o comando a seguir para anexar os resultados da consulta a uma tabela de destino chamada mytable em mydataset. O conjunto de dados está em myotherproject, e não no projeto padrão. O comando usa a sinalização --append para anexar os resultados da consulta à tabela de destino.

bq --location=US query --destination_table myotherproject:mydataset.mytable --append --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

API

Para salvar os resultados da consulta em uma tabela permanente, chame o método jobs.insert, configure um job query e inclua um valor na propriedade configuration.query.destinationTable. Para controlar a disposição de gravação de uma tabela de destino atual, configure a propriedade configuration.query.writeDisposition.

Especifique o local na propriedade location na seção jobReference do recurso do job.

Go

Antes de testar esta amostra, siga as instruções de configuração para 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 Go.

bigquery/snippets/snippet.go 
// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")

q := client.Query("SELECT 17 as my_col")
q.Location = "US" // Location must match the dataset(s) referenced in query.
q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

Antes de testar esta amostra, siga as instruções de configuração para 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 Java.

Para salvar os resultados da consulta em uma tabela permanente, defina a tabela de destino como o TableId de sua escolha em um QueryJobConfiguration.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // Note that setUseLegacySql is set to false by default
    QueryJobConfiguration.newBuilder(query)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python em 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 Python.

Para salvar os resultados da consulta em uma tabela permanente, crie um QueryJobConfig e defina o destino como a TableReference de sua escolha. Passe a configuração do job para o método de consulta. 

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'your_dataset_id'

job_config = bigquery.QueryJobConfig()
# Set the destination table
table_ref = client.dataset(dataset_id).table('your_table_id')
job_config.destination = table_ref
sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(
    sql,
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location='US',
    job_config=job_config)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print('Query results loaded to table {}'.format(table_ref.path))

Como gravar resultados de consulta extensos

Normalmente, as consultas têm um tamanho máximo de resposta. Se você planeja executar uma consulta que possa gerar resultados maiores, é possível:

  • especificar uma tabela de destino para os resultados da consulta no SQL padrão;
  • especificar uma tabela de destino e definir a opção allowLargeResults no SQL legado.

Ao especificar uma tabela de destino para resultados de consulta extensos, você será cobrado pelo armazenamento dos dados.

Limitações

No SQL legado, a gravação de resultados extensos está sujeita a estas limitações:

  • É necessário especificar uma tabela de destino.
  • Não é possível especificar uma cláusula ORDER BY, TOP ou LIMIT de nível superior. Se você fizer isso, o benefício de usar allowLargeResults será negado, porque a saída da consulta não poderá mais ser computada em paralelo.
  • As funções de janela somente poderão retornar resultados de consulta extensos se usadas em conjunto com uma cláusula PARTITION BY.

Como gravar resultados extensos usando SQL legado

Para gravar conjuntos de resultados extensos usando SQL legado:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. Clique em Escrever nova consulta.

  3. Insira uma consulta SQL do BigQuery válida na área de texto do Editor de consultas. Use o prefixo #legacySQL ou lembre-se de marcar Usar SQL legado nas configurações da consulta.

  4. Clique em Mais e selecione Configurações de consulta.

    Configurações de consulta

  5. Para Destino, marque Definir uma tabela de destino para os resultados da consulta.

    Definir destino

  6. Em Nome do projeto, escolha o projeto em que a tabela de destino será criada.

  7. Em Nome do conjunto de dados, escolha o conjunto de dados que armazenará a tabela.

  8. Insira o nome da tabela no campo Nome da tabela.

  9. Se você estiver gravando um conjunto de resultados extensos em uma tabela atual, poderá usar as opções de Preferência de gravação na tabela de destino para controlar a disposição de gravação da tabela de destino:

    • Gravar apenas se a tabela estiver vazia: grava os resultados da consulta na tabela somente se ela estiver vazia.
    • Anexar à tabela: anexa os resultados da consulta a uma tabela atual.
    • Substituir tabela: usa os resultados da consulta para substituir uma tabela atual com o mesmo nome.

    Botão de opção de substituir tabela

  10. Em Tamanho dos resultados, marque Permitir resultados extensos (sem limite de tamanho).

    Tamanho dos resultados da consulta

  11. (Opcional) Em Local de processamento, clique em Seleção automática e escolha o local dos seus dados.

    Local de processamento da consulta

  12. Clique em Salvar para atualizar as configurações da consulta.

  13. Clique em Executar. Isso cria um job de consulta que grava os resultados extensos definidos na tabela que você especificou.

IU clássica

  1. Acesse a IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery

  2. Clique no botão Escrever consulta.

  3. Insira uma consulta SQL válida do BigQuery na área de texto Nova consulta. Use o prefixo #legacySQL ou marque a opção Usar SQL legado nas opções de consulta.

  4. Clique em Mostrar opções.

  5. Em Tabela de destino, clique em Selecionar tabela.

  6. Na caixa de diálogo Selecionar tabela de destino:

    1. Em Projeto, selecione o projeto em que a tabela de destino será criada.

    2. Em Conjunto de dados, selecione o conjunto de dados que armazenará a tabela.

    3. No campo Código da tabela, insira um nome de tabela.

    4. Clique em OK.

  7. Se você estiver gravando um conjunto de resultados extenso em uma tabela atual, será possível usar a opção Preferência de gravação para controlar a disposição de gravação da tabela de destino:

    • Gravar apenas se a tabela estiver vazia: grava os resultados da consulta na tabela somente se ela estiver vazia.
    • Anexar à tabela: anexa os resultados da consulta a uma tabela atual.
    • Substituir tabela: usa os resultados da consulta para substituir uma tabela atual com o mesmo nome.

  8. Em Tamanho dos resultados, marque Permitir resultados extensos.

    Opção "Permitir resultados extensos"

  9. (Opcional) Em Local de processamento, clique em Não especificado e escolha o local dos dados.

  10. Clique em Executar consulta. Isso cria um job de consulta que grava os resultados extensos definidos na tabela que você especificou.

Linha de comando

Use as sinalizações --allow_large_results e --destination_table para criar uma tabela de destino que armazene o conjunto de resultados extensos. Como a opção --allow_large_results só se aplica ao SQL legado, você também precisa especificar a sinalização --use_legacy_sql=true. Para gravar os resultados da consulta em uma tabela que não esteja no projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET]. Forneça a sinalização --location e defina o valor como o local.

Para controlar a disposição de gravação de uma tabela de destino atual, especifique uma das seguintes sinalizações opcionais:

  • --append_table: se a tabela de destino existir, os resultados da consulta serão anexados a ela.

  • --replace: se a tabela de destino existir, ela será substituída pelos resultados da consulta.

    bq --location=[LOCATION] query --destination_table [PROJECT_ID]:[DATASET].[TABLE_NAME] --use_legacy_sql=true --allow_large_results "[QUERY]"

Em que:

  • [LOCATION] é o nome do local usado para processar a consulta. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, poderá definir o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é o nome do conjunto de dados que contém a tabela em que você está gravando os resultados da consulta;
  • [TABLE] é o nome da tabela em que você está gravando os resultados da consulta;
  • [QUERY] é uma consulta na sintaxe do SQL legado.

Exemplos:

Digite o comando a seguir para gravar os resultados de consulta extensos em uma tabela de destino chamada mytable em mydataset. O conjunto de dados está no projeto padrão. Como nenhuma sinalização de disposição de gravação está especificada no comando, a tabela precisa ser nova ou estar vazia. Caso contrário, um erro Already exists é retornado. A consulta recupera dados do conjunto de dados público USA Name Data. Essa consulta é usada apenas para fins de exemplo. O conjunto de resultados retornado não excede o tamanho máximo de resposta.

bq --location=US query --destination_table mydataset.mytable --use_legacy_sql=true --allow_large_results "SELECT name,number FROM [bigquery-public-data:usa_names.usa_1910_current] WHERE gender = 'M' ORDER BY number DESC"

Digite o comando a seguir para usar os resultados de consulta extensos a fim de substituir uma tabela de destino chamada mytable em mydataset. O conjunto de dados está em myotherproject, e não no projeto padrão. O comando usa a sinalização --replace para substituir a tabela de destino.

bq --location=US query --destination_table mydataset.mytable --replace --use_legacy_sql=true --allow_large_results "SELECT name,number FROM [bigquery-public-data:usa_names.usa_1910_current] WHERE gender = 'M' ORDER BY number DESC"

Digite o comando a seguir para anexar os resultados de consulta extensos a uma tabela de destino chamada mytable em mydataset. O conjunto de dados está em myotherproject, e não no projeto padrão. O comando usa a sinalização --append para anexar os resultados da consulta à tabela de destino.

bq --location=US query --destination_table myotherproject:mydataset.mytable --append --use_legacy_sql=true --allow_large_results "SELECT name,number FROM [bigquery-public-data:usa_names.usa_1910_current] WHERE gender = 'M' ORDER BY number DESC"

API

Para gravar resultados extensos em uma tabela de destino, chame o método jobs.insert, configure um job query e defina a propriedade configuration.query.allowLargeResults como true. Especifique a tabela de destino usando a propriedade configuration.query.destinationTable. Para controlar a disposição de gravação de uma tabela de destino, configure a propriedade configuration.query.writeDisposition.

Especifique o local na propriedade location na seção jobReference do recurso do job.

Go

Antes de testar esta amostra, siga as instruções de configuração para 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 do BigQuery para Go (em inglês). 

q := client.Query(
	"SELECT corpus FROM [bigquery-public-data:samples.shakespeare] GROUP BY corpus;")
q.UseLegacySQL = true
q.AllowLargeResults = true
q.QueryConfig.Dst = client.Dataset(dstDatasetID).Table(dstTableID)
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

Antes de testar esta amostra, siga as instruções de configuração para 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 do BigQuery para Java.

Para ativar resultados extensos, defina permitir resultados extensos como true e tabela de destino como o TableId de sua escolha em uma QueryJobConfiguration.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM [bigquery-public-data:samples.shakespeare] GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // To use legacy SQL syntax, set useLegacySql to true.
    QueryJobConfiguration.newBuilder(query)
        .setUseLegacySql(true)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        // Allow results larger than the maximum response size.
        // If true, a destination table must be set.
        .setAllowLargeResults(true)
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python em 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 Python. 

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'your_dataset_id'

job_config = bigquery.QueryJobConfig()
# Set use_legacy_sql to True to use legacy SQL syntax.
job_config.use_legacy_sql = True
# Set the destination table
table_ref = client.dataset(dataset_id).table("your_table_id")
job_config.destination = table_ref
job_config.allow_large_results = True
sql = """
    SELECT corpus
    FROM [bigquery-public-data:samples.shakespeare]
    GROUP BY corpus;
"""
# Start the query, passing in the extra configuration.
query_job = client.query(
    sql,
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location="US",
    job_config=job_config,
)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print("Query results loaded to table {}".format(table_ref.path))

Como fazer o download e salvar resultados de consulta

Depois de executar uma consulta SQL, faça o download dos resultados em um arquivo na sua máquina local ou salve-os no Google Drive, no Planilhas Google ou em uma tabela permanente no BigQuery.

Limitações

As seguintes limitações podem ser aplicadas quando você fizer download dos resultados da consulta e salvá-los:

  • Só é possível fazer o download dos resultados da consulta para um arquivo local ou para o Planilhas Google na IU da Web clássica do BigQuery. Para fazer o download dos resultados para o Google Drive, use o Console do GCP.
  • Para fazer o download dos resultados da consulta usando a IU da Web clássica do BigQuery, o conjunto de resultados deve conter menos de 16.000 linhas e até 10 MB. Se os resultados tiverem mais que 10 MB ou 16.000 linhas, será possível salvá-los em uma tabela.
  • Só é possível fazer o download dos resultados da consulta localmente no formato CSV ou JSON delimitado por linhas novas.
  • Não é possível fazer o download dos resultados da consulta contendo dados aninhados e repetidos no formato CSV.
  • Não é possível salvar os resultados das consultas contendo dados aninhados e repetidos no Planilhas Google.
  • Para salvar os resultados da consulta no Planilhas Google usando a IU da Web clássica do BigQuery, o conjunto de resultados deve conter menos de 16.000 linhas e até 10 MB. Se os resultados forem maiores do que 10 MB ou 16.000 linhas, será possível salvá-los em uma tabela.
  • Não é possível salvar os resultados em um arquivo local, no Planilhas Google ou no Google Drive com a ferramenta de linha de comando nem com a API.
  • Para salvar os resultados da consulta no Google Drive usando o Console do GCP, o conjunto de resultados deve ter até 1 GB. Se os resultados forem maiores do que 1 GB, será possível salvá-los em uma tabela.
  • Só é possível salvar os resultados da consulta no Google Drive em formato CSV ou JSON delimitado por linhas novas.

Como fazer o download dos resultados da consulta para um arquivo local

Não é possível fazer o download dos resultados da consulta para um arquivo local usando a ferramenta de linha de comando nem a API.

Para fazer o download dos resultados da consulta como um arquivo CSV ou JSON delimitado por linhas novas usando a IU da Web:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. Clique em Escrever nova consulta.

  3. Insira uma consulta SQL válida na área de texto do Editor de consultas.

  4. (Opcional) Para alterar o local de processamento, clique em Mais e selecione Configurações de consulta. Em Local de processamento, clique em Seleção automática e escolha o local dos seus dados.

  5. Clique em Executar.

  6. Quando os resultados forem retornados, clique em Salvar resultados e selecione o formato/local em que você quer salvá-los.

    O arquivo é salvo no local de download padrão do navegador.

IU clássica

  1. Acesse a IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery

  2. Clique no botão Escrever consulta.

  3. Insira uma consulta SQL válida na área de texto Nova consulta.

  4. Clique em Mostrar opções.

  5. (Opcional) Em Local de processamento, clique em Não especificado e escolha o local dos dados.

  6. Clique em Executar consulta.

  7. Quando os resultados forem retornados, clique no botão Fazer o download como CSV ou Fazer o download como JSON acima dos resultados da consulta.

    captura de tela dos botões de download e salvar

    O arquivo é salvo no local de download padrão do navegador.

Como salvar os resultados da consulta no Google Drive

Não é possível salvar os resultados da consulta no Google Drive com a ferramenta de linha de comando, com a API nem com a IU da Web clássica do BigQuery.

Para salvar os resultados da consulta no Google Drive usando o Console do GCP:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.

    Acessar a IU da Web do BigQuery

  2. Insira uma consulta SQL válida na área de texto do Editor de consultas.

  3. Clique em Executar.

  4. Quando os resultados forem retornados, clique em Salvar resultados.

    captura de tela do botão de salvar resultados

  5. Selecione CSV (Google Drive) ou JSON (Google Drive). Não é possível selecionar o local ao salvar os resultados no Google Drive. Eles sempre são salvos na raiz "Meu Drive".

  6. Pode levar alguns minutos para salvar os resultados no Google Drive. Depois que eles estiverem salvos, você receberá uma mensagem pop-up que inclui o nome do arquivo - bq-results-[TIMESTAMP]-[RANDOM_CHARACTERS].[CSV or JSON].

    captura de tela do botão de salvar resultados

  7. Na mensagem pop-up, abra o arquivo clicando em Abrir ou navegue até o Google Drive e clique em Meu Drive.

Como salvar os resultados da consulta como uma tabela

Para salvar os resultados da consulta como uma tabela:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. No painel de navegação, localizado na seção Recursos, expanda seu projeto e selecione um conjunto de dados.

  3. Se o Editor de consultas estiver oculto, clique em Exibir editor no canto superior à direita da janela.

  4. Insira uma consulta SQL válida na área de texto do Editor de consultas.

  5. Clique em Mais abaixo do editor e selecione Configurações de consulta.

    Configurações de consulta

  6. Marque a caixa Definir uma tabela de destino para os resultados da consulta.

    Definir destino

  7. Na seção Destino, selecione o Nome do Projeto e o Nome do conjunto de dados em que a tabela será criada. Depois, escolha o Nome da tabela.

  8. Na seção Preferência de gravação na tabela de destino, escolha uma das seguintes opções:

    • Gravar apenas se a tabela estiver vazia: grava os resultados da consulta na tabela somente se ela estiver vazia.
    • Anexar à tabela: anexa os resultados da consulta a uma tabela atual.
    • Substituir tabela: usa os resultados da consulta para substituir uma tabela atual com o mesmo nome.

  9. (Opcional) Em Local de processamento, clique em Seleção automática e escolha o local dos seus dados.

  10. Clique em Executar consulta. Isso cria um job de consulta que grava os resultados da consulta na tabela que você especificou.

Como alternativa, se você esquecer de especificar uma tabela de destino antes de executar a consulta, será possível copiar a tabela temporária para uma permanente. Basta clicar no botão Salvar visualização abaixo do editor.

IU clássica

Opção 1: usar uma instrução DDL

Com as instruções de linguagem de definição de dados (DDL, na sigla em inglês), é possível criar e modificar tabelas usando a sintaxe de consulta do SQL padrão.

Para mais informações, consulte a página da instrução CREATE TABLE e o exemplo CREATE TABLE: Como criar uma nova tabela a partir de uma atual.

Opção 2: usar a IU clássica da Web

  1. Acesse a IU clássica da Web do BigQuery.
    Acesse a IU da Web clássica do BigQuery

  2. Clique no botão Escrever consulta.

  3. Insira uma consulta SQL válida na área de texto Nova consulta.

  4. Clique em Mostrar opções.

  5. Na seção Tabela de destino, clique em Selecionar tabela.

  6. Na caixa de diálogo Selecionar tabela de destino:

    1. Em Projeto, selecione o projeto em que a tabela de destino será criada.

    2. Em Conjunto de dados, selecione o conjunto de dados que armazenará a tabela.

    3. No campo Código da tabela, insira um nome de tabela. Ele precisa ser exclusivo no conjunto de dados de destino. O nome da tabela pode conter até 1.024 caracteres, sendo eles a-z, A-Z, 0-9 ou _ (caractere de sublinhado).

    4. Clique em OK.

  7. Na seção Tabela de destino, em Preferência de gravação, escolha uma das seguintes opções:

    • Gravar apenas se a tabela estiver vazia: grava os resultados da consulta na tabela somente se ela estiver vazia.
    • Anexar à tabela: anexa os resultados da consulta a uma tabela atual.
    • Substituir tabela: usa os resultados da consulta para substituir uma tabela atual com o mesmo nome.

  8. (Opcional) Em Local de processamento, clique em Não especificado e escolha o local dos dados.

  9. Clique em Executar consulta. Isso cria um job de consulta que grava os resultados da consulta na tabela que você especificou.

Como alternativa, se você esquecer de especificar uma tabela de destino antes de executar a consulta, será possível copiar a tabela temporária para uma permanente. Basta clicar no botão Salvar como tabela na janela de resultados.

CLI

Digite o comando bq query e especifique a sinalização --destination_table para criar uma tabela permanente com base nos resultados da consulta. Especifique a sinalização use_legacy_sql=false para usar a sintaxe SQL padrão. Para gravar os resultados da consulta em uma tabela que não esteja no projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

Forneça a sinalização --location e defina o valor como o local.

Para controlar a disposição de gravação de uma tabela de destino atual, especifique uma das seguintes sinalizações opcionais:

  • --append_table: se a tabela de destino existir, os resultados da consulta serão anexados a ela.

  • --replace: se a tabela de destino existir, ela será substituída pelos resultados da consulta.

    bq --location=[LOCATION] query --destination_table [PROJECT_ID]:[DATASET].[TABLE] --use_legacy_sql=false '[QUERY]'

Em que:

  • [LOCATION] é o nome do local usado para processar a consulta. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região Tokyo, será possível definir o valor da sinalização como asia-northeast1. Defina um valor padrão para o local usando o arquivo .bigqueryrc;
  • [PROJECT_ID] é o ID do projeto;
  • [DATASET] é o nome do conjunto de dados que contém a tabela em que você está gravando os resultados da consulta;
  • [TABLE] é o nome da tabela em que você está gravando os resultados da consulta;
  • [QUERY] é uma consulta na sintaxe SQL padrão.

Se nenhuma sinalização de disposição de gravação for especificada, o comportamento padrão será gravar os resultados na tabela somente se ela estiver vazia. Se a tabela existir e não estiver vazia, o seguinte erro será retornado: BigQuery error in query operation: Error processing job '[PROJECT_ID]:bqjob_123abc456789_00000e1234f_1': Already Exists: Table [PROJECT_ID]:[DATASET].[TABLE].

Exemplos:

Digite o comando a seguir para gravar os resultados da consulta em uma tabela de destino chamada mytable em mydataset. O conjunto de dados está no projeto padrão. Como nenhuma sinalização de disposição de gravação está especificada no comando, a tabela precisa ser nova ou estar vazia. Caso contrário, um erro Already exists é retornado. A consulta recupera dados do conjunto de dados público USA Name Data.

bq --location=US query --destination_table mydataset.mytable --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Digite o comando a seguir para usar os resultados da consulta a fim de substituir uma tabela de destino chamada mytable em mydataset. O conjunto de dados está no projeto padrão. O comando usa a sinalização --replace para substituir a tabela de destino.

bq --location=US query --destination_table mydataset.mytable --replace --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

Digite o comando a seguir para anexar os resultados da consulta a uma tabela de destino chamada mytable em mydataset. O conjunto de dados está em myotherproject, e não no projeto padrão. O comando usa a sinalização --append para anexar os resultados da consulta à tabela de destino.

bq --location=US query --destination_table myotherproject:mydataset.mytable --append --use_legacy_sql=false 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC'

API

Para salvar os resultados da consulta em uma tabela permanente, chame o método jobs.insert, configure um job query e inclua um valor na propriedade configuration.query.destinationTable. Para controlar a disposição de gravação de uma tabela de destino atual, configure a propriedade configuration.query.writeDisposition.

Especifique o local na propriedade location na seção jobReference do recurso do job.

Go

Antes de testar esta amostra, siga as instruções de configuração para 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 Go.

bigquery/snippets/snippet.go 
// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")

q := client.Query("SELECT 17 as my_col")
q.Location = "US" // Location must match the dataset(s) referenced in query.
q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
job, err := q.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}
it, err := job.Read(ctx)
for {
	var row []bigquery.Value
	err := it.Next(&row)
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	fmt.Println(row)
}

Java

Antes de testar esta amostra, siga as instruções de configuração para 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 Java.

Para salvar os resultados da consulta em uma tabela permanente, defina a tabela de destino como o TableId de sua escolha em um QueryJobConfiguration.

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // Note that setUseLegacySql is set to false by default
    QueryJobConfiguration.newBuilder(query)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python em 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 Python.

Para salvar os resultados da consulta em uma tabela permanente, crie um QueryJobConfig e defina o destino como a TableReference de sua escolha. Passe a configuração do job para o método de consulta. 

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'your_dataset_id'

job_config = bigquery.QueryJobConfig()
# Set the destination table
table_ref = client.dataset(dataset_id).table('your_table_id')
job_config.destination = table_ref
sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(
    sql,
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location='US',
    job_config=job_config)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print('Query results loaded to table {}'.format(table_ref.path))

Como salvar os resultados da consulta no Planilhas Google

Não é possível salvar os resultados da consulta no Planilhas Google com a ferramenta de linha de comando nem com a API.

Para salvar os resultados da consulta no Planilhas Google usando a IU da Web:

Console

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. Clique em Escrever nova consulta.

  3. Insira uma consulta SQL válida na área de texto do Editor de consultas.

  4. (Opcional) Para alterar o local de processamento, clique em Mais e selecione Configurações de consulta. Em Local de processamento, clique em Seleção automática e escolha o local dos seus dados.

  5. Clique em Executar.

  6. Quando os resultados forem retornados, clique em Salvar resultados e selecione Planilhas Google.

  7. Se necessário, siga as instruções para fazer login na conta do Google e clique em Permitir para que o BigQuery possa gravar os dados na pasta MY Drive do Google Drive.

    Depois de seguir as instruções, você receberá um e-mail com o assunto "Ferramentas do cliente do BigQuery conectadas à sua Conta do Google". O e-mail contém informações sobre as permissões que você concedeu, além das etapas para remover essas permissões.

  8. Quando os resultados da consulta forem salvos, uma mensagem semelhante à seguinte aparecerá abaixo deles na IU da Web do console do BigQuery: Saved to Sheets as "results-20190225-103531. Open. Clique no link da mensagem para ver seus resultados no Planilhas Google ou navegue até a pasta My Drive e abra o arquivo manualmente.

    Quando você salva os resultados da consulta no Planilhas Google, o nome do arquivo começa com results-[DATE], em que [DATE] é a data de hoje no formato YYYYMMDD.

IU clássica

  1. Acesse a IU da Web do BigQuery.
    Acessar a IU da Web do BigQuery

  2. Clique no botão Escrever consulta.

  3. Insira uma consulta SQL válida na área de texto Nova consulta.

  4. Clique em Mostrar opções.

  5. (Opcional) Em Local de processamento, clique em Não especificado e escolha o local dos dados.

  6. Clique em Executar consulta.

  7. Quando os resultados forem retornados, clique no botão Salvar no Planilhas Google acima dos resultados da consulta.

    captura de tela dos botões de download e salvar

  8. Se necessário, siga as instruções para fazer login na conta do Google e clique em Permitir para que o BigQuery possa gravar os dados na pasta MY Drive do Google Drive.

    Depois de seguir as instruções, você receberá um e-mail com o assunto "Ferramentas do cliente do BigQuery conectadas à sua Conta do Google". O e-mail contém informações sobre as permissões que você concedeu, além das etapas para remover essas permissões.

  9. Quando os resultados forem salvos, a mensagem a seguir será exibida acima dos resultados da consulta na IU da Web do BigQuery: Results saved to Google Sheets. Click to view. Clique no link da mensagem para ver seus resultados no Planilhas Google ou navegue até a pasta MY Drive e abra o arquivo manualmente.

    Quando você salva os resultados da consulta no Planilhas Google, o nome do arquivo começa com results-[DATE], em que [DATE] é a data de hoje no formato YYYYMMDD.

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

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
BigQuery
Comentários sobre o produto
Precisa de ajuda? Acesse nossa página de suporte.