CREATE TABLE¶

Sintaxe¶

CREATE [ OR REPLACE ]
    [ { [ { LOCAL | GLOBAL } ] TEMP | TEMPORARY | VOLATILE | TRANSIENT } ]
  TABLE [ IF NOT EXISTS ] <table_name> (
    -- Column definition
    <col_name> <col_type>
      [ inlineConstraint ]
      [ NOT NULL ]
      [ COLLATE '<collation_specification>' ]
      [
        {
          DEFAULT <expr>
          | { AUTOINCREMENT | IDENTITY }
            [
              {
                ( <start_num> , <step_num> )
                | START <num> INCREMENT <num>
              }
            ]
            [ { ORDER | NOORDER } ]
        }
      ]
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]
      [ [ WITH ] PROJECTION POLICY <policy_name> ]
      [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
      [ COMMENT '<string_literal>' ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]

    -- Out-of-line constraints
    [ , outoflineConstraint [ ... ] ]
  )
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ ENABLE_SCHEMA_EVOLUTION = { TRUE | FALSE } ]
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ CHANGE_TRACKING = { TRUE | FALSE } ]
  [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , <col_name> ... ] ) ]
  [ [ WITH ] AGGREGATION POLICY <policy_name> [ ENTITY KEY ( <col_name> [ , <col_name> ... ] ) ] ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

Onde:

inlineConstraint ::=
  [ CONSTRAINT <constraint_name> ]
  { UNIQUE
    | PRIMARY KEY
    | [ FOREIGN KEY ] REFERENCES <ref_table_name> [ ( <ref_col_name> ) ]
  }
  [ <constraint_properties> ]

Copy

Para detalhes adicionais de restrição em linha, consulte CREATE | ALTER TABLE … CONSTRAINT.

outoflineConstraint ::=
  [ CONSTRAINT <constraint_name> ]
  { UNIQUE [ ( <col_name> [ , <col_name> , ... ] ) ]
    | PRIMARY KEY [ ( <col_name> [ , <col_name> , ... ] ) ]
    | [ FOREIGN KEY ] [ ( <col_name> [ , <col_name> , ... ] ) ]
      REFERENCES <ref_table_name> [ ( <ref_col_name> [ , <ref_col_name> , ... ] ) ]
  }
  [ <constraint_properties> ]
  [ COMMENT '<string_literal>' ]

Copy

Para detalhes adicionais de restrição fora de linha, consulte CREATE | ALTER TABLE … CONSTRAINT.

Sintaxe da variante¶

CREATE OR ALTER
    [ { [ { LOCAL | GLOBAL } ] TEMP | TEMPORARY | TRANSIENT } ]
  TABLE <table_name> (
    -- Column definition
    <col_name> <col_type>
      [ inlineConstraint ]
      [ NOT NULL ]
      [ COLLATE '<collation_specification>' ]
      [
        {
          DEFAULT <expr>
          | { AUTOINCREMENT | IDENTITY }
            [
              {
                ( <start_num> , <step_num> )
                | START <num> INCREMENT <num>
              }
            ]
            [ { ORDER | NOORDER } ]
        }
      ]
      [ COMMENT '<string_literal>' ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]

    -- Out-of-line constraints
    [ , outoflineConstraint [ ... ] ]
  )
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ ENABLE_SCHEMA_EVOLUTION = { TRUE | FALSE } ]
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ CHANGE_TRACKING = { TRUE | FALSE } ]
  [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
  [ COMMENT = '<string_literal>' ]

Parâmetros obrigatórios¶

name

Especifica o identificador (ou seja, nome) da tabela; deve ser único para o esquema no qual a tabela é criada.

Além disso, o identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais detalhes, consulte Requisitos para identificadores.

col_name

Especifica o identificador da coluna (ou seja, o nome). Todos os requisitos de identificadores de tabela também se aplicam aos identificadores de coluna.

Para obter mais detalhes, consulte Requisitos para identificadores e Palavras-chave reservadas e limitadas.

Nota

Além das palavras-chave padrão reservadas, as seguintes palavras-chave não podem ser usadas como identificadores de coluna porque são reservadas para funções de contexto padrão ANSI:

• CURRENT_DATE

• CURRENT_ROLE

• CURRENT_TIME

• CURRENT_TIMESTAMP

• CURRENT_USER

Para a lista de palavras-chave reservadas, consulte Palavras-chave reservadas e limitadas.

col_type

Especifica o tipo de dados para a coluna.

Para obter mais detalhes sobre os tipos de dados que podem ser especificados para colunas de tabela, consulte Referência dos tipos de dados SQL.

query

Necessário para CTAS e USING TEMPLATE.

• Para CTAS, especifica a instrução SELECT que preenche a tabela.

• Para CREATE TABLE … USING TEMPLATE, especifica a subconsulta que chama a função INFER_SCHEMA e formata a saída como uma matriz. Alternativamente, USING TEMPLATE aceita a saída INFER_SCHEMA como uma cadeia de caracteres literal ou variável.

source_table

Necessário para LIKE e CLONE.

• Para CREATE TABLE. .. LIKE, especifica a tabela da qual as propriedades e definições de coluna são copiadas.

• Para CREATE TABLE. .. CLONE, especifica a tabela a ser usada como origem para o clone.

Parâmetros opcionais¶

{ [ { LOCAL | GLOBAL } ] TEMP [ READ ONLY] | ` :newline:.` TEMPORARY [ READ ONLY] | . VOLATILE | ` :newline:.` TRANSIENT }

Especifica que a tabela persiste apenas pela duração da sessão em que você o criou. Uma tabela temporária e todo o seu conteúdo são descartados no final da sessão.

Os sinônimos e abreviações para TEMPORARY (por exemplo, GLOBAL TEMPORARY) são fornecidos para compatibilidade com outros bancos de dados (por exemplo, para evitar erros ao migrar instruções CREATE TABLE). As tabelas criadas com qualquer uma dessas palavras-chave aparecem e se comportam de forma idêntica a uma tabela criada com a palavra-chave TEMPORARY.

Padrão: sem valor. Se uma tabela não for declarada como TEMPORARY ou TRANSIENT, a tabela é permanente.

Se você deseja evitar conflitos inesperados, evite nomear tabelas temporárias como tabelas que já existem no esquema.

Se você criou uma tabela temporária com o mesmo nome de outra tabela no esquema, todas as consultas e operações usadas na tabela afetarão apenas a tabela temporária na sessão, até que você elimine a tabela temporária. Se você descartar a tabela, descartará a tabela temporária e não a tabela que já existe no esquema.

Para obter mais informações sobre tabelas temporárias ou transitórias e como elas podem afetar o armazenamento e o custo, consulte os seguintes recursos:

• Como trabalhar com tabelas temporárias e transitórias

• Custos de armazenamento para Time Travel e Fail-safe

READ ONLY

Especifica que a tabela é somente leitura. READ ONLY é válido apenas para uma tabela temporária que está sendo criada com a variante CREATE TABLE … CLONE do comando CREATE TABLE.

Uma tabela somente leitura não permite operações de DML e permite apenas o seguinte subconjunto de operações de DDL:

• ALTER TABLE … { ALTER | MODIFY } COLUMN … { SET | UNSET } COMMENT

• ALTER TABLE … { ALTER | MODIFY } COLUMN … { SET | UNSET } MASKING POLICY

• ALTER TABLE … { ALTER | MODIFY } COLUMN … { SET | UNSET } TAG

• ALTER TABLE … RENAME COLUMN … TO

• ALTER TABLE … RENAME TO

• ALTER TABLE … { SET | UNSET } COMMENT

• ALTER TABLE … { SET | UNSET } TAG

• COMMENT

• DESCRIBE

• DROP

• SHOW

• UNDROP

As tabelas somente leitura têm uma coluna METADATA$ROW_POSITION. Esta coluna de metadados atribui um número de linha a cada linha na tabela que é contínua e começa em 0. O número de linha atribuído a cada linha permanece inalterado até que a tabela somente leitura seja descartada.

TRANSIENT

Especifica que a tabela é transitória.

Assim como uma tabela permanente, uma tabela transitória existe até ser descartada explicitamente e fica visível para qualquer usuário com os privilégios correspondentes. No entanto, as tabelas transitórias têm um nível de proteção de dados inferior às tabelas permanentes, o que significa que os dados em uma tabela transitória podem ser perdidos no caso de uma falha do sistema. Como tal, tabelas transitórias devem ser usadas somente para dados que possam ser recriados fora do Snowflake.

Padrão: sem valor. Se uma tabela não for declarada como TRANSIENT ou TEMPORARY, a tabela é permanente.

Nota

As tabelas transitórias têm algumas considerações de armazenamento.

Para obter mais informações sobre estas e outras considerações ao decidir sobre a criação de tabelas temporárias ou transitórias, consulte Como trabalhar com tabelas temporárias e transitórias e Custos de armazenamento para Time Travel e Fail-safe.

CONSTRAINT ...

Define uma restrição em linha ou fora de linha para a(s) coluna(s) especificada(s) na tabela.

Para detalhes de sintaxe, consulte CREATE | ALTER TABLE … CONSTRAINT. Para obter mais informações sobre restrições, consulte Restrições.

COLLATE 'collation_specification'

Especifica o agrupamento a ser usado para operações de coluna, tais como comparação de cadeias de caracteres. Esta opção aplica-se somente às colunas de texto (VARCHAR, STRING, TEXT etc.). Para obter mais detalhes, consulte Especificações de agrupamento.

DEFAULT ... ou . AUTOINCREMENT ...

Especifica se um valor padrão é automaticamente inserido na coluna caso um valor não seja explicitamente especificado por uma instrução INSERT ou CREATE TABLE AS SELECT:

DEFAULT expr

O valor padrão da coluna é definido pela expressão especificada que pode ser qualquer uma das opções seguintes:

• Valor constante.

• Referência de sequência (seq_name.NEXTVAL).

• Expressão simples que retorna um valor escalar.

  A expressão simples pode incluir uma UDF (função definida pelo usuário) SQL se a UDF não for uma UDF segura.

  Nota

  Se uma expressão padrão se referir a uma UDF SQL, então a função será substituída por sua definição no momento da criação da tabela. Se a função definida pelo usuário for redefinida no futuro, isso não atualizará a expressão padrão da coluna.

  A expressão simples não pode conter referências a:

  • Subconsultas.

  • Agregados.

  • Funções de janela.

  • UDFs seguras.

  • UDFs escritas em outras linguagens além de SQL (por exemplo, Java, JavaScript).

  • Funções externas.

{ AUTOINCREMENT | IDENTITY } . [ { ( start_num , step_num ) | START num INCREMENT num } ] . [ { ORDER | NOORDER } ]

Quando você especifica AUTOINCREMENT ou IDENTITY, o valor padrão para a coluna começa com um número especificado e cada valor sucessivo é incrementado automaticamente pelo valor especificado.

AUTOINCREMENT e IDENTITY são sinônimos e podem ser usados somente para colunas com tipos de dados numéricos, como NUMBER, INT, FLOAT.

Cuidado

O Snowflake usa uma sequência para gerar os valores de uma coluna de incremento automático. As sequências têm limitações; consulte Semântica da sequência.

O valor padrão para o valor inicial e o valor da etapa/incremento é 1.

Nota

Inserir valores manualmente em uma coluna AUTOINCREMENT ou IDENTITY pode resultar em valores duplicados. Se você inserir manualmente o valor 5 em uma coluna AUTOINCREMENT ou IDENTITY, uma linha inserida posteriormente pode usar o mesmo valor 5 como o valor padrão para a coluna.

Use ORDER ou NOORDER para especificar se os valores serão gerados ou não para a coluna incrementada automaticamente em ordem crescente ou decrescente.

• ORDER especifica que os valores gerados para uma sequência ou coluna incrementada automaticamente estão em ordem crescente (ou, se o intervalor for um valor negativo, em ordem decrescente).

  Por exemplo, se uma sequência ou coluna incrementada automaticamente tiver START 1 INCREMENT 2, os valores gerados podem ser 1, 3, 5, 7, 9 etc.

• NOORDER especifica que não é garantido que os valores estejam em ordem crescente.

  Por exemplo, se uma sequência tiver START 1 INCREMENT 2, os valores gerados podem ser 1, 3, 101, 5, 103 etc.

  NOORDER pode melhorar o desempenho quando várias operações INSERT são executadas simultaneamente (por exemplo, quando vários clientes estão executando várias instruções INSERT).

Se você não especificar ORDER ou NOORDER, o parâmetro NOORDER_SEQUENCE_AS_DEFAULT determinará qual propriedade será configurada.

Nota

DEFAULT e AUTOINCREMENT são mutuamente exclusivos; apenas um deles pode ser especificado para uma coluna.

MASKING POLICY = policy_name

Especifica a política de mascaramento a ser definida em uma coluna.

Este parâmetro não é suportado pela sintaxe da variante CREATE OR ALTER.

PROJECTION POLICY policy_name

Especifica a política de projeção a ser definida em uma coluna.

Este parâmetro não é suportado pela sintaxe da variante CREATE OR ALTER.

COMMENT 'string_literal'

Especifica um comentário para a coluna.

(Observe que os comentários podem ser especificados no nível da coluna ou da tabela. A sintaxe de cada um é um pouco diferente).

USING ( col_name , cond_col_1 ... )

Especifica os argumentos para passar para a expressão SQL da política de mascaramento condicional.

A primeira coluna da lista especifica a coluna das condições da política para mascarar ou tokenizar os dados e deve corresponder à coluna para a qual a política de mascaramento é definida.

As colunas adicionais especificam as colunas a serem avaliadas para determinar se os dados em cada linha do resultado da consulta devem ser mascarados ou tokenizados quando uma consulta é feita na primeira coluna.

Se a cláusula USING for omitida, o Snowflake tratará a política de mascaramento condicional como uma política de mascaramento normal.

CLUSTER BY ( expr [ , expr , ... ] )

Especifica uma ou mais colunas ou expressões de colunas na tabela como a chave de clustering. Para obter mais detalhes, consulte Chaves de clustering e tabelas clusterizadas.

Padrão: sem valor (nenhuma chave de clustering está definida para a tabela)

Importante

As chaves de clustering não são destinadas ou recomendadas para todas as tabelas; elas normalmente são vantajosas para tabelas muito grandes (ou seja, com vários terabytes).

Antes de especificar uma chave de clustering para uma tabela, você deve entender as micropartições. Para obter mais informações, consulte Explicação das estruturas de tabela do Snowflake.

ENABLE_SCHEMA_EVOLUTION = { TRUE | FALSE }

Ativa ou desativa as alterações automáticas no esquema da tabela a partir dos dados carregados na tabela dos arquivos de origem, incluindo:

• Colunas adicionadas.

  Por padrão, a evolução do esquema é limitada a um máximo de 10 colunas adicionadas por operação de carregamento. Para solicitar mais de 10 colunas adicionadas por operação de carga, entre em contato com o suporte Snowflake.

• A restrição NOT NULL pode ser descartada de qualquer número de colunas ausentes em novos arquivos de dados.

Configurando como TRUE permite a evolução automática do esquema da tabela. O padrão FALSE desativa a evolução automática do esquema da tabela.

Nota

O carregamento de dados de arquivos evolui as colunas da tabela quando todas as condições a seguir forem verdadeiras:

• A instrução COPY INTO <tabela> inclui a opção MATCH_BY_COLUMN_NAME.

• A função usada para carregar os dados tem o privilégio EVOLVE SCHEMA ou OWNERSHIP na tabela.

Além disso, para a evolução do esquema com CSV, quando usado com MATCH_BY_COLUMN_NAME e PARSE_HEADER, ERROR_ON_COLUMN_COUNT_MISMATCH deve ser definido como falso.

DATA_RETENTION_TIME_IN_DAYS = integer

Especifica o período de retenção da tabela para que as ações do Time Travel (SELECT, CLONE, UNDROP) possam ser executadas nos dados históricos na tabela. Para obter mais detalhes, consulte Compreensão e uso do Time Travel e Como trabalhar com tabelas temporárias e transitórias.

Para uma descrição detalhada deste parâmetro de nível de objeto, bem como mais informações sobre parâmetros de objeto, consulte Parâmetros.

Valores:

• Standard Edition: 0 ou 1

• Enterprise Edition:

  • 0 a 90 para tabelas permanentes

  • 0 ou 1 para tabelas temporárias e transitórias

Padrão:

• Standard Edition: 1

• Enterprise Edition (ou superior): 1 (a menos que um valor padrão diferente tenha sido especificado no esquema, banco de dados ou nível de conta)

Nota

Um valor de 0 desabilita efetivamente o Time Travel para a tabela.

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

Parâmetro de objeto que especifica o número máximo de dias para os quais o Snowflake pode estender o período de retenção de dados da tabela para evitar que os fluxos na tabela se tornem obsoletos.

Para uma descrição detalhada deste parâmetro, consulte MAX_DATA_EXTENSION_TIME_IN_DAYS.

CHANGE_TRACKING = { TRUE | FALSE }

Especifica se deve permitir o rastreamento de alterações na tabela.

• TRUE habilita o rastreamento de alterações na tabela. Esta configuração adiciona um par de colunas ocultas à tabela de origem e começa a armazenar metadados de rastreamento de alterações nas colunas. Estas colunas consomem uma pequena quantidade de armazenamento.

  Os metadados de rastreamento de alterações podem ser consultados usando a cláusula CHANGES par instruções SELECT ou criando e consultando um ou mais fluxos na tabela.

• FALSE não permite o rastreamento de alterações na tabela.

Padrão: FALSE

DEFAULT_DDL_COLLATION = 'collation_specification'

Determina uma especificação de agrupamento padrão para as colunas da tabela, incluindo colunas adicionadas à tabela no futuro.

Para obter mais detalhes sobre o parâmetro, consulte DEFAULT_DDL_COLLATION.

COPY GRANTS

Especifica manter os privilégios de acesso da tabela original quando uma nova tabela é criada usando qualquer uma das seguintes variantes CREATE TABLE:

• CREATE OR REPLACE TABLE

• CREATE TABLE … LIKE

• CREATE TABLE … CLONE

O parâmetro copia todos os privilégios, exceto OWNERSHIP, da tabela existente para a nova tabela. A nova tabela não herda as concessões futuras definidas para o tipo de objeto no esquema. Por padrão, a função que executa a instrução CREATE TABLE é a proprietária da nova tabela.

Se o parâmetro não estiver incluído na instrução CREATE TABLE, então a nova tabela não herda qualquer privilégio de acesso explícito concedido na tabela original, mas herda qualquer concessão futura definida para o tipo de objeto no esquema.

Nota:

• Com compartilhamento de dados:

  • Se a tabela existente foi compartilhada com outra conta, a tabela de substituição também será compartilhada.

  • Se a tabela existente foi compartilhada com sua conta como consumidor de dados, e o acesso foi ainda concedido a outras funções na conta (usando GRANT IMPORTED PRIVILEGES no banco de dados pai), o acesso também é concedido à tabela de substituição.

• A saída SHOW GRANTS para a tabela de substituição relaciona o cessionário para os privilégios copiados como a função que executou a instruçãoCREATE TABLE, com o carimbo de data/hora atual quando a instrução foi executada.

• A operação de cópia de concessões ocorre atomicamente no comando CREATE TABLE (ou seja, dentro da mesma transação).

• Este parâmetro não é suportado pela sintaxe da variante CREATE OR ALTER.

COMMENT = 'string_literal'

Especifica um comentário para a tabela.

Padrão: sem valor

(Observe que os comentários podem ser especificados no nível da coluna, no nível da restrição ou no nível da tabela. A sintaxe de cada um é um pouco diferente).

ROW ACCESS POLICY policy_name ON ( col_name [ , col_name ... ] )

Especifica a política de acesso a linhas a ser definida em uma tabela.

Este parâmetro não é suportado pela sintaxe da variante CREATE OR ALTER.

AGGREGATION POLICY policy_name [ ENTITY KEY ( col_name [ , col_name ... ] ) ]

Especifica a política de agregação a ser definida em uma tabela.

Use o parâmetro opcional ENTITY KEY para definir quais colunas identificam exclusivamente uma entidade dentro da tabela. Para obter mais informações, consulte Implementação de privacidade ao nível de entidade com políticas de agregação.

Este parâmetro não é suportado pela sintaxe da variante CREATE OR ALTER.

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )

