Aplicar comprimento exato em inserções em colunas fixed[L] Apache Iceberg™ (versão preliminar)

Atenção

Essa alteração de comportamento está no pacote 2026_02.

Para saber o status atual do pacote, consulte Histórico do pacote.

Snowflake aplicará inserções de comprimento exato em colunas fixed[L] Iceberg.

Antes da mudança:

Colunas que usam o tipo de dados fixed[L] Iceberg aceitam valores binários de até o comprimento definido “L” em bytes. Valores menores que L são permitidos.

Valores maiores que L farão com que a consulta falhe.

Após a mudança:

Colunas que usam o tipo de dados fixed[L] Iceberg aceitam valores binários que correspondem exatamente ao comprimento definido “L” em bytes. Instruções INSERT que tentam inserir um valor binário menor que L resultam em um erro.

Essa alteração alinha o Snowflake com a especificação do Iceberg e outros mecanismos compatíveis com o Iceberg, como o Apache Spark™.

A lista a seguir resume o comportamento após a ativação dessa alteração:

  • Esta alteração se aplica a tabelas Iceberg novas e existentes.

  • Esta alteração aplica-se tanto a tabelas Iceberg gerenciadas pelo Snowflake quanto a tabelas gerenciadas externamente.

  • Em relação às leituras, esta alteração não afeta Time Travel ou instantâneos mais antigos. Os instantâneos existentes permanecerão legíveis, pois o Snowflake valida o comprimento do tipo de dados fixed[L] Iceberg apenas durante as operações DML.

  • Em relação às gravações, com esta alteração ativada, o Snowflake sempre aplicará o comprimento correto do tipo de dados fixed[L] Iceberg durante as operações de gravação, inclusive durante o Time Travel. As gravações que tentarem inserir um valor binário que não corresponda exatamente ao comprimento definido “L” em bytes sempre falharão. Valores maiores que L ainda farão com que a consulta falhe.

O que você precisa fazer para evitar qualquer interrupção do serviço: Identificar e resolver colunas afetadas.

Identificar e resolver colunas afetadas

Esta seção mostra como identificar se uma coluna foi afetada por este BCR e como resolver as colunas afetadas.

Etapa 1: Identificar colunas afetadas

Para identificar se você tem alguma coluna afetada, siga estas etapas:

  1. Execute o comando DESCRIBE ICEBERG TABLE.

    Na saída, procure por colunas com tipo de origem fixed[L] Iceberg. Se encontrar uma coluna fixed[L] do tipo Iceberg, prossiga para a próxima etapa.

  2. Execute a seguinte consulta:

    SELECT BOOLOR_AGG(OCTET_LENGTH(<column_name>) != L) from <table_name>
    Copy

    Se a consulta retorna verdadeiro, a coluna contém valores de comprimento incorreto; portanto, a coluna foi afetada.

Etapa 2: Resolver as colunas afetadas

Para resolver as colunas afetadas, realize uma das seguintes opções:

Permitir a inserção de valores binários de tamanho arbitrário na coluna afetada, até um comprimento máximo

Para resolver as colunas afetadas, você pode permitir a inserção de valores binários de tamanho arbitrário na coluna afetada, até um comprimento máximo.

Essa resolução garante que os metadados e os arquivos físicos da tabela estejam alinhados com a especificação do Iceberg e, portanto, sejam compatíveis com mecanismos externos.

Para permitir a inserção de valores binários de tamanho arbitrário na coluna afetada, até um comprimento máximo, siga estas instruções:

  • Se a sua tabela for acessada por mecanismos externos, como o Spark, você deverá recriá-la usando o tipo de coluna BINARY.

    Para recriar a tabela usando o tipo de coluna BINARY, siga estas etapas:

    1. Para criar e preencher uma nova tabela com base na tabela com as colunas afetadas, execute o comando CREATE ICEBERG TABLE … AS SELECT (também conhecido como CTAS) e especifique binário como o tipo de dados para as colunas afetadas.

      O exemplo a seguir mostra uma instrução CTAS em que o tipo de dados para a coluna b na nova tabela é especificado como binário:

      CREATE ICEBERG TABLE my_table (..., b binary) AS SELECT * FROM my_old_table
      Copy

    2. Use o comando DROP ICEBERG TABLE para remover a tabela com as colunas afetadas.

  • Como alternativa, você pode evoluir o esquema da tabela executando o comando ALTER ICEBERG TABLE para definir o tipo de dados da coluna como BINARY.

    Importante

    Antes de executar uma instrução ALTER ICEBERG TABLE para alterar o tipo de dados de uma coluna para BINARY, você deve primeiro entrar em contato com o suporte Snowflake para habilitar essa funcionalidade para sua conta.

    Por exemplo, a seguinte instrução evolui o esquema da tabela t alterando o tipo de dados da coluna c para BINARY:

    ALTER ICEBERG TABLE t ALTER COLUMN c SET DATA TYPE BINARY;
    Copy

    Essa abordagem é uma solução temporária e com suporte para clientes afetados durante o período BCR. A vantagem dessa abordagem é que você só precisa atualizar o esquema da tabela em vez de recriar a tabela inteira.

    Importante

    Essa abordagem não é uma promoção de tipo válida do Iceberg; portanto, mecanismos externos podem detectar uma promoção de tipo inválida e não conseguir atualizar a tabela. Portanto, você deve usar essa abordagem somente com tabelas Iceberg gerenciadas pelo Snowflake que não são lidas ou gravadas por mecanismos externos.

Permitir a inserção de valores binários de comprimento fixo exatamente igual a L na coluna afetada

Para permitir a inserção de valores binários de comprimento fixo exatamente igual a L na coluna afetada, certifique-se de que o tamanho do valor inserido corresponda ao tamanho desejado, ajustando seu fluxo de trabalho, usando truncamento ou preenchimento, por exemplo. Recomendamos também que você recrie a tabela Iceberg com o tipo de coluna fixed(L) Iceberg para garantir que o tamanho de qualquer valor inserido anteriormente na tabela corresponda exatamente ao comprimento definido L.

Ref: 2246