Crie tabelas em cluster

É possível reduzir a quantidade de dados processados por uma consulta usando tabelas de cluster no BigQuery.

Com tabelas em cluster, os dados são organizados com base nos valores de colunas especificadas, também chamadas de colunas de clustering. O BigQuery classifica os dados pelas colunas em cluster e armazena as linhas com valores semelhantes nos mesmos blocos físicos ou em blocos próximos. Quando uma consulta filtra uma coluna em cluster, o BigQuery verifica com eficiência apenas os blocos relevantes e ignora os dados que não correspondem ao filtro.

Para ver mais informações, consulte os seguintes tópicos:

• Para saber mais sobre tabelas em cluster no BigQuery, consulte Introdução às tabelas em cluster.
• Para saber como trabalhar e controlar o acesso a tabelas em cluster, consulte Gerenciar tabelas em cluster.

Antes de começar

Para criar uma tabela, você precisa das seguintes permissões do IAM:

• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.jobs.create

Além disso, é possível exigir a permissão bigquery.tables.getData para acessar os dados gravados na tabela.

Cada um dos papéis predefinidos do IAM a seguir inclui as permissões necessárias para atualizar uma tabela:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin (inclui a permissão bigquery.jobs.create)
• roles/bigquery.user (inclui a permissão bigquery.jobs.create)
• roles/bigquery.jobUser (inclui a permissão bigquery.jobs.create)

Além disso, se você tiver a permissão bigquery.datasets.create, será possível criar e atualizar tabelas nos conjuntos de dados que criar.

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Requisitos de nomenclatura de tabelas

Ao criar uma tabela no BigQuery, o nome dela precisa ser exclusivo para cada conjunto de dados. Esse nome pode:

• Conter caracteres com um total de até 1.024 bytes UTF-8.
• conter caracteres Unicode na categoria L (letra), M (marca), N (número), Pc (conector, inclusive sublinhado), Pd (travessão), Zs (espaço). Para mais informações, consulte Categoria geral.

Veja a seguir exemplos de nomes de tabela válidos: table 01, ग्राहक, 00_お客様 e étudiant-01.

Advertências:

• Por padrão, os nomes de tabelas diferenciam maiúsculas de minúsculas. mytable e MyTable podem coexistir no mesmo conjunto de dados, a menos que façam parte de um conjunto de dados com diferenciação de maiúsculas e minúsculas desativada.
• Alguns nomes de tabelas e prefixos de nome de tabela são reservados. Se você receber um erro informando que o nome ou o prefixo da tabela está reservado, selecione um nome diferente e tente novamente.

• Se você incluir vários operadores de ponto (.) em uma sequência, os operadores duplicados serão removidos implicitamente.

  Por exemplo, este: project_name....dataset_name..table_name

  Se tornaria: project_name.dataset_name.table_name

Requisitos de colunas em cluster

É possível especificar as colunas usadas para criar a tabela em cluster ao criar uma tabela no BigQuery. Depois que a tabela é criada, é possível modificar as colunas usadas para criar a tabela em cluster. Para mais detalhes, consulte Como modificar a especificação de clustering.

É preciso que as colunas de clustering sejam de nível superior, sem repetição e de um dos seguintes tipos de dados:

• BIGNUMERIC
• BOOL
• DATE
• DATETIME
• GEOGRAPHY
• INT64
• NUMERIC
• RANGE
• STRING
• TIMESTAMP

É possível especificar até quatro colunas de clustering. Quando você especifica várias colunas, a ordem delas determina como os dados são classificados. Por exemplo, se a tabela estiver em cluster pelas colunas a, b e c, os dados serão classificados na mesma ordem: primeiro pela "a", depois pela "b" e, em seguida, pela "c". Como prática recomendada, coloque a coluna agregada ou filtrada com mais frequência primeiro.

A ordem das colunas de clustering também afeta o desempenho e o preço das consultas. Para mais informações sobre as práticas recomendadas de consulta para tabelas em cluster, acesse este link.

