Criar e usar tabelas em cluster

Neste documento, descrevemos como criar e usar tabelas em cluster no BigQuery. Para uma visão geral do suporte a tabelas em cluster no BigQuery, consulte Introdução às tabelas em cluster.

Crie tabelas em cluster

É possível criar uma tabela em cluster usando os seguintes métodos:

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

Permissões necessárias

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.

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

Ao criar um tabela no BigQuery, você especifica o agrupamento de colunas em cluster. Após a criação da tabela, é possível modificar as colunas de clustering. 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 simples:

  • DATE
  • BOOLEAN
  • GEOGRAPHY
  • INTEGER
  • NUMERIC
  • BIGNUMERIC
  • STRING
  • TIMESTAMP
  • RANGE (visualização)

É 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.

Para criar uma tabela em cluster vazia com uma definição de esquema, siga estas instruções:

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 uma chave pertencente e gerenciada pelo Google.
    6. Selecione 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.

    Ir para 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.

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 do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o projeto padrão do Google Cloud 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 projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

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:

É 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.

    Ir para 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.

    Ir para 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
    )
)

Controlar o acesso a tabelas em cluster

Para configurar o acesso a tabelas e visualizações, conceda um papel do IAM a uma entidade nos seguintes níveis, listados em ordem de intervalo de recursos permitidos (do maior para o menor):

Também é possível restringir o acesso a dados nas tabelas usando os métodos a seguir:

O acesso a qualquer recurso protegido pelo IAM é aditivo. Por exemplo, se uma entidade não tiver acesso no nível alto, como o projeto, uma opção será conceder à entidade o acesso no nível do conjunto de dados, e ela terá acesso às tabelas e visualizações no conjunto de dados. Da mesma forma, se a entidade não tiver nível acesso alto ou ao conjunto de dados, você tem a opção de conceder acesso à tabela/visualização.

A concessão de papéis do IAM em um nível mais alto na hierarquia de recursos do Google Cloud, como projeto, pasta ou organização, concede à entidade acesso a um amplo conjunto de recursos. Por exemplo, conceder um papel a uma entidade no nível do projeto fornece a ela permissões referentes aos conjuntos de dados em todo o projeto.

Conceder um papel no nível do conjunto de dados especifica as operações que uma entidade tem permissão de realizar em tabelas e define as visualizações nesse conjunto de dados específico, mesmo que a entidade não tenha acesso em um nível superior. Para informações sobre como configurar controles de acesso no nível do conjunto de dados, consulte este link.

A concessão de um papel no nível da tabela ou da visualização especifica as operações que uma entidade pode realizar em tabelas e visualizações específicas, mesmo que a entidade não tenha acesso em um nível superior. Para informações sobre como configurar controles de acesso no nível da tabela e da visualização, consulte este link.

Você também pode criar papéis personalizados do IAM. Se você criar um papel personalizado, as permissões concedidas dependerão das operações específicas que a entidade poderá executar.

Não é possível definir uma permissão "deny" em nenhum recurso protegido pelo IAM.

Para mais informações sobre papéis e permissões, consulte Noções básicas sobre papéis na documentação do IAM e os papéis e permissões do IAM do BigQuery.

Usar tabelas em cluster

Receber informações sobre tabelas em cluster

É possível conseguir informações sobre tabelas das seguintes maneiras:

Permissões necessárias

Para ver informações sobre tabelas, é preciso ter pelo menos as permissões bigquery.tables.get. Os seguintes papéis predefinidos do IAM incluem as permissões bigquery.tables.get:

  • bigquery.metadataViewer
  • bigquery.dataViewer
  • bigquery.dataOwner
  • bigquery.dataEditor
  • bigquery.admin

Além disso, quando um usuário tem permissões bigquery.datasets.create e cria um conjunto de dados, ele recebe o acesso bigquery.dataOwner ao conjunto. O acesso bigquery.dataOwner permite que o usuário receba informações sobre tabelas em um conjunto de dados.

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

Receber informações da tabela em cluster

Para ver informações sobre uma tabela em cluster, faça o seguinte:

