Como criar e usar tabelas em cluster

Neste documento, descreveremos como criar e usar tabelas em cluster no BigQuery.

Limitações

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

  • Atualmente o agrupamento em cluster é compatível apenas com tabelas particionadas.
  • 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 do agrupamento de colunas em cluster só é possível durante a criação de uma tabela.
  • Depois que uma tabela em cluster é criada, o agrupamento de colunas em cluster não pode ser modificado.
  • O agrupamento de colunas em cluster precisa ser de nível superior, as colunas não podem ser repetidas e precisam ser de um dos seguintes tipos: INT64, STRING, DATE, TIMESTAMP, BOOL ou NUMERIC. Para mais informações sobre os tipos de dados, consulte Tipos de dados do SQL padrão.
  • É possível especificar até quatro agrupamentos de colunas em cluster.

Como criar tabelas em cluster

Atualmente, só é possível agrupar tabelas particionadas. Isso inclui tabelas particionadas por tempo de ingestão e tabelas particionadas por uma coluna TIMESTAMP ou DATE.

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

Ao criar uma tabela no BigQuery, ela precisa ter um nome 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 exigidas

Para criar uma tabela em cluster, é necessário ter o acesso WRITER no nível do conjunto de dados ou um papel de IAM para envolvidos no projeto que inclua permissões bigquery.tables.create. Os seguintes papéis predefinidos do IAM do projeto incluem permissões bigquery.tables.create:

Além disso, como a função bigquery.user tem permissões bigquery.datasets.create, um usuário a quem tiver sido atribuído o papel bigquery.user pode criar tabelas em cluster em qualquer conjunto de dados que criar. Por padrão, quando um usuário com o papel bigquery.user cria um conjunto de dados, ele recebe acesso OWNER a esse conjunto. O acesso OWNER a um conjunto de dados concede ao usuário controle total sobre o conjunto e todas as tabelas nele contidas.

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

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 foi criada, não é possível modificar esse agrupamento. Atualmente, só é possível especificar o agrupamento de colunas em cluster para uma tabela particionada.

O agrupamento de colunas em cluster precisa ser de nível superior, as colunas não podem ser repetidas e precisam ser de um dos seguintes tipos de dados simples: INTEGER, STRING, DATE, TIMESTAMP, BOOLEAN ou NUMERIC.

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

A ordem do agrupamento de colunas em cluster também afeta o desempenho e o preço das consultas. Para mais informações sobre as práticas recomendadas para consulta de tabelas em cluster, veja Como consultar tabelas em cluster.

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

Console

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

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

  3. No lado direito da janela, no painel de detalhes, clique em Criar tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.

    Adicionar esquema usando campos de adição

  4. Na página Criar tabela, na seção Origem, em Criar tabela a partir de, selecione Tabela vazia .

    Adicionar esquema usando campos de adição

  5. Na página Criar tabela, na seção Destino:

    • 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 no BigQuery.

      Adicionar esquema usando campos de adição

    • Verifique se o Tipo de tabela está definido como Tabela nativa.

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

    • Insira as informações do esquema manualmente usando um dos seguintes métodos:

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

      • Use Adicionar campo para inserir manualmente o esquema.

  7. Na seção Configurações de particionamento e cluster:

    • Em Particionamento, selecione Partição por tempo de ingestão.

      Adicionar esquema usando campos de adição

    • Em Ordem de agrupamento, insira entre um e quatro nomes de campos separados por vírgulas.

  8. Clique em Criar tabela.

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

IU clássica

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

    Acesse a IU da Web clássica do BigQuery

  2. Clique no ícone de seta para baixo ícone de seta para baixo ao lado do nome do conjunto de dados na navegação e em Criar nova tabela.

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

  4. Na página Create Table, na seção Destination Table:

    • Em Table name, 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.

      • Use Add Field para inserir o esquema:

  6. Na seção Options, faça o seguinte:

    • Para Partitioning Type, clique em None e escolha Day.
    • Para Partitioning Field, escolha uma das seguintes opções:
      • Escolha timestamp para criar uma tabela particionada por uma coluna DATE ou TIMESTAMP.
      • Escolha _PARTITIONTIME para criar uma tabela particionada por tempo de ingestão.
    • Para Clustering columns, insira de um a quatro nomes de campo.
    • Em Tipo de criptografia, deixe a opção Default. Esta propriedade é para chaves de criptografia gerenciadas pelo cliente. Por padrão, o BigQuery criptografa o conteúdo do cliente armazenado em repouso.

      Detalhes da tabela particionada

  7. Clique em Criar tabela.

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