Criar uma tabela em cluster vazia com uma definição de esquema

Para criar uma tabela em cluster vazia com uma definição de esquema, faça o seguinte:

Console

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
3. Na seção Informações do conjunto de dados, clique em Criar tabela.
4. No painel Criar tabela, especifique os seguintes detalhes:
1. Na seção Origem, selecione Tabela vazia na lista Criar tabela de.
2. Na seção Destino, especifique os seguintes campos:
   1. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
   2. No campo Tabela, insira o nome da tabela que você quer criar.
   3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
3. Na seção Esquema, insira a definição do esquema. É possível inserir as informações do esquema manualmente usando um dos seguintes métodos:
   • Opção 1: clique em Editar como texto e cole o esquema na forma de uma matriz JSON. Com ela, você gera o esquema usando um processo igual ao de criação de um arquivo de esquema JSON. É possível visualizar o esquema de uma tabela existente no formato JSON inserindo o seguinte comando:

         bq show --format=prettyjson dataset.table
         

   • Opção 2: clique em Adicionar campo e insira o esquema da tabela. Especifique o Nome, o Tipo e o Modo de cada campo.
4. Em Pedido de clustering, insira de um a quatro nomes de coluna separados por vírgulas.
5. Opcional: na seção Opções avançadas, se você quiser usar uma chave de criptografia gerenciada pelo cliente, selecione a opção Usar uma chave de criptografia gerenciada pelo cliente (CMEK, na sigla em inglês). Por padrão, o BigQuery criptografa o conteúdo do cliente armazenado em repouso usando um Google-owned and Google-managed encryption key.
6. Clique em Criar tabela.

SQL

Use o comando instrução DDL CREATE TABLE com a opção CLUSTER BY. No exemplo a seguir, é criada uma tabela em cluster denominada myclusteredtable em mydataset.

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   CREATE TABLE mydataset.myclusteredtable
   (
     customer_id STRING,
     transaction_amount NUMERIC
   )
   CLUSTER BY
     customer_id
     OPTIONS (
       description = 'a table clustered by customer_id');

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando bq mk com as seguintes sinalizações:

• --table ou o atalho -t.
• --schema. É possível fornecer a definição de esquema da tabela in-line ou por meio de um arquivo de esquema JSON.
• --clustering_fields. É possível especificar até quatro colunas de clustering.

Os parâmetros opcionais incluem --expiration, --description, --time_partitioning_type, --time_partitioning_field, --time_partitioning_expiration, --destination_kms_key, e --label.

Se você estiver criando uma tabela em um projeto diferente do projeto padrão, adicione o ID do projeto ao conjunto de dados no seguinte formato: project_id:dataset.

--destination_kms_key não é demonstrado aqui. Para mais informações sobre o uso de --destination_kms_key, consulte chaves de criptografia gerenciadas pelo cliente.

Digite o seguinte comando para criar uma tabela em cluster vazia com uma definição de esquema:

bq mk \
    --table \
    --expiration INTEGER1 \
    --schema SCHEMA \
    --clustering_fields CLUSTER_COLUMNS \
    --description "DESCRIPTION" \
    --label KEY:VALUE,KEY:VALUE \
    PROJECT_ID:DATASET.TABLE

Substitua:

• INTEGER1: a vida útil padrão, em segundos, para a tabela. O valor mínimo é de 3.600 segundos (uma hora). O prazo de expiração é a soma do horário UTC atual com o valor inteiro. Se você definir o prazo de expiração da tabela ao criar uma tabela a configuração de expiração da tabela padrão do conjunto de dados será ignorada. Definir esse valor exclui a tabela após o tempo especificado.
• SCHEMA: uma definição de esquema in-line no formato COLUMN:DATA_TYPE,COLUMN:DATA_TYPE ou o caminho para o arquivo de esquema JSON na máquina local.
• CLUSTER_COLUMNS: uma lista separada por vírgulas de até quatro colunas de clustering. A lista não pode conter espaços.
• DESCRIPTION: uma descrição da tabela, entre aspas.
• KEY:VALUE: o par de chave-valor que representa um rótulo. Insira vários rótulos usando uma lista separada por vírgulas.
• PROJECT_ID: o ID do projeto.
• DATASET: um conjunto de dados no projeto;
• TABLE: o nome da tabela que você está criando;

