É comum, em tabelas que contêm uma coluna de array, gerar uma nova tabela com uma linha para cada elemento individual do array dessa coluna inicial, enquanto os valores das outras colunas são duplicados. Esse é o caso básico do que a cláusula ARRAY JOIN faz.
Seu nome vem do fato de que ela pode ser vista como a execução de um JOIN com um array ou uma estrutura de dados aninhada. A ideia é semelhante à da função arrayJoin, mas a funcionalidade da cláusula é mais ampla.
Sintaxe:
Os tipos compatíveis de ARRAY JOIN estão listados abaixo:
ARRAY JOIN - No caso básico, arrays vazios não são incluídos no resultado do JOIN.LEFT ARRAY JOIN - O resultado do JOIN contém linhas com arrays vazios. O valor de um array vazio é definido como o valor padrão do tipo de elemento do array (geralmente 0, string vazia ou NULL).
Exemplos básicos de ARRAY JOIN
ARRAY JOIN e LEFT ARRAY JOIN
ARRAY JOIN e LEFT ARRAY JOIN. Vamos criar uma tabela com uma coluna do tipo Array e inserir valores nela:
O exemplo abaixo usa a cláusula ARRAY JOIN:
O próximo exemplo usa a cláusula LEFT ARRAY JOIN:
ARRAY JOIN e a função arrayEnumerate
ARRAY JOIN. Ela permite contar algo apenas uma vez para cada array depois de aplicar ARRAY JOIN. Exemplo:
Neste exemplo, Reaches é o número de conversões (as cadeias de caracteres recebidas após aplicar ARRAY JOIN), e Hits é o número de visualizações de página (cadeias de caracteres antes de ARRAY JOIN). Neste caso específico, você pode obter o mesmo resultado de forma mais simples:
ARRAY JOIN e arrayEnumerateUniq
ARRAY JOIN e agregar elementos de um array.
Neste exemplo, para cada ID de meta, há um cálculo do número de conversões (cada elemento na estrutura de dados aninhada Goals é uma meta que foi atingida, à qual nos referimos como uma conversão) e do número de sessões. Sem ARRAY JOIN, teríamos contado o número de sessões como sum(Sign). Mas, neste caso específico, as linhas foram multiplicadas pela estrutura aninhada Goals, então, para contar cada sessão apenas uma vez depois disso, aplicamos uma condição ao valor da função arrayEnumerateUniq(Goals.ID).
É possível especificar um alias para um array na cláusula ARRAY JOIN. Nesse caso, um item do array pode ser acessado por esse alias, mas o próprio array é acessado pelo nome original. Exemplo:
Com aliases, você pode executar ARRAY JOIN com um Array externo. Por exemplo:
Vários arrays podem ser separados por vírgulas na cláusula ARRAY JOIN. Nesse caso, o JOIN é realizado com eles simultaneamente (a soma direta, e não o produto cartesiano). Observe que, por padrão, todos os arrays devem ter o mesmo tamanho. Exemplo:
O exemplo abaixo usa a função arrayEnumerate:
Vários arrays com tamanhos diferentes podem ser unidos usando: SETTINGS enable_unaligned_array_join = 1. Exemplo:
ARRAY JOIN também funciona com estruturas de dados aninhadas:
Ao especificar nomes de estruturas de dados aninhadas em ARRAY JOIN, o significado é o mesmo de ARRAY JOIN com todos os elementos do array que a compõem. Os exemplos estão listados abaixo:
Essa variação também faz sentido:
Um alias pode ser usado em uma estrutura de dados aninhada para selecionar o resultado do JOIN ou o array de origem. Exemplo:
Exemplo de uso da função arrayEnumerate:
Detalhes de implementação
ARRAY JOIN. Embora ARRAY JOIN sempre deva ser especificado antes da cláusula WHERE/PREWHERE em uma consulta, tecnicamente essas operações podem ser executadas em qualquer ordem, a menos que o resultado de ARRAY JOIN seja usado para filtrar. A ordem de processamento é controlada pelo otimizador de consultas.
Avaliação de funções em curto-circuito é um recurso que otimiza a execução de expressões complexas em funções específicas, como if, multiIf, and e or. Ele evita que possíveis exceções, como divisão por zero, ocorram durante a execução dessas funções.
arrayJoin é sempre executada e não oferece suporte à avaliação de funções em curto-circuito. Isso ocorre porque ela é uma função especial, processada separadamente de todas as outras durante a análise e a execução da consulta, e exige uma lógica adicional que não funciona com a execução em curto-circuito. O motivo é que o número de linhas no resultado depende do resultado de arrayJoin, e implementar a execução preguiçosa de arrayJoin é complexo e custoso demais.
Última modificação em 2 de julho de 2026