Linha de comando

Use o comando mk com as sinalizações a seguir:

  • --table (ou o atalho -t).
  • --schema &mdash: é possível fornecer a definição de esquema da tabela in-line ou por meio de um arquivo de esquema JSON.
  • --time_partitioning_type (para tabelas particionadas por tempo de ingestão) ou --time_partitioning_field (para tabelas particionadas). Atualmente, DAY é o único valor compatível com --time_partitioning_type.
  • --clustering_fields para especificar até quatro agrupamentos de colunas.

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

Se você estiver criando uma tabela em um projeto diferente do projeto padrão, adicione o código do projeto ao conjunto de dados no formato a seguir: [PROJECT_ID]:[DATASET].

--destination_kms_key não é demonstrado aqui. Para mais informações sobre como usar essa sinalização, 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 [COLUMN] --clustering_fields [COLUMNS] --time_partitioning_expiration [INTEGER2] --description "[DESCRIPTION]" --label [KEY:VALUE, KEY:VALUE] [PROJECT_ID]:[DATASET].[TABLE]

Em que:

  • [INTEGER1] é a vida útil padrão em segundos da tabela. O valor mínimo é de 3.600 segundos (uma hora). O tempo de expiração é avaliado para a hora atual mais 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] é a definição de esquema in-line no formato [FIELD]:[DATA_TYPE],[FIELD]:[DATA_TYPE] ou o caminho para o arquivo de esquema JSON na máquina local;
  • [COLUMN] é o nome da coluna TIMESTAMP ou DATE, usada para criar uma tabela particionada. Se você criar uma tabela particionada, não precisará especificar o --time_partitioning_type=DAY;
  • [COLUMNS] é uma lista separada por vírgulas de até quatro agrupamentos de colunas em cluster;
  • [INTEGER2] é a vida útil padrão (em segundos) para as partições da tabela. Não há valor mínimo. A data de validade é avaliada para a data da partição acrescida deste valor. A expiração da partição é independente da expiração da tabela, mas não a substitui. Se você definir uma expiração de partição mais longa do que a expiração da tabela, a expiração 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. Você pode inserir vários marcadores usando uma lista separada por vírgulas;
  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é um conjunto de dados no projeto;
  • [TABLE] é o nome da tabela particionada que você está criando.

Ao especificar o esquema na linha de comando, não é possível incluir um tipo RECORD (STRUCT) nem uma descrição de coluna. Também não é possível especificar o modo da coluna. Todos os modos assumem NULLABLE como padrão. Para incluir tipos RECORD, descrições e modos, 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 é uma tabela particionada por uma coluna TIMESTAMP. A expiração do particionamento é configurada para 86.400 segundos (um dia), a expiração da tabela é definida como 2.592.000 (um mês de 30 dias), a descrição é definida como This is my clustered table e o marcador é 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 agrupamento especificado customer_id é 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 comando a seguir para criar uma tabela em cluster chamada myclusteredtable em myotherproject, não no seu projeto padrão. A tabela é uma tabela 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 marcador é 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

Após criar a tabela particionada, atualize a validade dela, a validade da partição, a descrição e os rótulos.

API

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

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API do BigQuery para Go.

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

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. Este método é discutido abaixo.
  • Usando uma instrução DDL CREATE TABLE AS SELECT. Para mais informações sobre esse método, consulte Como criar uma tabela em cluster a partir do resultado de uma consulta na página "Como usar declaraçõ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 existente 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 agrupamento em cluster para uma tabela de destino ao consultar dados usando a IU da web do BigQuery do console, a menos que você use uma instrução DDL. Para mais informações, consulte Como usar declarações de linguagem de definição de dados.

IU clássica

Não é possível especificar opções de agrupamento em cluster 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 declarações de linguagem de definição de dados.

CLI

Digite o comando bq query e especifique as seguintes sinalizações:

  • Especifique a sinalização use_legacy_sql=false para usar a sintaxe SQL padrão.
  • Forneça a sinalização --location e defina o valor como o local.