Console

  1. No console do Google Cloud, acesse o painel Recursos. Clique no nome do conjunto de dados para expandi-lo e, em seguida, selecione o nome da tabela que você quer visualizar.

  2. Clique em Detalhes. Essa página exibe os detalhes da tabela, incluindo as colunas de clustering.

    Detalhes da tabela

SQL

Para tabelas em cluster, consulte a coluna CLUSTERING_ORDINAL_POSITION na visualização INFORMATION_SCHEMA.COLUMNS para encontrar o deslocamento de índice 1 da coluna nas colunas de clustering da tabela:

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

    Ir para o BigQuery

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

    CREATE TABLE mydataset.data (column1 INT64, column2 INT64)
CLUSTER BY column1, column2;
SELECT
  column_name, clustering_ordinal_position
FROM
  mydataset.INFORMATION_SCHEMA.COLUMNS;

  3. Clique em Executar.

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

A posição ordinal do clustering é 1 para column1 e 2 para column2. Mais metadados da tabela estão disponíveis nas visualizações TABLES, TABLE_OPTIONS, COLUMNS e COLUMN_FIELD_PATH em INFORMATION_SCHEMA.

bq

Emita o comando bq show para exibir todas as informações da tabela. Use a sinalização --schema para exibir somente informações de esquema da tabela. A sinalização --format pode ser usada para controlar a saída.

Se você estiver recebendo informações sobre 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.

bq show \
    --schema \
    --format=prettyjson \
    PROJECT_ID:DATASET.TABLE

Substitua:

  • PROJECT_ID: o ID do projeto
  • DATASET: o nome do conjunto de dados
  • TABLE: o nome da tabela

Exemplos:

Digite o comando a seguir para exibir todas as informações sobre myclusteredtable em mydataset. mydataset está no seu projeto padrão.

bq show --format=prettyjson mydataset.myclusteredtable

A saída será semelhante a esta: 

{
  "clustering": {
    "fields": [
      "customer_id"
    ]
  },
...
}

API

Chame o método bigquery.tables.get e forneça os parâmetros relevantes.

Listar tabelas em cluster em um conjunto de dados

É possível listar tabelas em cluster nos conjuntos de dados das seguintes maneiras:

  • Usando o Console do Google Cloud.
  • Use o comando bq ls da ferramenta de linha de comando bq.
  • faça uma chamada do método de API tables.list;
  • usando as bibliotecas de cliente;
  • consultando a coluna CLUSTERING_ORDINAL_POSITION na visualização INFORMATION_SCHEMA.COLUMNS.

As permissões e as etapas necessárias para listar tabelas em cluster são as mesmas das tabelas padrão. Para mais informações sobre como listar tabelas, consulte Como listar tabelas em um conjunto de dados.

Modificar a especificação de clustering

É possível alterar ou remover as especificações de clustering de uma tabela ou alterar o conjunto de colunas em cluster em uma tabela em cluster. Esse método de atualização do conjunto de colunas em cluster é útil para tabelas que usam inserções de streaming contínuas, porque essas tabelas não podem ser facilmente alternadas por outros métodos.

Siga estas etapas para aplicar uma nova especificação de clustering a tabelas não particionadas ou particionadas.

  1. Na ferramenta bq, atualize a especificação de clustering da tabela para corresponder ao novo clustering:

     bq update --clustering_fields=CLUSTER_COLUMN DATASET.ORIGINAL_TABLE

    Substitua:

    • CLUSTER_COLUMN: a coluna que você está agrupando, por exemplo, mycolumn.
    • DATASET: o nome do conjunto de dados que contém a tabela. Por exemplo, mydataset
    • ORIGINAL_TABLE: o nome da tabela original, por exemplo, mytable

    Também é possível chamar o método de API tables.update ou tables.patch para modificar a especificação de clustering.

  2. Para agrupar todas as linhas de acordo com a nova especificação de clustering, execute a seguinte instrução UPDATE:

    UPDATE DATASET.ORIGINAL_TABLE SET CLUSTER_COLUMN=CLUSTER_COLUMN WHERE true

Segurança de tabelas

Para controlar o acesso a tabelas no BigQuery, consulte Introdução aos controles de acesso a tabelas.

A seguir