Especifica o nome da tag e o valor da cadeia de caracteres dela.

O valor de tag é sempre uma cadeia de caracteres, e o número máximo de caracteres do valor da tag é 256.

Para obter informações sobre como especificar tags em uma instrução, consulte Cotas de tags para objetos e colunas.

Este parâmetro não é suportado pela sintaxe da variante CREATE OR ALTER.

Requisitos de controle de acesso¶

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

Observe que operar em qualquer objeto de um esquema também requer o privilégio USAGE no banco de dados e esquema principais.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

• Um esquema não pode conter tabelas e/ou visualizações com o mesmo nome. Ao criar uma tabela:

  • Se já existir uma visualização com o mesmo nome no esquema, um erro é emitido e a tabela não é criada.

  • Se uma tabela com o mesmo nome já existir no esquema, um erro é emitido e a tabela não é criada, a menos que a palavra-chave opcional OR REPLACE esteja incluída no comando.

    Importante

    Usar OR REPLACE é o equivalente a usar DROP TABLE na tabela existente e depois criar uma nova tabela com o mesmo nome; no entanto, a tabela descartada não é permanentemente removida do sistema. Em vez disso, ela fica retida no Time Travel. Isto é importante notar porque as tabelas descartadas no Time Travel podem ser recuperadas, mas elas também contribuem para o armazenamento de dados de sua conta. Para obter mais informações, consulte Custos de armazenamento para Time Travel e Fail-safe.

    Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando um objeto é substituído, o objeto antigo é excluído e o novo objeto é criado em uma única transação.

    Isso significa que qualquer consulta concorrente com a operação CREATE OR REPLACE TABLE utiliza a versão da tabela antiga ou nova.

    A recriação ou troca de uma tabela descarta seus dados de alteração. Qualquer fluxo na tabela se torna obsoleto. Além disso, qualquer fluxo em uma visualização que tenha esta tabela como uma tabela subjacente, torna-se obsoleto. Um fluxo obsoleto é ilegível.

