CREATE ICEBERG TABLE¶

Sintaxe¶

• Snowflake como o catálogo Iceberg

• Catálogo Iceberg externo

-- Snowflake as the Iceberg catalog
CREATE [ OR REPLACE ] ICEBERG 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>
              } ]
        } ]
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]
      [ [ 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> , ... ] ) ]
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = 'SNOWFLAKE' ]
  BASE_LOCATION = '<relative_path_from_external_volume>'
  [ 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 ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

-- External Iceberg catalog
CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  externalCatalogParams
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ COMMENT = '<string_literal>' ]

Sintaxe da variante¶

A sintaxe de variante a seguir é suportada para a criação de tabelas Iceberg que usam Snowflake como catálogo.

Parâmetros obrigatórios¶

table_name

Especifica o identificador (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 informações, consulte Requisitos para identificadores.

col_name

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

Para obter mais informações, 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 informações sobre os tipos de dados que podem ser especificados para colunas de tabela, consulte Tipos de dados da tabela Iceberg.

query

Subconsulta que chama a função INFER_SCHEMA e formata a saída como uma matriz.

Parâmetros opcionais¶

EXTERNAL_VOLUME = 'external_volume_name'

Especifica o identificador (nome) do volume externo onde a tabela Iceberg armazena seus arquivos de metadados e dados no formato Parquet. Os metadados e arquivos de manifesto do Iceberg armazenam o esquema da tabela, partições, instantâneos e outros metadados.

Se você não especificar esse parâmetro, o padrão da tabela Iceberg será o volume externo do esquema, banco de dados ou conta. O esquema tem precedência sobre o banco de dados e o banco de dados tem precedência sobre a conta.

CONSTRAINT ...

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

Para obter informações 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 informações, 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 linguagens diferentes de SQL (por exemplo, Java, JavaScript).

  • Funções externas.

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

AUTOINCREMENT e IDENTITY são sinônimos. Quando um ou outro é usado, o valor padrão para a coluna começa com um número especificado e cada valor sucessivo é incrementado automaticamente pelo valor especificado.

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 início e o passo/incremento é 1.

AUTOINCREMENT e IDENTITY podem ser usados somente para colunas com tipos de dados numéricos.

Padrão: sem valor (a coluna não tem valor padrão)

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.

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 informações, consulte Chaves de clustering e tabelas clusterizadas.

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

Importante

O clustering só é suportado para tabelas que usam Snowflake como catálogo Iceberg

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.

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 informações, 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 os 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 para 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 informações 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 ICEBERG TABLE, então a nova tabela não herdará nenhum 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ção CREATE ICEBERG 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 ICEBERGTABLE (ou seja, dentro da mesma transação).

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

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.

Parâmetros do catálogo Snowflake¶

CATALOG = 'SNOWFLAKE'

Especifica o Snowflake como o catálogo Iceberg. Snowflake cuida de toda a manutenção do ciclo de vida, como compactação, da tabela.

BASE_LOCATION = 'relative_path_from_external_volume'

Especifica um caminho relativo do local EXTERNAL_VOLUME da tabela até um diretório onde o Snowflake pode gravar dados e metadados da tabela.

Este parâmetro não pode ser alterado após a criação de uma tabela.

Parâmetros do catálogo externo (externalCatalogParams)¶

CATALOG = 'catalog_integration_name'

Especifica o identificador (nome) da integração do catálogo para esta tabela.

Se não for especificado, a tabela Iceberg assumirá como padrão a integração do catálogo para o esquema, banco de dados ou conta. O esquema tem precedência sobre o banco de dados e o banco de dados tem precedência sobre a conta.

AWS Glue

CATALOG_TABLE_NAME = 'catalog_table_name'

Especifica o nome da tabela conforme reconhecido pelo seu catálogo de dados do AWS Glue. Para ver um exemplo de uso de CATALOG_TABLE_NAME ao criar uma tabela Iceberg, consulte Exemplos (neste tópico). Este parâmetro não pode ser alterado após a criação da tabela.

CATALOG_NAMESPACE = 'catalog_namespace'

Opcionalmente, especifica o namespace (por exemplo, my_glue_database) para a origem do catálogo de dados do AWS Glue e substitui o namespace de catálogo padrão especificado com a integração do catálogo. Ao especificar um namespace no nível da tabela, você pode usar uma única integração de catálogo para o AWS Glue para criar tabelas Iceberg em diferentes bancos de dados.

Se não for especificado, a tabela usará o namespace de catálogo padrão associado à integração de catálogo.

Arquivos Iceberg no armazenamento de objetos

METADATA_FILE_PATH = 'metadata_file_path'

Especifica o caminho relativo do arquivo de metadados Iceberg a ser usado para definições de colunas. Por exemplo, se s3://mybucket_us_east_1/metadata/v1.metadata.json for o caminho completo para seu arquivo de metadados e o local de armazenamento do volume externo for s3://mybucket_us_east_1/, especifique metadata/v1.metadata.json como o valor de METADATA_FILE_PATH.

Antes da versão 7.34 do Snowflake, esse parâmetro era chamado de METADATA_FILE_NAME.

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.

• 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 ICEBERG TABLE utiliza a versão da tabela antiga ou nova.

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

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

• Atualmente, as tabelas Iceberg entre nuvens e entre regiões não são suportadas quando você usa o Snowflake como o catálogo Iceberg. Se CREATE ICEBERG TABLE retornar uma mensagem de erro como "External volume <nome_do_volume> must have a STORAGE_LOCATION defined in the local region ...", certifique-se de que seu volume externo esteja usando um local de armazenamento ativo na mesma região que sua conta Snowflake.

• Se você criou seu volume externo ou integração de catálogo usando um identificador entre aspas duplas, deverá especificar o identificador exatamente conforme criado (incluindo as aspas duplas) na instrução CREATE ICEBERG TABLE. A não inclusão das aspas pode resultar em um erro Object does not exist (ou um tipo similar de erro).

  Para ver um exemplo, consulte a seção Exemplos (neste tópico).

• Com as versões 7.34 e posteriores do Snowflake, você não especifica um BASE_LOCATION para criar uma tabela a partir de arquivos Iceberg no armazenamento de objetos.

  Antes da versão 7.34, um parâmetro denominado BASE_LOCATION (também chamado de FILE_PATH nas versões anteriores) era necessário para criar uma tabela a partir de arquivos Iceberg no armazenamento de objetos. O parâmetro especificou um caminho relativo do local EXTERNAL_VOLUME.

  Você pode continuar a executar um script ou instrução que usa a sintaxe antiga. Se você fizer isso, as seguintes notas serão aplicadas:

  • Os arquivos de dados Parquet e os arquivos de metadados Iceberg da tabela devem estar dentro de BASE_LOCATION.

  • Para atualizar a tabela, você deve especificar um caminho relativo ao BASE_LOCATION. Por exemplo, se o caminho completo para o arquivo de metadados for s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json, especifique metadata/v1.metadata.json como metadata-file-relative-path.

    Para obter mais informações, consulte ALTER ICEBERG TABLE … REFRESH.

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

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

    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.

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

Exemplos¶

Criação de uma tabela Iceberg com Snowflake como catálogo

Este exemplo cria uma tabela Iceberg com Snowflake como catálogo Iceberg. A tabela resultante é gerenciada pelo Snowflake e oferece suporte ao acesso de leitura e gravação. A instrução especifica um valor para o parâmetro BASE_LOCATION. Isso informa ao Snowflake onde gravar dados e metadados da tabela no volume externo.

CREATE ICEBERG TABLE my_iceberg_table (amount int)
  CATALOG='SNOWFLAKE'
  EXTERNAL_VOLUME='my_external_volume'
  BASE_LOCATION='my/relative/path/from/extvol';

Criação de uma tabela Iceberg com AWS Glue como catálogo

Este exemplo cria uma tabela Iceberg que usa o catálogo de dados do AWS Glue. Para substituir o namespace de catálogo padrão e definir um namespace de catálogo para a tabela, a instrução usa o parâmetro opcional CATALOG_NAMESPACE.

CREATE ICEBERG TABLE glue_iceberg_table
  EXTERNAL_VOLUME='glue_catalog_volume'
  CATALOG='glue_catalog_integration'
  CATALOG_TABLE_NAME='my_glue_catalog_table'
  CATALOG_NAMESPACE='icebergcatalogdb2';

Criação de uma tabela Iceberg a partir dos metadados Iceberg no armazenamento de objetos

Este exemplo cria uma tabela Iceberg a partir de metadados Iceberg armazenados em armazenamento externo em nuvem. Ele também especifica um caminho relativo para os metadados da tabela no volume externo.

CREATE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME='my_external_volume'
  CATALOG='my_catalog_integration'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';

Especificação de um volume externo ou integração de catálogo com um identificador entre aspas duplas

Este exemplo cria uma tabela Iceberg com um volume externo e integração de catálogo cujos identificadores contêm aspas duplas. Os identificadores colocados entre aspas duplas diferenciam maiúsculas de minúsculas e geralmente contêm caracteres especiais.

Os identificadores "exvol_lower" e "catint_lower" são especificados exatamente como foram criados (incluindo as aspas duplas). A não inclusão das aspas pode resultar em um erro Object does not exist (ou um tipo similar de erro).

Para saber mais, consulte Identificadores entre aspas duplas.

CREATE OR REPLACE ICEBERG TABLE itable_with_quoted_catalog
  EXTERNAL_VOLUME = '"exvol_lower"'
  CATALOG = '"catint_lower"'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';