Use o seguinte comando para criar uma nova tabela de destino em cluster a partir do resultado da consulta:

    bq --location=[LOCATION] query --use_legacy_sql=false '[QUERY]'

Em que:

  • [LOCATION] é o nome do seu local. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, poderá definir o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • [QUERY] é uma consulta na sintaxe SQL padrão. Não é possível usar o SQL legado para consultar tabelas em cluster ou gravar resultados de consulta nessas tabelas. É possível que a consulta contenha uma instrução DDL CREATE TABLE que especifica as opções para criar a 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. O 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 --location=US 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 de query e inclua uma instrução DDL CREATE TABLE que cria sua tabela em cluster.

Especifique o local na propriedade 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 vazia para carregar os dados. Crie a tabela em cluster e carregue seus dados ao mesmo tempo.

Para mais informações sobre como carregar dados, consulte Introdução ao carregamento de dados no BigQuery.

Para definir o armazenamento em cluster ao definir um job de carga:

API

Para definir a configuração de agrupamento em cluster ao criar uma tabela por meio de um job de carregamento, você pode preencher a mensagem configuration.load.clustering, preenchendo a propriedade configuration.load.clustering.Fields com até quatro colunas de agrupamento em cluster em ordem de prioridade.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Início rápido do BigQuery: como usar bibliotecas de cliente. Para saber mais informações, consulte a documentação de referência da API do BigQuery para Go.

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

Como controlar o acesso a tabelas em cluster

Não é possível atribuir controles de acesso diretamente a tabelas em cluster ou a partições. Controle o acesso à tabela configurando controles de acesso no conjunto de dados ou no projeto.

Os controles de acesso no nível do conjunto de dados especificam quais operações usuários, grupos e contas de serviço podem executar nas tabelas nesse conjunto de dados específico. Se você atribuir apenas permissões no nível do conjunto de dados, também precisará atribuir um papel primitivo ou predefinido para envolvidos no projeto que forneça acesso a ele. Por exemplo, bigquery.user.

Em vez de conceder acesso a conjuntos de dados individuais, você pode atribuir papéis do IAM predefinidos para envolvidos no projeto que concedem permissões aos dados de todas as tabelas em todos os conjuntos de dados de um projeto.

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 da tabela que você quer atribuir ao usuário, grupo ou a conta de serviço.

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

Para conseguir informações sobre tabelas, faça o seguinte:

  • Use o Console do GCP ou a IU da Web clássica do BigQuery.
  • Use o comando bq show da CLI.
  • Chame o método de API tables.get.
  • Consulte as visualizações INFORMATION_SCHEMA (Beta).

Permissões exigidas

Para informações sobre tabelas, é necessário ter o acesso de READER no nível do conjunto de dados ou um papel do IAM para envolvidos no projeto que inclua permissões bigquery.tables.get. Se você tem permissões bigquery.tables.get no nível do projeto, pode acessar informações sobre todas as tabelas do projeto. Todos os papéis predefinidos do IAM para envolvidos no projeto incluem permissões bigquery.tables.get, exceto bigquery.jobUser e bigquery.user.

Além disso, um usuário com papel bigquery.user tem permissões bigquery.datasets.create. Isso permite que um usuário com o papel bigquery.user receba informações sobre tabelas em qualquer conjunto de dados criado por ele. Quando um usuário com o papel bigquery.user cria um conjunto de dados, ele recebe o acesso OWNER ao conjunto. O acesso OWNER a um conjunto de dados concede ao usuário controle total sobre o conjunto e todas as tabelas contidas nele.

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

Como conseguir informações de tabelas em cluster

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

Console

  1. No painel Recursos, clique no nome do seu conjunto de dados para expandi-lo e, em seguida, clique no nome da tabela que você quer visualizar.

  2. Clique em Detalhes. Esta página exibe os detalhes da tabela, incluindo as colunas de agrupamento em cluster.

    Detalhes da tabela

IU clássica

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

  2. Clique no nome da tabela.

  3. Clique em Detalhes. Na página Detalhes da tabela são exibidas informações, incluindo as colunas de clustering.

    Detalhes de tabelas em cluster

Linha de comando

