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

Limitações

No BigQuery, as tabelas em cluster estão sujeitas às seguintes limitações:

• A consulta a tabelas em cluster e a gravação de resultados de consultas a tabelas em cluster são compatíveis apenas com o SQL padrão.
• A especificação das colunas de clustering é possível somente durante a criação de uma tabela.
• Após a criação de uma tabela em cluster, não é possível modificar as colunas de clustering.

• As colunas de clustering precisam ser de nível superior, sem repetição de um dos seguintes tipos:

  • DATE
  • BOOL
  • GEOGRAPHY
  • INT64
  • NUMERIC
  • STRING
  • TIMESTAMP

  Para mais informações sobre tipos de dados, consulte Tipos de dados do SQL padrão.

• É possível especificar até quatro colunas de clustering.

• Ao usar colunas com tipo STRING para clustering, o BigQuery usa apenas os primeiros 1.024 caracteres para agrupar os dados. Os valores nas colunas podem ser maiores que 1.024.

Como criar tabelas em cluster

É possível criar uma tabela em cluster no BigQuery:

• usando os resultados da consulta;
  • usando uma instrução DDL CREATE TABLE AS SELECT;
  • executando uma consulta que cria uma tabela de destino em cluster;
• usando uma instrução DDL CREATE TABLE com uma cláusula CLUSTER BY que contém uma clustering_column_list;
• usando manualmente o comando bq mk da ferramenta de linha de comando gcloud;
• chamando programaticamente o método de API tables.insert;
• ao carregar dados;
• usando as bibliotecas de cliente.

Nomenclatura de tabelas

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

• Conter até 1.024 caracteres
• conter letras (maiúsculas e minúsculas), números e sublinhados.

Permissões necessárias

Para criar uma tabela, você precisa ter pelo menos as seguintes permissões:

• bigquery.tables.create para criar a tabela
• bigquery.tables.updateData para gravar dados na tabela usando um job de carregamento, de consulta ou de cópia.
• bigquery.jobs.create para executar jobs de consulta, de carregamento ou de cópia que gravem os dados na tabela

Outras permissões, como bigquery.tables.getData, são necessárias para acessar os dados que você está gravando na tabela.

Os seguintes papéis predefinidos do Cloud IAM incluem permissões bigquery.tables.create e bigquery.tables.updateData:

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

Os seguintes papéis predefinidos do Cloud IAM incluem permissões bigquery.jobs.create:

• bigquery.user
• bigquery.jobUser
• bigquery.admin

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário crie e atualize tabelas no conjunto de dados.

Para mais informações sobre os papéis e permissões do Cloud IAM no BigQuery, acesse este link.

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

Ao criar um tabela no BigQuery, você especifica o agrupamento de colunas em cluster. Depois que a tabela for criada, as colunas de clustering poderão ser modificadas. 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
• 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.

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 IU da Web do BigQuery.

   Acesse a IU da Web do BigQuery

2. Na seção Recursos do painel de navegação, expanda o projeto e selecione um conjunto de dados.

3. No lado direito da janela, no painel de detalhes, clique em Criar tabela.

   

4. Na página Criar tabela, em Criar tabela de: abaixo de Origem, selecione Tabela vazia.

   

5. Em Destino, siga estas instruções:

   • Em Nome do conjunto de dados, escolha o conjunto de dados apropriado e, no campo Nome da tabela, insira o nome da tabela que você está criando.
   • Verifique se o Tipo de tabela está definido como Tabela nativa.

6. Abaixo de Esquema, digite a definição do esquema.

   • Para inserir as informações do esquema manualmente:

     • Ative Editar como texto e insira o esquema da tabela como uma matriz JSON.

       Observação: é possível visualizar o esquema de uma tabela existente no formato JSON digitando o seguinte comando de interface de linha de comando: bq show --format=prettyjson dataset.table.

     • Use Adicionar campo para inserir manualmente o esquema.

