Instruções de linguagem de definição de dados (DDL) no SQL padrão

As instruções de linguagem de definição de dados (DDL) permitem criar e modificar recursos do BigQuery usando a sintaxe de consulta do SQL padrão. É possível usar comandos DDL para criar, alterar e excluir recursos, como tabelas, clones de tabela, snapshots de tabela, visualizações, funções definidas pelo usuário (UDFs) e políticas de acesso no nível da linha.

Permissões necessárias

Para criar um job que execute uma instrução DDL, é necessário ter a permissão bigquery.jobs.create no projeto em que o job está sendo executado. Cada instrução DDL também requer permissões específicas nos recursos afetados, que são documentados em cada instrução.

Papéis IAM

Os papéis predefinidos bigquery.user, bigquery.jobUser e bigquery.admin do IAM incluem a permissão bigquery.jobs.create necessária.

Para mais informações sobre os papéis do IAM no BigQuery, consulte Papéis e permissões predefinidos ou a Referência de permissões do IAM.

Como executar instruções DDL

É possível executar instruções DDL usando o console, com a ferramenta de linha de comando bq, chamando a API REST jobs.query ou de maneira programática, usando as bibliotecas de cliente da API BigQuery.

Console

  1. Acesse a página do BigQuery no console.

    Ir para o BigQuery

  2. Clique em Escrever nova consulta.

    Escrever nova consulta.

  3. Insira a instrução DDL na área de texto do Editor de consultas. Por exemplo:

     CREATE TABLE mydataset.newtable ( x INT64 )
     

  4. Clique em Executar.

bq

Digite o comando bq query e forneça a instrução DDL como o parâmetro de consulta. Defina a sinalização use_legacy_sql como false.

bq query --use_legacy_sql=false \
  'CREATE TABLE mydataset.newtable ( x INT64 )'

API

Chame o método jobs.query e forneça a instrução DDL na propriedade query do corpo da solicitação.

A funcionalidade DDL amplia as informações retornadas por um recurso de jobs. statistics.query.statementType inclui estes outros valores para compatibilidade com DDL:

  • CREATE_TABLE
  • CREATE_TABLE_AS_SELECT
  • DROP_TABLE
  • CREATE_VIEW
  • DROP_VIEW

statistics.query tem dois campos extras:

  • ddlOperationPerformed: a operação DDL realizada, possivelmente dependente da existência do destino DDL. Os valores atuais incluem:
    • CREATE: a consulta criou o destino DDL.
    • SKIP: exemplos de ambiente autônomo: CREATE TABLE IF NOT EXISTS foi enviado e a tabela existe. Ou DROP TABLE IF EXISTS foi enviado e a tabela não existe.
    • REPLACE: a consulta substituiu o destino DDL. Exemplo: CREATE OR REPLACE TABLE foi enviado e a tabela já existe.
    • DROP: a consulta excluiu o destino DDL.
  • ddlTargetTable: quando você envia uma instrução CREATE TABLE/VIEW ou DROP TABLE/VIEW, a tabela de destino é retornada como um objeto com três campos:
    • "projectId": string
    • "datasetId": string
    • "tableId": string

Java

Chame o método BigQuery.create() para iniciar um job de consulta. Chame o Job.waitFor() para aguardar a conclusão da consulta DDL.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.QueryJobConfiguration;

// Sample to create a view using DDL
public class DDLCreateView {

  public static void runDDLCreateView() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_VIEW_ID";
    String ddl =
        "CREATE VIEW "
            + "`"
            + projectId
            + "."
            + datasetId
            + "."
            + tableId
            + "`"
            + " OPTIONS("
            + " expiration_timestamp=TIMESTAMP_ADD("
            + " CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),"
            + " friendly_name=\"new_view\","
            + " description=\"a view that expires in 2 days\","
            + " labels=[(\"org_unit\", \"development\")]"
            + " )"
            + " AS SELECT name, state, year, number"
            + " FROM `bigquery-public-data.usa_names.usa_1910_current`"
            + " WHERE state LIKE 'W%'`";
    ddlCreateView(ddl);
  }

  public static void ddlCreateView(String ddl) {
    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();

      QueryJobConfiguration config = QueryJobConfiguration.newBuilder(ddl).build();

      // create a view using query and it will wait to complete job.
      Job job = bigquery.create(JobInfo.of(config));
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("View created successfully");
      } else {
        System.out.println("View was not created");
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("View was not created. \n" + e.toString());
    }
  }
}

Node.js

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function ddlCreateView() {
  // Creates a view via a DDL query

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = "my_project"
  // const datasetId = "my_dataset"
  // const tableId = "my_new_view"

  const query = `
  CREATE VIEW \`${projectId}.${datasetId}.${tableId}\`
  OPTIONS(
      expiration_timestamp=TIMESTAMP_ADD(
          CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
      friendly_name="new_view",
      description="a view that expires in 2 days",
      labels=[("org_unit", "development")]
  )
  AS SELECT name, state, year, number
      FROM \`bigquery-public-data.usa_names.usa_1910_current\`
      WHERE state LIKE 'W%'`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);

  job.on('complete', metadata => {
    console.log(`Created new view ${tableId} via job ${metadata.id}`);
  });
}

Python

Chame o método Client.query() para iniciar um job de consulta. Chame o QueryJob.result() para aguardar a conclusão da consulta DDL.

# from google.cloud import bigquery
# project = 'my-project'
# dataset_id = 'my_dataset'
# table_id = 'new_view'
# client = bigquery.Client(project=project)

sql = """
CREATE VIEW `{}.{}.{}`
OPTIONS(
    expiration_timestamp=TIMESTAMP_ADD(
        CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
    friendly_name="new_view",
    description="a view that expires in 2 days",
    labels=[("org_unit", "development")]
)
AS SELECT name, state, year, number
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state LIKE 'W%'
""".format(
    project, dataset_id, table_id
)

job = client.query(sql)  # API request.
job.result()  # Waits for the query to finish.

print(
    'Created new view "{}.{}.{}".'.format(
        job.destination.project,
        job.destination.dataset_id,
        job.destination.table_id,
    )
)

Instrução CREATE SCHEMA

Cria um novo conjunto de dados.

Sintaxe

CREATE SCHEMA [ IF NOT EXISTS ]
[project_name.]dataset_name
[DEFAULT COLLATE collate_specification]
[OPTIONS(schema_option_list)]

Argumentos

  • IF NOT EXISTS: se houver algum conjunto de dados com o mesmo nome, a instrução CREATE não terá efeito. Não pode aparecer com OR REPLACE.

  • DEFAULT COLLATE collate_specification: quando uma nova tabela é criada no esquema, ela herda uma especificação de compilação padrão, a menos que uma especificação de compilação seja explicitamente especificada para uma coluna.

    Se você remover ou alterar essa especificação de compilação mais tarde com a instrução ALTER SCHEMA, as especificações de compilação existentes não serão alteradas nesse esquema. Se você quiser atualizar uma especificação de compilação em um esquema, precisará alterar a coluna que contém a especificação.

  • project_name: o nome do projeto onde você está criando o conjunto de dados. O padrão é o projeto que executa essa consulta DDL.

  • dataset_name: o nome do conjunto de dados a ser criado.

  • schema_option_list: uma lista de opções para criar o conjunto de dados.

Detalhes

O conjunto de dados é criado no local especificado nas configurações da consulta. Para mais informações, consulte Como especificar seu local.

Para mais informações sobre como criar um conjunto de dados, consulte Como criar conjuntos de dados. Para informações sobre cotas, consulte Limites do conjunto de dados.

schema_option_list

A lista de opções especifica opções para o conjunto de dados. Especifique as opções no seguinte formato: NAME=VALUE, ...

As seguintes opções são compatíveis:

NAME VALUE Detalhes
default_kms_key_name STRING Especifica a chave padrão do Cloud KMS para criptografar dados da tabela neste conjunto de dados. É possível modificar esse valor ao criar uma tabela.
default_partition_expiration_days FLOAT64 Especifica o prazo de validade padrão, em dias, para partições de tabela nesse conjunto de dados. É possível modificar esse valor ao criar uma tabela.
default_table_expiration_days FLOAT64 Especifica o prazo de validade padrão, em dias, das tabelas neste conjunto de dados. É possível modificar esse valor ao criar uma tabela.
description STRING A descrição do conjunto de dados.
friendly_name STRING Um nome descritivo do conjunto de dados.
labels <ARRAY<STRUCT<STRING, STRING>>> Uma matriz de rótulos para o conjunto de dados, expressa como pares de chave-valor.
location STRING O local em que o conjunto de dados será criado. Se você não especificar essa opção, o conjunto de dados será criado no local em que a consulta será executada. Se você especificar essa opção e também definir explicitamente o local do job de consulta, os dois valores precisam corresponder; caso contrário, a consulta falhará.
max_time_travel_hours SMALLINT

Em pré-lançamento

Especifica a duração em horas da janela de viagem no tempo para o novo conjunto de dados. O valor de max_time_travel_hours precisa ser um número inteiro entre 48 (2 dias) e 168 (7 dias). O padrão será 168 horas se essa opção não for especificada.

Para mais informações sobre a janela de viagem no tempo, consulte Como configurar a janela de viagem no tempo.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.datasets.create O projeto em que você cria o conjunto de dados.

Examples

Como criar um novo esquema

O exemplo a seguir cria um conjunto de dados com uma validade de tabela padrão e um conjunto de rótulos.

CREATE SCHEMA mydataset
OPTIONS(
  location="us",
  default_table_expiration_days=3.75,
  labels=[("label1","value1"),("label2","value2")]
  )

Como criar um esquema compatível com compilação

O exemplo a seguir cria um conjunto de dados com uma especificação de compilação.

CREATE SCHEMA mydataset
DEFAULT COLLATE 'und:ci'

Instrução CREATE TABLE

Cria uma nova tabela.

Sintaxe

CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] TABLE [ IF NOT EXISTS ]
table_name
[(
  column[, ...]
)]
[DEFAULT COLLATE collate_specification]
[PARTITION BY partition_expression]
[CLUSTER BY clustering_column_list]
[OPTIONS(table_option_list)]
[AS query_statement]