Quando você especifica o esquema na linha de comando, não é possível especificar o modo da coluna ou incluir um tipo RECORD (STRUCT) e uma descrição de coluna. Todos os modos assumem NULLABLE como padrão. Para incluir descrições, modos e tipos RECORD, forneça um arquivo de esquema JSON.

Exemplos:

Digite o comando a seguir para criar uma tabela em cluster chamada myclusteredtable em mydataset no seu projeto padrão. A expiração da tabela é configurada para 2.592.000 (um mês de 30 dias), a descrição é definida como This is my clustered table e o rótulo é definido como organization:development. O comando usa o atalho -t em vez de --table.

O esquema é especificado in-line como: timestamp:timestamp,customer_id:string,transaction_amount:float O campo de clustering customer_id especificado é usado para agrupar as tabelas.

bq mk \
    -t \
    --expiration 2592000 \
    --schema 'timestamp:timestamp,customer_id:string,transaction_amount:float' \
    --clustering_fields customer_id \
    --description "This is my clustered table" \
    --label org:dev \
    mydataset.myclusteredtable

Digite o seguinte comando para criar uma tabela em cluster chamada myclusteredtable em myotherproject, não no projeto padrão. A descrição é definida como This is my clustered table, e o rótulo é definido como organization:development. O comando usa o atalho -t em vez de --table. Esse comando não especifica a expiração da tabela. Se o conjunto de dados tiver uma expiração de tabela padrão, ela será aplicada. Caso contrário, a tabela nunca expirará.

O esquema é especificado em um arquivo JSON local: /tmp/myschema.json. O campo customer_id é usado para agrupar as tabelas.

bq mk \
    -t \
    --expiration 2592000 \
    --schema /tmp/myschema.json \
    --clustering_fields=customer_id \
    --description "This is my clustered table" \
    --label org:dev \
    myotherproject:mydataset.myclusteredtable

Após a criação da tabela, é possível atualizar a descrição e os rótulos da tabela.

Terraform

Use o recurso google_bigquery_table.

Observação: para criar objetos do BigQuery usando o Terraform, é necessário ativar a API Cloud Resource Manager.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

No exemplo a seguir, criamos uma tabela chamada mytable em agrupada em cluster nas colunas ID e Created:

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  clustering = ["ID", "Created"]

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  },
 {
   "name": "Created",
   "type": "TIMESTAMP"
 }
]
EOF

}

Para aplicar a configuração do Terraform em um projeto Google Cloud , siga as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto Google Cloud padrão em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

   Faça as correções necessárias na configuração.

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu Google Cloud projeto para conferir os resultados. No console Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

Observação:as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu Google Cloud projeto.

API

Chame o método tables.insert com um recurso de tabela definido que especifique a property clustering.fields e a property schema.

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.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

schema = [
    bigquery.SchemaField("full_name", "STRING"),
    bigquery.SchemaField("city", "STRING"),
    bigquery.SchemaField("zipcode", "INTEGER"),
]

table = bigquery.Table(table_id, schema=schema)
table.clustering_fields = ["city", "zipcode"]
table = client.create_table(table)  # Make an API request.
print(
    "Created clustered table {}.{}.{}".format(
        table.project, table.dataset_id, table.table_id
    )
)

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.