7. (Opcional) Em Configurações de particionamento e cluster, selecione Partição por campo e escolha a coluna DATE or TIMESTAMP. A opção estará indisponível se o esquema não incluir uma coluna DATE ou TIMESTAMP.

   Para criar uma tabela particionada por tempo de ingestão, selecione Partição por tempo de processamento.

8. Opcional: em Filtro de particionamento, clique na caixa de seleção Exigir filtro de particionamento para solicitar que os usuários incluam uma cláusula WHERE que especifique as partições a serem consultadas. A exigência de um filtro de partição pode reduzir os custos e melhorar o desempenho. Para mais informações, veja Como consultar tabelas particionadas.

9. Em Ordem de clustering, insira de um a quatro nomes de coluna separados por vírgulas.

10. Opcional: clique em Opções avançadas e, para Criptografia, selecione Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você escolher a configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.

11. Clique em Criar tabela.

Observação: ao criar uma tabela particionada vazia usando o Console do Cloud, não é possível adicionar um rótulo ou uma descrição, além de uma expiração da tabela ou da partição. Você pode adicionar essas propriedades opcionais quando cria uma tabela usando a interface de linha de comando ou a API.

Após a criação da tabela, é possível atualizar a expiração da tabela, a descrição e os rótulos da tabela particionada. Não é possível adicionar uma expiração de partição após a criação de uma tabela no Console do Cloud.

IU clássica

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

   Acesse a IU da Web clássica do BigQuery

2. No painel de navegação, clique no ícone de seta para baixo ao lado do nome do conjunto de dados e selecione Criar nova tabela.

3. Na página Criar tabela, na seção Dados de origem, clique em Criar tabela em branco.

4. Na página Criar tabela, na seção Tabela de destino:

   • Em Nome da Tabela, escolha o conjunto de dados apropriado e, no campo adequado, insira o nome da tabela que você está criando.
   • Verifique se o Tipo de tabela está definido como Tabela nativa.

5. Na seção Esquema, insira manualmente a definição do esquema.

   • É possível inserir informações de esquema manualmente com um destes procedimentos:

     • Clique em Editar como texto e insira o esquema da tabela como uma matriz JSON.

       Observação: é possível ver o esquema de uma tabela atual no formato JSON. Basta digitar o seguinte comando:

       bq show
          --schema
          --format=prettyjson
       project_id:dataset.table

       .

     • Use Adicionar campo para inserir o esquema.

6. Em Opções, siga estas instruções:

   • Em Tipo de particionamento, clique em Nenhum e escolha Dia.
   • No Campo de particionamento, escolha uma das seguintes opções:
     • timestamp para criar uma tabela particionada por uma coluna DATE ou TIMESTAMP.
     • _PARTITIONTIME para criar uma tabela particionada por tempo de ingestão.
   • Nos Campos de clustering, insira de um a quatro nomes de campo.

   • Em Criptografia de destino, mantenha a opção Default. Essa propriedade refere-se a chaves de criptografia gerenciadas pelo cliente. Por padrão, o BigQuery criptografa o conteúdo do cliente armazenado em repouso.

     

7. Clique em Criar tabela.

Observação: quando você cria uma tabela em cluster vazia usando a IU da Web do BigQuery, não é possível adicionar um rótulo ou descrição, além de uma expiração da tabela ou da partição. É possível adicionar essas propriedades opcionais quando cria uma tabela usando a interface de linha de comando ou a API.

Após criar a tabela, atualize a expiração, a descrição e os rótulos dela. Não é possível adicionar a validade de partição após a criação de uma tabela usando a IU da Web do BigQuery.

bq