• Assim como as palavras-chave reservadas, nomes de funções reservadas ANSI (CURRENT_DATE, CURRENT_TIMESTAMP etc.) não podem ser usados como nomes de colunas.

• CREATE OR ALTER TABLE:

  Para obter mais informações, consulte Notas de uso de CREATE OR ALTER TABLE.

• CREATE TABLE … CLONE:

  Se a tabela de origem tiver chaves de clustering, então a nova tabela terá chaves de clustering. Por padrão, o Clustering automático é suspenso para a nova tabela – mesmo que o Clustering automático não tenha sido suspenso para a tabela de origem.

• CREATE TABLE … CHANGE_TRACKING = TRUE:

  Quando o rastreamento da alterações é ativado, a tabela é bloqueada durante toda a operação. Os bloqueios podem causar latência com algumas operações associadas DDL/DML. Para obter mais informações, consulte Bloqueio de recursos.

• CREATE TABLE … LIKE:

  Se a tabela de origem tiver chaves de clustering, então a nova tabela terá chaves de clustering. Por padrão, o Clustering automático não é suspenso para a nova tabela – mesmo que o Clustering automático tenha sido suspenso para a tabela de origem.

• CREATE TABLE … AS SELECT (CTAS):

  • Se os aliases para os nomes das colunas na lista SELECT forem colunas válidas, então as definições das colunas não são exigidas na instrução CTAS; se omitidos, os nomes e tipos das colunas são inferidos a partir da consulta subjacente:

    CREATE TABLE <table_name> AS SELECT ...
    

    Copy

    Alternativamente, os nomes podem ser explicitamente especificados usando a seguinte sintaxe:

    CREATE TABLE <table_name> ( <col1_name> , <col2_name> , ... ) AS SELECT ...
    

    Copy

    O número de nomes de colunas especificados deve corresponder ao número de itens da lista SELECT na consulta; os tipos das colunas são inferidos a partir dos tipos produzidos pela consulta.

  • Quando as chaves de clustering são especificadas em uma instrução CTAS:

    • As definições das colunas são necessárias e devem ser explicitamente especificadas na instrução.

    • Por padrão, o Clustering automático não é suspenso para a nova tabela – mesmo que o Clustering automático seja suspenso para a tabela de origem.

  • Se você quiser que a tabela seja criada com linhas em uma ordem específica, então use uma subcláusula ORDER BY na cláusula SELECT do CTAS. Especificar CLUSTER BY não agrupa os dados no momento em que a tabela é criada; em vez disso, CLUSTER BY depende do clustering automático para reter os dados ao longo do tempo.

    A subcláusula ORDER BY em uma instrução CREATE TABLE não afeta a ordem das linhas devolvidas por futuras instruções SELECT naquela tabela. Para especificar a ordem das linhas nas futuras instruções SELECT, use uma subcláusula ORDER BY nessas instruções.