Emita o comando bq show para exibir todas as informações da tabela. Use a sinalização --schema para exibir apenas informações de esquema de 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 padrão, adicione o código do projeto ao conjunto de dados no formato abaixo: [PROJECT_ID]:[DATASET].

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

Em que:

  • [PROJECT_ID] é o código 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. O mydataset está no projeto padrão.

bq show --format=prettyjson mydataset.myclusteredtable

O esquema será semelhante a este:

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

API

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

Como receber informações da tabela em cluster usando INFORMATION_SCHEMA (Beta)

INFORMATION_SCHEMA é uma série de visualizações que fornece acesso a metadados sobre conjuntos de dados, tabelas e visualizações.

É possível consultar as visualizações INFORMATION_SCHEMA.TABLES e INFORMATION_SCHEMA.TABLE_OPTIONS para recuperar metadados sobre tabelas e visualizações em um projeto. Também é possível consultar as visualizações INFORMATION_SCHEMA.COLUMNS e INFORMATION_SCHEMA.COLUMN_FIELD_PATHS para recuperar metadados sobre as colunas (campos) de uma tabela.

Para tabelas em cluster, consulte a coluna CLUSTERING_ORDINAL_POSITION na visualização INFORMATION_SCHEMA.COLUMNS para recuperar informações sobre as colunas de cluster.

Visualização TABLES

Quando consultamos a visualização INFORMATION_SCHEMA.TABLES, os resultados contêm uma linha para cada tabela ou visualização no conjunto de dados.

As consultas na visualização INFORMATION_SCHEMA.TABLES precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas ou visualizações.

A visualização INFORMATION_SCHEMA.TABLES tem o seguinte esquema:

Nome da coluna Tipo de dado Valor
TABLE_CATALOG STRING O nome do projeto que contém o conjunto de dados.
TABLE_SCHEMA STRING O nome do conjunto de dados que contém a tabela ou visualização, também conhecido como o datasetId.
TABLE_NAME STRING O nome da tabela ou visualização, também conhecido como o tableId.
TABLE_TYPE STRING O tipo de tabela:
IS_INSERTABLE_INTO STRING YES ou NO, dependendo da compatibilidade da tabela com instruções DML INSERT.
IS_TYPED STRING O valor sempre é NO.
CREATION_TIME TIMESTAMP O horário de criação da tabela.

Exemplos

Exemplo 1:

O exemplo a seguir recupera todas as colunas da visualização INFORMATION_SCHEMA.TABLES, exceto is_typed, que é reservada para uso futuro. Os metadados retornados correspondem a todas as tabelas em mydataset no projeto padrão (myproject).

O mydataset contém as seguintes tabelas:

  • mytable1: uma tabela padrão do BigQuery.
  • myview1: uma visualização do BigQuery.

As consultas na visualização INFORMATION_SCHEMA.TABLES precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

Para executar a consulta em um projeto diferente do padrão, adicione o código do projeto ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] por exemplo, `myproject`.mydataset.INFORMATION_SCHEMA.TABLES.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
     * EXCEPT(is_typed)
    FROM
     mydataset.INFORMATION_SCHEMA.TABLES
    
  3. Clique em Executar.

Linha de comando

Use o comando query e especifique a sintaxe SQL padrão usando a sinalização --nouse_legacy_sql ou --use_legacy_sql=false. A sintaxe SQL padrão é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_typed) FROM mydataset.INFORMATION_SCHEMA.TABLES'

Os resultados terão a aparência abaixo:

  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | myproject      | mydataset     | mytable1       | BASE TABLE | YES                | 2018-10-29 20:34:44 |
  | myproject      | mydataset     | myview1        | VIEW       | NO                 | 2018-12-29 00:19:20 |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  

Exemplo 2:

O exemplo a seguir recupera todas as tabelas do tipo BASE TABLE da visualização INFORMATION_SCHEMA.TABLES. A coluna is_typed é excluída. Os metadados retornados correspondem às tabelas em mydataset no projeto padrão (myproject).

As consultas na visualização INFORMATION_SCHEMA.TABLES precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

Para executar a consulta em um projeto diferente do padrão, adicione o código do projeto ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] por exemplo, `myproject`.mydataset.INFORMATION_SCHEMA.TABLES.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
     * EXCEPT(is_typed)
    FROM
     mydataset.INFORMATION_SCHEMA.TABLES
    WHERE
     table_type="BASE TABLE"
    
  3. Clique em Executar.

