ALTER ICEBERG TABLE … ALTER COLUMN … SET DATA TYPE¶

Nota

Esta variante da sintaxe não é suportada para tabelas Iceberg que usam um catálogo externo.

Modifica (evolui) uma coluna de tipo estruturado em uma tabela Apache Iceberg™ gerenciada pelo Snowflake.

Com este comando, você pode modificar tipos estruturados em uma coluna da tabela Iceberg. Você pode renomear uma chave em um OBJECT estruturado ou executar uma combinação das seguintes alterações:

Evoluindo o tipo de um campo dentro de um tipo estruturado.
Reordenando chaves em um OBJECT estruturado.
Adicionando chaves a um OBJECT estruturado.
Descartando chaves de um OBJECT estruturado.

Não é possível combinar a renomeação de uma chave com nenhuma outra modificação.

Para resumir, este tópico se refere às tabelas Iceberg apenas como “tabelas”, exceto ao fazer uma distinção entre tabelas Iceberg e tabelas Snowflake comuns.

Consulte também:: CREATE ICEBERG TABLE , DROP ICEBERG TABLE , SHOW ICEBERG TABLES , DESCRIBE ICEBERG TABLE

Sintaxe¶

Modificar uma coluna de tipo estruturado

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> ALTER COLUMN <structured_column>
  SET DATA TYPE <new_structured_type>

Copy

Renomear chaves em um OBJECT estruturado

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> ALTER COLUMN <structured_column>
  SET DATA TYPE <new_structured_type>
  RENAME FIELDS

Copy

Parâmetros¶

table_name

Identificador da tabela a ser modificada.

Se o identificador contiver espaços ou caracteres especiais, toda a cadeia de caracteres deverá ser delimitada por aspas duplas. Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais informações, consulte Requisitos para identificadores.

ALTER COLUMN structured_column

Especifica a coluna de tipo estruturado a ser modificada.

Para obter mais informações, consulte Requisitos para identificadores.

SET DATA TYPE new_structured_type

Uma especificação completa para o novo tipo estruturado a ser usado na coluna. Por exemplo, para especificar uma ARRAY estruturada de elementos NUMBER, use ARRAY(NUMBER).

Para mais informações, consulte Como especificar um tipo estruturado e os exemplos nesta página.

RENAME FIELDS

Especifica que o comando deve renomear uma ou mais chaves em um OBJECT estruturado. As chaves antigas e novas devem diferir apenas no nome e devem ter exatamente a mesma hierarquia e tipos de dados. Renomear chaves não altera o campo IDs.

A renomeação de chaves não pode ser combinada com nenhuma outra modificação em tipos estruturados em uma tabela Iceberg.

Consulte o exemplo de RENAME FIELDS.

Requisitos de controle de acesso¶

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

Privilégio	Objeto	Notas
OWNERSHIP	Tabela Iceberg	OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).
USAGE	Volume externo

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¶

Este comando não oferece suporte às seguintes ações:
- Evoluir um tipo estruturado para um tipo não estruturado (ou vice-versa).
- Definir uma restrição nula em um elemento de ARRAY estruturado ou nos pares chave-valor de um MAP estruturado.
- Usar RENAME FIELDS para renomear uma chave que faz parte da chave de clustering da tabela.
- Alterar a restrição NULL restrição para um OBJECT estruturado.
Para tabelas que usam políticas de acesso a dados, certifique-se de que o novo tipo de dados para uma coluna seja compatível com o tipo de argumento da sua política de acesso a dados. Caso contrário, a consulta à tabela poderá falhar. Por exemplo, se você adicionar uma chave a uma coluna OBJECT estruturada, você deve alterar sua política ou criar uma nova política e aplicá-la à sua tabela.
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¶

Evolução de tipos¶

Você pode evoluir o tipo de um campo em um tipo estruturado. Evoluir o tipo significa ampliá-lo para um tipo de dados Iceberg maior e relacionado.

O Snowflake oferece suporte às seguintes evoluções de tipo, de acordo com a Especificação do Apache Iceberg:

