CREATE ICEBERG TABLE (AWS Glue como catálogo Iceberg)¶

Sintaxe¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  CATALOG_TABLE_NAME = '<catalog_table_name>'
  [ CATALOG_NAMESPACE = '<catalog_namespace>' ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ AUTO_REFRESH = { 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.

CATALOG_TABLE_NAME = 'catalog_table_name'

Especifica o nome da tabela conforme reconhecido pelo 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.

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. Você deve especificar uma integração de catálogo que você configurou para o AWS Glue. Para obter mais informações, consulte Configuração de uma integração de catálogo para AWS Glue.

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.

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.

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

AUTO_REFRESH = { TRUE | FALSE }

Especifica se o Snowflake deve pesquisar automaticamente o catálogo Iceberg externo associado à tabela para atualizações de metadados ao usar a atualização automatizada. Se nenhum valor for especificado para o parâmetro REFRESH_INTERVAL_SECONDS na integração do catálogo, o Snowflake usará um intervalo de atualização padrão de 30 segundos.

Padrão: FALSE

Recurso em versão preliminar

Disponível para todas as contas.

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

• 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 glue_iceberg_table
  EXTERNAL_VOLUME='glue_catalog_volume'
  CATALOG='glue_catalog_integration'
  CATALOG_TABLE_NAME='my_glue_catalog_table'
  CATALOG_NAMESPACE='icebergcatalogdb2';

CREATE OR REPLACE ICEBERG TABLE itable_with_quoted_catalog
  EXTERNAL_VOLUME = '"glue_volume_1"'
  CATALOG = '"glue_catalog_integration_1"'
  CATALOG_TABLE_NAME='my_glue_catalog_table'
  CATALOG_NAMESPACE='icebergcatalogdb2';