Skip to main content
Uma estrutura de dados aninhada é como uma tabela dentro de uma célula. Os parâmetros de uma estrutura de dados aninhada — os nomes e tipos das colunas — são especificados da mesma forma que em uma consulta CREATE TABLE. Cada linha da tabela pode corresponder a qualquer quantidade de linhas em uma estrutura de dados aninhada.
Evite usar pontos em nomes de colunasNomes de colunas que contêm pontos, colunas que compartilham o mesmo prefixo com ponto e colunas do tipo Array podem ser interpretados como parte de uma estrutura Nested achatada quando flatten_nested = 1 (o padrão). Isso pode causar validação inesperada do tamanho dos arrays durante inserts e restrições de renomeação.Evite usar pontos em nomes de colunas, se possível. Use sublinhados (_) ou outro separador em vez de pontos nos nomes das colunas, a menos que você realmente precise da semântica de Nested.
Exemplo:
A instrução DDL CREATE TABLE acima declara a estrutura de dados aninhada Goals, que contém dados sobre conversões, ou metas alcançadas. Cada linha na tabela ‘visits’ corresponde a zero ou mais conversões. Quando a configuração flatten_nested é definida como 0 (flatten_nested=1 por padrão), níveis arbitrários de aninhamento são suportados. Na maioria dos casos, ao trabalhar com uma estrutura de dados aninhada, suas colunas são especificadas com nomes de colunas separados por ponto. Essas colunas formam um array de tipos correspondentes. Todos os arrays de colunas de uma mesma estrutura de dados aninhada têm o mesmo comprimento. Por exemplo:
É mais fácil pensar em uma estrutura de dados aninhada como um conjunto de vários arrays de colunas com o mesmo comprimento.

​
Filtrando colunas Nested em WHERE

Como cada coluna de uma estrutura Nested é armazenada como um Array, referenciá-la em uma cláusula WHERE retorna o array inteiro para cada linha, e não um elemento individual. Não é possível comparar diretamente uma coluna aninhada com um valor escalar, portanto você deve usar funções de array. Por exemplo, esta consulta não simplesmente retorna zero linhas — ela gera uma exceção, porque Goals.ID tem o tipo Array(UInt32) e equals(Array(UInt32), UInt32) não é uma comparação válida:
Use has para verificar se um array contém determinado valor:
Use arrayExists quando a condição for mais complexa:
Você pode filtrar pelo tamanho do array com length ou excluir arrays vazios com notEmpty:
Para filtrar elementos individuais de uma estrutura aninhada, em vez de linhas inteiras, use ARRAY JOIN para expandir os arrays primeiro. Após ARRAY JOIN, cada elemento se torna uma linha separada, então a cláusula WHERE se aplica a valores escalares. Para mais informações, consulte a cláusula ARRAY JOIN. Exemplo:
Você não pode executar SELECT em uma estrutura de dados aninhada inteira. Só é possível listar explicitamente as colunas individuais que fazem parte dela.

​
Inserção de dados

Para uma consulta INSERT, você deve passar separadamente todos os arrays das colunas componentes de uma estrutura de dados aninhada (como se fossem arrays de colunas individuais). Durante a inserção, o sistema verifica se eles têm o mesmo tamanho. Cada subcoluna aninhada é listada na lista de colunas usando notação de ponto (Goals.ID, Goals.Serial, …), e os valores correspondentes são arrays:
Todos os arrays de subcolunas aninhadas em uma mesma linha devem ter o mesmo comprimento. Comprimentos diferentes geram um erro:
Para uma consulta DESCRIBE, as colunas em uma estrutura de dados aninhada são listadas separadamente da mesma forma.

​
Limitações do ALTER

As consultas ALTER em estruturas de dados aninhadas têm as seguintes limitações: Adicionar subcolunas funciona normalmente. Você pode adicionar uma nova subcoluna a uma estrutura Nested existente:
A remoção de subcolunas funciona com subcolunas individuais:
Modificar o tipo de uma subcoluna funciona e dispara uma mutação (reescrita de dados):
Renomeação tem restrições. Você pode renomear uma subcoluna dentro da mesma estrutura aninhada:
No entanto, você não pode:
  • Renomear a estrutura aninhada como um todo (por exemplo, Goals para Conversions).
  • Mover uma subcoluna para uma estrutura aninhada diferente (por exemplo, Goals.ID para OtherNested.ID).
  • Mover uma subcoluna para fora de uma estrutura aninhada ou para dentro dela (por exemplo, Goals.ID para GoalID ou vice-versa).
Última modificação em 14 de agosto de 2026