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.

  • 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 das seguintes maneiras:

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

Por exemplo, os nomes de tabela a seguir são válidos: table-01, ग्राहक, 00_お客様, étudiant.

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 IAM incluem as permissões bigquery.tables.create e bigquery.tables.updateData:

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

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

  • bigquery.user
  • bigquery.jobUser
  • 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 crie e atualize tabelas no conjunto de dados.

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

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. 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
  • 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 página do BigQuery.

    Acessar a página 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.

    Botão

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

    Opção

  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 Table type está definido como Native table.

  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.

      • 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 ou 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.

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

Python

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

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 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 em Go. 

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 em Java. 

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:

É 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 o Console do Cloud, 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.

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

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 em Go. 

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 em Java. 

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

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

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

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

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 estes tópicos:

Como usar tabelas em cluster

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

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.

    Detalhes da tabela

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

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

  • usando o Console do Cloud;
  • usando o comando bq da ferramenta de linha de comando bq ls;
  • 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 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 confirmados na tabela após a atualização.

Próximas etapas