Argumentos

  • OR REPLACE: substitui qualquer função com o mesmo nome, se houver. Não pode aparecer com IF NOT EXISTS.

  • TEMP | TEMPORARY: cria uma tabela temporária.

  • IF NOT EXISTS: se houver alguma tabela com o mesmo nome, a instrução CREATE não terá efeito. Não pode aparecer com OR REPLACE.

  • table_name: o nome da tabela a ser criada. Consulte Sintaxe do caminho da tabela. Para tabelas temporárias, não inclua o nome do projeto ou do conjunto de dados.

  • column: as informações do esquema da tabela.

  • collation_specification: quando uma nova coluna é criada no esquema e ela não tem uma especificação de compilação explícita, a coluna herda essa especificação de compilação para os tipos STRING.

    Se você remover ou alterar essa especificação de compilação mais tarde com a instrução ALTER TABLE, as especificações de compilação atuais não serão alteradas nessa tabela. Se quiser atualizar uma especificação de compilação existente em uma tabela, precisará alterar a coluna que contém a especificação.

    Se a tabela fizer parte de um esquema, a especificação de compilação padrão dela substituirá a especificação de compilação padrão do esquema.

  • partition_expression: é uma expressão que determina como particionar a tabela.

  • clustering_column_list: uma lista separada por vírgulas de referências de coluna que determinam como agrupar a tabela em cluster. Não é possível ter a compilação em colunas dessa lista.

  • table_option_list: uma lista de opções para criar a tabela.

  • query_statement: a consulta a partir da qual a tabela será criada. Para a sintaxe da consulta, consulte a Referência da sintaxe do SQL. {: #query_statement } Se uma especificação de compilação for usada nessa tabela, ela será transmitida por essa instrução de consulta.

Detalhes

Nas instruções CREATE TABLE, siga estas regras:

  • Apenas uma instrução CREATE é permitida.
  • A lista de colunas, a cláusula as query_statement ou ambas precisam estar presentes.
  • Quando a lista de colunas e a cláusula as query_statement estão presentes, o BigQuery ignora os nomes na cláusula as query_statement e combina as colunas com a lista de colunas por posição.
  • Quando a cláusula as query_statement está presente e a lista de colunas não existe, o BigQuery determina os nomes e os tipos de coluna com base na cláusula as query_statement.
  • Os nomes das colunas precisam ser especificados na lista de colunas, na cláusula as query_statement ou no esquema da tabela na cláusula LIKE.
  • Não é permitido duplicar nomes de colunas.
  • Quando a cláusula LIKE e a cláusula as query_statement estão presentes, a lista de colunas na instrução de consulta deve corresponder às colunas da tabela referenciadas pela cláusula LIKE.

Limitações:

  • Não é possível criar uma tabela particionada por tempo de ingestão a partir do resultado de uma consulta. Em vez disso, use uma instrução DDL CREATE TABLE para criar a tabela e, em seguida, uma instrução DML INSERT para inserir os dados.
  • Não é possível usar o modificador OR REPLACE para substituir uma tabela por outro tipo de particionamento. Em vez disso, DROP a tabela e use uma instrução CREATE TABLE ... AS SELECT ... para recriá-la.

Esta instrução é compatível com as seguintes variantes:

column

(column_name column_schema[, ...]) contém as informações de esquema da tabela, em uma lista separada por vírgulas.

column :=
  column_name column_schema

column_schema :=
   {
     simple_type [NOT NULL]
     | STRUCT<field_list> [NOT NULL]
     | ARRAY<array_element_schema>
   }
   [OPTIONS(column_option_list)]

field_list :=
  field_name column_schema [, ...]

array_element_schema :=
  { simple_type | STRUCT<field_list> }
  [NOT NULL]

simple_type :=
  { data_type | STRING COLLATE collate_specification }
  • column_name é o nome da coluna. Um nome de coluna:

    • precisa conter apenas letras (a-z, A-Z), números (0-9) ou sublinhados (_);
    • precisa começar com uma letra ou um sublinhado;
    • pode ter até 300 caracteres.
  • column_schema: é semelhante a um tipo de dados, mas aceita uma restrição NOT NULL opcional para tipos diferentes de ARRAY. column_schema também é compatível com opções em colunas de nível superior e campos STRUCT.

    column_schema pode ser usado apenas na lista de definições de coluna das instruções CREATE TABLE. Não pode ser usado como um tipo em expressões. Por

  • simple_type: é qualquer tipo de dados compatível, exceto STRUCT e ARRAY.

    Se simple_type for um STRING, será compatível com outra cláusula de compilação, que define como um STRING resultante pode ser comparado e ordenado. A sintaxe é assim:

    STRING COLLATE collate_specification
    

    Se você tiver DEFAULT COLLATE collate_specification atribuído à tabela, a especificação de compilação de uma coluna substituirá a especificação da tabela.

  • field_list: representa os campos em um struct.

  • field_name: o nome do campo do struct. Os nomes dos campos struct têm as mesmas restrições que os nomes das colunas.

  • NOT NULL: quando a restrição NOT NULL está presente em uma coluna ou um campo, a coluna ou o campo é criado com o modo REQUIRED. Por outro lado, quando a restrição NOT NULL está ausente, a coluna ou campo é criado com o modo NULLABLE.

    As colunas e campos do tipo ARRAY não são compatíveis com o modificador NOT NULL. Por exemplo, um column_schema de ARRAY<INT64> NOT NULL é inválido, uma vez que as colunas ARRAY têm o modo REPEATED e podem estar vazias, mas não podem ser NULL. Um elemento de matriz em uma tabela nunca pode ser NULL, independentemente de a restrição NOT NULL ser especificada. Por exemplo, ARRAY<INT64> é equivalente a ARRAY<INT64 NOT NULL>.

    O atributo NOT NULL de column_schema de uma tabela não se propaga por consultas nela. Se a tabela T contiver uma coluna declarada como x INT64 NOT NULL, por exemplo, o CREATE TABLE dataset.newtable AS SELECT x FROM T criará uma tabela denominada dataset.newtable em que x é NULLABLE.

partition_expression

PARTITION BY é uma cláusula opcional que controla o particionamento de tabelas. partition_expression é uma expressão que determina como particionar a tabela. A expressão da partição pode conter os seguintes valores:

  • _PARTITIONDATE. Partição por tempo de ingestão com partições diárias. Essa sintaxe não pode ser usada com a cláusula AS query_statement.
  • DATE(_PARTITIONTIME). Equivale a _PARTITIONDATE. Essa sintaxe não pode ser usada com a cláusula AS query_statement.
  • <date_column>. Partição por uma coluna DATE com partições diárias.
  • DATE({ <timestamp_column> | <datetime_column> }). Partição por uma coluna TIMESTAMP ou DATETIME com partições diárias.
  • DATETIME_TRUNC(<datetime_column>, { DAY | HOUR | MONTH | YEAR }). Partição por uma coluna DATETIME com o tipo de particionamento especificado.
  • TIMESTAMP_TRUNC(<timestamp_column>, { DAY | HOUR | MONTH | YEAR }). Partição por uma coluna TIMESTAMP com o tipo de particionamento especificado.
  • TIMESTAMP_TRUNC(_PARTITIONTIME, { DAY | HOUR | MONTH | YEAR }). Partição por tempo de ingestão com o tipo de particionamento especificado. Essa sintaxe não pode ser usada com a cláusula AS query_statement.
  • DATE_TRUNC(<date_column>, { MONTH | YEAR }). Partição por uma coluna DATE com o tipo de particionamento especificado.
  • RANGE_BUCKET(<int64_column>, GENERATE_ARRAY(<start>, <end>[, <interval>])). Partição por uma coluna de números inteiros com o intervalo especificado, em que:

    • start é o início do particionamento por intervalo, inclusivo;
    • end é o fim do particionamento por intervalo, exclusivo;
    • interval é a largura de cada intervalo dentro da partição. O padrão é 1.

clustering_column_list

CLUSTER BY é uma cláusula opcional que controla o clustering de tabelas. clustering_column_list é uma lista separada por vírgulas que termina como agrupar a tabela em cluster. A lista de colunas de agrupamento em cluster pode conter uma lista de até quatro agrupamentos de colunas em cluster.

table_option_list

A lista de opções permite que você defina opções de tabela, como um rótulo e um prazo de validade. Para incluir várias opções, use uma lista separada por vírgulas.

Especifique uma lista de opções de tabela no formato a seguir:

NAME=VALUE, ...

NAME e VALUE precisam ser uma das combinações a seguir:

NAME VALUE Detalhes
expiration_timestamp TIMESTAMP

Exemplo: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Essa propriedade é equivalente à propriedade de recurso de tabela expirationTime.

partition_expiration_days

FLOAT64

Exemplo: partition_expiration_days=7

Define a validade da partição em dias. Para mais informações, consulte Definir a validade da partição. Por padrão, as partições não expiram.

Essa propriedade é equivalente à propriedade de recurso de tabela timePartitioning.expirationMs, mas usa dias em vez de milissegundos. Um dia é equivalente a 86.400.000 milissegundos, ou 24 horas.

Só é possível definir essa propriedade se a tabela for particionada.

require_partition_filter

BOOL

Exemplo: require_partition_filter=true

Especifica se as consultas nesta tabela precisam incluir um filtro de predicado que filtre na coluna de particionamento. Para mais informações, consulte Definir requisitos de filtro de partição. O valor padrão é false.

Essa propriedade é equivalente à propriedade de recurso de tabela timePartitioning.requirePartitionFilter.

Só é possível definir essa propriedade se a tabela for particionada.

kms_key_name

STRING

Exemplo: kms_key_name="projects/project_id/locations/location/keyRings/keyring/cryptoKeys/key"

Essa propriedade é equivalente à propriedade de recurso de tabela encryptionConfiguration.kmsKeyName.

Consulte mais detalhes sobre Como proteger dados com chaves do Cloud KMS.

friendly_name

STRING

Exemplo: friendly_name="my_table"

Essa propriedade é equivalente à propriedade de recurso de tabela friendlyName.

description

STRING

Exemplo: description="a table that expires in 2025"

Essa propriedade é equivalente à propriedade de recurso de tabela description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemplo: labels=[("org_unit", "development")]

Essa propriedade é equivalente à propriedade de recurso de tabela labels.

VALUE é uma expressão constante que contém apenas literais, parâmetros de consulta e funções escalares.

A expressão constante não pode conter os itens a seguir:

  • Uma referência a uma tabela
  • Subconsultas ou instruções SQL, como SELECT, CREATE ou UPDATE
  • Funções definidas pelo usuário, funções agregadas ou funções analíticas
  • as funções escalares a seguir:
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

Se VALUE for avaliado como NULL, a opção correspondente NAME na instrução CREATE TABLE será ignorada.

column_option_list

A column_option_list em column_schema permite especificar opções de coluna ou campo opcionais. As opções de coluna têm a mesma sintaxe e requisitos que as opções de tabela, mas com uma lista diferente de NAMEs e VALUEs:

NAME VALUE Detalhes
description

STRING

Exemplo: description="a unique id"

Essa propriedade é equivalente à propriedade de recurso de tabela schema.fields[].description.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.create O conjunto de dados em que a tabela é criada.

Além disso, a cláusula OR REPLACE requer as permissões bigquery.tables.update e bigquery.tables.updateData.

Se a cláusula OPTIONS incluir alguma opção de expiração, a permissão bigquery.tables.delete também será obrigatória.

Examples

Como criar uma nova tabela

No exemplo a seguir, criamos uma tabela particionada denominada newtable em mydataset.

CREATE TABLE mydataset.newtable
(
  x INT64 OPTIONS(description="An optional INTEGER field"),
  y STRUCT<
    a ARRAY<STRING> OPTIONS(description="A repeated STRING field"),
    b BOOL
  >
)
PARTITION BY _PARTITIONDATE
OPTIONS(
  expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC",
  partition_expiration_days=1,
  description="a table that expires in 2025, with each partition living for 24 hours",
  labels=[("org_unit", "development")]
)

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.newtable, o qualificador de tabela pode ser `myproject.mydataset.newtable`.

Se o nome da tabela existir no conjunto de dados, o erro a seguir será retornado:

Already Exists: project_id:dataset.table

A tabela usa partition_expression a seguir para particionar a tabela: PARTITION BY _PARTITIONDATE. Essa expressão particiona a tabela usando a data na pseudocoluna _PARTITIONDATE.

O esquema da tabela tem duas colunas:

  • x: um inteiro, com a descrição "Um campo INTEGER opcional"
  • y: um STRUCT que contém duas colunas:

    • a: uma matriz de strings, com a descrição "Um campo STRING repetido"
    • b: um booleano

A lista de opções da tabela especifica:

  • Prazo de validade da tabela: 1º de janeiro de 2025 às 00:00:00 UTC;
  • Prazo de validade da partição: 1 dia;
  • Descrição: A table that expires in 2025
  • Rótulo: org_unit = development

Como criar uma nova tabela a partir de uma atual

No exemplo a seguir, criamos uma tabela chamada top_words em mydataset de uma consulta:

CREATE TABLE mydataset.top_words
OPTIONS(
  description="Top ten words per Shakespeare corpus"
) AS
SELECT
  corpus,
  ARRAY_AGG(STRUCT(word, word_count) ORDER BY word_count DESC LIMIT 10) AS top_words
FROM bigquery-public-data.samples.shakespeare
GROUP BY corpus;

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.top_words, o qualificador de tabela pode ser `myproject.mydataset.top_words`.

Se o nome da tabela existir no conjunto de dados, o erro a seguir será retornado:

Already Exists: project_id:dataset.table

O esquema da tabela contém duas colunas:

  • corpus: nome de um corpus de Shakespeare
  • top_words: um ARRAY de STRUCTs contendo dois campos: word (uma STRING) e word_count (um INT64 com a contagem de palavras)

A lista de opções da tabela especifica:

  • Descrição: Top ten words per Shakespeare corpus

Como criar uma tabela somente se a tabela não existir

O exemplo a seguir cria uma tabela denominada newtable em mydataset somente se não houver uma tabela denominada newtable em mydataset. Se o nome da tabela existir no conjunto de dados, nenhum erro será retornado e nenhuma ação será realizada.

CREATE TABLE IF NOT EXISTS mydataset.newtable (x INT64, y STRUCT<a ARRAY<STRING>, b BOOL>)
OPTIONS(
  expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC",
  description="a table that expires in 2025",
  labels=[("org_unit", "development")]
)

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.newtable, o qualificador de tabela pode ser `myproject.mydataset.newtable`.

O esquema da tabela contém duas colunas:

  • x: um número inteiro
  • y: STRUCT que contém a (uma matriz de strings) e b (um booleano)

A lista de opções da tabela especifica:

  • Prazo de validade: 1º de janeiro de 2025 às 00:00:00 UTC;
  • Descrição: A table that expires in 2025
  • Rótulo: org_unit = development

Como criar ou substituir uma tabela

No exemplo a seguir, será criada uma tabela chamada newtable em mydataset, e se newtable existir em mydataset, ela será substituída por uma tabela vazia.

CREATE OR REPLACE TABLE mydataset.newtable (x INT64, y STRUCT<a ARRAY<STRING>, b BOOL>)
OPTIONS(
  expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC",
  description="a table that expires in 2025",
  labels=[("org_unit", "development")]
)

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.newtable, o qualificador de tabela pode ser `myproject.mydataset.newtable`.

O esquema da tabela contém duas colunas:

  • x: um número inteiro
  • y: STRUCT que contém a (uma matriz de strings) e b (um booleano)

A lista de opções da tabela especifica:

  • Prazo de validade: 1º de janeiro de 2025 às 00:00:00 UTC;
  • Descrição: A table that expires in 2025
  • Rótulo: org_unit = development

Como criar uma tabela com colunas REQUIRED

No exemplo a seguir, criamos uma tabela denominada newtable em mydataset. O modificador NOT NULL na lista de definição de coluna de uma instrução CREATE TABLE especifica que uma coluna ou campo seja criado no modo REQUIRED.

CREATE TABLE mydataset.newtable (
  x INT64 NOT NULL,
  y STRUCT<
    a ARRAY<STRING>,
    b BOOL NOT NULL,
    c FLOAT64
  > NOT NULL,
  z STRING
)

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.newtable, o qualificador de tabela pode ser `myproject.mydataset.newtable`.

Se o nome da tabela existir no conjunto de dados, o erro a seguir será retornado:

Already Exists: project_id:dataset.table

O esquema da tabela contém três colunas:

  • x: um número inteiro REQUIRED;
  • y: um REQUIRED STRUCT contendo a (uma matriz de strings), b (um booleano REQUIRED) e c (um flutuante NULLABLE);
  • z: uma string NULLABLE.

Como criar uma tabela compatível com compilação

Os exemplos a seguir criam uma tabela chamada newtable em mydataset com as colunas a, b, c e um struct com os campos x e y.

Todos os esquemas de coluna STRING nessa tabela são compilados com 'und:ci':

CREATE TABLE mydataset.newtable (
  a STRING,
  b STRING,
  c STRUCT<
    x FLOAT64
    y ARRAY<STRING>
  >
)
DEFAULT COLLATE 'und:ci';

Somente b e y são compilados com 'und:ci':

CREATE TABLE mydataset.newtable (
  a STRING,
  b STRING COLLATE 'und:ci',
  c STRUCT<
    x FLOAT64
    y ARRAY<STRING COLLATE 'und:ci'>
  >
);

Como criar uma tabela com tipos de dados parametrizados

No exemplo a seguir, criamos uma tabela denominada newtable em mydataset. Os parâmetros entre parênteses especificam que a coluna contenha um tipo de dados parametrizado. Consulte Tipos de dados parametrizados para mais informações sobre os tipos parametrizados.

CREATE TABLE mydataset.newtable (
  x STRING(10),
  y STRUCT<
    a ARRAY<BYTES(5)>,
    b NUMERIC(15, 2),
    c FLOAT64
  >,
  z BIGNUMERIC(35)
)

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Em vez de mydataset.newtable, o qualificador de tabela precisa ser `myproject.mydataset.newtable`.

Se o nome da tabela existir no conjunto de dados, o erro a seguir será retornado:

Already Exists: project_id:dataset.table

O esquema da tabela contém três colunas:

  • x: uma string parametrizada com o comprimento máximo de 10.
  • y: STRUCT que contém a (uma matriz de bytes parametrizados com comprimento máximo de 5), NUMERIC (parametrizado com precisão máxima de 15 e escala máxima de 2) e c (um flutuante)
  • z: BIGNUMERIC parametrizado com uma precisão máxima de 35 e escala máxima de 0

Como criar uma tabela particionada

No exemplo a seguir, criamos uma tabela particionada denominada newtable em mydataset usando uma coluna DATE.

CREATE TABLE mydataset.newtable (transaction_id INT64, transaction_date DATE)
PARTITION BY transaction_date
OPTIONS(
  partition_expiration_days=3,
  description="a table partitioned by transaction_date"
)

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.newtable, o qualificador de tabela pode ser `myproject.mydataset.newtable`.

O esquema da tabela contém duas colunas:

  • transaction_id: um número inteiro
  • transaction_date: uma data

A lista de opções da tabela especifica:

  • validade da partição: três dias;
  • Descrição: A table partitioned by transaction_date

Como criar uma tabela particionada a partir do resultado de uma consulta

No exemplo a seguir, criamos uma tabela particionada denominada days_with_rain em mydataset usando uma coluna DATE.

CREATE TABLE mydataset.days_with_rain
PARTITION BY date
OPTIONS (
  partition_expiration_days=365,
  description="weather stations with precipitation, partitioned by day"
) AS
SELECT
  DATE(CAST(year AS INT64), CAST(mo AS INT64), CAST(da AS INT64)) AS date,
  (SELECT ANY_VALUE(name) FROM `bigquery-public-data.noaa_gsod.stations` AS stations
   WHERE stations.usaf = stn) AS station_name,  -- Stations can have multiple names
  prcp
FROM `bigquery-public-data.noaa_gsod.gsod2017` AS weather
WHERE prcp != 99.9  -- Filter unknown values
  AND prcp > 0      -- Filter stations/days with no precipitation

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.days_with_rain, o qualificador de tabela pode ser `myproject.mydataset.days_with_rain`.

O esquema da tabela contém duas colunas:

  • data: a DATE da coleta de dados;
  • station_name: o nome da estação meteorológica como uma STRING;
  • prcp: a quantidade de precipitação em polegadas como um FLOAT64.

A lista de opções da tabela especifica:

  • validade da partição: um ano;
  • Descrição: Weather stations with precipitation, partitioned by day

Como criar uma tabela em cluster

Exemplo 1

No exemplo a seguir, é criada uma tabela em cluster denominada myclusteredtable em mydataset. É uma tabela particionada por uma coluna TIMESTAMP e agrupada em cluster por uma coluna STRING denominada customer_id.

CREATE TABLE mydataset.myclusteredtable
(
  timestamp TIMESTAMP,
  customer_id STRING,
  transaction_amount NUMERIC
)
PARTITION BY DATE(timestamp)
CLUSTER BY customer_id
OPTIONS (
  partition_expiration_days=3,
  description="a table clustered by customer_id"
)

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.myclusteredtable, o qualificador de tabela pode ser `myproject.mydataset.myclusteredtable`.

O esquema da tabela contém três colunas:

  • timestamp: o momento da coleta de dados como um TIMESTAMP;
  • customer_id: o ID do cliente como STRING;
  • transaction_amount: o valor da transação como NUMERIC.

A lista de opções da tabela especifica:

  • Validade da partição: 3 dias;
  • Descrição: A table clustered by customer_id
Exemplo 2

No exemplo a seguir, é criada uma tabela em cluster denominada myclusteredtable em mydataset. É uma tabela particionada por tempo de processamento.

CREATE TABLE mydataset.myclusteredtable
(
  customer_id STRING,
  transaction_amount NUMERIC
)
PARTITION BY DATE(_PARTITIONTIME)
CLUSTER BY
  customer_id
OPTIONS (
  partition_expiration_days=3,
  description="a table clustered by customer_id"
)

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.myclusteredtable, o qualificador de tabela pode ser `myproject.mydataset.myclusteredtable`.

O esquema da tabela contém duas colunas:

  • customer_id: o ID do cliente como STRING;
  • transaction_amount: o valor da transação como NUMERIC.

A lista de opções da tabela especifica:

  • Validade da partição: 3 dias;
  • Descrição: A table clustered by customer_id
Exemplo 3

No exemplo a seguir, é criada uma tabela em cluster denominada myclusteredtable em mydataset. A tabela não é particionada.

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

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.myclusteredtable, o qualificador de tabela pode ser `myproject.mydataset.myclusteredtable`.

O esquema da tabela contém duas colunas:

  • customer_id: o ID do cliente como STRING;
  • transaction_amount: o valor da transação como NUMERIC.

A lista de opções da tabela especifica:

  • Descrição: A table clustered by customer_id

Como criar uma tabela em cluster a partir do resultado de uma consulta

Exemplo 1

No exemplo a seguir, é criada uma tabela em cluster denominada myclusteredtable em mydataset usando o resultado de uma consulta. É uma tabela particionada por uma coluna TIMESTAMP.

CREATE TABLE mydataset.myclusteredtable
(
  timestamp TIMESTAMP,
  customer_id STRING,
  transaction_amount NUMERIC
)
PARTITION BY DATE(timestamp)
CLUSTER BY
  customer_id
OPTIONS (
  partition_expiration_days=3,
  description="a table clustered by customer_id"
)
AS SELECT * FROM mydataset.myothertable

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.myclusteredtable, o qualificador de tabela pode ser `myproject.mydataset.myclusteredtable`.

O esquema da tabela contém três colunas:

  • timestamp: o momento da coleta de dados como um TIMESTAMP;
  • customer_id: o ID do cliente como STRING;
  • transaction_amount: o valor da transação como NUMERIC.

A lista de opções da tabela especifica:

  • Validade da partição: 3 dias;
  • Descrição: A table clustered by customer_id
Exemplo 2

No exemplo a seguir, é criada uma tabela em cluster denominada myclusteredtable em mydataset usando o resultado de uma consulta. A tabela não é particionada.

CREATE TABLE mydataset.myclusteredtable
(
  customer_id STRING,
  transaction_amount NUMERIC
)
CLUSTER BY
  customer_id
OPTIONS (
  description="a table clustered by customer_id"
)
AS SELECT * FROM mydataset.myothertable

Se você não tiver configurado um projeto padrão, anexe um ID do projeto ao nome do conjunto de dados no SQL de exemplo e coloque o nome entre crases caso project_id contenha caracteres especiais: `project_id.dataset.table`. Assim, em vez de mydataset.myclusteredtable, o qualificador de tabela pode ser `myproject.mydataset.myclusteredtable`.

O esquema da tabela contém duas colunas:

  • customer_id: o ID do cliente como STRING;
  • transaction_amount: o valor da transação como NUMERIC.

A lista de opções da tabela especifica:

  • Descrição: A table clustered by customer_id

Como criar uma tabela temporária

No exemplo a seguir, criamos uma tabela temporária chamada Example e insere valores nela.

CREATE TEMP TABLE Example
(
  x INT64,
  y STRING
);

INSERT INTO Example
VALUES (5, 'foo');

INSERT INTO Example
VALUES (6, 'bar');

SELECT *
FROM Example;

Esse script retorna a saída a seguir:

+-----+---+-----+
| Row | x | y   |
+-----+---|-----+
| 1   | 5 | foo |
| 2   | 6 | bar |
+-----+---|-----+

Instrução CREATE TABLE LIKE

Cria uma nova tabela com todos os mesmos metadados de outra tabela.

Sintaxe

CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ]
table_name
LIKE [[project_name.]dataset_name.]source_table_name
...
[OPTIONS(table_option_list)]

