Compartilhar via

JSON_ARRAYAGG (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x) Versão prévia do Banco de Dados SQL do Azurebanco de dadosSQL do Banco de Dados SQL do Azure banco de dados SQL gerenciadono Microsoft Fabric

Constrói uma matriz JSON de uma agregação de colunas ou dados SQL. JSON_ARRAYAGG também pode ser usado em uma instrução SELECT com a cláusula GROUP BY GROUPING SETS.

Para criar um objeto JSON de um agregado, use JSON_OBJECTAGG.

Observação

Ambas as funções de agregação JSON_OBJECTAGG e JSON_ARRAYAGG geralmente estão disponíveis para o Banco de Dados SQL do Azure, a Instância Gerenciada de SQL do Azure (configurada com a política de atualização always-up-to-date) e o Microsoft Fabric Data Warehouse.

Convenções de sintaxe de Transact-SQL

Sintaxe

JSON_ARRAYAGG (value_expression [ order_by_clause ] [ json_null_clause ] )

json_null_clause ::=  NULL ON NULL | ABSENT ON NULL

order_by_clause ::= ORDER BY <column_list>

Argumentos

value_expression

A expressão de valor pode ser uma coluna ou uma expressão em uma consulta ou constantes/literais.

json_null_clause

Opcional. json_null_clause pode ser usado para controlar o comportamento da função JSON_ARRAYAGG quando value_expression é NULL. A opção NULL ON NULL converte o valor SQL NULL em um valor nulo JSON ao gerar o valor do elemento na matriz JSON. A opção ABSENT ON NULL omite o elemento na matriz JSON se o valor é NULL. Se omitido, ABSENT ON NULL é o padrão.

order_by_clause

Opcional. A ordem dos elementos na matriz JSON resultante pode ser especificada para ordenar as linhas de entrada da agregação.

Exemplos

Exemplo 1

O exemplo a seguir retorna uma matriz JSON vazia.

SELECT JSON_ARRAYAGG(NULL);

Resultado

[]

Exemplo 2

O exemplo a seguir cria uma matriz JSON com três elementos de um conjunto de resultados.

SELECT JSON_ARRAYAGG(c1)
FROM (VALUES ('c'), ('b'), ('a')) AS t(c1);

Resultado

["c","b","a"]

Exemplo 3

O exemplo a seguir cria uma matriz JSON com três elementos ordenados pelo valor da coluna.

SELECT JSON_ARRAYAGG( c1 ORDER BY c1)
FROM (
    VALUES ('c'), ('b'), ('a')
) AS t(c1);

Resultado

["a","b","c"]

Exemplo 4

O exemplo a seguir retorna um resultado com duas colunas. A primeira coluna contém o valor object_id. A segunda coluna contém uma matriz JSON com os nomes das colunas. As colunas na matriz JSON são ordenadas com base no valor column_id.

SELECT TOP(5) c.object_id, JSON_ARRAYAGG(c.name ORDER BY c.column_id) AS column_list
FROM sys.columns AS c
GROUP BY c.object_id;

Resultado

id_objeto column_list
3 ["rsid","rscolid","hbcolid","rcmodified","ti","cid","ordkey","maxinrowlen","status","offset","nullbit","bitpos","colguid","ordlock"]
5 ["rowsetid","ownertype","idmajor","idminor","numpart","status","fgidfs","rcrows","cmprlevel","fillfact","maxnullbit","maxleaf","maxint","minleaf","minint","rsguid","lockres","scope_id"]
6 ["id","subid","partid","version","segid","cloneid","rowsetid","dbfragid","status"]
7 ["auid","type","ownerid","status","fgid","pgfirst","pgroot","pgfirstiam","pcused","pcdata","pcreserved"]
oito ["status","fileid","name","filename"]

Exemplo 5

O exemplo a seguir retorna um resultado com quatro colunas de uma instrução SELECT contendo agregações SUM e JSON_ARRAYAGG com GROUP BY GROUPING SETS. As duas primeiras colunas retornam o valor e id a type coluna. A terceira coluna total_amount retorna o valor da agregação SUM na amount coluna. A quarta coluna json_total_amount retorna o valor de JSON_ARRAYAGG agregação na amount coluna.

WITH T
AS (SELECT *
    FROM (VALUES (1, 'k1', 'a', 2), (1, 'k2', 'b', 3), (1, 'k3', 'b', 4), (2, 'j1', 'd', 7), (2, 'j2', 'd', 9)) AS b(id, name, type, amount))
SELECT id,
       type,
       SUM(amount) AS total_amount,
       JSON_ARRAYAGG(amount) AS json_total_amount
FROM T
GROUP BY GROUPING SETS((id), (type), (id, type), ());

Resultado

id tipo total_amount json_total_name_amount
1 um 2 [2]
NULL um 2 [2]
1 b 7 [4,3]
NULL b 7 [4,3]
2 d 16 [9,7]
NULL d 16 [9,7]
NULL NULL vinte e cinco [2,4,3,9,7]
1 NULL 9 [3,4,2]
2 NULL 16 [9,7]

Conteúdo relacionado