Linha de comando

Use o comando query e especifique a sintaxe SQL padrão usando a sinalização --nouse_legacy_sql ou --use_legacy_sql=false. A sintaxe SQL padrão é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_typed) FROM mydataset.INFORMATION_SCHEMA.TABLES
WHERE table_type="BASE TABLE"'

Os resultados terão a aparência abaixo:

  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | myproject      | mydataset     | mytable1       | BASE TABLE | NO                 | 2018-10-31 22:40:05 |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  

Visualização TABLE_OPTIONS

Quando consultamos a visualização INFORMATION_SCHEMA.TABLE_OPTIONS, os resultados contêm uma linha para cada tabela ou visualização no conjunto de dados.

As consultas na visualização INFORMATION_SCHEMA.TABLE_OPTIONS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas ou visualizações.

A visualização INFORMATION_SCHEMA.TABLE_OPTIONS tem o seguinte esquema:

Nome da coluna Tipo de dado Valor
TABLE_CATALOG STRING O nome do projeto que contém o conjunto de dados.
TABLE_SCHEMA STRING O nome do conjunto de dados que contém a tabela ou visualização, também conhecido como o datasetId.
TABLE_NAME STRING O nome da tabela ou visualização, também conhecido como o tableId.
OPTION_NAME STRING Um dos valores de nome na tabela de opções.
OPTION_TYPE STRING Um dos valores de tipo de dados na tabela de opções.
OPTION_VALUE STRING Uma das opções de valor na tabela de opções.
Tabela de opções
OPTION_NAME OPTION_TYPE OPTION_VALUE
partition_expiration_days FLOAT64 A vida útil padrão em dias de todas as partições em uma tabela particionada.
expiration_timestamp FLOAT64 A vida útil padrão em dias da tabela.
kms_key_name STRING O nome da chave do Cloud KMS usada para criptografar a tabela.
friendly_name STRING O nome descritivo da tabela.
description STRING Uma descrição da tabela.
labels ARRAY<STRUCT<STRING, STRING>> Uma matriz de STRUCTs que representa os rótulos na tabela.

Exemplos

Exemplo 1:

O exemplo a seguir recupera os prazos de validade padrão de todas as tabelas em mydataset no projeto padrão (myproject) por meio da consulta da visualização INFORMATION_SCHEMATA.TABLE_OPTIONS.

As consultas na visualização INFORMATION_SCHEMA.TABLE_OPTIONS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

Para executar a consulta em um projeto diferente do padrão, adicione o código do projeto ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] por exemplo, `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
     *
    FROM
     mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
    WHERE
     option_name="expiration_timestamp"
    
  3. Clique em Executar.

Linha de comando

Use o comando query e especifique a sintaxe SQL padrão usando a sinalização --nouse_legacy_sql ou --use_legacy_sql=false. A sintaxe SQL padrão é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * FROM mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE option_name="expiration_timestamp"'

Os resultados terão a aparência abaixo:

  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | table_catalog  | table_schema  | table_name |     option_name      | option_type |             option_value             |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | myproject      | mydataset     | mytable1   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2020-01-16T21:12:28.000Z" |
  | myproject      | mydataset     | mytable2   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2021-01-01T21:12:28.000Z" |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  

Exemplo 2:

O exemplo a seguir recupera os metadados sobre todas as tabelas em mydataset que contêm dados de teste. A consulta usa os valores na opção description para localizar as tabelas que contêm “test” (teste) em qualquer lugar da descrição. mydataset está no projeto padrão (myproject).

Para executar a consulta em um projeto diferente do padrão, adicione o código do projeto ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] por exemplo, `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
     *
    FROM
     mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
    WHERE
     option_name="description" AND option_value LIKE "%test%"
    
  3. Clique em Executar.

Linha de comando

Use o comando query e especifique a sintaxe SQL padrão usando a sinalização --nouse_legacy_sql ou --use_legacy_sql=false. A sintaxe SQL padrão é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * FROM mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE option_name="description" AND option_value LIKE "%test%"'

