Compartilhar via

JSON_ARRAYAGG (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x) Banco de Dados SQL do AzureBanco de DadosSQL do Azure Banco de Dados SQL banco de dados SQL do Banco de Dados SQL do Azurebanco de dados SQL no 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 SELECT instrução com GROUP BY GROUPING SETS cláusula.

Observação

Para criar um objeto JSON de uma agregação, use JSON_OBJECTAGG.

Ambas as funções de agregação JSON_OBJECTAGG e JSON_ARRAYAGG são:

  • geralmente disponível para o Banco de Dados SQL do Azure, a Instância Gerenciada de SQL do Azure (com a política de atualização always-up-to-date do SQL 2025 ou do SQL Server**), o banco de dados SQL no Microsoft Fabric e o Fabric Data Warehouse.

  • em prévia para SQL Server 2025 (17.x).

Convenções de sintaxe de Transact-SQL

Syntax

JSON_ARRAYAGG (value_expression [ order_by_clause ] [ json_null_clause ] [ RETURNING json ] )

json_null_clause ::=  NULL ON NULL | ABSENT ON NULL

order_by_clause ::= ORDER BY <column_list>

Arguments

value_expression

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

json_null_clause

Optional. json_null_clause pode ser usado para controlar o comportamento da JSON_ARRAYAGG função 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

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

Valor de retorno

Retorna uma cadeia de caracteres de matriz JSON válida do tipo nvarchar(max ). Se a opção RETURNING json estiver incluída, a matriz JSON será retornada como tipo json .

Examples

Exemplo 1

O exemplo a seguir retorna uma matriz JSON vazia.

SELECT JSON_ARRAYAGG(NULL);

Result

[]

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);

Result

["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);

Result

["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;

Result

object_id 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"]
8 ["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), ());

Result

id tipo total_amount json_total_name_amount
1 a 2 [2]
NULL a 2 [2]
1 b 7 [4,3]
NULL b 7 [4,3]
2 d 16 [9,7]
NULL d 16 [9,7]
NULL NULL 25 [2,4,3,9,7]
1 NULL 9 [3,4,2]
2 NULL 16 [9,7]

Exemplo 6

O exemplo a seguir retorna uma matriz JSON como tipo json .

SELECT JSON_ARRAYAGG(1 RETURNING JSON);

Result

[1]

Conteúdo relacionado

  • Last updated on