Detalhes

Além do uso da cláusula LIKE no lugar de uma lista de colunas, a sintaxe é idêntica à sintaxe CREATE TABLE.

A instrução CREATE TABLE LIKE copia apenas os metadados da tabela de origem. É possível usar a cláusula as query_statement para incluir dados na nova tabela.

A nova tabela não tem qualquer relação com a tabela de origem após a criação. Portanto, as modificações na tabela de origem não serão propagadas para a nova tabela.

Por padrão, a nova tabela herda os metadados de particionamento, clustering e opções da tabela de origem. É possível personalizar metadados na nova tabela usando as cláusulas opcionais na instrução SQL. Por exemplo, se você quiser especificar um conjunto diferente de opções para a nova tabela, inclua a cláusula OPTIONS com uma lista de opções e valores. Esse comportamento corresponde ao de ALTER TABLE SET OPTIONS.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.create O conjunto de dados em que a tabela é criada.
bigquery.tables.get A tabela de origem.

Além disso, a cláusula OR REPLACE requer as permissões bigquery.tables.update e bigquery.tables.updateData.

Se a cláusula OPTIONS incluir alguma opção de expiração, a permissão bigquery.tables.delete também será obrigatória.

Examples

Exemplo 1

No exemplo a seguir, criamos uma nova tabela chamada newtable em mydataset com os mesmos metadados que sourcetable:

CREATE TABLE mydataset.newtable
LIKE mydataset.sourcetable

Exemplo 2

No exemplo a seguir, criamos uma nova tabela chamada newtable em mydataset com os mesmos metadados que sourcetable e os dados da instrução SELECT:

CREATE TABLE mydataset.newtable
LIKE mydataset.sourcetable
AS SELECT * FROM mydataset.myothertable

Instrução CREATE TABLE COPY

Cria uma tabela que tem os mesmos metadados e dados de outra tabela. A tabela de origem pode ser uma tabela, um clone de tabela ou um snapshot de tabela.

Sintaxe

CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ] table_name
COPY source_table_name
...
[OPTIONS(table_option_list)]

Detalhes

Além do uso da cláusula COPY no lugar de uma lista de colunas, a sintaxe é idêntica à sintaxe CREATE TABLE.

A instrução CREATE TABLE COPY copia os metadados e os dados da tabela de origem.

A nova tabela herda o particionamento e o clustering da tabela de origem. Por padrão, os metadados das opções da tabela de origem também são herdados, mas é possível substituir as opções usando a cláusula OPTIONS. O comportamento equivale a executar ALTER TABLE SET OPTIONS depois que a tabela é copiada.

Após a criação, a nova tabela não tem relação com a tabela de origem. Portanto, as modificações na tabela de origem não são propagadas para a nova tabela.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.create O conjunto de dados em que você cria o snapshot da tabela.
bigquery.tables.get A tabela de origem.
bigquery.tables.getData A tabela de origem.

Além disso, a cláusula OR REPLACE requer as permissões bigquery.tables.update e bigquery.tables.updateData.

Se a cláusula OPTIONS incluir alguma opção de expiração, a permissão bigquery.tables.delete também será obrigatória.

Instrução CREATE SNAPSHOT TABLE

Cria um snapshot de tabela com base em uma tabela de origem. A tabela de origem pode ser uma tabela, um clone de tabela ou um snapshot de tabela.

Sintaxe

CREATE SNAPSHOT TABLE [ IF NOT EXISTS ] table_snapshot_name
CLONE source_table_name
[FOR SYSTEM_TIME AS OF time_expression]
[OPTIONS(snapshot_option_list)]

Argumentos

  • IF NOT EXISTS: se um snapshot de tabela ou outro recurso de tabela existir com o mesmo nome, a instrução CREATE não terá efeito.

  • table_snapshot_name: o nome do snapshot da tabela que você quer criar. O nome do snapshot da tabela precisa ser exclusivo por conjunto de dados. Consulte Sintaxe do caminho da tabela.

  • source_table_name: o nome da tabela que você quer copiar ou o snapshot da tabela que quer copiar. Consulte Sintaxe do caminho da tabela.

    Se a tabela de origem for uma tabela padrão, o BigQuery criará um snapshot da tabela de origem. Se a tabela de origem for um snapshot de tabela, o BigQuery criará uma cópia do snapshot da tabela.

  • FOR SYSTEM_TIME AS OF: permite que você selecione a versão da tabela que estava sendo atualizada no momento especificado por timestamp_expression. Ela só pode ser usada ao criar um snapshot de uma tabela; não será possível usá-la para copiar um snapshot de tabela.

  • snapshot_option_list: outras opções de criação de snapshots de tabelas, como um rótulo e um prazo de validade.

Detalhes

Nas instruções CREATE SNAPSHOT TABLE, siga estas regras:

  • Apenas uma instrução CREATE é permitida.
  • A tabela de origem precisa ser um dos seguintes itens:
    • Uma tabela
    • Um clone de tabela
    • Um snapshot da tabela
  • A cláusula FOR SYSTEM_TIME AS OF só pode ser usada ao criar, e não ao copiar, o snapshot de uma tabela.

snapshot_option_list

A lista de opções permite que você defina opções de snapshot da tabela, como um rótulo e um prazo de validade. Para incluir várias opções, use uma lista separada por vírgulas.

Especifique uma lista de opções de snapshot de tabela no formato a seguir:

NAME=VALUE, ...

NAME e VALUE precisam ser uma das combinações a seguir:

NAME VALUE Detalhes
expiration_timestamp TIMESTAMP

Exemplo: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Essa propriedade é equivalente à propriedade de recurso de tabela expirationTime.

friendly_name

STRING

Exemplo: friendly_name="my_table_snapshot"

Essa propriedade é equivalente à propriedade de recurso de tabela friendlyName.

description

STRING

Exemplo: description="A table snapshot that expires in 2025"

Essa propriedade é equivalente à propriedade de recurso de tabela description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemplo: labels=[("org_unit", "development")]

Essa propriedade é equivalente à propriedade de recurso de tabela labels.

VALUE é uma expressão constante que contém apenas literais, parâmetros de consulta e funções escalares.

A expressão constante não pode conter os itens a seguir:

  • Uma referência a uma tabela
  • Subconsultas ou instruções SQL, como SELECT, CREATE e UPDATE
  • funções definidas pelo usuário, funções agregadas ou funções analíticas
  • as funções escalares a seguir:
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

Se VALUE for avaliado como NULL, a opção correspondente NAME na instrução CREATE SNAPSHOT TABLE será ignorada.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.create O conjunto de dados em que você cria o snapshot da tabela.
bigquery.tables.createSnapshot A tabela de origem.
bigquery.tables.get A tabela de origem.
bigquery.tables.getData A tabela de origem.

Exemplos

Criar um snapshot da tabela: falha se ele já existir

No exemplo a seguir, criamos um snapshot da tabela myproject.mydataset.mytable. O snapshot da tabela é criado no conjunto de dados mydataset e denominado mytablesnapshot:

CREATE SNAPSHOT TABLE `myproject.mydataset.mytablesnapshot`
CLONE `myproject.mydataset.mytable`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="my_table_snapshot",
  description="A table snapshot that expires in 2 days",
  labels=[("org_unit", "development")]
)

Se o nome do snapshot da tabela já existir no conjunto de dados, o erro a seguir será retornado:

Already Exists: myproject.mydataset.mytablesnapshot

A lista de opções de snapshot da tabela especifica o seguinte:

  • Prazo de validade: 48 horas após a criação do snapshot da tabela
  • Nome amigável: my_table_snapshot
  • Descrição: A table snapshot that expires in 2 days
  • Rótulo: org_unit = development

Criar um snapshot da tabela: ignorar se já existir

No exemplo a seguir, criamos um snapshot da tabela myproject.mydataset.mytable. O snapshot da tabela é criado no conjunto de dados mydataset e denominado mytablesnapshot:

CREATE SNAPSHOT TABLE IF NOT EXISTS `myproject.mydataset.mytablesnapshot`
CLONE `myproject.mydataset.mytable`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="my_table_snapshot",
  description="A table snapshot that expires in 2 days"
  labels=[("org_unit", "development")]
)

A lista de opções de snapshot da tabela especifica o seguinte:

  • Prazo de validade: 48 horas após a criação do snapshot da tabela
  • Nome amigável: my_table_snapshot
  • Descrição: A table snapshot that expires in 2 days
  • Rótulo: org_unit = development

Se o nome do snapshot da tabela já existir no conjunto de dados, nenhuma ação será tomada e nenhum erro será retornado.

Para mais informações sobre como restaurar snapshots de tabelas, consulte CREATE TABLE CLONE.

Para mais informações sobre como remover snapshots de tabelas, consulte DROP SNAPSHOT TABLE.

Instrução CREATE TABLE CLONE

Cria um clone de tabela com base em uma tabela de origem. A tabela de origem pode ser uma tabela, um clone de tabela ou um snapshot de tabela.

Sintaxe

CREATE [ OR REPLACE ] TABLE [ IF NOT EXISTS ]
destination_table_name
CLONE source_table_name [FOR SYSTEM_TIME AS OF time_expression]
...
[OPTIONS(table_option_list)]

Detalhes

Além do uso da cláusula CLONE no lugar de uma lista de colunas, a sintaxe é idêntica à sintaxe CREATE TABLE.

Argumentos

  • OR REPLACE: substitui qualquer função com o mesmo nome, se houver. Não pode aparecer com IF NOT EXISTS.

  • IF NOT EXISTS: se o nome da tabela de destino especificado já existir, a instrução CREATE não terá efeito. Não pode aparecer com OR REPLACE.

destination_table_name é o nome da tabela que você quer criar; O nome da tabela precisa ser exclusivo por conjunto de dados. O nome da tabela pode conter:

  • até 1.024 caracteres
  • Letras (maiúsculas e minúsculas), números e sublinhados

OPTIONS(table_option_list) permite especificar outras opções de criação de visualizações, como um rótulo e um prazo de validade.

source_table_name é o nome da tabela de origem.

Nas instruções CREATE TABLE CLONE, siga estas regras:

  • Apenas uma instrução CREATE é permitida.
  • A tabela que está sendo clonada precisa ser uma tabela, um clone de tabela ou um snapshot de tabela.

OPTIONS

As opções CREATE TABLE CLONE são iguais às opções CREATE TABLE.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.create O conjunto de dados em que o clone de tabela é criado.
bigquery.tables.get A tabela de origem.
bigquery.tables.getData A tabela de origem.
bigquery.tables.restoreSnapshot A tabela de origem (obrigatório apenas se a tabela de origem for um snapshot de tabela).

Além disso, a cláusula OR REPLACE requer as permissões bigquery.tables.update e bigquery.tables.updateData.

Se a cláusula OPTIONS incluir alguma opção de expiração, a permissão bigquery.tables.delete também será obrigatória.

Examples

Restaurar um snapshot da tabela: falhará se a tabela de destino já existir

O exemplo a seguir cria a tabela myproject.mydataset.mytable a partir do snapshot da tabela myproject.mydataset.mytablesnapshot:

CREATE TABLE `myproject.mydataset.mytable`
CLONE `myproject.mydataset.mytablesnapshot`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 365 DAY),
  friendly_name="my_table",
  description="A table that expires in 1 year",
  labels=[("org_unit", "development")]
)

Se o nome da tabela existir no conjunto de dados, o erro a seguir será retornado:

Already Exists: myproject.mydataset.mytable.

A lista de opções da tabela especifica:

  • Prazo de validade: 365 dias após a criação da tabela
  • Nome amigável: my_table
  • Descrição: A table that expires in 1 year
  • Rótulo: org_unit = development

Criar o clone de uma tabela: ignore se a tabela de destino já existir

O exemplo a seguir cria o clone da tabela myproject.mydataset.mytableclone com base na tabela myproject.mydataset.mytable:

CREATE TABLE IF NOT EXISTS `myproject.mydataset.mytableclone`
CLONE `myproject.mydataset.mytable`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 365 DAY),
  friendly_name="my_table",
  description="A table that expires in 1 year",
  labels=[("org_unit", "development")]
)

A lista de opções da tabela especifica:

  • Prazo de validade: 365 dias após a criação da tabela
  • Nome amigável: my_table
  • Descrição: A table that expires in 1 year
  • Rótulo: org_unit = development

Se o nome da tabela existir no conjunto de dados, nenhuma ação será tomada e nenhum erro será retornado.

Saiba mais sobre como criar uma cópia de tabela em CREATE TABLE COPY.

Saiba mais sobre como criar um snapshot de tabela em CREATE SNAPSHOT TABLE.

Instrução CREATE VIEW

Cria uma nova visualização.

Sintaxe

CREATE [ OR REPLACE ] VIEW [ IF NOT EXISTS ] view_name
[(view_column_name_list)]
[OPTIONS(view_option_list)]
AS query_expression

Argumentos

  • OR REPLACE: substitui qualquer visualização com o mesmo nome, se houver. Não pode aparecer com IF NOT EXISTS.

  • IF NOT EXISTS: se uma visualização ou outro recurso de tabela existir com o mesmo nome, a instrução CREATE não terá efeito. Não pode aparecer com OR REPLACE.

  • view_name: o nome da visualização que você está criando. Consulte Sintaxe do caminho da tabela.

  • view_column_name_list: permite especificar explicitamente os nomes das colunas da visualização, que podem ser aliases dos nomes de coluna na consulta SQL subjacente.

  • view_option_list: outras opções de criação de visualizações, como um rótulo e um prazo de validade.

  • query_expression é a expressão da consulta SQL padrão usada para definir a visualização.

Detalhes

Nas instruções CREATE VIEW, siga estas regras:

  • Apenas uma instrução CREATE é permitida.

view_column_name_list

A lista de nomes de colunas da visualização é opcional. Os nomes precisam ser exclusivos, mas não precisam ser iguais aos nomes das colunas da consulta SQL subjacente. Por exemplo, se a visualização for criada com a seguinte instrução:

CREATE VIEW mydataset.age_groups(age, count) AS SELECT age, COUNT(*)
FROM mydataset.people
group by age;

Você pode consultá-la com:

SELECT age, count from mydataset.age_groups;

o número de colunas na lista de nomes de colunas precisa corresponder ao número de colunas na consulta SQL subjacente. Se as colunas na tabela da consulta SQL subjacente forem adicionadas ou removidas, a visualização ficará inválida e precisará ser recriada. Por exemplo, se a coluna age for removida da tabela mydataset.people, a visualização criada no exemplo anterior ficará inválida.

view_option_list

A lista de opções permite que você defina opções de visualização, como um rótulo e um prazo de validade. Para incluir várias opções, use uma lista separada por vírgulas.

Especifique uma lista de opções de visualização no formato a seguir:

NAME=VALUE, ...

NAME e VALUE precisam ser uma das combinações a seguir:

NAME VALUE Detalhes
expiration_timestamp TIMESTAMP

Exemplo: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Essa propriedade é equivalente à propriedade de recurso de tabela expirationTime.

friendly_name

STRING

Exemplo: friendly_name="my_view"

Essa propriedade é equivalente à propriedade de recurso de tabela friendlyName.

description

STRING

Exemplo: description="a view that expires in 2025"

Essa propriedade é equivalente à propriedade de recurso de tabela description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemplo: labels=[("org_unit", "development")]

Essa propriedade é equivalente à propriedade de recurso de tabela labels.

VALUE é uma expressão constante que contém apenas literais, parâmetros de consulta e funções escalares.

A expressão constante não pode conter os itens a seguir:

  • Uma referência a uma tabela
  • Subconsultas ou instruções SQL, como SELECT, CREATE ou UPDATE
  • Funções definidas pelo usuário, funções agregadas ou funções analíticas
  • as funções escalares a seguir:
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

Se VALUE for avaliado como NULL, a opção correspondente NAME na instrução CREATE VIEW será ignorada.

Projeto padrão no corpo da visualização

Se a visualização for criada no mesmo projeto usado para executar a instrução CREATE VIEW, o corpo da visualização query_expression poderá referir-se a entidades sem especificar o projeto. O projeto padrão é o proprietário da visualização. Considere o exemplo de consulta abaixo.

CREATE VIEW myProject.myDataset.myView AS SELECT * FROM anotherDataset.myTable;

Depois de executar a consulta CREATE VIEW acima no projeto myProject, execute SELECT * FROM myProject.myDataset.myView. Independentemente do projeto escolhido para executar essa consulta SELECT, a tabela referenciada anotherDataset.myTable é sempre resolvida em relação ao projeto myProject.

Se a visualização não for criada no mesmo projeto usado para executar a instrução CREATE VIEW, todas as referências no corpo da visualização query_expression precisarão ser qualificadas com os IDs do projeto. Por exemplo, a consulta de amostra CREATE VIEW anterior é inválida se for executada em um projeto diferente de myProject.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.create O conjunto de dados em que a visualização é criada.