Os resultados terão a aparência abaixo:

  +----------------+---------------+------------+-------------+-------------+--------------+
  | table_catalog  | table_schema  | table_name | option_name | option_type | option_value |
  +----------------+---------------+------------+-------------+-------------+--------------+
  | myproject      | mydataset     | mytable1   | description | STRING      | "test data"  |
  | myproject      | mydataset     | mytable2   | description | STRING      | "test data"  |
  +----------------+---------------+------------+-------------+-------------+--------------+
  

Visualização COLUMNS

Quando consultamos a visualização INFORMATION_SCHEMA.COLUMNS, os resultados contêm uma linha para cada coluna (campo) em uma tabela.

As consultas na visualização INFORMATION_SCHEMA.COLUMNS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

A visualização INFORMATION_SCHEMA.COLUMNS tem o seguinte esquema:

Nome da coluna Tipo de dado Valor
TABLE_CATALOG STRING O nome do projeto que contém o conjunto de dados.
TABLE_SCHEMA STRING O nome do conjunto de dados que contém a tabela, também conhecido como o datasetId.
TABLE_NAME STRING O nome da tabela ou visualização, também conhecido como o tableId.
COLUMN_NAME STRING O nome da coluna.
ORDINAL_POSITION INT64 O deslocamento de índice 1 da coluna dentro da tabela. Se for uma pseudocoluna, como _PARTITIONTIME ou _PARTITIONDATE, o valor será NULL.
IS_NULLABLE STRING YES ou NO, dependendo se o modo da coluna permite valores NULL.
DATA_TYPE STRING O tipo de dados SQL padrão da coluna.
IS_GENERATED STRING O valor sempre é NEVER.
GENERATION_EXPRESSION STRING O valor sempre é NULL.
IS_STORED STRING O valor sempre é NULL.
IS_HIDDEN STRING YES ou NO, dependendo do tipo de coluna (se é ou não é uma pseudocoluna, como _PARTITIONTIME ou _PARTITIONDATE).
IS_UPDATABLE STRING O valor sempre é NULL.
IS_SYSTEM_DEFINED STRING YES ou NO, dependendo do tipo de coluna (se é ou não é uma pseudocoluna, como _PARTITIONTIME ou _PARTITIONDATE).
IS_PARTITIONING_COLUMN STRING YES ou NO, dependendo se a coluna é de particionamento.
CLUSTERING_ORDINAL_POSITION STRING O deslocamento com índice 1 da coluna dentro das colunas de clustering da tabela. O valor será NULL se a tabela não estiver em um cluster.

Exemplos

O exemplo a seguir recupera os metadados da visualização INFORMATION_SCHEMA.COLUMNS correspondentes à tabela population_by_zip_2010 no conjunto de dados census_bureau_usa. Esse conjunto de dados faz parte do programa de conjunto de dados públicos do BigQuery.

Como a tabela está no projeto bigquery-public-data, adicione o código dele ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW] por exemplo, `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES.

As colunas a seguir são excluídas dos resultados da consulta porque atualmente estão reservadas para uso futuro:

  • IS_GENERATED
  • GENERATION_EXPRESSION
  • IS_STORED
  • IS_UPDATABLE

As consultas na visualização INFORMATION_SCHEMA.COLUMNS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
     * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
    FROM
     `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
    WHERE
     table_name="population_by_zip_2010"
    
  3. Clique em Executar.

Linha de comando