• Dentro de uma transação, qualquer instrução DDL (incluindo CREATE TEMPORARY/TRANSIENT TABLE) executa a transação antes de executar a própria instrução DDL. A instrução DDL é então executada em sua própria transação. A próxima instrução após a instrução DDL inicia uma nova transação. Portanto, você não pode criar, usar e descartar uma tabela temporária ou transitória dentro de uma única transação. Se você quiser usar uma tabela temporária ou transitória dentro de uma transação, então crie a tabela antes da transação, e descarte a tabela após a transação.

• Recriar uma tabela (usando a palavra-chave opcional OR REPLACE) diminui seu histórico, o que torna qualquer fluxo na tabela obsoleto. Um fluxo obsoleto é ilegível.

• Uma única política de mascaramento que utilize colunas condicionais pode ser aplicada a várias tabelas, desde que a estrutura de colunas da tabela corresponda às colunas especificadas na política.

• Ao criar uma tabela com uma política de mascaramento em uma ou mais colunas da tabela, ou uma política de acesso a linhas adicionada à tabela, use a função POLICY_CONTEXT para simular uma consulta na(s) coluna(s) protegida(s) por uma política de mascaramento e a tabela protegida por uma política de acesso a linhas.

• Em relação aos metadados:

  Atenção

  Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