Além disso, a cláusula OR REPLACE requer a permissão bigquery.tables.update.

Se a cláusula OPTIONS incluir um prazo de validade, a permissão bigquery.tables.delete também será obrigatória.

Examples

Como criar uma nova visualização

No exemplo a seguir, criamos uma visualização denominada newview em mydataset:

CREATE VIEW `myproject.mydataset.newview`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="newview",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")]
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

Se o nome da visualização existir no conjunto de dados, o erro a seguir será retornado:

Already Exists: project_id:dataset.table

A visualização é definida usando a consulta SQL padrão a seguir:

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

A lista de opções de visualização especifica:

  • Prazo de validade: 48 horas a partir do momento em que a visualização é criada;
  • Nome amigável: newview
  • Descrição: A view that expires in 2 days
  • Rótulo: org_unit = development

Como criar uma visualização somente se ela não existir

No exemplo a seguir, criaremos uma visualização chamada newview em mydataset somente se nenhuma visualização chamada newview existir em mydataset. Se o nome da visualização existir no conjunto de dados, nenhum erro será retornado e nenhuma ação será tomada.

CREATE VIEW IF NOT EXISTS `myproject.mydataset.newview`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="newview",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")]
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

A visualização é definida usando a consulta SQL padrão a seguir:

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

A lista de opções de visualização especifica:

  • Prazo de validade: 48 horas a partir do momento em que a visualização é criada;
  • Nome amigável: newview
  • Descrição: A view that expires in 2 days
  • Rótulo: org_unit = development

Como criar ou substituir uma visualização

No exemplo a seguir, criamos uma visualização chamada newview em mydataset, e se newview existir em mydataset, ela será substituída usando a expressão de consulta especificada.

CREATE OR REPLACE VIEW `myproject.mydataset.newview`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="newview",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")]
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

A visualização é definida usando a consulta SQL padrão a seguir:

SELECT column_1, column_2, column_3 FROM myproject.mydataset.mytable

A lista de opções de visualização especifica:

  • Prazo de validade: 48 horas a partir do momento em que a visualização é criada;
  • Nome amigável: newview
  • Descrição: A view that expires in 2 days
  • Rótulo: org_unit = development

Instrução CREATE MATERIALIZED VIEW

Cria uma nova visualização materializada.

Sintaxe

CREATE [ OR REPLACE ] MATERIALIZED VIEW [ IF NOT EXISTS ] materialized_view_name
[PARTITION BY partition_expression]
[CLUSTER BY clustering_column_list]
[OPTIONS(materialized_view_option_list)]
AS query_expression

Argumentos

  • OR REPLACE: substitui qualquer visualização materializada com o mesmo nome, se houver. Não pode aparecer com IF NOT EXISTS.

  • IF NOT EXISTS: se uma visualização materializada ou outro recurso de tabela existir com o mesmo nome, a instrução CREATE não terá efeito. Não pode aparecer com OR REPLACE.

  • materialized_view_name: o nome da visualização materializada que está sendo criada. Consulte Sintaxe do caminho da tabela.

    Se o project_name for omitido do nome da visualização materializada ou for igual ao projeto que executa essa consulta DDL, o último também será usado como projeto padrão para referências a tabelas, funções. e outros recursos em query_expression. O projeto padrão das referências é fixo e não depende das futuras consultas que invocam a nova visualização materializada. Caso contrário, todas as referências em query_expression precisam ser qualificadas com nomes de projetos.

    Esse nome precisa ser exclusivo por conjunto de dados.

  • partition_expression: é uma expressão que determina como particionar a tabela. Uma visualização materializada só pode ser particionada da mesma maneira como se particiona a tabela em query expression (a tabela base).

  • clustering_column_list: uma lista separada por vírgulas de referências de coluna que determinam como agrupar a visualização materializada.

  • materialized_view_option_list** permite que você especifique outras opções de visualização materializadas, como a ativação e o intervalo da atualização, um rótulo e um prazo de validade.

  • query_expression é a expressão de consulta SQL padrão usada para definir a visualização materializada.

Detalhes

Nas instruções CREATE MATERIALIZED VIEW, siga estas regras:

  • Apenas uma instrução CREATE é permitida.

Projeto padrão no corpo da visualização materializada

Se a visualização materializada for criada no mesmo projeto usado para executar a instrução CREATE MATERIALIZED VIEW, o corpo da visualização materializada query_expression poderá referir-se a entidades sem especificar o projeto. O projeto padrão é o proprietário da visualização materializada. Considere o exemplo de consulta abaixo.

CREATE MATERIALIZED VIEW myProject.myDataset.myView AS SELECT * FROM anotherDataset.myTable;

Depois de executar a consulta CREATE MATERIALIZED VIEW acima no projeto myProject, execute SELECT * FROM myProject.myDataset.myView. Independentemente do projeto escolhido para executar essa consulta SELECT, a tabela referenciada anotherDataset.myTable é sempre resolvida em relação ao projeto myProject.

Se a visualização materializada não for criada no mesmo projeto usado para executar a instrução CREATE VIEW, todas as referências no corpo da visualização materializada query_expression precisarão ser qualificadas com IDs de projeto. Por exemplo, a consulta de amostra CREATE MATERIALIZED VIEW anterior é inválida se for executada em um projeto diferente de myProject.

materialized_view_option_list

A lista de opções permite que você defina opções de visualização materializadas, como a ativação e o intervalo de atualização, um rótulo e um prazo de validade. Para incluir várias opções, use uma lista separada por vírgulas.

Especifique uma lista de opções de visualização materializada no formato a seguir:

NAME=VALUE, ...

NAME e VALUE precisam ser uma das combinações a seguir:

NAME VALUE Detalhes
enable_refresh BOOLEAN

Exemplo: enable_refresh=false

refresh_interval_minutes FLOAT64

Exemplo: refresh_interval_minutes=20

expiration_timestamp TIMESTAMP

Exemplo: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Essa propriedade é equivalente à propriedade de recurso de tabela expirationTime.

friendly_name

STRING

Exemplo: friendly_name="my_mv"

Essa propriedade é equivalente à propriedade de recurso de tabela friendlyName.

description

STRING

Exemplo: description="a materialized view that expires in 2025"

Essa propriedade é equivalente à propriedade de recurso de tabela description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemplo: labels=[("org_unit", "development")]

Essa propriedade é equivalente à propriedade de recurso de tabela labels.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.create O conjunto de dados em que você cria a visualização materializada.

Além disso, a cláusula OR REPLACE requer a permissão bigquery.tables.update.

Se a cláusula OPTIONS incluir alguma opção de expiração, a permissão bigquery.tables.delete também será obrigatória.

Examples

Como criar uma nova visualização materializada

O exemplo a seguir cria uma visualização materializada denominada new_mv em mydataset:

CREATE MATERIALIZED VIEW `myproject.mydataset.new_mv`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="new_mv",
  description="a materialized view that expires in 2 days",
  labels=[("org_unit", "development")],
  enable_refresh=true,
  refresh_interval_minutes=20
)
AS SELECT column_1, SUM(column_2) AS sum_2, AVG(column_3) AS avg_3
FROM `myproject.mydataset.mytable`
GROUP BY column_1

Se o nome da visualização materializada existir no conjunto de dados, este erro será retornado:

Already Exists: project_id:dataset.materialized_view

Ao usar uma instrução DDL para criar uma visualização materializada, especifique o projeto, o conjunto de dados e a visualização materializada no seguinte formato: `project_id.dataset.materialized_view` (incluindo os acentos graves, se project_id tiver caracteres especiais); por exemplo, `myproject.mydataset.new_mv`.

A visualização materializada é definida usando a consulta SQL padrão a seguir:

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

A lista de opções de visualização materializada especifica:

  • Prazo de validade: 48 horas a partir da criação da visualização materializada;
  • Nome amigável: new_mv
  • Descrição: A materialized view that expires in 2 days
  • Rótulo: org_unit = development
  • Atualização ativada: true;
  • Intervalo de atualização: 20 minutos.

Como criar uma visualização materializada apenas se ela não existir

O exemplo a seguir cria uma visualização materializada chamada new_mv no mydataset apenas se não houver nenhuma com o nome new_mv no mydataset. Se esse nome existir no conjunto de dados, nenhum erro será retornado e nenhuma ação será realizada.

CREATE MATERIALIZED VIEW IF NOT EXISTS `myproject.mydataset.new_mv`
OPTIONS(
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 48 HOUR),
  friendly_name="new_mv",
  description="a view that expires in 2 days",
  labels=[("org_unit", "development")],
  enable_refresh=false
)
AS SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

A visualização materializada é definida usando a consulta SQL padrão a seguir:

SELECT column_1, column_2, column_3 FROM `myproject.mydataset.mytable`

A lista de opções de visualização materializada especifica:

  • Prazo de validade: 48 horas a partir do momento em que a visualização é criada;
  • Nome amigável: new_mv
  • Descrição: A view that expires in 2 days
  • Rótulo: org_unit = development
  • Atualização ativada: falso.

Como criar uma visualização materializada com particionamento e clustering

O exemplo a seguir cria uma visualização materializada denominada new_mv em mydataset, particionada pela coluna col_datetime e em cluster pela coluna col_int:

CREATE MATERIALIZED VIEW `myproject.mydataset.new_mv`
PARTITION BY DATE(col_datetime)
CLUSTER BY col_int
AS SELECT col_int, col_datetime, COUNT(1) as cnt
   FROM `myproject.mydataset.mv_base_table`
   GROUP BY col_int, col_datetime

A tabela base, mv_base_table, também precisa ser particionada pela coluna col_datetime. Para mais informações, consulte Como trabalhar com tabelas particionadas e em cluster.

Instrução CREATE EXTERNAL TABLE

Cria uma nova tabela externa.

Com as tabelas externas, os dados de consulta do BigQuery são armazenados fora do armazenamento do BigQuery. Para mais informações sobre tabelas externas, consulte Introdução às fontes de dados externas.

Sintaxe

CREATE [ OR REPLACE ] EXTERNAL TABLE [ IF NOT EXISTS ] table_name
[(
  column_name column_schema,
  ...
)]
[WITH CONNECTION connection_name]
[WITH PARTITION COLUMNS
  [(
      partition_column_name partition_column_type,
      ...
  )]
]
OPTIONS (
  external_table_option_list,
  ...
);

Argumentos

  • OR REPLACE: substitui qualquer função com o mesmo nome, se houver. Não pode aparecer com IF NOT EXISTS.

  • IF NOT EXISTS: se uma tabela externa ou outro recurso de tabela existir com o mesmo nome, a instrução CREATE não terá efeito. Não pode aparecer com OR REPLACE.

  • table_name: o nome da tabela externa. Consulte Sintaxe do caminho da tabela.

  • column_name: o nome de uma coluna na tabela.

  • column_schema especifica o esquema da coluna. Ele usa a mesma sintaxe da definição column_schema na instrução CREATE TABLE. Se você não incluir essa cláusula, o esquema será detectado automaticamente pelo BigQuery.

  • connection_name: especifica um recurso de conexão que tem credenciais para acessar os dados externos. Especifique o nome da conexão no formato PROJECT_ID.LOCATION.CONNECTION_ID. Se o ID ou o local do projeto contiver um traço, coloque o nome da conexão entre acentos graves (`).

  • partition_column_name: o nome de uma coluna de partição. Inclua este campo se os dados externos usarem um layout particionado do Hive. Para mais informações, consulte Layouts de dados compatíveis.

  • partition_column_type: o tipo de coluna da partição.

  • external_table_option_list: uma lista de opções para criar a tabela externa.

Detalhes

A instrução CREATE EXTERNAL TABLE não é compatível com a criação de tabelas externas temporárias.

Para criar uma tabela particionada externamente, use a cláusula WITH PARTITION COLUMNS para especificar os detalhes do esquema de partição. O BigQuery valida as definições de coluna em relação ao local externo de dados. A declaração do esquema precisa seguir estritamente a ordem dos campos do caminho externo. Para mais informações sobre o particionamento externo, consulte Como consultar dados particionados externamente.

external_table_option_list

A lista especifica opções para a criação da tabela externa. As opções format e uris são obrigatórias. Especifique a lista de opções no seguinte formato: NAME=VALUE, ...

Opções
allow_jagged_rows

BOOL

Se true, permita linhas que não têm colunas opcionais posteriores.

Aplica-se a dados CSV.

allow_quoted_newlines

BOOL

Se true, permita seções de dados entre aspas que contenham caracteres de nova linha no arquivo.

Aplica-se a dados CSV.

compression

STRING

O tipo de compactação da fonte de dados. Os valores aceitos são: GZIP. Se não for especificada, a fonte de dados será descompactada.

Aplica-se a dados CSV e JSON.

description

STRING

Uma descrição da tabela.

enable_logical_types

BOOL

Se true, converta tipos lógicos Avro nos tipos SQL correspondentes. Para mais informações, consulte Tipos lógicos.

Aplica-se a dados Avro.

enum_as_string

BOOL

Se true, inferir o tipo lógico Parquet ENUM como STRING em vez de BYTES por padrão.

Aplicável a dados Parquet.

enable_list_inference

BOOL

Se true, use a inferência de esquema especificamente para o tipo lógico Parquet LIST.

Aplicável a dados Parquet.

encoding

STRING

A codificação de caracteres dos dados. Os valores aceitos incluem: UTF8 (ou UTF-8), ISO_8859_1 (ou ISO-8859-1).

Aplica-se a dados CSV.

expiration_timestamp

TIMESTAMP

A hora em que esta tabela expira. Se não for especificado, a tabela não expirará.

Exemplo: "2025-01-01 00:00:00 UTC".

field_delimiter

STRING

O separador de campos em um arquivo CSV.

Aplica-se a dados CSV.

format

STRING

O formato dos dados externos. Os valores compatíveis de CREATE EXTERNAL TABLE incluem: AVRO, CSV, DATASTORE_BACKUP, GOOGLE_SHEETS, NEWLINE_DELIMITED_JSON (ou JSON), ORC e PARQUET.

Os valores compatíveis de LOAD DATA incluem: AVRO, CSV, NEWLINE_DELIMITED_JSON (ou JSON), ORC e PARQUET.

O valor JSON é equivalente a NEWLINE_DELIMITED_JSON.

decimal_target_types

ARRAY<STRING>

Determina como converter um tipo Decimal. Equivalente a ExternalDataConfiguration.decimal_target_types

Exemplo: ["NUMERIC", "BIGNUMERIC"].

json_extension

STRING

Para dados JSON, indica um determinado formato de intercâmbio JSON. Se não for especificado, o BigQuery lerá os dados como registros JSON genéricos.

Os valores aceitos são:
GEOJSON. Dados GeoJSON delimitados por nova linha. Para mais informações, consulte Como criar uma tabela externa a partir de um arquivo GeoJSON delimitado por nova linha.

hive_partition_uri_prefix

STRING

Um prefixo comum para todos os URIs de origem antes do início da codificação da chave de partição. Aplica-se apenas a tabelas externas particionadas pelo Hive.

Aplica-se aos dados Avro, CSV, JSON, Parquet e ORC.

Exemplo: "gs://bucket/path".

ignore_unknown_values

BOOL

Se for true, ignora valores extras que não estejam representados no esquema da tabela, sem retornar um erro.

Aplica-se a dados CSV e JSON.

max_bad_records

INT64

O número máximo de registros corrompidos a serem ignorados durante a leitura dos dados.

Aplica-se a: dados CSV, JSON e Planilhas.

null_marker

STRING

A string que representa os valores NULL em um arquivo CSV.

Aplica-se a dados CSV.

preserve_ascii_control_characters

BOOL

Se true, os caracteres ASCII de controle incorporados que são os primeiros 32 caracteres na tabela ASCII, que variam de "\x00" a "\x1F", serão preservados.

Aplica-se a dados CSV.

projection_fields

STRING

Uma lista de propriedades da entidade a serem carregadas.

Aplica-se aos dados do Datastore.

quote

STRING

A string usada para citar seções de dados em um arquivo CSV. Se os dados contiverem caracteres de nova linha entre aspas, defina também a propriedade allow_quoted_newlines como true.

Aplica-se a dados CSV.

require_hive_partition_filter

BOOL

Se true, todas as consultas nesta tabela exigem um filtro de partição que pode ser usado para eliminar partições ao ler dados. Aplica-se apenas a tabelas externas particionadas pelo Hive.

Aplica-se aos dados Avro, CSV, JSON, Parquet e ORC.

sheet_range

STRING

Intervalo de uma planilha do Planilhas a ser consultada.

Aplicável aos dados do Planilhas.

Exemplo: “sheet1!A1:B20”,

skip_leading_rows

INT64

O número de linhas na parte superior de um arquivo a ser ignorado na leitura dos dados.

Aplicável aos dados CSV e Planilhas.

uris

ARRAY<STRING>

Uma matriz de URIs totalmente qualificados para os locais de dados externos.

Exemplo: ["gs://bucket/path/*"].

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.create O conjunto de dados em que a tabela externa é criada

Além disso, a cláusula OR REPLACE requer a permissão bigquery.tables.update.

Se a cláusula OPTIONS incluir um prazo de validade, a permissão bigquery.tables.delete também será obrigatória.

Examples

No exemplo a seguir, criamos uma tabela externa a partir de vários URIs. O formato dos dados é CSV. Este exemplo usa detecção automática de esquema.

CREATE EXTERNAL TABLE dataset.CsvTable OPTIONS (
  format = 'CSV',
  uris = ['gs://bucket/path1.csv', 'gs://bucket/path2.csv']
);

O exemplo a seguir cria uma tabela externa a partir de um arquivo CSV e especifica explicitamente o esquema. Ele também especifica o delimitador do campo ('|') e define o número máximo de registros inválidos permitidos.

CREATE OR REPLACE EXTERNAL TABLE dataset.CsvTable
(
  x INT64,
  y STRING
)
OPTIONS (
  format = 'CSV',
  uris = ['gs://bucket/path1.csv'],
  field_delimiter = '|',
  max_bad_records = 5
);

No exemplo a seguir, criamos uma tabela particionada externamente. Ele usa a detecção automática de esquema para detectar o esquema de arquivo e o layout de particionamento do Hive.

Por exemplo, se o caminho externo for gs://bucket/path/field_1=first/field_2=1/data.csv, as colunas da partição serão field_1 (STRING) e field_2 (INT64).

CREATE EXTERNAL TABLE dataset.AutoHivePartitionedTable
WITH PARTITION COLUMNS
OPTIONS (
  uris=['gs://bucket/path/*'],
  format=csv,
  hive_partition_uri_prefix='gs://bucket/path'
);

O exemplo a seguir cria uma tabela particionada externamente especificando explicitamente as colunas de partição. Neste exemplo, consideramos que o caminho do arquivo externo tem o padrão gs://bucket/path/field_1=first/field_2=1/data.csv.

CREATE EXTERNAL TABLE dataset.CustomHivePartitionedTable
WITH PARTITION COLUMNS (
  field_1 STRING, -- column order must match the external path
  field_2 INT64
)
OPTIONS (
  uris=['gs://bucket/path/*'],
  format=csv,
  hive_partition_uri_prefix='gs://bucket/path'
);

Instrução CREATE FUNCTION

Cria uma nova função definida pelo usuário (UDF, na sigla em inglês). O BigQuery é compatível com UDFs escritas em SQL ou JavaScript.

Sintaxe

Para criar uma UDF em SQL, use a seguinte sintaxe:

CREATE [ OR REPLACE ] [ TEMPORARY | TEMP ] FUNCTION [ IF NOT EXISTS ]
    [[project_name.]dataset_name.]function_name
    ([named_parameter[, ...]])
     ([named_parameter[, ...]])
  [RETURNS data_type]
  AS (sql_expression)
  [OPTIONS (function_option_list)]

named_parameter:
  param_name param_type

Para criar uma UDF em JavaScript, use a seguinte sintaxe:

CREATE [OR REPLACE] [TEMPORARY | TEMP] FUNCTION [IF NOT EXISTS]
    [[project_name.]dataset_name.]function_name
    ([named_parameter[, ...]])
  RETURNS data_type
  [determinism_specifier]
  LANGUAGE js
  [OPTIONS (function_option_list)]
  AS javascript_code

named_parameter:
  param_name param_type

determinism_specifier:
  { DETERMINISTIC | NOT DETERMINISTIC }

Para criar uma função remota, use esta sintaxe:

CREATE [OR REPLACE] FUNCTION [IF NOT EXISTS]
    [[project_name.]dataset_name.]function_name
    ([named_parameter[, ...]])
  RETURNS data_type
  REMOTE WITH CONNECTION connection_path
  [OPTIONS (function_option_list)]

named_parameter:
  param_name param_type

Os nomes de rotina precisam conter apenas letras, números e sublinhados e ter no máximo 256 caracteres.

Argumentos

  • OR REPLACE: substitui qualquer função com o mesmo nome, se houver. Não pode aparecer com IF NOT EXISTS.

  • IF NOT EXISTS: se houver algum conjunto de dados com o mesmo nome, a instrução CREATE não terá efeito. Não pode aparecer com OR REPLACE.

  • TEMP ou TEMPORARY: cria uma função temporária. Se a cláusula não estiver presente, a instrução criará uma UDF permanente. É possível reutilizar UDFs permanentes em várias consultas, mas as UDFs temporárias só podem ser usadas em uma única consulta, script ou procedimento.

  • project_name. Para funções permanentes, o nome do projeto onde você está criando a função. O padrão é o projeto que executa a consulta DDL. Não inclua o nome do projeto para funções temporárias.

  • dataset_name. Para funções permanentes, o nome do conjunto de dados em que você está criando a função. O padrão na solicitação é defaultDataset. Não inclua o nome do conjunto de dados para funções temporárias.

  • function_name. O nome da função.

  • named_parameter: um par de param_name e param_type separado por vírgula. O valor de param_type é um tipo de dados do BigQuery. Para uma UDF SQL, o valor de param_type também pode ser ANY TYPE.

  • determinism_specifier: aplicável apenas a UDFs em JavaScript. Indica ao BigQuery se o resultado da consulta pode ser armazenado em cache. Pode ser um dos seguintes valores:

    • DETERMINISTIC: a função sempre retorna o mesmo resultado quando os mesmos argumentos são transmitidos. O resultado da consulta é potencialmente armazenável em cache. Por exemplo, se a função add_one(i) sempre retornar i + 1, a função será determinista.

    • NOT DETERMINISTIC: a função nem sempre retorna o mesmo resultado quando os mesmos argumentos são transmitidos e, portanto, não é armazenável em cache. Por exemplo, se a função add_random(i) retornar i + rand(), a função não é determinista e o BigQuery não usa resultados armazenados em cache.

      Se todas as funções invocadas forem DETERMINISTIC, o BigQuery tentará armazenar o resultado em cache, a menos que os resultados não possam ser armazenados em cache por outros motivos. Para saber mais, consulte Como usar resultados de consulta armazenados em cache.

  • data_type: especifica o tipo de dados retornado pela função.

    • Se a função estiver definida em SQL, a cláusula RETURNS será opcional. Se a cláusula RETURNS for omitida, o BigQuery deduzirá o tipo de resultado da função a partir do corpo da função SQL quando uma consulta chamar a função.
    • Se a função estiver definida em JavaScript, a cláusula RETURNS será obrigatória. Para mais informações sobre valores permitidos para data_type, consulte Tipos de dados de UDF JavaScript compatíveis.
  • sql_expression: especifica a expressão SQL que define a função.

  • function_option_list. Uma lista de opções para criar a função.

  • javascript_code: especifica a definição de uma função JavaScript. O valor é um literal de string. Se o código incluir aspas e barras invertidas, ele precisará ter escape ou ser representado como uma string bruta. Por exemplo, o código return "\n"; pode ser representado como um dos seguintes:

    • String entre aspas"return \"\\n\";". As aspas e as barras invertidas precisam ter escape.
    • String entre três aspas: """return "\\n";""". As barras invertidas precisam ser escapadas, sem aspas.
    • String bruta: r"""return "\n";""". Não é necessário escape.
  • connection_name: especifica um recurso de conexão que tem credenciais para acessar o endpoint remoto. Especifique o nome da conexão no formato project_name.location.connection_id. Se o nome ou o local do projeto tiver um traço, coloque o nome da conexão entre acentos graves (`).