Use o comando 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 \
--time_partitioning_type=DAY \
--time_partitioning_field PARTITION_COLUMN \
--clustering_fields CLUSTER_COLUMNS \
--time_partitioning_expiration INTEGER2 \
--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 tempo de expiração é a soma do horário UTC atual com o valor inteiro. Se você definir o tempo de expiração ao criar uma tabela particionada por tempo, a configuração padrão de expiração da tabela do conjunto de dados será ignorada. Definir esse valor exclui a tabela e todas as partições 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.
• PARTITION_COLUMN: o nome da coluna TIMESTAMP ou DATE usada para criar uma tabela particionada. Se você criar uma tabela particionada, não precisará especificar a sinalização --time_partitioning_type=DAY.
• CLUSTER_COLUMNS: uma lista separada por vírgulas de até quatro colunas de clustering. A lista não pode conter espaços.
• INTEGER2: a vida útil padrão, em segundos, para as partições da tabela. Não há valor mínimo. O tempo de expiração é determinado pela data da partição acrescida do valor do número inteiro. A expiração da partição é independente da expiração da tabela, mas não a modifica. Se você definir uma validade de partição maior que a validade da tabela, a validade da tabela terá precedência.
• 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 particionada 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 tabela é particionada por uma coluna TIMESTAMP. A expiração do particionamento é configurada para 86.400 segundos (um dia), 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 partições.

bq mk -t \
--expiration 2592000 \
--schema 'timestamp:timestamp,customer_id:string,transaction_amount:float' \
--time_partitioning_field timestamp \
--clustering_fields customer_id \
--time_partitioning_expiration 86400  \
--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 tabela é uma particionada por tempo de ingestão. A expiração do particionamento é configurada para 259.200 segundos (três dias), a descrição é definida como This is my partitioned 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á, mas as partições expirarão em três dias.

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

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

Depois da criação da tabela, atualize a expiração da tabela e da partição, a descrição e os rótulos da tabela particionada.

API

Chame o método tables.insert com um recurso de tabela definido que especifique as propriedades timePartitioning, clustering.fields e schema.

Go

Antes de testar essa 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 (em inglês).

Ver no GitHub Feedback

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 essa 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 (em inglês).

Ver no GitHub Feedback

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());
    }
  }
}

Como 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:

• Gravar os resultados em uma nova tabela de destino e especificar as colunas do agrupamento em cluster. Esse método é discutido abaixo.
• 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.

Console

Não é possível especificar opções de clustering para uma tabela de destino ao consultar dados usando a IU da Web do BigQuery no console, a menos que você use uma instrução DDL. Para mais informações, consulte Como usar instruções de linguagem de definição de dados.

IU clássica

Não é possível especificar opções de clustering para uma tabela de destino ao consultar dados usando a IU da Web clássica do BigQuery, a não ser que você use uma instrução DDL. Para mais informações, consulte Como usar instruções de linguagem de definição de dados.

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 SQL padrão. 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.

Como 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. É possível criar a tabela em cluster e carregar 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:

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 essa 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 (em inglês).

Ver no GitHub Feedback

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 essa 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 (em inglês).

Ver no GitHub Feedback

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());
    }
  }
}

Como 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):

• Um nível alto na hierarquia de recursos do Google Cloud, como o nível do projeto, da pasta ou da organização
• O nível do conjunto de dados
• O nível da tabela/visualização

O acesso com qualquer recurso protegido pelo Cloud IAM é um adicional. 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 acesso no nível alto ou no nível do conjunto de dados, uma opção será conceder acesso à entidade no nível da tabela/visualização.

Conceder papéis do Cloud IAM em um nível superior na hierarquia de recursos do Google Cloud, como o nível do projeto, da pasta ou da 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.

Também é possível criar papéis personalizados do Cloud 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 qualquer recurso protegido pelo Cloud IAM.

Para saber mais sobre papéis e permissões, consulte:

• Como entender os papéis na documentação do Cloud IAM
• Permissões e papéis predefinidos do BigQuery
• Como controlar o acesso a conjuntos de dados
• Como controlar o acesso a tabelas e visualizações
• Como restringir o acesso com a segurança no nível da coluna do BigQuery

