Agregação JSON e cadeia de caracteres

Concluído

O SQL Server 2025 apresenta novas funções de agregação para a criação de matrizes JSON, objetos JSON e cadeias de caracteres delimitadas. Essas adições facilitam a geração de saída estruturada, como respostas de API, relatórios ou exportações de log diretamente de consultas T-SQL. As novas funções permitem mover a formatação de dados para a camada de banco de dados, reduzindo a necessidade de uma transformação complexa do lado do cliente.

Visão geral das funções de agregação JSON e string

Vamos examinar as três novas funções de agregação:

JSON_ARRAYAGG

Cria uma matriz JSON com base nos valores de uma expressão. O valor de cada linha torna-se um elemento na matriz JSON resultante. Ele simplifica a geração de matrizes de valores, como listas de IDs ou nomes.

JSON_OBJECTAGG

Cria um objeto JSON com base em pares chave-valor. O primeiro argumento define a chave e o segundo define o valor. Esse emparelhamento de valor facilita a criação de documentos JSON diretamente com base nos resultados da consulta.

STRING_CONCAT_WS

Concatena cadeias de caracteres com um separador especificado ao ignorar valores NULL. O nome da função significa String CONCAT com Separador. Ele fornece uma maneira eficiente de unir valores como nomes, marcas ou listas delimitadas por vírgulas.

Operador de concatenação de cadeia de caracteres ||

O SQL Server 2025 apresenta o operador padrão ANSI || como uma alternativa a + para a concatenação de cadeias de caracteres. Ele fornece uma sintaxe mais portátil e geralmente é preferencial ao combinar várias colunas em uma única saída de texto.

Função UNISTR

UNISTR() retorna uma cadeia de caracteres Unicode com base em sequências de escape, permitindo que você insira caracteres por ponto de código ou notação de escape. É útil ao criar scripts que incluem caracteres não imprimíveis ou multilíngues.

Exemplo 1: Criar matrizes JSON e objetos com base nos resultados da consulta

Imagine que seu banco de dados armazena dados de pedido do cliente em duas tabelas Sales.Customer e Sales.SalesOrderHeader. A equipe de análise precisa de um relatório JSON resumindo cada cliente e suas IDs de pedido para integração com um painel da Web.

Consulta: Usar JSON_ARRAYAGG e JSON_OBJECTAGG

A consulta a seguir recupera cada cliente juntamente com uma matriz JSON de suas IDs de pedido, encapsuladas em um objeto JSON.

SELECT
    C.CustomerID,
    C.FirstName + ' ' + C.LastName AS CustomerName,
    JSON_OBJECTAGG(
        'Customer' : C.CustomerID,
        'Orders'   : JSON_ARRAYAGG(SOH.SalesOrderID)
    ) AS CustomerSummary
FROM Sales.Customer AS C
JOIN Sales.SalesOrderHeader AS SOH
    ON C.CustomerID = SOH.CustomerID
GROUP BY C.CustomerID, C.FirstName, C.LastName;

Resultados

ID do Cliente	Nome do Cliente	Resumo do Cliente
11001	Jordan Patterson	{"Cliente":11001,"Pedidos":[43722,43723,43724]}
11002	Alicia Tran	{"Cliente":11002,"Orders":[43725,43726]}
11003	Marco Diaz	{"Customer":11003,"Orders":[43727]}

Neste exemplo, JSON_ARRAYAGG coleta todas as IDs de pedido para cada cliente em uma matriz JSON e JSON_OBJECTAGG encapsula o resultado em um objeto JSON com pares chave-valor claros. Toda a estrutura é produzida em uma consulta T-SQL.

Exemplo 2: formatar saída de texto usando STRING_CONCAT_WS

A equipe de marketing precisa de uma lista dos nomes de produtos comprados de cada cliente separados por vírgulas para uma campanha de email. A STRING_CONCAT_WS função pode gerar esses resultados de forma limpa, omitindo todos os valores NULL.

Consulta: unir nomes de produtos usando um separador

A consulta a seguir recupera cada cliente juntamente com uma lista separada por vírgulas de produtos que eles compraram.

SELECT
    C.CustomerID,
    C.FirstName + ' ' + C.LastName AS CustomerName,
    STRING_CONCAT_WS(', ',
        P.Name
    ) AS ProductsPurchased
FROM Sales.Customer AS C
JOIN Sales.SalesOrderHeader AS SOH
    ON C.CustomerID = SOH.CustomerID
JOIN Sales.SalesOrderDetail AS SOD
    ON SOH.SalesOrderID = SOD.SalesOrderID
JOIN Production.Product AS P
    ON SOD.ProductID = P.ProductID
GROUP BY C.CustomerID, C.FirstName, C.LastName;

Resultados

ID do Cliente	Nome do Cliente	ProdutosComprados
11001	Jordan Patterson	Touring-2000 Blue, 50, Mountain-100 Black, 44
11002	Alicia Tran	Estrada-250 Amarelo, 44, Montanha-200 Vermelho, 48
11003	Marco Diaz	Touring-3000 Blue, 62

Aqui, STRING_CONCAT_WS une nomes de produtos com vírgulas e ignora entradas NULAS automaticamente, evitando COALESCE manual ou lógica ISNULL.

Exemplo 3: combinar json e texto delimitado para saída de API

Você também pode usar essas funções em conjunto para preparar dados estruturados para uma resposta à API. A consulta a seguir cria uma matriz JSON de objetos em que cada objeto contém o nome do cliente e a lista de produtos delimitados por vírgula.

SELECT
    JSON_ARRAYAGG(
        JSON_OBJECTAGG(
            'Customer' : C.FirstName + ' ' + C.LastName,
            'Products' : STRING_CONCAT_WS(', ', P.Name)
        )
    ) AS ApiOutput
FROM Sales.Customer AS C
JOIN Sales.SalesOrderHeader AS SOH
    ON C.CustomerID = SOH.CustomerID
JOIN Sales.SalesOrderDetail AS SOD
    ON SOH.SalesOrderID = SOD.SalesOrderID
JOIN Production.Product AS P
    ON SOD.ProductID = P.ProductID
GROUP BY C.CustomerID, C.FirstName, C.LastName;

Exemplo de resultado

[
  {"Customer":"Jordan Patterson","Products":"Touring-2000 Blue, 50, Mountain-100 Black, 44"},
  {"Customer":"Alicia Tran","Products":"Road-250 Yellow, 44, Mountain-200 Red, 48"},
  {"Customer":"Marco Diaz","Products":"Touring-3000 Blue, 62"}
]

Um aplicativo consome diretamente essa estrutura ou a exporta como um documento JSON por meio de ferramentas como o SSMS (SQL Server Management Studio) ou o Azure Data Studio.

Resumo

O SQL Server 2025 adiciona JSON_ARRAYAGG, JSON_OBJECTAGG e STRING_CONCAT_WS para simplificar a criação de texto estruturado e a saída JSON no T-SQL. Essas funções permitem que você gere dados prontos para uso em aplicativos a partir de consulta sem código externo. Se você estiver preparando cargas JSON, construindo relatórios ou formatando respostas de API, esses recursos de agregação tornam o SQL Server 2025 uma plataforma mais versátil para aplicativos de dados modernos.