CREATE ICEBERG TABLE (Arquivos Delta no armazenamento de objeto)¶

Sintaxe¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  BASE_LOCATION = '<relative_path_from_external_volume>'
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

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.

BASE_LOCATION = 'relative_path_from_external_volume'

Especifica um caminho relativo do local EXTERNAL_VOLUME da tabela para um diretório onde o Snowflake pode acessar seus arquivos de tabela Delta.

O local base deve apontar para um diretório e não pode apontar para um único arquivo. Ele deve conter a subpasta do log de transação Delta (por exemplo, my/base/location/_delta_log/).

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.

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.

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

Especifica se deve substituir os caracteres UTF-8 inválidos pelo caractere de substituição Unicode (�) nos resultados da consulta. Você só pode definir esse parâmetro para tabelas que usam um catálogo Iceberg externo.

• TRUE substitui os caracteres UTF-8 inválidos pelo caractere de substituição Unicode.

• FALSE deixa caracteres UTF-8 inválidos inalterados. O Snowflake retorna uma mensagem de erro do usuário quando encontra caracteres UTF-8 inválidos em um arquivo de dados Parquet.

Se não for especificado, a tabela Iceberg assumirá o valor do parâmetro 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.

Padrão: FALSE

COMMENT = 'string_literal'

Especifica um comentário para a tabela.

Padrão: sem valor

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.

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¶

• Considerações para executar este comando:

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

• Considerações para tabelas Iceberg criadas a partir de arquivos de tabela Delta:

  • É possível usar o Time Travel para consultar tabelas Iceberg criadas a partir de arquivos de tabela Delta. As versões da tabela correspondem aos arquivos de confirmação de log Delta individuais.

  • As tabelas Iceberg são compatíveis com dados gerados pelo Delta Lake versão 3.1 e anteriores.

  • Os fluxos Snowflake não são compatíveis com tabelas Iceberg criadas a partir de arquivos de tabela Delta com colunas de partição. No entanto, os fluxos apenas de inserção para tabelas criadas a partir de arquivos Delta sem colunas de partição são compatíveis.

  • Tabelas dinâmicas não são compatíveis com tabelas Iceberg criadas a partir de arquivos de tabela Delta.

  • Snowflake não oferece suporte à criação de tabelas Iceberg a partir de definições de tabela Delta no AWS Glue Data Catalog.

  • Arquivos Parquet (arquivos de dados para tabelas Delta) que usam qualquer um dos seguintes recursos ou tipos de dados não são compatíveis:

    • Campo IDs.

    • O tipo de dados INTERVAL.

    • O tipo de dados DECIMAL com precisão maior que 38.

    • Os tipos LIST ou MAP com representação de um ou dois níveis.

    • Tipos inteiros sem sinal (INT(signed = false)).

    • O tipo de dados FLOAT16.

    Para obter mais informações sobre os tipos de dados Delta e tabelas Iceberg, consulte Tipos de dados Delta.

  • As operações de atualização durante CREATE e ALTER … REFRESH podem processar no máximo 1.000 arquivos de confirmação Delta por operação.

    Nota

    O Snowflake usa arquivos de ponto de verificação Delta ao criar uma tabela Iceberg. O limite de 1.000 arquivo de confirmação se aplica somente a confirmações após o último ponto de verificação.

  • Não há suporte para gerar metadados do Iceberg usando a função SYSTEM$GET_ICEBERG_TABLE_INFORMATION.

  • Os seguintes recursos do Delta Lake não são compatíveis no momento: rastreamento de linhas, arquivos vetoriais de exclusão, arquivos de dados de alteração, metadados de alteração, DataChange, CDC e evolução de protocolo.

• Considerações para a criação de tabelas:

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

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

O comando de exemplo a seguir cria uma tabela Iceberg a partir de arquivos de tabela Delta no armazenamento de objeto.

O exemplo especifica um volume externo associado ao local da nuvem dos arquivos da tabela Delta, uma integração de catálogo configurada para Delta e um valor para o parâmetro BASE_LOCATION necessário.

CREATE ICEBERG TABLE my_delta_iceberg_table
  CATALOG = delta_catalog_integration
  EXTERNAL_VOLUME = delta_external_volume
  BASE_LOCATION = 'relative/path/from/ext/vol/';

Se a tabela Delta usar um esquema de particionamento, o Snowflake interpretará automaticamente o esquema do log Delta.