function_option_list

A lista de opções especifica opções para criar uma UDF. As seguintes opções são compatíveis:

NAME VALUE Detalhes
description

STRING

Uma descrição da UDF.
library

ARRAY<STRING>

Matriz de bibliotecas JavaScript a serem incluídas na definição da função. Aplica-se apenas a UDFs em JavaScript. Para mais informações, consulte Como incluir bibliotecas JavaScript.

Exemplo: ["gs://my-bucket/lib1.js", "gs://my-bucket/lib2.js"]

endpoint

STRING

Um endpoint HTTP do Cloud Functions. Aplica-se somente a funções remotas.

Exemplo: "https://us-east1-your-project.cloudfunctions.net/foo"

Saiba mais em Como criar uma função remota.

user_defined_context

ARRAY<STRUCT<STRING,STRING>>

Uma lista de pares de chave-valor que será enviado com cada solicitação HTTP quando a função for invocada. Aplica-se somente a funções remotas.

Exemplo: [("key1","value1"),("key2", "value2")]

max_batching_rows

INT64

O número máximo de linhas em cada solicitação HTTP. Se não for especificado, o BigQuery decidirá quantas linhas serão incluídas em uma solicitação HTTP. Aplica-se somente a funções remotas.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.routines.create O conjunto de dados em que a função é criada.

Além disso, a cláusula OR REPLACE requer a permissão bigquery.routines.update.

Para criar uma função remota, são necessárias mais permissões do IAM:

Permissão Recurso
bigquery.connections.delegate A conexão usada para criar a função remota.

Examples

Criar uma UDF em SQL

No exemplo a seguir, é criada uma UDF em SQL permanente chamada multiplyInputs em um conjunto de dados chamado mydataset.

CREATE FUNCTION mydataset.multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
AS (x * y);

Criar uma UDF em JavaScript

O exemplo a seguir cria uma UDF em JavaScript temporária chamada multiplyInputs e a chama de dentro de uma instrução SELECT.

CREATE TEMP FUNCTION multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE js
AS r"""
  return x*y;
""";

SELECT multiplyInputs(a, b) FROM (SELECT 3 as a, 2 as b);

Criar uma função remota

No exemplo a seguir, criamos uma função remota permanente chamada remoteMultiplyInputs em um conjunto de dados chamado mydataset, supondo que mydataset está no local US e que existe uma conexão myconnection no mesmo local e no mesmo projeto.

CREATE FUNCTION mydataset.remoteMultiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
REMOTE WITH CONNECTION us.myconnection
OPTIONS(endpoint="https://us-central1-myproject.cloudfunctions.net/multiply");

Instrução CREATE TABLE FUNCTION

Cria uma nova função de tabela, também chamada de função com valor de tabela (TVF, na sigla em inglês).

Sintaxe

CREATE [ OR REPLACE ] TABLE FUNCTION [ IF NOT EXISTS ]
  [[project_name.]dataset_name.]function_name
  ( [ function_parameter [, ...] ] )
  [RETURNS TABLE < column_declaration [, ...] > ]
  AS sql_query

function_parameter:
  parameter_name { data_type | ANY TYPE }

column_declaration:
  column_name data_type

Argumentos

  • OR REPLACE. Substitui qualquer função de tabela com o mesmo nome, se houver. Não pode aparecer com IF NOT EXISTS.
  • IF NOT EXISTS: se houver alguma função de tabela com o mesmo nome, a instrução CREATE não terá efeito. Não pode aparecer com OR REPLACE.
  • project_name: o nome do projeto onde você está criando a função. O padrão é o projeto que executa essa consulta DDL.
  • dataset_name: o nome do conjunto de dados onde você está criando a função.
  • function_name: o nome da função a ser criada.
  • function_parameter: um parâmetro para a função, especificado como um nome de parâmetro e um tipo de dados. O valor de data_type é um tipo de dados do BigQuery escalar ou ANY TYPE.
  • RETURNS TABLE: o esquema da tabela que a função retorna, especificada como uma lista separada por vírgulas de pares de nome de coluna e tipo de dados. Se RETURNS TABLE estiver ausente, o BigQuery inferirá o esquema de saída da instrução de consulta no corpo da função. Se RETURNS TABLE estiver incluído, os nomes no tipo de tabela retornado precisarão corresponder aos nomes das colunas da consulta SQL.
  • sql_query: especifica a consulta SQL a ser executada. A consulta SQL precisa incluir nomes para todas as colunas.

Detalhes

Quando possível, o BigQuery força os tipos de argumento. Por exemplo, se o tipo de parâmetro for FLOAT64 e você transmitir um valor INT64, o BigQuery o forçará a um FLOAT64.

Se o tipo de parâmetro for ANY TYPE, a função aceitará uma entrada de qualquer tipo para esse argumento. O tipo que você transmite para a função precisa ser compatível com a definição da função. Se você passar um argumento com um tipo incompatível, a consulta retornará um erro. Se mais de um parâmetro tiver o tipo ANY TYPE, o BigQuery não aplicará qualquer relação de tipo entre eles.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.routines.create O conjunto de dados em que a função de tabela é criada.

Além disso, a cláusula OR REPLACE requer a permissão bigquery.routines.update.

Examples

A função de tabela a seguir usa um parâmetro INT64 que é usado para filtrar os resultados de uma consulta:

CREATE OR REPLACE TABLE FUNCTION mydataset.names_by_year(y INT64)
AS
  SELECT year, name, SUM(number) AS total
  FROM `bigquery-public-data.usa_names.usa_1910_current`
  WHERE year = y
  GROUP BY year, name

O exemplo a seguir especifica o tipo TABLE de retorno na cláusula RETURNS:

CREATE OR REPLACE TABLE FUNCTION mydataset.names_by_year(y INT64)
RETURNS TABLE<name STRING, year INT64, total INT64>
AS
  SELECT year, name, SUM(number) AS total
  FROM `bigquery-public-data.usa_names.usa_1910_current`
  WHERE year = y
  GROUP BY year, name

Instrução CREATE PROCEDURE

Cria um procedimento, que é um bloco de instruções que podem ser chamadas de outras consultas. Os procedimentos podem ser chamados recursivamente.

Sintaxe

CREATE [OR REPLACE] PROCEDURE [IF NOT EXISTS]
[[project_name.]dataset_name.]procedure_name (procedure_argument[, ...] )
[OPTIONS(procedure_option_list)]
BEGIN
multi_statement_query
END;

procedure_argument: [procedure_argument_mode] argument_name argument_type

procedure_argument_mode: IN | OUT | INOUT