import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// createTableClustered demonstrates creating a BigQuery table with advanced properties like
// partitioning and clustering features.
func createTableClustered(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	sampleSchema := bigquery.Schema{
		{Name: "timestamp", Type: bigquery.TimestampFieldType},
		{Name: "origin", Type: bigquery.StringFieldType},
		{Name: "destination", Type: bigquery.StringFieldType},
		{Name: "amount", Type: bigquery.NumericFieldType},
	}
	metaData := &bigquery.TableMetadata{
		Schema: sampleSchema,
		TimePartitioning: &bigquery.TimePartitioning{
			Field:      "timestamp",
			Expiration: 90 * 24 * time.Hour,
		},
		Clustering: &bigquery.Clustering{
			Fields: []string{"origin", "destination"},
		},
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); err != nil {
		return err
	}
	return nil
}

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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Clustering;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;
import com.google.cloud.bigquery.TimePartitioning;
import com.google.common.collect.ImmutableList;

public class CreateClusteredTable {
  public static void runCreateClusteredTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    createClusteredTable(datasetName, tableName);
  }

  public static void createClusteredTable(String datasetName, String tableName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      TimePartitioning partitioning = TimePartitioning.of(TimePartitioning.Type.DAY);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      Clustering clustering =
          Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

      StandardTableDefinition tableDefinition =
          StandardTableDefinition.newBuilder()
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .setClustering(clustering)
              .build();
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Clustered table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Clustered table was not created. \n" + e.toString());
    }
  }
}

Criar uma tabela em cluster com base em um resultado de consulta

Há duas maneiras de criar uma tabela em cluster com base em um resultado da consulta:

• Grave os resultados em uma nova tabela de destino e especifique as colunas de clustering.
• Use uma instrução DDL CREATE TABLE AS SELECT. Para mais informações sobre esse método, consulte Como criar uma tabela em cluster usando o resultado de uma consulta na página Como usar instruções de linguagem de definição de dados .

É possível criar uma tabela em cluster consultando uma tabela particionada ou não particionada. Não é possível transformar uma tabela atual em uma particionada usando os resultados de consulta.

Quando uma tabela em cluster é criada a partir de um resultado de consulta, é necessário usar o SQL padrão. Atualmente, o SQL legado não é compatível com a consulta de tabelas em cluster ou com a gravação de resultados de consulta em tabelas em cluster.

SQL

Para criar uma tabela em cluster a partir do resultado da consulta, use a instrução DDL CREATE TABLE com a opção CLUSTER BY. O exemplo a seguir cria uma nova tabela em cluster por customer_id consultando uma tabela não em cluster atual:

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   CREATE TABLE mydataset.clustered_table
   (
     customer_id STRING,
     transaction_amount NUMERIC
   )
   CLUSTER BY
     customer_id
   AS (
     SELECT * FROM mydataset.unclustered_table
   );

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando a seguir para criar uma nova tabela de destino em cluster usando o resultado da consulta:

bq --location=LOCATION query \
    --use_legacy_sql=false 'QUERY'

Substitua:

• LOCATION: o nome do seu local. A sinalização --location é opcional. Por exemplo, se estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc.
• QUERY: uma consulta na sintaxe do GoogleSQL. No momento, não é possível usar o SQL legado para consultar tabelas em cluster ou gravar resultados de consulta nessas tabelas. A consulta pode conter uma instrução DDL CREATE TABLE que especifica as opções para criar sua tabela em cluster. Use o DDL em vez de especificar as sinalizações de linha de comando individuais.

Exemplos:

Digite o comando a seguir para gravar os resultados da consulta em uma tabela de destino em cluster denominada myclusteredtable em mydataset. mydataset está no projeto padrão. A consulta recupera dados de uma tabela não particionada: mytable. A coluna customer_id da tabela é usada para agrupar a tabela. A coluna timestamp da tabela é usada para criar uma tabela particionada.

bq query --use_legacy_sql=false \
    'CREATE TABLE
       mydataset.myclusteredtable
     PARTITION BY
       DATE(timestamp)
     CLUSTER BY
       customer_id
     AS (
       SELECT
         *
       FROM
         `mydataset.mytable`
     );'

API

