CREATE ICEBERG TABLE (catálogo REST Iceberg)¶

Sintaxe¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  CATALOG_TABLE_NAME = '<rest_catalog_table_name>'
  [ CATALOG_NAMESPACE = '<catalog_namespace>' ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

Sintaxe da variante¶

CREATE ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [
    --Column definition
    <col_name> <col_type>
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]
  ]
  [ PARTITION BY ( partitionExpression [ , partitionExpression , ... ] ) ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ COPY GRANTS ]
  [ 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 no Snowflake; deve ser exclusivo 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.

Nota

Para recuperar uma lista de tabelas ou namespaces em seu catálogo remoto, é possível usar as seguintes funções:

• SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG

• SYSTEM$LIST_NAMESPACES_FROM_CATALOG

CATALOG_TABLE_NAME = 'rest_catalog_table_name'

Especifica o nome da tabela conforme reconhecido pelo seu catálogo externo. Este parâmetro não pode ser alterado após criar a tabela.

Nota

Não especifique um namespace com o nome da tabela (mynamespace.mytable). Para especificar um namespace para essa tabela e substituir o namespace padrão definido para a integração do catálogo, use o parâmetro CATALOG_NAMESPACE.

col_name

Para criar uma tabela em um banco de dados vinculado a catálogo (versão preliminar).

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

Para criar uma tabela em um banco de dados vinculado a catálogo (versão preliminar).

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 para tabelas Apache Iceberg™.

Parâmetros opcionais¶

MASKING POLICY = policy_name

Para criar uma tabela em um banco de dados vinculado a catálogo (versão preliminar).

Especifica a política de mascaramento a ser definida em uma coluna. A política de mascaramento deve pertencer a um banco de dados Snowflake padrão (não ao banco de dados vinculado a catálogo).

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 você não especificar esse parâmetro, a tabela Iceberg assumirá como padrão a integração de 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_database) para a fonte do catálogo REST. Ao especificar um namespace com a integração do catálogo e, em seguida, no nível da tabela, você pode usar uma única integração do catálogo REST para criar tabelas Iceberg em diferentes bancos de dados. Se você não especificar um namespace com a tabela, a tabela usará o namespace padrão do catálogo associado à integração do catálogo.

• Se um namespace padrão não for especificado com a integração do catálogo, você deverá especificar o namespace da origem do catálogo REST para definir um namespace de catálogo para a tabela.

Nota

Para recuperar uma lista de tabelas ou namespaces em seu catálogo remoto, é possível usar as seguintes funções:

• SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG

• SYSTEM$LIST_NAMESPACES_FROM_CATALOG

TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }'

Recurso em versão preliminar — Aberto

Disponível para todas as contas.

Especifica um tamanho de arquivo Parquet de destino para a tabela.

• '{ 16MB | 32MB | 64MB | 128MB }' especifica um tamanho de arquivo de destino fixo para a tabela.

• 'AUTO' funciona de forma diferente, dependendo do tipo de tabela:

  • Tabelas gerenciadas pelo Snowflake: AUTO especifica que o Snowflake deve escolher o tamanho do arquivo para a tabela com base em características da tabela, como tamanho, DML padrões, carga de trabalho de ingestão e configuração de cluster. O Snowflake ajusta automaticamente o tamanho do arquivo, começando em 16 MB, para melhor desempenho de leitura e gravação no Snowflake. Use essa opção para otimizar o desempenho da tabela no Snowflake.

  • Tabelas gerenciadas externamente: AUTO especifica que o Snowflake deve ser dimensionado agressivamente para o maior tamanho de arquivo (128 MB).

Para obter mais informações, consulte Definir um tamanho de arquivo de destino.

Padrão: AUTO

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.

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.

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.

Para obter mais informações, consulte atualização automatizada.

Padrão: FALSE

Nota

O uso de AUTO_REFRESH com INFER_SCHEMA não é compatível.

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

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

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 Cota de tags para objetos.

WITH CONTACT ( purpose = contact [ , purpose = contact ...] )

Associe o novo objeto a um ou mais contatos.

Requisitos de controle de acesso¶

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:

O privilégio USAGE no banco de dados e no esquema pai é necessário para executar operações em qualquer objeto de um esquema.

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¶

• 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 criar uma tabela Iceberg com suporte a gravação (versão preliminar):

  • Se você usar um banco de dados Snowflake padrão, primeiro deverá criar uma tabela Iceberg no catálogo remoto. Por exemplo, você pode usar o Spark para gravar uma tabela Iceberg no Open Catalog. Não especifique definições de coluna em sua instrução CREATE ICEBERG TABLE.

  • Se você usar um banco de dados vinculado a catálogo, deve especificar as definições de coluna ao criar a tabela. Como alternativa, você pode gravar em tabelas Iceberg que o Snowflake descobre automaticamente em seu catálogo remoto.

• A propriedade TARGET_FILE_SIZE é compatível apenas com tabelas com suporte a gravação (versão preliminar).

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

  • As cláusulas OR REPLACE e IF NOT EXISTS são mutuamente exclusivas. Elas não podem ser usadas na mesma instrução.

  • 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 OR REPLACE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'my_rest_catalog_integration'
  CATALOG_TABLE_NAME = 'my_remote_table'
  AUTO_REFRESH = TRUE;

CREATE ICEBERG TABLE open_catalog_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'open_catalog_int'
  CATALOG_TABLE_NAME = 'my_open_catalog_table'
  AUTO_REFRESH = TRUE;

USE DATABASE my_catalog_linked_db;

USE SCHEMA 'my_namespace';

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table (
  first_name string,
  last_name string,
  amount int,
  create_date date
);