Alteração de um campo de tipo int para tipo long.
Alteração de um campo de tipo float para tipo double.
Alteração de um campo de tipo decimal(p,s) para tipo decimal(p',s) em que p é menor do que p'.

Para evoluir um tipo de campo, use a sintaxe Snowflake para especificar um tipo estruturado. Você pode usar o tipo de dados Iceberg em sua especificação. Por exemplo, a seguinte instrução altera o tipo de elemento em uma coluna de ARRAY estruturada para tipo (Iceberg) long.

ALTER ICEBERG TABLE my_iceberg_table ALTER COLUMN col1
  SET DATA TYPE ARRAY(long);

Copy

Para obter informações sobre como os tipos de dados Iceberg são mapeados para os tipos de dados Snowflake, consulte Tipos de dados para tabelas Apache Iceberg™.

Reordenação de chaves¶

Para reorganizar a ordem das chaves em um OBJECT estruturado, especifique uma nova ordem em sua instrução ALTER ICEBERG TABLE. A reorganização da ordem das chaves não afeta os dados no OBJECT.

Por exemplo, considere a seguinte instrução CREATE ICEBERG TABLE: A tabela tem uma coluna (column_1) do tipo OBJECT com duas chaves em uma ordem específica:

CREATE ICEBERG TABLE my_iceberg_table (
  column_1 OBJECT(
      key_a int,
      key_b int
    )
  )
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume'
  BASE_LOCATION = '';

Copy

O comando a seguir altera a ordem das chaves para que key_b venha antes de key_a:

ALTER ICEBERG TABLE my_iceberg_table ALTER COLUMN column_1
  SET DATA TYPE OBJECT(
    key_b int,
    key_a int
  );

Copy

Adição de chaves¶

Você pode adicionar chaves a um OBJECT estruturado. Uma nova chave pode usar qualquer um dos tipos de dados suportados para tabelas Iceberg pelo seu valor.

Nota

Você não pode definir uma restrição nula ao adicionar uma chave, porque o Snowflake define o valor da chave como NULL para todas as linhas existentes na tabela.

Por exemplo, considere a seguinte instrução CREATE ICEBERG TABLE: A tabela tem uma coluna (column_1) do tipo OBJECT com uma chave (key_1):

CREATE ICEBERG TABLE my_iceberg_table (
  column_1 OBJECT(
      key_1 int
    )
  )
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume'
  BASE_LOCATION = '';

Copy

O comando a seguir adiciona uma chave chamada key_2 para column_1:

ALTER ICEBERG TABLE my_iceberg_table ALTER COLUMN column_1
  SET DATA TYPE OBJECT(
    key_1 int,
    key_2 int
  );

Copy

Descarte de chaves¶

Nota

Não há suporte para descartar uma chave cujo valor é um tipo de dados estruturado que pertence a uma chave de clustering.

Para remover uma chave de um OBJECT estruturado, use o comando ALTER ICEBERG TABLE…ALTER COLUMN para redefinir o OBJECT.

O descarte da chave remove a chave e seu valor de todas as linhas da tabela.

Por exemplo, considere a seguinte instrução CREATE ICEBERG TABLE: A tabela tem uma coluna (column_1) do tipo OBJECT com duas chaves:

CREATE ICEBERG TABLE my_iceberg_table (
  column_1 OBJECT(
      key_1 int,
      key_2 ARRAY(string)
    )
  )
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume'
  BASE_LOCATION = '';

Copy

O comando a seguir descarta a chave chamada key_2 omitindo-a da especificação OBJECT:

ALTER ICEBERG TABLE my_iceberg_table ALTER COLUMN column_1
  SET DATA TYPE OBJECT(
    key_1 int
  );

Copy

Renomeação de chaves¶

Para alterar os nomes das chaves em um OBJECT estruturado, use as palavras-chave RENAME FIELDS.

Por exemplo, considere a seguinte instrução CREATE ICEBERG TABLE:

CREATE ICEBERG TABLE my_iceberg_table (
  column_1 OBJECT(
      key_1 int,
      key_2 int
    )
  )
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume'
  BASE_LOCATION = '';

Copy

O comando a seguir usa RENAME FIELDS para renomear as chaves em column_1:

ALTER ICEBERG TABLE my_iceberg_table ALTER COLUMN column_1
  SET DATA TYPE OBJECT(
    k_1 int,
    k_2 int
  )
  RENAME FIELDS;

Copy