Notas de uso de CREATE OR ALTER TABLE¶

• Limitações

  • Atualmente, oferece suporte apenas a tabelas permanentes, temporárias e transitórias. Tabelas somente leitura, externas, dinâmicas, Apache Iceberg™ e híbridas não são compatíveis.

  • Todas as limitações do comando ALTER TABLE se aplicam.

  • Atualmente não oferece suporte ao seguinte:

    • Sintaxe da variante CREATE TABLE … AS SELECT (CTAS).

    • Sintaxe da variante CREATE TABLE … USING TEMPLATE.

    • Sintaxe da variante CREATE TABLE … LIKE.

    • Sintaxe da variante CREATE TABLE … CLONE.

• Parâmetros e propriedades da tabela

  • A ausência de uma propriedade ou parâmetro que foi previamente definido na definição da tabela modificada resulta no cancelamento de sua definição.

  • O cancelamento da definição de um valor de parâmetro explícito resulta na configuração do valor do parâmetro padrão. Se o parâmetro for definido no esquema ou banco de dados que contém a tabela, a tabela herdará o valor do parâmetro definido no esquema ou banco de dados.

• Governança de dados

  • Definir ou desmarcar uma tag ou política em uma tabela ou coluna usando uma instrução CREATE OR ALTER TABLE não é suportado.

    As políticas ou tags existentes não são alteradas por uma instrução CREATE OR ALTER e permanecem inalteradas.

