CREATE ICEBERG TABLE (arquivos Iceberg no armazenamento de objetos)¶

Sintaxe¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  METADATA_FILE_PATH = '<metadata_file_path>'
  [ 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.

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.

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

    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.

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

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

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