Use o comando query e especifique a sintaxe SQL padrão usando a sinalização --nouse_legacy_sql ou --use_legacy_sql=false. A sintaxe SQL padrão é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
FROM `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
WHERE table_name="population_by_zip_2010"'

Os resultados terão a aparência abaixo. Para melhor legibilidade, table_catalog e table_schema foram excluídos dos resultados:

+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
|       table_name       | column_name | ordinal_position | is_nullable | data_type | is_hidden | is_system_defined | is_partitioning_column | clustering_ordinal_position |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
| population_by_zip_2010 | zipcode     |                1 | NO          | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | geo_id      |                2 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | minimum_age |                3 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | maximum_age |                4 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | gender      |                5 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | population  |                6 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
  

Visualização COLUMN_FIELD_PATHS

Quando consultamos a visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS, os resultados contêm uma linha para cada coluna aninhada em uma coluna RECORD (ou STRUCT).

As consultas na visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

A visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS tem o seguinte esquema:

Nome da coluna Tipo de dado Valor
TABLE_CATALOG STRING O nome do projeto que contém o conjunto de dados.
TABLE_SCHEMA STRING O nome do conjunto de dados que contém a tabela, também conhecido como o datasetId.
TABLE_NAME STRING O nome da tabela ou visualização, também conhecido como o tableId.
COLUMN_NAME STRING O nome da coluna.
FIELD_PATH STRING O caminho para uma coluna aninhada dentro de uma coluna RECORD (ou "STRUCT").
DATA_TYPE STRING O tipo de dados SQL padrão da coluna.
DESCRIPTION STRING A descrição da coluna.

Exemplos

O exemplo a seguir recupera os metadados da visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS correspondentes à tabela commits no conjunto de dados github_repos. Esse conjunto de dados faz parte do programa de conjunto de dados públicos do BigQuery.

Como a tabela está no projeto bigquery-public-data, adicione o código dele ao conjunto de dados no seguinte formato: `[PROJECT_ID]`.[DATASET].INFORMATION_SCHEMA.[VIEW]. Por exemplo, `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS.

A tabela commits contém as seguintes colunas aninhadas e repetidas ou só aninhadas:

  • author: coluna RECORD aninhada
  • committer: coluna RECORD aninhada
  • trailer: coluna RECORD aninhada e repetida
  • difference: coluna RECORD aninhada e repetida

A consulta recuperará os metadados sobre as colunas author e difference.

As consultas na visualização INFORMATION_SCHEMA.COLUMN_FIELD_PATHS precisam ter um qualificador de conjunto de dados. O usuário que envia a consulta precisa ter acesso ao conjunto de dados que contém as tabelas.

Para executar a consulta, faça o seguinte:

Console

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

    Acesse a IU da Web do BigQuery

  2. Digite a seguinte consulta SQL padrão na caixa Editor de consultas. INFORMATION_SCHEMA requer sintaxe SQL padrão. SQL padrão é a sintaxe padrão no Console do GCP.

    SELECT
     *
    FROM
     `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
    WHERE
     table_name="commits"
     AND column_name="author"
     OR column_name="difference"
    
  3. Clique em Executar.

Linha de comando

Use o comando query e especifique a sintaxe SQL padrão usando a sinalização --nouse_legacy_sql ou --use_legacy_sql=false. A sintaxe SQL padrão é necessária para consultas de INFORMATION_SCHEMA.

Para executar a consulta, digite:

bq query --nouse_legacy_sql \
'SELECT * FROM `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
WHERE table_name="commits" AND column_name="author" OR column_name="difference"'

Os resultados terão a aparência abaixo. Para melhor legibilidade, table_catalog e table_schema foram excluídos dos resultados:

  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | table_name | column_name |     field_path      |                                                                      data_type                                                                      | description |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | commits    | author      | author              | STRUCT<name STRING, email STRING, time_sec INT64, tz_offset INT64, date TIMESTAMP>                                                                  | NULL        |
  | commits    | author      | author.name         | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.email        | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.time_sec     | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.tz_offset    | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.date         | TIMESTAMP                                                                                                                                           | NULL        |
  | commits    | difference  | difference          | ARRAY<STRUCT<old_mode INT64, new_mode INT64, old_path STRING, new_path STRING, old_sha1 STRING, new_sha1 STRING, old_repo STRING, new_repo STRING>> | NULL        |
  | commits    | difference  | difference.old_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.new_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.old_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_repo | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_repo | STRING                                                                                                                                              | NULL        |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  

Como listar tabelas em cluster em um conjunto de dados

Para listar tabelas em cluster nos conjuntos de dados, use o Console do GCP, a IU clássica da Web do BigQuery, o comando bq ls da CLI ou chame o método de API tables.list.

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, veja Como listar tabelas particionadas em um conjunto de dados.

Recursos em desenvolvimento

Os recursos a seguir estão sendo desenvolvidos e ainda não estão disponíveis na versão Alfa:

  • Suporte para o agrupamento em cluster de tabelas nativas (não particionadas)
  • Redução dos custos para tipos específicos de consultas que usam filtros em agrupamento de colunas em cluster

A seguir

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

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.