• Restrições

  Definir ou cancelar a definição de uma chave primária inline altera a nulidade da coluna de acordo. Isso está alinhado com o comportamento do comando CREATE TABLE, mas é diferente do comportamento do comando ALTER TABLE.

• Colunas

  • Novas colunas só podem ser adicionadas ao final da lista de colunas.

  • As colunas não podem ser renomeadas. Se você tentar renomear uma coluna, ela será descartada e uma nova coluna será adicionada.

  • O valor padrão de uma coluna só pode ser modificado para usar uma sequência.

  • A sequência padrão para uma coluna (por exemplo, SET DEFAULT seq_name.NEXTVAL) só pode ser alterado se a coluna já tiver uma sequência.

  • Para obter mais informações sobre como modificar colunas, consulte ALTER TABLE … ALTER COLUMN.

• Agrupamento

  • As especificações de agrupamento não podem ser alteradas.

  • A definição do parâmetro DEFAULT_DDL_COLLATION no comando CREATE OR ALTER TABLE define a especificação de agrupamento padrão para colunas existentes, o que garante o comando CREATE OR ALTER TABLE produza os mesmos resultados que o comando CREATE TABLE. Portanto, você não pode usar o comando CREATE OR ALTER TABLE para definir o parâmetro DEFAULT_DDL_COLLATION em uma tabela que possui colunas de texto existentes. No entanto, você pode tornar as comparações explícitas para colunas existentes ao alterar o parâmetro DEFAULT_DDL_COLLATION para uma tabela.

    Por exemplo, crie uma nova tabela my_table e defina a especificação de ordenação padrão para a tabela como “fr”:

    CREATE OR ALTER TABLE my_table (
      a INT PRIMARY KEY,
      b VARCHAR(20)
    )
    DEFAULT_DDL_COLLATION = 'fr';
    

    Copy

    A especificação de ordenação para coluna b é “fr” e não pode ser alterado. Para alterar a especificação de ordenação padrão para tabela my_table, você deve definir explicitamente a ordenação para a coluna de texto b na instrução CREATE OR ALTER:

    CREATE OR ALTER TABLE my_table (
      a INT PRIMARY KEY,
      b VARCHAR(200) COLLATE 'fr'
    )
    DEFAULT_DDL_COLLATION = 'de';
    

    Copy

