Compartir a través de

JSON_ARRAYAGG (Transact-SQL)

Se aplica a: SQL Server 2025 (17.x) Base de datos SQL de Azure SQL Database deAzure SQL Managed Instanceen Microsoft Fabric

Construye una matriz JSON a partir de una agregación de datos o columnas SQL. JSON_ARRAYAGGtambién se puede usar en una instrucción con SELECT cláusula GROUP BY GROUPING SETS .

Nota:

Para crear un objeto JSON a partir de un agregado, use JSON_OBJECTAGG.

Tanto las funciones JSON_OBJECTAGG de agregado JSON_ARRAYAGG como las siguientes:

  • disponible con carácter general para Azure SQL Database, Azure SQL Managed Instance (con SQL Server 2025 o Always-up-to-dateupdate policy**), SQL Database en Microsoft Fabric y Fabric Data Warehouse.

  • en vista previa para SQL Server 2025 (17.x).

Convenciones de sintaxis 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

La expresión de valor puede ser una columna o expresión en una consulta o constantes o literales.

json_null_clause

Optional. json_null_clause se puede usar para controlar el comportamiento de la JSON_ARRAYAGG función cuando value_expression es NULL. La opción NULL ON NULL convierte el valor NULL de SQL en un valor NULL de JSON al generar el valor del elemento en la matriz JSON. La opción ABSENT ON NULL omitirá el elemento de la matriz JSON si el valor es NULL. Si se omite, ABSENT ON NULL es el valor predeterminado.

order_by_clause

Optional. El orden de los elementos de la matriz JSON resultante se puede especificar para ordenar las filas de entrada al agregado.

Valor devuelto

Devuelve una cadena de matriz JSON válida de tipo nvarchar(max). Si se incluye la RETURNING json opción, la matriz JSON se devuelve como tipo json .

Examples

Ejemplo 1

En el siguiente ejemplo se devuelve una matriz JSON vacía.

SELECT JSON_ARRAYAGG(NULL);

Result

[]

Ejemplo 2

En el siguiente ejemplo se construye una matriz JSON con tres elementos de un conjunto de resultados.

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

Result

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

Ejemplo 3

En el ejemplo siguiente se construye una matriz JSON con tres elementos ordenados por el valor de la columna.

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

Result

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

Ejemplo 4

En el ejemplo siguiente se devuelve un conjunto de resultados con dos columnas. La primera columna contiene el valor object_id. La segunda columna contiene una matriz JSON que contiene los nombres de las columnas. Las columnas de la matriz JSON se ordenan en función del 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"]

Ejemplo 5

En el ejemplo siguiente se devuelve un resultado con cuatro columnas de una instrucción SELECT que contiene SUM y JSON_ARRAYAGG agregados con GROUP BY GROUPING SETS. Las dos primeras columnas devuelven el valor de id columna y type . La tercera columna total_amount devuelve el valor de sum agregado en la amount columna. La cuarta columna json_total_amount devuelve el valor de JSON_ARRAYAGG agregado en la amount columna.

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 type 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]

Ejemplo 6

En el ejemplo siguiente se devuelve una matriz JSON como tipo json .

SELECT JSON_ARRAYAGG(1 RETURNING JSON);

Result

[1]

Contenido relacionado

  • Last updated on