Argumentos

  • OR REPLACE: substitui qualquer função com o mesmo nome, se houver. Não pode aparecer com IF NOT EXISTS.

  • IF NOT EXISTS: se houver algum procedimento com o mesmo nome, a instrução CREATE não terá efeito. Não pode aparecer com OR REPLACE.

  • project_name**: é o nome do projeto onde você está criando o procedimento. O padrão é o projeto que executa essa consulta DDL. Se o nome do projeto tiver caracteres especiais, como dois pontos, ele deverá estar entre crases ` (exemplo: `google.com:my_project`).

  • dataset_name: o nome do conjunto de dados onde você está criando o procedimento. O padrão na solicitação é defaultDataset.

  • procedure_name: o nome do procedimento a ser criado.

  • multi_statement_query: a consulta de várias instruções a ser executada.

  • argument_type: qualquer tipo válido do BigQuery.

  • procedure_argument_mode: especifica se um argumento é uma entrada, uma saída ou ambas.

procedure_option_list

O procedure_option_list permite especificar opções de procedimento. As opções de procedimento têm a mesma sintaxe e requisitos que as opções de tabela, mas com uma lista diferente de NAMEs e VALUEs:

NAME VALUE Detalhes
strict_mode

BOOL

Exemplo: strict_mode=FALSE

Se strict_mode for TRUE, o corpo do procedimento passará por verificações adicionais de erros, como tabelas ou colunas inexistentes. A instrução CREATE PROCEDURE falhará, se o corpo falhar em alguma dessas verificações.

Embora strict_mode seja útil para capturar muitos tipos comuns de erros, ele não é completo, e a criação bem-sucedida de um procedimento com strict_mode não garante que o procedimento será executado com sucesso no ambiente de execução.

Se strict_mode for FALSE, apenas à sintaxe do corpo do procedimento será verificada. Os procedimentos chamados recorrentemente precisam ser criados com strict_mode=FALSE, para evitar erros causados pelo procedimento que ainda não existem durante a validação.

O valor padrão é TRUE.

Modo de argumento

IN indica que o argumento é somente uma entrada do procedimento. Você pode especificar uma variável ou uma expressão de valor para argumentos IN.

OUT indica que o argumento é uma saída do procedimento. Um argumento OUT é inicializado como NULL junto do procedimento. Para argumentos OUT, é necessário especificar uma variável.

INOUT indica que o argumento é uma entrada e uma saída do procedimento. Para argumentos INOUT, é necessário especificar uma variável. Um argumento INOUT pode ser referenciado no corpo de um procedimento como uma variável e novos valores atribuídos.

Se não forem especificados IN, OUT nem INOUT, o argumento é tratado como IN.

Escopo de variáveis

Se uma variável for declarada fora de um procedimento, passar o argumento INOUT ou OUT para um procedimento e esse procedimento atribuir um novo valor à variável, esse novo valor fica visível fora do procedimento.

Os valores declarados em um procedimento não são visíveis fora do procedimento e vice-versa.

Um argumento OUT ou INOUT pode ser atribuído a um valor usando SET. Nesse caso, o valor modificado é visível fora do procedimento. Se o procedimento sair com sucesso, o valor do argumento OUT ou INOUT será o valor final atribuído à variável INOUT.

Tabelas temporárias existem enquanto o script durar. Por isso, se um procedimento cria uma tabela temporária, o autor da chamada do procedimento também poderá referenciar a tabela temporária.

Projeto padrão no corpo do procedimento

Corpos de procedimentos podem referenciar entidades sem especificar o projeto. O projeto padrão é o proprietário do procedimento, não necessariamente o projeto usado para executar a instrução CREATE PROCEDURE. Considere o exemplo de consulta abaixo.

CREATE PROCEDURE myProject.myDataset.QueryTable()
BEGIN
  SELECT * FROM anotherDataset.myTable;
END;

Depois de criar o procedimento acima, execute a consulta CALL myProject.myDataset.QueryTable(). Independentemente do projeto escolhido para executar essa consulta CALL, a tabela referenciada anotherDataset.myTable é sempre resolvida em relação ao projeto myProject.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.routines.create O conjunto de dados em que você cria o procedimento.

Além disso, a cláusula OR REPLACE requer a permissão bigquery.routines.update.

Examples

No exemplo a seguir, criaremos um procedimento que usa x como argumento de entrada e retorna x como saída. Como não há um modo para o argumento delta, ele é um argumento de entrada. O procedimento é composto por um bloco com uma única instrução, que atribui a soma dos dois argumentos de entrada a x.

CREATE PROCEDURE mydataset.AddDelta(INOUT x INT64, delta INT64)
BEGIN
  SET x = x + delta;
END;

No exemplo a seguir, é chamado o procedimento AddDelta do exemplo acima, passando a variável accumulator nas duas vezes. Como as alterações em x dentro de AddDelta são visíveis fora de AddDelta, essas chamadas de procedimento têm um incremento accumulator de 8.

DECLARE accumulator INT64 DEFAULT 0;
CALL mydataset.AddDelta(accumulator, 5);
CALL mydataset.AddDelta(accumulator, 3);
SELECT accumulator;

Isso retorna o resultado a seguir:

+-------------+
| accumulator |
+-------------+
|           8 |
+-------------+

No exemplo a seguir, criaremos o procedimento SelectFromTablesAndAppend, que leva target_date como um argumento de entrada e retorna rows_added como saída. O procedimento cria uma tabela temporária DataForTargetDate a partir de uma consulta. Em seguida, ele calcula o número de linhas em DataForTargetDate e atribui o resultado a rows_added. Em seguida, ele insere uma nova linha em TargetTable, passando o valor de target_date como um dos nomes de coluna. Por fim, ele descarta a tabela DataForTargetDate e retorna rows_added.

CREATE PROCEDURE mydataset.SelectFromTablesAndAppend(
  target_date DATE, OUT rows_added INT64)
BEGIN
  CREATE TEMP TABLE DataForTargetDate AS
  SELECT t1.id, t1.x, t2.y
  FROM dataset.partitioned_table1 AS t1
  JOIN dataset.partitioned_table2 AS t2
  ON t1.id = t2.id
  WHERE t1.date = target_date
    AND t2.date = target_date;

  SET rows_added = (SELECT COUNT(*) FROM DataForTargetDate);

  SELECT id, x, y, target_date  -- note that target_date is a parameter
  FROM DataForTargetDate;

  DROP TABLE DataForTargetDate;
END;

No exemplo a seguir, declaramos uma variável rows_added e a transmitimos como um argumento ao procedimento SelectFromTablesAndAppend do exemplo anterior com o valor de CURRENT_DATE. Em seguida, é retornada uma mensagem informando quantas linhas foram adicionadas.

DECLARE rows_added INT64;
CALL mydataset.SelectFromTablesAndAppend(CURRENT_DATE(), rows_added);
SELECT FORMAT('Added %d rows', rows_added);

Instrução CREATE ROW ACCESS POLICY

Cria ou substitui uma política de acesso no nível da linha. As políticas de acesso no nível da linha em uma tabela precisam ter nomes exclusivos.

Sintaxe

CREATE [ OR REPLACE ] ROW ACCESS POLICY [ IF NOT EXISTS ]
row_access_policy_name ON table_name
[GRANT TO (grantee_list)]
FILTER USING (filter_expression);

Argumentos

  • IF NOT EXISTS: se houver alguma política de acesso no nível da linha com o mesmo nome, a instrução CREATE não terá efeito. Não pode aparecer com OR REPLACE.

  • row_access_policy_name: o nome da política de acesso no nível da linha que você está criando. O nome da política de acesso na linha precisa ser exclusivo para cada tabela. O nome da política de acesso no nível da linha:

    • Até 256 caracteres.
    • Letras (maiúsculas e minúsculas), números e sublinhados. Precisa começar com uma letra.
  • table_name: o nome da tabela em que você quer criar uma política de acesso na linha. A tabela já deve existir.

  • GRANT TO grantee_list: é uma cláusula opcional que especifica os membros iniciais com que a política de acesso no nível da linha precisa ser criada.

    grantee_list é uma lista de usuários ou grupos iam_member. As strings precisam ser participantes do IAM válidos, ou membros, seguindo o formato de um membro da política de vinculação de políticas e precisam ser citadas. Veja a seguir os tipos compatíveis:

    Tipos grantee_list
    user:{emailid}

    Um endereço de e-mail que representa uma Conta do Google específica.

    Exemplo: user:alice@example.com

    serviceAccount:{emailid}

    Um endereço de e-mail que representa uma conta de serviço.

    Exemplo: serviceAccount:my-other-app@appspot.gserviceaccount.com

    group:{emailid}

    Um endereço de e-mail que representa um grupo do Google.

    Exemplo: group:admins@example.com

    domain:{domain}

    O domínio do Google Workspace (principal) que representa todos os usuários dele.

    Exemplo: domain:example.com

    allAuthenticatedUsers Um identificador especial que representa todas as contas de serviço e todos os usuários na Internet que se autenticaram com uma Conta do Google. Esse identificador inclui contas que não estão conectadas a um domínio do Google Workspace ou do Cloud Identity, como contas pessoais do Gmail. Os usuários que não forem autenticados, como os visitantes anônimos, não serão incluídos.
    allUsers Um identificador especial que representa qualquer pessoa na Internet, incluindo usuários autenticados e não autenticados. Como o BigQuery exige autenticação antes que um usuário possa acessar o serviço, allUsers inclui apenas usuários autenticados.

    É possível combinar uma série de valores iam_member, se eles forem separados por vírgulas e estiverem entre aspas separadamente. Por exemplo: "user:alice@example.com","group:admins@example.com","user:sales@example.com"

  • filter_expression: define o subconjunto de linhas da tabela a ser exibido apenas para os membros do grantee_list. O filter_expression é semelhante à cláusula WHERE em uma consulta SELECT.

    As expressões de filtro a seguir são válidas:

    • funções escalares SQL padrão do BigQuery, funções agregadas, funções analíticas.
    • SESSION_USER(), para restringir o acesso apenas a linhas que pertençam ao usuário que está executando a consulta. Se nenhuma das políticas de acesso no nível da linha for aplicável ao usuário que fez a consulta, ele não terá acesso aos dados na tabela.
    • TRUE. Concede aos principais no campo grantee_list acesso a todas as linhas da tabela.

    A expressão de filtro não pode conter:

    • uma referência a uma tabela;
    • subconsultas ou instruções SQL, como SELECT, CREATE ou UPDATE;
    • funções definidas pelo usuário.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.rowAccessPolicies.create A tabela de destino.
bigquery.rowAccessPolicies.setIamPolicy A tabela de destino.
bigquery.tables.getData A tabela de destino.

Examples

Instrução CREATE CAPACITY

Compra slots criando um novo compromisso de capacidade.

Sintaxe

CREATE CAPACITY
project_id.location_id.commitment_id
AS JSON
capacity_json_object

Argumentos

  • project_id: o ID do projeto de administração que vai manter a propriedade desse compromisso.
  • location_id: o local do projeto.
  • commitment_id: o ID do compromisso. O valor precisa ser exclusivo para o projeto e o local. Ele precisa começar e terminar com uma letra minúscula ou um número e conter apenas letras minúsculas, números e traços.
  • capacity_json_object: uma string JSON que descreve o compromisso de capacidade.

capacity_json_object

Especifica um objeto JSON que contém os seguintes campos:

NAME TYPE Detalhes
plan String O plano de compromisso a ser comprado. Os valores aceitos são: FLEX, MONTHLY, ANNUAL. Para mais informações, consulte Planos de compromisso;
renewal_plan String O plano de renovação de compromisso. Aplicável somente quando plan é ANNUAL. Para mais informações, consulte Como renovar compromissos.
slot_count Inteiro O número de slots no compromisso.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.capacityCommitments.create O projeto de administração que mantém a propriedade dos compromissos.

Exemplo

O exemplo a seguir cria um compromisso de capacidade de 100 slots flexíveis que estão localizados na região region-us e gerenciados por um projeto admin_project:

CREATE CAPACITY `admin_project.region-us.my-commitment`
AS JSON """{
 "slot_count": 100,
 "plan": "FLEX"
}"""

Instrução CREATE RESERVATION

Cria uma reserva. Para mais informações, consulte Introdução às reservas.

Sintaxe

CREATE RESERVATION
project_id.location_id.reservation_id
AS JSON
reservation_json_object

Argumentos

  • project_id o ID do projeto de administração em que o compromisso de capacidade foi criado.
  • location_id: o local do projeto.
  • reservation_id: o ID da reserva.
  • reservation_json_object: uma string JSON que descreve a reserva.

reservation_json_object

Especifica um objeto JSON que contém os seguintes campos:

NAME TYPE Detalhes
ignore_idle_slots Booleano Se o valor for true, a reserva usará apenas os slots provisionados para ele. O valor padrão é false. Para mais informações, consulte Slots inativos.
slot_capacity Inteiro o número de slots a serem alocados para a reserva.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.reservations.create O projeto de administração que mantém a propriedade dos compromissos.

Exemplo

O exemplo a seguir cria uma reserva de 100 slots no projeto admin_project:

CREATE RESERVATION `admin_project.region-us.prod`
AS JSON """{
 "slot_capacity": 100
}"""

Instrução CREATE ASSIGNMENT

Atribui um projeto, uma pasta ou uma organização a uma reserva.

Sintaxe

CREATE ASSIGNMENT
project_id.location_id.reservation_id.assignment_id
AS JSON
assignment_json_object

Argumentos

  • project_id: o ID do projeto de administração em que a reserva foi criada.
  • location_id: o local do projeto.
  • reservation_id: o ID da reserva.
  • assignment_id: o ID da atribuição. O valor precisa ser exclusivo para o projeto e o local. Ele precisa começar e terminar com uma letra minúscula ou um número e conter apenas letras minúsculas, números e traços.
  • assignment_json_object: uma string JSON que descreve a atribuição.

Para remover um projeto de qualquer reserva e usar o faturamento sob demanda, defina reservation_id como none.

assignment_json_object

Especifica um objeto JSON que contém os seguintes campos:

NAME TYPE Detalhes
assignee String O ID do projeto, da pasta ou da organização a ser atribuído à reserva.
job_type String o tipo de job a ser atribuído a essa reserva. Os valores aceitos incluem: QUERY, PIPELINE e ML_EXTERNAL. Para mais informações, consulte Atribuições.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.reservationAssignments.create O projeto de administração e o responsável.

Exemplo

O exemplo a seguir atribui o projeto my_project à reserva prod para jobs de consulta:

CREATE ASSIGNMENT `admin_project.region-us.prod.my_assignment`
AS JSON """{
 "assignee": "projects/my_project",
 "job_type": "QUERY"
}"""

O exemplo a seguir atribui uma organização à reserva prod para jobs de pipeline, como jobs de carregamento e de exportação:

CREATE ASSIGNMENT `admin_project.region-us.prod.my_assignment`
AS JSON """{
 "assignee": "organizations/1234",
 "job_type": "PIPELINE"
}"""

Instrução CREATE SEARCH INDEX

Cria um novo índice de pesquisa em uma ou mais colunas de uma tabela.

Um índice de pesquisa permite consultas eficientes usando a função SEARCH.

Sintaxe

CREATE SEARCH INDEX [ IF NOT EXISTS ] index_name
ON table_name({ALL COLUMNS | column_name [, ...]})

Argumentos

  • IF NOT EXISTS: se já houver um índice com esse nome na tabela, não faça nada. Se a tabela tiver um índice com um nome diferente, retorne um erro.

  • index_name: o nome do índice que você está criando. Como o índice é sempre criado no mesmo projeto e conjunto de dados da tabela base, não é necessário especificá-los no nome.

  • table_name: o nome da tabela. Consulte Sintaxe do caminho da tabela.

  • ALL COLUMNS: cria um índice em cada coluna da tabela que contém um campo STRING.

  • column_name: o nome de uma coluna de nível superior na tabela que é um STRING ou contém um campo STRING. A coluna precisa ser um dos seguintes tipos:

    • STRING
    • ARRAY<STRING>
    • STRUCT contendo pelo menos um campo aninhado do tipo STRING ou ARRAY<STRING>
    • JSON

Detalhes

É possível criar apenas um índice por tabela base. Não é possível criar um índice em uma visualização ou visualização materializada. Para modificar quais colunas são indexadas, DROP o índice atual e crie um novo.

O BigQuery retorna um erro quando column_name não é STRING ou não contém um campo STRING ou se você chama CREATE SEARCH INDEX em ALL COLUMNS de uma tabela. que não contém campos STRING.

A criação de um índice falhará em uma tabela que tem ACLs de coluna ou filtros de linha. No entanto, todos eles poderão ser adicionados à tabela após a criação do índice.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.createIndex A tabela base em que você cria o índice.

Examples

No exemplo a seguir, criamos um índice chamado my_index em todas as colunas de string de my_table. Nesse caso, o índice só é criado na coluna a.

CREATE TABLE dataset.my_table(a STRING, b INT64);

CREATE SEARCH INDEX my_index
ON dataset.my_table(ALL COLUMNS);

No exemplo a seguir, criamos um índice nas colunas a, my_struct.string_field e b.

CREATE TABLE dataset.complex_table(
  a STRING,
  my_struct STRUCT<string_field STRING, int_field INT64>,
  b ARRAY<STRING>
);

CREATE SEARCH INDEX my_index
ON dataset.complex_table(a, my_struct, b);

Instrução ALTER SCHEMA SET DEFAULT COLLATE

Define as especificações de compilação em um conjunto de dados.

Sintaxe

ALTER SCHEMA [IF EXISTS]
[project_name.]dataset_name
SET DEFAULT COLLATE collate_specification

Argumentos

  • IF EXISTS: se não existir um conjunto de dados com esse nome, a instrução não terá efeito.

  • DEFAULT COLLATE collate_specification: quando uma nova tabela é criada no esquema, ela herda uma especificação de compilação padrão, a menos que uma especificação de compilação seja explicitamente especificada para uma coluna.

    A especificação de compilação atualizada é aplicada somente às tabelas criadas posteriormente. Se quiser atualizar uma especificação de compilação existente, precisará alterar a coluna que contém a especificação.

  • project_name: nome do projeto que contém o conjunto de dados. O padrão é o projeto que executa essa consulta DDL.

  • dataset_name: o nome do conjunto de dados.

  • collate_specification: especifica as especificações de compilação a serem definidas.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.datasets.get O conjunto de dados a ser alterado.
bigquery.datasets.update O conjunto de dados a ser alterado.

Exemplo

Suponha que você tenha uma tabela, mytable_a, em um esquema chamado mydataset. Exemplo:

CREATE SCHEMA mydataset
CREATE TABLE mydataset.mytable_a
(
  number INT64,
  word STRING
)
+----------------------+
| mydataset.mytable_a  |
|   number INT64       |
|   word STRING        |
+----------------------+

Mais tarde, você decide adicionar uma especificação de compilação ao esquema. Exemplo:

ALTER SCHEMA mydataset
SET DEFAULT COLLATE 'und:ci'

Se você criar uma nova tabela para o esquema, ela herdará COLLATE 'und:ci' para todas as colunas STRING. Por exemplo, a compilação é adicionada a characters quando você cria a tabela mytable_b no esquema mydataset:

CREATE TABLE mydataset.mytable_b
(
  amount INT64,
  characters STRING
)
+--------------------------------------+
| mydataset.mytable_b                  |
|   amount INT64                       |
|   characters STRING COLLATE 'und:ci' |
+--------------------------------------+

No entanto, mesmo que você tenha atualizado a especificação de compilação do esquema, a tabela existente, mytable_a, continua usando a especificação de compilação anterior. Exemplo:

+---------------------+
| mydataset.mytable_a |
|   number INT64      |
|   word STRING       |
+---------------------+

Instrução ALTER SCHEMA SET OPTIONS

Define opções em um conjunto de dados.

A instrução será executada no local do conjunto de dados, se ele existir, a menos que você especifique o local nas configurações da consulta. Para mais informações, consulte Como especificar seu local.

Sintaxe

ALTER SCHEMA [IF EXISTS]
[project_name.]dataset_name
SET OPTIONS(schema_set_options_list)

Argumentos

  • IF EXISTS: se não existir um conjunto de dados com esse nome, a instrução não terá efeito.

  • project_name: nome do projeto que contém o conjunto de dados. O padrão é o projeto que executa essa consulta DDL.

  • dataset_name: o nome do conjunto de dados.

  • schema_set_options_list: a lista de opções a serem definidas.

schema_set_options_list

A lista de opções especifica opções para o conjunto de dados. Especifique as opções no seguinte formato: NAME=VALUE, ...

As seguintes opções são compatíveis:

NAME VALUE Detalhes
default_kms_key_name STRING Especifica a chave padrão do Cloud KMS para criptografar dados da tabela neste conjunto de dados. É possível modificar esse valor ao criar uma tabela.
default_partition_expiration_days FLOAT64 Especifica o prazo de validade padrão, em dias, para partições de tabela nesse conjunto de dados. É possível modificar esse valor ao criar uma tabela.
default_table_expiration_days FLOAT64 Especifica o prazo de validade padrão, em dias, das tabelas neste conjunto de dados. É possível modificar esse valor ao criar uma tabela.
description STRING A descrição do conjunto de dados.
friendly_name STRING Um nome descritivo do conjunto de dados.
labels <ARRAY<STRUCT<STRING, STRING>>> Uma matriz de rótulos para o conjunto de dados, expressa como pares de chave-valor.
location STRING O local em que o conjunto de dados será criado. Se você não especificar essa opção, o conjunto de dados será criado no local em que a consulta será executada. Se você especificar essa opção e também definir explicitamente o local do job de consulta, os dois valores precisam corresponder; caso contrário, a consulta falhará.
max_time_travel_hours SMALLINT

Em pré-lançamento

Especifica a duração em horas da janela de viagem no tempo para o novo conjunto de dados. O valor de max_time_travel_hours precisa ser um número inteiro entre 48 (2 dias) e 168 (7 dias). O padrão será 168 horas se essa opção não for especificada.

Para mais informações sobre a janela de viagem no tempo, consulte Como configurar a janela de viagem no tempo.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.datasets.get O conjunto de dados a ser alterado.
bigquery.datasets.update O conjunto de dados a ser alterado.

Exemplo

No exemplo a seguir, definimos a expiração da tabela padrão.

ALTER SCHEMA mydataset
SET OPTIONS(
  default_table_expiration_days=3.75
  )

Instrução ALTER TABLE SET OPTIONS

Define as opções em uma tabela.

Sintaxe

ALTER TABLE [IF EXISTS] table_name
SET OPTIONS(table_set_options_list)

Argumentos

Detalhes

Essa instrução não é compatível com tabelas externas.

table_set_options_list

A lista de opções permite que você defina opções de tabela, como um rótulo e um prazo de validade. Para incluir várias opções, use uma lista separada por vírgulas.

Especifique uma lista de opções de tabela no formato a seguir:

NAME=VALUE, ...

NAME e VALUE precisam ser uma das combinações a seguir:

NAME VALUE Detalhes
expiration_timestamp TIMESTAMP

Exemplo: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Essa propriedade é equivalente à propriedade de recurso de tabela expirationTime.

partition_expiration_days

FLOAT64

Exemplo: partition_expiration_days=7

Define a validade da partição em dias. Para mais informações, consulte Definir a validade da partição. Por padrão, as partições não expiram.

Essa propriedade é equivalente à propriedade de recurso de tabela timePartitioning.expirationMs, mas usa dias em vez de milissegundos. Um dia é equivalente a 86.400.000 milissegundos, ou 24 horas.

Só é possível definir essa propriedade se a tabela for particionada.

require_partition_filter

BOOL

Exemplo: require_partition_filter=true

Especifica se as consultas nesta tabela precisam incluir um filtro de predicado que filtre na coluna de particionamento. Para mais informações, consulte Definir requisitos de filtro de partição. O valor padrão é false.

Essa propriedade é equivalente à propriedade de recurso de tabela timePartitioning.requirePartitionFilter.

Só é possível definir essa propriedade se a tabela for particionada.

kms_key_name

STRING

Exemplo: kms_key_name="projects/project_id/locations/location/keyRings/keyring/cryptoKeys/key"

Essa propriedade é equivalente à propriedade de recurso de tabela encryptionConfiguration.kmsKeyName.

Consulte mais detalhes sobre Como proteger dados com chaves do Cloud KMS.

friendly_name

STRING

Exemplo: friendly_name="my_table"

Essa propriedade é equivalente à propriedade de recurso de tabela friendlyName.

description

STRING

Exemplo: description="a table that expires in 2025"

Essa propriedade é equivalente à propriedade de recurso de tabela description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemplo: labels=[("org_unit", "development")]

Essa propriedade é equivalente à propriedade de recurso de tabela labels.

VALUE é uma expressão constante que contém apenas literais, parâmetros de consulta e funções escalares.

A expressão constante não pode conter os itens a seguir:

  • Uma referência a uma tabela
  • Subconsultas ou instruções SQL, como SELECT, CREATE ou UPDATE
  • Funções definidas pelo usuário, funções agregadas ou funções analíticas
  • as funções escalares a seguir:
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

A definição de valor substitui o valor atual dessa opção para a tabela (se havia um). Definir o valor como NULL limpa o valor da tabela para essa opção.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.get A tabela a ser alterada.
bigquery.tables.update A tabela a ser alterada.

Exemplos

Como configurar o carimbo de data e hora de validade e descrição em uma tabela

No exemplo a seguir, o carimbo de data/hora de validade em uma tabela é definido como sete dias a partir do horário da execução da instrução ALTER TABLE, e a descrição também é definida:

ALTER TABLE mydataset.mytable
SET OPTIONS (
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 7 DAY),
  description="Table that expires seven days from now"
)

Como configurar o atributo "require partition filter" em uma tabela particionada

No exemplo a seguir, definimos o atributo timePartitioning.requirePartitionFilter em uma tabela particionada .

ALTER TABLE mydataset.mypartitionedtable
SET OPTIONS (require_partition_filter=true)

As consultas que fazem referência a essa tabela precisam usar um filtro na coluna de particionamento. Caso contrário, o BigQuery retorna um erro. Definir essa opção como true pode ajudar a evitar erros na consulta de mais dados do que o pretendido.

Como apagar o carimbo de data e hora de expiração em uma tabela

No exemplo a seguir, limpamos o carimbo de data/hora de validade em uma tabela para que ela não expire:

ALTER TABLE mydataset.mytable
SET OPTIONS (expiration_timestamp=NULL)

Instrução ALTER TABLE ADD COLUMN

Adiciona uma ou mais colunas novas a um esquema de tabela.

Sintaxe

ALTER TABLE table_name
ADD COLUMN [IF NOT EXISTS] column[, ...]

Argumentos

  • table_name: o nome da tabela. Consulte Sintaxe do caminho da tabela.

  • IF EXISTS: se o nome da coluna já existir, a instrução não terá efeito.

  • column: a coluna a ser adicionada. Isso inclui o nome da coluna e o esquema a ser adicionado. O nome e o esquema dessa coluna usam a mesma sintaxe usada na instrução CREATE TABLE.

Detalhes

Não é possível usar esta instrução para criar:

  • Colunas particionadas.
  • Colunas em cluster.
  • Colunas aninhadas dentro de campos RECORD existentes.

Não é possível adicionar uma coluna REQUIRED a um esquema de tabela existente. No entanto, é possível criar uma coluna REQUIRED aninhada como parte de um novo campo RECORD.

Essa instrução não é compatível com tabelas externas.

Sem a cláusula IF NOT EXISTS, se a tabela já contiver uma coluna com esse nome, a instrução retornará um erro. Se a cláusula IF NOT EXISTS estiver incluída e o nome da coluna já existir, nenhum erro será retornado e nenhuma medida será tomada.

O valor da nova coluna para linhas existentes é definido como um dos seguintes itens:

  • NULL se a nova coluna foi adicionada com o modo NULLABLE. Esse é o modo padrão.
  • Um ARRAY vazio se a nova coluna foi adicionada com o modo REPEATED.

Para mais informações sobre modificações de esquema no BigQuery, consulte Como modificar esquemas de tabelas.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.get A tabela a ser alterada.
bigquery.tables.update A tabela a ser alterada.

Exemplos

Como adicionar colunas

O exemplo a seguir adiciona as seguintes colunas a uma tabela existente chamada mytable:

  • Coluna A do tipo STRING.
  • Coluna B do tipo GEOGRAPHY.
  • Coluna C do tipo NUMERIC com o modo REPEATED.
  • Coluna D do tipo DATE com uma descrição.
ALTER TABLE mydataset.mytable
  ADD COLUMN A STRING,
  ADD COLUMN IF NOT EXISTS B GEOGRAPHY,
  ADD COLUMN C ARRAY<NUMERIC>,
  ADD COLUMN D DATE OPTIONS(description="my description")

Se qualquer uma das colunas chamadas A, C ou D já existir, a instrução falhará. Se a coluna B já existir, a instrução será bem-sucedida devido à cláusula IF NOT EXISTS.

Como adicionar uma coluna RECORD

O exemplo a seguir adiciona uma coluna chamada A do tipo STRUCT que contém as seguintes colunas aninhadas:

  • Coluna B do tipo GEOGRAPHY.
  • Coluna C do tipo INT64 com o modo REPEATED.
  • Coluna D do tipo INT64 com o modo REQUIRED.
  • Coluna E do tipo TIMESTAMP com uma descrição.
ALTER TABLE mydataset.mytable
   ADD COLUMN A STRUCT<
       B GEOGRAPHY,
       C ARRAY<INT64>,
       D INT64 NOT NULL,
       E TIMESTAMP OPTIONS(description="creation time")
       >

A consulta falhará se a tabela já tiver uma coluna chamada A, mesmo que essa coluna não contenha nenhuma das colunas aninhadas especificadas.

O novo STRUCT denominado A é anulável, mas a coluna aninhada D em A é obrigatória para qualquer valor STRUCT de A.

Como adicionar compatibilidade com compilação a uma coluna

Quando você cria uma nova coluna para a tabela, é possível atribuir especificamente uma nova especificação de compilação a essa coluna.

ALTER TABLE mydataset.mytable
ADD COLUMN word STRING COLLATE 'und:ci'

Instrução ALTER TABLE RENAME TO

Renomeia um clone, um snapshot ou uma tabela.

Sintaxe

ALTER TABLE [IF EXISTS] table_name
RENAME TO new_table_name

Argumentos

  • IF EXISTS: se não houver tabelas com esse nome, a instrução não terá efeito.

  • table_name: o nome da tabela a ser renomeada. Consulte Sintaxe do caminho da tabela.

  • new_table_name: o novo nome da tabela. O novo nome não pode ser um nome de tabela atual.

Detalhes

  • Essa instrução não é compatível com tabelas externas.
  • Se você alterar as políticas de tabela ou de acesso no nível da linha ao renomear a tabela, essas alterações talvez não sejam eficazes.
  • Se você quiser renomear uma tabela que tenha streaming de dados, pare o streaming e aguarde o BigQuery indicar que ele não está em uso.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.get A tabela a ser alterada.
bigquery.tables.update A tabela a ser alterada.

Exemplos

Como renomear uma tabela

No exemplo a seguir, a tabela mydataset.mytable é renomeada como mydataset.mynewtable:

ALTER TABLE mydataset.mytable RENAME TO mynewtable

Instrução ALTER TABLE DROP COLUMN

Descarta uma ou mais colunas de um esquema de tabela.

Sintaxe

ALTER TABLE table_name
DROP COLUMN [IF EXISTS] column_name [, ...]

Argumentos

  • table_name: o nome da tabela a ser alterada. Consulte Sintaxe do caminho da tabela. A tabela já precisa existir e ter um esquema.

  • IF EXISTS: se a coluna especificada não existir, a instrução não terá efeito.

  • column_name: o nome da coluna a ser descartada.

Detalhes

A instrução não libera imediatamente o armazenamento associado à coluna descartada. O armazenamento é reivindicado em segundo plano no período de sete dias a partir do dia em que uma coluna é descartada.

Para informações sobre como reivindicar armazenamento imediatamente, consulte Como excluir uma coluna de um esquema de tabela.

Não é possível usar esta instrução para descartar:

  • Colunas particionadas
  • Colunas em cluster
  • Colunas aninhadas dentro de campos RECORD existentes

Essa instrução não é compatível com tabelas externas.

Sem a cláusula IF EXISTS, se a tabela não contiver uma coluna com esse nome, a instrução retornará um erro. Se a cláusula IF EXISTS estiver incluída e o nome da coluna não existir, nenhum erro será retornado e nenhuma ação será tomada.

Essa instrução só remove a coluna da tabela. Todos os objetos que se referirem à coluna, como visualizações ou visualizações materializadas, precisam ser atualizados ou recriados separadamente.

Para mais informações sobre modificações de esquema no BigQuery, consulte Como modificar esquemas de tabelas.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.get A tabela a ser alterada.
bigquery.tables.update A tabela a ser alterada.

Exemplos

Como descartar colunas

O exemplo a seguir descarta as seguintes colunas de uma tabela existente chamada mytable:

  • Coluna A
  • Coluna B
ALTER TABLE mydataset.mytable
  DROP COLUMN A,
  DROP COLUMN IF EXISTS B

Se a coluna denominada A não existir, a instrução falhará. Se a coluna B não existir, a instrução ainda será bem-sucedida devido à cláusula IF EXISTS.

Instrução ALTER TABLE SET DEFAULT COLLATE

Define as especificações de compilação em uma tabela.

Sintaxe

ALTER TABLE
  table_name
  SET DEFAULT COLLATE collate_specification

Argumentos

  • table_name: o nome da tabela a ser alterada. Consulte Sintaxe do caminho da tabela. A tabela já precisa existir e ter um esquema.

  • SET DEFAULT COLLATE collate_specification: quando uma nova coluna é criada no esquema e ela não tem uma especificação de compilação explícita, a coluna herda essa especificação de compilação para os tipos STRING. A especificação de compilação atualizada é aplicada somente às colunas adicionadas posteriormente.

    Se você quiser atualizar uma especificação de compilação existente, precisará alterar a coluna que contém a especificação. Se você quiser adicionar uma especificação de compilação a uma nova coluna de uma tabela existente, faça isso ao adicionar a coluna. Se você adicionar uma especificação de compilação diretamente a uma coluna, a especificação de compilação da coluna terá prioridade sobre a especificação de compilação padrão de uma tabela.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.get A tabela a ser alterada.
bigquery.tables.update A tabela a ser alterada.

Exemplo

Suponha que você tenha uma tabela, mytable, em um esquema chamado mydataset.

CREATE TABLE mydataset.mytable
(
  number INT64,
  word STRING
) DEFAULT COLLATE 'und:ci'

Quando você cria mytable, todas as colunas STRING herdam COLLATE 'und:ci'. A tabela resultante tem esta estrutura:

+--------------------------------+
| mydataset.mytable              |
|   number INT64                 |
|   word STRING COLLATE 'und:ci' |
+--------------------------------+

Mais tarde, você decide mudar a especificação de compilação da tabela.

ALTER TABLE mydataset.mytable
SET DEFAULT COLLATE ''

Mesmo que você tenha atualizado a especificação de compilação, a coluna existente, word, continua usando a especificação de compilação anterior.

+--------------------------------+
| mydataset.mytable              |
|   number INT64                 |
|   word STRING COLLATE 'und:ci' |
+--------------------------------+

No entanto, se você criar uma nova coluna para a tabela, ela incluirá a nova especificação de compilação. No exemplo a seguir, uma coluna chamada name é adicionada. Como a nova especificação de compilação está vazia, a especificação padrão é usada.

ALTER TABLE mydataset.mytable
ADD COLUMN name STRING
+--------------------------------+
| mydataset.mytable              |
|   number INT64                 |
|   word STRING COLLATE 'und:ci' |
|   name STRING COLLATE          |
+--------------------------------+

Instrução ALTER COLUMN SET OPTIONS

Define opções, como a descrição da coluna, em uma coluna de uma tabela no BigQuery.

Sintaxe

ALTER TABLE [IF EXISTS] table_name
ALTER COLUMN [IF EXISTS] column_name SET OPTIONS(column_set_options_list)

Argumentos

  • (ALTER TABLE) IF EXISTS: se não houver uma tabela com esse nome, a instrução não terá efeito.

  • table_name: o nome da tabela a ser alterada. Consulte Sintaxe do caminho da tabela.

  • (ALTER COLUMN) IF EXISTS: se a coluna especificada não existir, a instrução não terá efeito.

  • column_name: o nome da coluna de nível superior que você está alterando. A modificação de subcampos, como colunas aninhadas em um STRUCT, não é aceita.

  • column_set_options_list: a lista de opções a serem definidas na coluna.

Detalhes

Essa instrução não é compatível com tabelas externas.

column_set_options_list

Especifique uma lista de opções de coluna no formato a seguir:

NAME=VALUE, ...

NAME e VALUE precisam ser uma das combinações a seguir:

NAME VALUE Detalhes
description

STRING

Exemplo: description="a table that expires in 2025"

VALUE é uma expressão constante que contém apenas literais, parâmetros de consulta e funções escalares.

A expressão constante não pode conter os itens a seguir:

  • Uma referência a uma tabela
  • Subconsultas ou instruções SQL, como SELECT, CREATE ou UPDATE
  • Funções definidas pelo usuário, funções agregadas ou funções analíticas
  • as funções escalares a seguir:
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

A definição de VALUE substitui o valor atual dessa opção para a tabela (se havia um). Definir o VALUE como NULL limpa o valor da coluna para essa opção.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.get A tabela a ser alterada.
bigquery.tables.update A tabela a ser alterada.

Exemplos

No exemplo a seguir, definimos uma nova descrição em uma coluna chamada price:

ALTER TABLE mydataset.mytable
ALTER COLUMN price
SET OPTIONS (
  description="Price per unit"
)

Instrução ALTER COLUMN DROP NOT NULL

Remove uma restrição NOT NULL de uma coluna em uma tabela no BigQuery.

Sintaxe

ALTER TABLE [IF EXISTS] table_name
ALTER COLUMN [IF EXISTS] column DROP NOT NULL

Argumentos

  • (ALTER TABLE) IF EXISTS: se não houver uma tabela com esse nome, a instrução não terá efeito.

  • table_name: o nome da tabela a ser alterada. Consulte Sintaxe do caminho da tabela.

  • (ALTER COLUMN) IF EXISTS: se a coluna especificada não existir, a instrução não terá efeito.

  • column_name: o nome da coluna de nível superior que você está alterando. Não é possível modificar subcampos.

Detalhes

Se uma coluna não tiver uma restrição NOT NULL, a consulta retornará um erro.

Essa instrução não é compatível com tabelas externas.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.get A tabela a ser alterada.
bigquery.tables.update A tabela a ser alterada.

Exemplos

No exemplo a seguir, a restrição NOT NULL é removida de uma coluna chamada mycolumn:

ALTER TABLE mydataset.mytable
ALTER COLUMN mycolumn
DROP NOT NULL

Instrução ALTER COLUMN SET DATA TYPE

Altera o tipo de dados de uma coluna em uma tabela no BigQuery para um tipo de dados menos restritivo. Por exemplo, um tipo de dados NUMERIC pode ser alterado para um tipo BIGNUMERIC, mas não o inverso.

Sintaxe

ALTER TABLE [IF EXISTS] table_name
ALTER COLUMN [IF EXISTS] column_name SET DATA TYPE column_schema

Argumentos

  • (ALTER TABLE) IF EXISTS: se não houver uma tabela com esse nome, a instrução não terá efeito.

  • table_name: o nome da tabela a ser alterada. Consulte Sintaxe do caminho da tabela.

  • (ALTER COLUMN) IF EXISTS: se a coluna especificada não existir, a instrução não terá efeito.

  • column_name: o nome da coluna de nível superior que você está alterando. Não é possível modificar subcampos.

  • column_schema: o esquema em que você está convertendo a coluna. Esse esquema usa a mesma sintaxe usada na instrução CREATE TABLE.

Detalhes

Para uma tabela com coerções de tipo de dados válidas, compare a coluna "Do tipo" com a coluna "Coerção para" na página Regras de conversão no SQL padrão.

Veja a seguir exemplos de coerções de tipo de dados válidas:

  • INT64 a NUMERIC, BIGNUMERIC, FLOAT64
  • NUMERIC a BIGNUMERIC, FLOAT64

Essa instrução não é compatível com tabelas externas.

Sem a cláusula IF EXISTS, se a tabela não contiver uma coluna com esse nome, a instrução retornará um erro. Se a cláusula IF EXISTS for incluída e o nome da coluna não existir, nenhum erro será retornado e nenhuma ação será tomada.

Você também pode fazer a coerção dos tipos de dados parametrizados mais restritivos para os menos restritivos. Por exemplo, é possível aumentar o comprimento máximo de um tipo de string, bem como a precisão ou a escala de um tipo numérico.

Veja a seguir exemplos de alterações de tipo de dados parametrizados válidas:

  • NUMERIC(6,10) a NUMERIC(8,12)
  • NUMERIC a BIGNUMERIC(40, 20)
  • STRING(5) a STRING(7)

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.get A tabela a ser alterada.
bigquery.tables.update A tabela a ser alterada.

Examples

Como alterar o tipo de dados de uma coluna

O exemplo a seguir altera o tipo de dados da coluna c1 de INT64 para NUMERIC:

CREATE TABLE dataset.table(c1 INT64);

ALTER TABLE dataset.table ALTER COLUMN c1 SET DATA TYPE NUMERIC;

Como alterar o tipo de dados de um campo

O exemplo a seguir altera o tipo de dados de um dos campos na coluna s1:

CREATE TABLE dataset.table(s1 STRUCT<a INT64, b STRING>);

ALTER TABLE dataset.table ALTER COLUMN s1
SET DATA TYPE STRUCT<a NUMERIC, b STRING>;

Como mudar a precisão

O exemplo a seguir altera a precisão de uma coluna de tipo de dados parametrizados:

CREATE TABLE dataset.table (pt NUMERIC(7,2));

ALTER TABLE dataset.table
ALTER COLUMN pt
SET DATA TYPE NUMERIC(8,2);

Instrução ALTER VIEW SET OPTIONS

Define as opções em uma visualização.

Sintaxe

ALTER VIEW [IF EXISTS] view_name
SET OPTIONS(view_set_options_list)

Argumentos

  • IF EXISTS: se não existir uma visualização com esse nome, a instrução não terá efeito.

  • view_name: o nome da visualização a ser alterada. Consulte Sintaxe do caminho da tabela.

  • view_set_options_list: a lista de opções a serem definidas.

view_set_options_list

A lista de opções permite que você defina opções de visualização, como um rótulo e um prazo de validade. Para incluir várias opções, use uma lista separada por vírgulas.

Especifique uma lista de opções de visualização no formato a seguir:

NAME=VALUE, ...

NAME e VALUE precisam ser uma das combinações a seguir:

NAME VALUE Detalhes
expiration_timestamp TIMESTAMP

Exemplo: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Essa propriedade é equivalente à propriedade de recurso de tabela expirationTime.

friendly_name

STRING

Exemplo: friendly_name="my_view"

Essa propriedade é equivalente à propriedade de recurso de tabela friendlyName.

description

STRING

Exemplo: description="a view that expires in 2025"

Essa propriedade é equivalente à propriedade de recurso de tabela description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemplo: labels=[("org_unit", "development")]

Essa propriedade é equivalente à propriedade de recurso de tabela labels.

VALUE é uma expressão constante que contém apenas literais, parâmetros de consulta e funções escalares.

A expressão constante não pode conter os itens a seguir:

  • Uma referência a uma tabela
  • Subconsultas ou instruções SQL, como SELECT, CREATE ou UPDATE
  • Funções definidas pelo usuário, funções agregadas ou funções analíticas
  • as funções escalares a seguir:
    • ARRAY_TO_STRING
    • REPLACE
    • REGEXP_REPLACE
    • RAND
    • FORMAT
    • LPAD
    • RPAD
    • REPEAT
    • SESSION_USER
    • GENERATE_ARRAY
    • GENERATE_DATE_ARRAY

A definição de valor substitui o valor atual dessa opção para a visualização (se havia um). Definir o valor como NULL limpa o valor da visualização para essa opção.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.get A visualização a ser alterada.
bigquery.tables.update A visualização a ser alterada.

Exemplos

Como configurar o carimbo de data e hora de expiração e descrição em uma visualização

No exemplo a seguir, definimos o carimbo de data/hora de validade em uma visualização como sete dias a partir do horário da execução da instrução ALTER VIEW e também definimos a descrição:

ALTER VIEW mydataset.myview
SET OPTIONS (
  expiration_timestamp=TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 7 DAY),
  description="View that expires seven days from now"
)

Instrução ALTER MATERIALIZED VIEW SET OPTIONS

Define as opções em uma visualização materializada.

Sintaxe

ALTER MATERIALIZED VIEW [IF EXISTS] materialized_view_name
SET OPTIONS(materialized_view_set_options_list)

Argumentos

materialized_view_set_options_list

A lista de opções permite que você defina opções de visualização materializadas, como a ativação e o intervalo de atualização, um rótulo e um prazo de validade. Para incluir várias opções, use uma lista separada por vírgulas.

Especifique uma lista de opções de visualização materializada no formato a seguir:

NAME=VALUE, ...

NAME e VALUE precisam ser uma das combinações a seguir:

NAME VALUE Detalhes
enable_refresh BOOLEAN

Exemplo: enable_refresh=false

refresh_interval_minutes FLOAT64

Exemplo: refresh_interval_minutes=20

expiration_timestamp TIMESTAMP

Exemplo: expiration_timestamp=TIMESTAMP "2025-01-01 00:00:00 UTC"

Essa propriedade é equivalente à propriedade de recurso de tabela expirationTime.

friendly_name

STRING

Exemplo: friendly_name="my_mv"

Essa propriedade é equivalente à propriedade de recurso de tabela friendlyName.

description

STRING

Exemplo: description="a materialized view that expires in 2025"

Essa propriedade é equivalente à propriedade de recurso de tabela description.

labels

ARRAY<STRUCT<STRING, STRING>>

Exemplo: labels=[("org_unit", "development")]

Essa propriedade é equivalente à propriedade de recurso de tabela labels.

A configuração de valor substitui o valor existente dessa opção para a visualização materializada, se houver. Definir o valor como NULL limpa o valor da visualização materializada para essa opção.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.get A visualização materializada a ser alterada.
bigquery.tables.update A visualização materializada a ser alterada.

Exemplos

Como definir o estado e o intervalo de atualização em uma visualização materializada

O exemplo a seguir ativa a atualização e define o intervalo dela para 20 minutos em uma visualização materializada:

ALTER MATERIALIZED VIEW mydataset.my_mv
SET OPTIONS (
  enable_refresh=true,
  refresh_interval_minutes=20
)

Instrução ALTER ORGANIZATION SET OPTIONS

Define as opções em uma organização.

Sintaxe

ALTER ORGANIZATION
SET OPTIONS (
  organization_set_options_list);

Argumentos

organization_set_options_list

A lista de opções especifica opções para a empresa. Especifique as opções no seguinte formato: NAME=VALUE, ...

As seguintes opções são compatíveis:

NAME VALUE Detalhes
default_kms_key_name STRING

Exemplo: kms_key_name="projects/project_id/locations/location/keyRings/keyring/cryptoKeys/key"

Essa propriedade é equivalente à propriedade de recurso de tabela encryptionConfiguration.kmsKeyName.

Consulte mais detalhes sobre Como proteger dados com chaves do Cloud KMS.

default_time_zone STRING Exemplo: `region-us.default_time_zone` = "America/Los_Angeles". Define o fuso horário padrão como America/Los_Angeles na região us.
default_query_job_timeout_ms INT64 Exemplo: `region-us.default_query_job_timeout_ms` = 1800000. Define o tempo limite do job de consulta padrão como 30 minutos para uma organização na região us.

A definição do valor substitui o valor existente dessa opção para a organização, se houver. Definir o valor como NULL limpa o valor da organização para essa opção.

Permissões necessárias

Esta instrução ALTER ORGANIZATION SET OPTIONS requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.config.update A organização a ser alterada.

Examples

No exemplo a seguir, o fuso horário padrão é definido como América/Chicago e o tempo limite do job de consulta padrão como uma hora para uma organização nos EUA.

ALTER ORGANIZATION
SET OPTIONS (
  `region-us.default_time_zone` = "America/Chicago",
  `region-us.default_job_query_timeout_ms` = 3600000
);

Instrução ALTER PROJECT SET OPTIONS

Define as opções em um projeto.

Sintaxe

ALTER PROJECT project_id
SET OPTIONS (project_set_options_list);

Argumentos

  • project_id: o nome do projeto que você está alterando. O padrão é o projeto que executa essa consulta DDL.
  • project_set_options_list: a lista de opções a serem definidas.

project_set_options_list

A lista de opções especifica opções para o projeto. Especifique as opções no seguinte formato: NAME=VALUE, ...

As seguintes opções são compatíveis:

NAME VALUE Detalhes
default_kms_key_name STRING

Exemplo: kms_key_name="projects/project_id/locations/location/keyRings/keyring/cryptoKeys/key"

Essa propriedade é equivalente à propriedade de recurso de tabela encryptionConfiguration.kmsKeyName.

Consulte mais detalhes sobre Como proteger dados com chaves do Cloud KMS.

default_time_zone STRING Exemplo: `region-us.default_time_zone` = "America/Los_Angeles". Define o fuso horário padrão como America/Los_Angeles na região us.
default_query_job_timeout_ms INT64 Exemplo: `region-us.default_query_job_timeout_ms` = 1800000. Define o tempo limite do job de consulta padrão como 30 minutos para um projeto na região us.

A definição do valor substitui o valor existente dessa opção para o projeto, se houver. Definir o valor como NULL limpa o valor do projeto para essa opção.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.config.update O projeto a ser alterado.

Examples

No exemplo a seguir, o fuso horário padrão é definido como America/New_York, e o tempo limite padrão do job de consulta como 30 minutos para um projeto na região us.

ALTER PROJECT project_id
SET OPTIONS (
  `region-us.default_time_zone` = "America/New_York",
  `region-us.default_job_query_timeout_ms` = 1800000
);

Instrução ALTER BI_CAPACITY SET OPTIONS

Define as opções na capacidade do BigQuery BI Engine.

Sintaxe

ALTER BI_CAPACITY `project_id.location_id.default`
SET OPTIONS(bi_capacity_options_list)

Argumentos

  • project_id: ID opcional do projeto que se beneficiará da aceleração do BI Engine. Se omitido, o ID do projeto de consulta é usado.

  • location_id: o local em que os dados precisam ser armazenados em cache, prefixados com region-. Exemplos: region-us, region-us-central1.

  • bi_capacity_options_list: a lista de opções a serem definidas.

bi_capacity_options_list

A lista especifica opções para o BigQuery BI Engine.

Especifique uma lista de opções de coluna no formato a seguir:

NAME=VALUE, ...

As seguintes opções são compatíveis:

NAME VALUE Detalhes
size_gb INT64 Especifica o tamanho da reserva em gigabytes.
preferred_tables <ARRAY<STRING>> Lista de tabelas às quais a aceleração precisa ser aplicada. Formato: project.dataset.table or dataset.table. Se o projeto for omitido, o projeto de consulta será usado.

A definição de VALUE substitui o valor atual dessa opção para a capacidade do BI Engine, se houver. Definir VALUE como NULL limpa o valor dessa opção.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.bireservations.update Reserva do BI Engine

Examples

Como alocar capacidade do BI Engine sem tabelas preferenciais

ALTER BI_CAPACITY `my-project.region-us.default`
SET OPTIONS(
  size_gb = 250
)

Desalocar a capacidade de BI

ALTER BI_CAPACITY `my-project.region-us.default`
SET OPTIONS(
  size_gb = 0
)

Como remover um conjunto de tabelas preferenciais da reserva

ALTER BI_CAPACITY `my-project.region-us.default`
SET OPTIONS(
  preferred_tables = NULL
)

Como alocar capacidade de BI com a lista de tabelas preferenciais

ALTER BI_CAPACITY `my-project.region-us.default`
SET OPTIONS(
  size_gb = 250,
  preferred_tables = ["data_project1.dataset1.table1",
                      "data_project2.dataset2.table2"]
)

Substituindo lista de tabelas preferenciais sem alterar o tamanho

ALTER BI_CAPACITY `region-us.default`
SET OPTIONS(
  preferred_tables = ["dataset1.table1",
                      "data_project2.dataset2.table2"]
)

Instrução DROP SCHEMA

Exclui um conjunto de dados.

Sintaxe

DROP SCHEMA [IF EXISTS]
[project_name.]dataset_name
[ CASCADE | RESTRICT ]

Argumentos

  • IF EXISTS: se não existir um conjunto de dados com esse nome, a instrução não terá efeito.

  • project_name: nome do projeto que contém o conjunto de dados. O padrão é o projeto que executa essa consulta DDL.

  • dataset_name: o nome do conjunto de dados a ser excluído.

  • CASCADE: exclui o conjunto de dados e todos os recursos dentro do conjunto de dados, como tabelas, visualizações e funções. Você precisa ter permissão para excluir os recursos ou o comando retornará um erro. Para uma lista de permissões do BigQuery, consulte Papéis e permissões predefinidos.

  • RESTRICT: só exclui o conjunto de dados se ele estiver vazio. Caso contrário, retornará um erro. Se você não especificar CASCADE ou RESTRICT, o comportamento padrão será RESTRICT.

Detalhes

A instrução será executada no local do conjunto de dados, se ele existir, a menos que você especifique o local nas configurações da consulta. Para mais informações, consulte Como especificar seu local.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.datasets.delete O conjunto de dados a ser excluído.
bigquery.tables.delete O conjunto de dados a ser excluído. Se o conjunto de dados estiver vazio, essa permissão não será necessária.

Exemplos

No exemplo a seguir, o conjunto de dados chamado mydataset é excluído. Se o conjunto de dados não existir ou não estiver vazio, a instrução retornará um erro.

DROP SCHEMA mydataset

No exemplo a seguir, o conjunto de dados chamado mydataset e os recursos nele são descartados. Se o conjunto de dados não existir, nenhum erro será retornado.

DROP SCHEMA IF EXISTS mydataset CASCADE

Instrução DROP TABLE

Exclui uma tabela ou um clone de tabela.

Sintaxe

DROP TABLE [IF EXISTS] table_name

Argumentos

  • IF EXISTS: se não houver tabelas com esse nome, a instrução não terá efeito.

  • table_name: o nome da tabela a ser excluída. Consulte Sintaxe do caminho da tabela.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.delete A tabela a ser excluída.
bigquery.tables.get A tabela a ser excluída.

Exemplos

Como excluir tabelas

No exemplo a seguir, uma tabela chamada mytable no mydataset é excluída:

DROP TABLE mydataset.mytable

Se o nome da tabela não existir no conjunto de dados, o erro a seguir será retornado:

Error: Not found: Table myproject:mydataset.mytable

Como excluir uma tabela somente se ela existir

O exemplo a seguir exclui uma tabela chamada mytable em mydataset somente se a tabela existir. Se o nome da tabela não existir no conjunto de dados, nenhum erro será retornado e nenhuma ação será tomada.

DROP TABLE IF EXISTS mydataset.mytable

Instrução DROP SNAPSHOT TABLE

Exclui um snapshot de tabela.

Sintaxe

DROP SNAPSHOT TABLE [IF EXISTS] table_snapshot_name

Argumentos

  • IF EXISTS: se não houver um snapshot de tabela com esse nome, a instrução não terá efeito.

  • table_snapshot_name: o nome do snapshot da tabela a ser excluído. Consulte Sintaxe do caminho da tabela.

Permissões necessárias

Esta instrução requer as seguintes permissões do IAM:

Permissão Recurso
bigquery.tables.deleteSnapshot O snapshot da tabela a ser excluído.

Exemplos

Excluir um snapshot da tabela: falha se não existir

No exemplo a seguir, o snapshot da tabela chamado mytablesnapshot no conjunto de dados mydataset é excluído:

DROP SNAPSHOT TABLE mydataset.mytablesnapshot

Se o snapshot da tabela não existir no conjunto de dados, o erro a seguir será retornado:

Error: Not found: Table snapshot myproject:mydataset.mytablesnapshot