• Atomicidade

  O comando CREATE OR ALTER TABLE atualmente não garante atomicidade. Isto significa que se uma instrução CREATE OR ALTER TABLE falhar durante a execução, é possível que um subconjunto de alterações tenha sido aplicado à tabela. Se houver possibilidade de alterações parciais, a mensagem de erro, na maioria dos casos, inclui o seguinte texto:

  CREATE OR ALTER execution failed. Partial updates may have been applied.
  

  Por exemplo, se a instrução estiver tentando remover a coluna A e adicionar uma nova coluna B em uma tabela e a instrução for abortada, é possível que a coluna A tenha sido descartado mas a coluna B não foi adicionada.

  Nota

  Se as alterações forem aplicadas parcialmente, a tabela resultante ainda estará em um estado válido e você poderá usar instruções ALTER TABLE para completar o conjunto original de alterações.

  Para se recuperar de atualizações parciais, a Snowflake recomenda os seguintes mecanismos de recuperação:

  • Reparo adiantado

    • Execute a instrução CREATE OR ALTER TABLE novamente. Se as instruções forem bem-sucedidas na segunda tentativa, o estado alvo será alcançado.

    • Investigue a mensagem de erro. Se possível, corrija o erro e execute novamente a instrução CREATE OR ALTER TABLE.

  • Reversão

    Se não for possível fazer o reparo aidantado, a Snowflake recomenda reverter manualmente as alterações parciais:

    • Investigue o estado da tabela usando os comandos DESCRIBE TABLE e SHOW TABLES. Determine quais alterações parciais foram aplicadas, se houver.

    • Se alguma alteração parcial foi aplicada, execute as instrução ALTER TABLE apropriadas para transformar a tabela de volta ao seu estado original.

      Nota

      Em alguns casos, talvez não seja possível desfazer alterações parciais. Para obter mais informações, consulte as ações com e sem suporte para modificar as propriedades da coluna no tópico ALTER TABLE … ALTER COLUMN.

  • Se precisar de ajuda para se recuperar de uma atualização parcial, entre em contato com o suporte Snowflake.

Exemplos¶

CREATE OR ALTER TABLE my_table(a INT);

CREATE OR ALTER TABLE my_table(
    a INT PRIMARY KEY,
    b VARCHAR(200)
  )
  DATA_RETENTION_TIME_IN_DAYS = 5
  DEFAULT_DDL_COLLATION = 'de';

CREATE OR ALTER TABLE my_table(
    a INT PRIMARY KEY,
    c VARCHAR(200)
  )
  DEFAULT_DDL_COLLATION = 'de';