Para salvar os resultados da consulta em uma tabela em cluster, chame o método jobs.insert, configure um job query e inclua uma instrução DDL CREATE TABLE que crie sua tabela em cluster.

Especifique seu local na property location da seção jobReference do recurso do job.

Criar uma tabela em cluster ao carregar dados

Ao carregar dados em uma nova tabela, é possível criar uma tabela em cluster especificando o agrupamento de colunas em cluster. Não é necessário criar uma tabela em branco para carregar os dados. Crie a tabela em cluster e carregue seus dados ao mesmo tempo.

Para mais informações sobre como carregar dados no BigQuery, acesse este link.

Para definir o clustering ao configurar um job de carga:

SQL

Use a instrução LOAD DATA. O exemplo a seguir carrega dados AVRO para criar uma tabela particionada pelo campo transaction_date e agrupada pelo campo customer_id. Ele também configura as partições para expirar após três dias.

1. No console do Google Cloud , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   LOAD DATA INTO mydataset.mytable
   PARTITION BY transaction_date
   CLUSTER BY customer_id
     OPTIONS (
       partition_expiration_days = 3)
   FROM FILES(
     format = 'AVRO',
     uris = ['gs://bucket/path/file.avro']);

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

API

Para definir uma configuração de clustering ao criar uma tabela por meio de um job de carga, preencha as propriedades Clustering da tabela.

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.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importClusteredTable demonstrates creating a table from a load job and defining partitioning and clustering
// properties.
func importClusteredTable(projectID, destDatasetID, destTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/sample-transactions/transactions.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "timestamp", Type: bigquery.TimestampFieldType},
		{Name: "origin", Type: bigquery.StringFieldType},
		{Name: "destination", Type: bigquery.StringFieldType},
		{Name: "amount", Type: bigquery.NumericFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field: "timestamp",
	}
	loader.Clustering = &bigquery.Clustering{
		Fields: []string{"origin", "destination"},
	}
	loader.WriteDisposition = bigquery.WriteEmpty

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Clustering;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TimePartitioning;
import com.google.common.collect.ImmutableList;

public class LoadTableClustered {

  public static void runLoadTableClustered() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    loadTableClustered(datasetName, tableName, sourceUri);
  }

  public static void loadTableClustered(String datasetName, String tableName, String sourceUri)
      throws Exception {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      TimePartitioning partitioning = TimePartitioning.of(TimePartitioning.Type.DAY);

      Clustering clustering =
          Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .setClustering(clustering)
              .build();

      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).build());

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Data successfully loaded into clustered table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Data not loaded into clustered table during load job \n" + e.toString());
    }
  }
}

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.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    skip_leading_rows=1,
    source_format=bigquery.SourceFormat.CSV,
    schema=[
        bigquery.SchemaField("timestamp", bigquery.SqlTypeNames.TIMESTAMP),
        bigquery.SchemaField("origin", bigquery.SqlTypeNames.STRING),
        bigquery.SchemaField("destination", bigquery.SqlTypeNames.STRING),
        bigquery.SchemaField("amount", bigquery.SqlTypeNames.NUMERIC),
    ],
    time_partitioning=bigquery.TimePartitioning(field="timestamp"),
    clustering_fields=["origin", "destination"],
)

job = client.load_table_from_uri(
    ["gs://cloud-samples-data/bigquery/sample-transactions/transactions.csv"],
    table_id,
    job_config=job_config,
)

job.result()  # Waits for the job to complete.

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

A seguir

• Para informações sobre como trabalhar com tabelas em cluster, consulte Gerenciar tabelas em cluster.
• Para mais informações sobre como consultar tabelas em cluster, consulte esta página.
• Para uma visão geral do suporte a tabelas particionadas no BigQuery, consulte esta página.
• Para saber como criar tabelas particionadas, consulte Como criar tabelas particionadas.
• Para ter uma visão geral do INFORMATION_SCHEMA, consulte Introdução ao BigQuery INFORMATION_SCHEMA.