Como usar tabelas em cluster

Como conseguir informações sobre tabelas em cluster

Para ver mais informações sobre tabelas:

• Use o Console do Cloud ou a IU da Web clássica do BigQuery
• Use o comando de interface da linha de comando bq show
• chame o método tables.get da API;
• consulte visualizações INFORMATION_SCHEMA.

Permissões necessárias

No mínimo, para ver informações sobre tabelas, você precisa receber as permissões bigquery.tables.get. Os papéis predefinidos do Cloud IAM a seguir incluem permissões bigquery.tables.get:

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

Além disso, se um usuário tiver permissões bigquery.datasets.create ao criar um conjunto de dados, será concedido o acesso bigquery.dataOwner. O acesso bigquery.dataOwner permite que o usuário receba informações sobre tabelas em um conjunto de dados.

Para mais informações sobre as permissões e os papéis predefinidos do Cloud IAM no BigQuery, acesse este link.

Como conseguir informações de tabelas 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.

   

IU clássica

1. No painel de navegação, clique no ícone de seta para baixo à esquerda do conjunto de dados para expandi-lo, ou clique duas vezes no nome do conjunto de dados. Fazer isso exibe as tabelas e visualizações no conjunto de dados.

2. Clique no nome da tabela.

3. Clique em Detalhes. A página Detalhes da tabela contém os detalhes correspondentes, incluindo as colunas de clustering.

   

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.

SQL

Nas tabelas em cluster, é possível consultar a coluna CLUSTERING_ORDINAL_POSITION na visualização INFORMATION_SCHEMA.COLUMNS para recuperar informações sobre as colunas de clustering de uma tabela.

-- Set up a table with clustering.
CREATE TABLE myDataset.data (column1 INT64, column2 INT64)
PARTITION BY _PARTITIONDATE
CLUSTER BY column1, column2;

-- This query returns 1 for column1 and 2 for column2.
SELECT column_name, clustering_ordinal_position
FROM myDataset.INFORMATION_SCHEMA.COLUMNS;

Mais metadados da tabela estão disponíveis nas visualizações TABLES, TABLE_OPTIONS, COLUMNS e COLUMN_FIELD_PATH em INFORMATION_SCHEMA.

Como listar tabelas em cluster em um conjunto de dados

Para fazer isso:

• Use o Console do Cloud ou a IU da Web clássica do BigQuery
• Use o comando de interface da linha de comando bq ls
• Chame o método tables.list da API.
• Use as bibliotecas de cliente.
• consulte a coluna CLUSTERING_ORDINAL_POSITION na visualização INFORMATION_SCHEMA.COLUMNS.

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

Como modificar a especificação de clustering

Ao chamar os métodos tables.update ou tables.patch, as especificações de clustering da tabela podem ser alteradas ou removidas. O conjunto de colunas em cluster em uma tabela em cluster também pode ser alterado para um conjunto diferente de colunas. Esse método de atualização do conjunto de colunas em cluster é mais útil para tabelas com inserções de streaming contínuas, porque elas não podem ser facilmente trocadas.

Quando uma tabela é convertida de não-cluster para cluster ou o conjunto de colunas em cluster é alterado, o novo cluster automático só funciona dali em diante. Por exemplo, uma tabela de 1 PB sem cluster convertida em uma tabela em cluster usando tables.update ainda tem 1 PB de dados sem cluster. O reclustering automático se aplica somente aos novos dados alocados à tabela após a atualização

A seguir

• 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 Introdução a tabelas particionadas.
• Para saber como criar e usar tabelas particionadas por tempo de ingestão, consulte Como criar e usar tabelas particionadas por tempo de ingestão.
• Para saber como criar e usar tabelas particionadas, acesse este link.
• Acesse Introdução ao BigQuery INFORMATION_SCHEMA para uma visão geral de INFORMATION_SCHEMA.