Partilhar via

JSON_ARRAYAGG (Transact-SQL)

Aplica-se a: SQL Server 2025 (17.x) Azure SQL Database AzureSQL Managed InstanceSQL database in Microsoft Fabric

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

Observação

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

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

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

  • em pré-visualização para SQL Server 2025 (17.x).

Transact-SQL convenções de sintaxe

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 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 NULL SQL 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 for NULL. Se omitido, ABSENT ON NULL é padrão.

order_by_clause

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

Valor de retorno

Retorna uma cadeia de caracteres de matriz JSON válida do tipo nvarchar(max ). Se a RETURNING json opção 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 constrói 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 constrói 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 contendo 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 SOMA e JSON_ARRAYAGG agregações com GROUP BY GROUPING SETS. As duas primeiras colunas retornam o valor da coluna e id .type A terceira coluna total_amount retorna o valor da soma SOMA na amount coluna. A quarta coluna json_total_amount retorna o valor de JSON_ARRAYAGG agregado 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 json type.

SELECT JSON_ARRAYAGG(1 RETURNING JSON);

Result

[1]

Conteúdo relacionado

  • Last updated on