STRING_AGG (Transact-SQL)

Aplica-se a: SQL Server 2017 (14.x) e posterior Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics Ponto de extremidade de análise de SQL no Microsoft Fabric Warehouse no Microsoft Fabric

Concatena os valores das expressões de cadeia de caracteres e coloca os valores de separador entre eles. O separador não é adicionado ao final da cadeia de caracteres.

Convenções de sintaxe de Transact-SQL

Sintaxe

STRING_AGG ( expression, separator ) [ <order_clause> ]

<order_clause> ::=   
    WITHIN GROUP ( ORDER BY <order_by_expression_list> [ ASC | DESC ] )   

Argumentos

expressão
É uma expressão de qualquer tipo. As expressões são convertidas em tipos NVARCHAR ou VARCHAR durante a concatenação. Tipos que não são uma cadeia de caracteres são convertidos no tipo NVARCHAR.

separator
É uma expression do tipo NVARCHAR ou VARCHAR que é usada como separador de cadeias de caracteres concatenadas. Pode ser um literal ou uma variável.

<order_clause>
Opcionalmente, especifique a ordem dos resultados concatenados usando a cláusula WITHIN GROUP:

WITHIN GROUP ( ORDER BY <order_by_expression_list> [ ASC | DESC ] )

<order_by_expression_list>

Uma lista de expressions de não constante que pode ser usada para classificar os resultados. Apenas uma order_by_expression é permitida por consulta. A ordem de classificação padrão é crescente.

Tipos de retorno

O tipo de retorno depende do primeiro argumento (expressão). Se o argumento de entrada for um tipo de cadeia de caracteres (NVARCHAR, VARCHAR), o tipo de resultado será o mesmo do tipo de entrada. A seguinte tabela lista as conversões automáticas:

Comentários

STRING_AGG é uma função de agregação que usa todas as expressões de linhas e concatena-as em uma única cadeia de caracteres. Os valores de expressão são convertidos implicitamente em tipos de cadeia de caracteres e depois concatenados. A conversão implícita em cadeias de caracteres segue as regras existentes para conversões de tipo de dados. Para obter mais informações sobre conversões de tipo de dados, consulte CAST e CONVERT (Transact-SQL).

Se a expressão de entrada for um tipo VARCHAR, o separador não poderá ser um tipo NVARCHAR.

Valores nulos são ignorados e o separador correspondente não é adicionado. Para retornar um espaço reservado para valores nulos, use a função ISNULL, conforme demonstrado no exemplo B.

STRING_AGG está disponível em qualquer nível de compatibilidade.

Exemplos

A maioria dos exemplos neste artigo faz referência aos bancos de dados de exemplo do AdventureWorks.

a. Gerar a lista de nomes separados em novas linhas

O exemplo a seguir gera uma lista de nomes em uma única célula de resultados, separados com retornos de carro.

USE AdventureWorks2022;
GO
SELECT STRING_AGG (CONVERT(NVARCHAR(max),FirstName), CHAR(13)) AS csv 
FROM Person.Person;
GO

Veja a seguir o conjunto de resultados.

Os valores NULL encontrados nas células name não são retornados no resultado.

B. Gerar uma lista de nomes separados por vírgula sem valores NULL

O exemplo a seguir substitui valores nulos por 'N/A' e retorna os nomes separados por vírgulas em uma única célula de resultados.

USE AdventureWorks2022;
GO
SELECT STRING_AGG(CONVERT(NVARCHAR(max), ISNULL(FirstName,'N/A')), ',') AS csv 
FROM Person.Person;
GO

Veja a seguir o conjunto de resultados.

C. Gerar valores separados por vírgula

USE AdventureWorks2022;
GO
SELECT STRING_AGG(CONVERT(NVARCHAR(max), CONCAT(FirstName, ' ', LastName, '(', ModifiedDate, ')')), CHAR(13)) AS names 
FROM Person.Person;
GO

Veja a seguir o conjunto de resultados.

D. Retornar artigos de notícias com marcas relacionadas

Imagine um banco de dados em que artigos e suas marcas sejam separados em tabelas diferentes. Um desenvolvedor deseja retornar uma linha por artigo com todas as marcas associadas. A seguinte consulta atinge este resultado:

SELECT a.articleId, title, STRING_AGG (tag, ',') as tags
FROM dbo.Article AS a
LEFT JOIN dbo.ArticleTag AS t
    ON a.ArticleId = t.ArticleId
GROUP BY a.articleId, title;
GO

Veja a seguir o conjunto de resultados.

E. Gerar uma lista de emails por cidades

A seguinte consulta localiza os endereços de email de funcionários e agrupa-os por cidade:

USE AdventureWorks2022;
GO

SELECT TOP 10 City, STRING_AGG(CONVERT(NVARCHAR(max), EmailAddress), ';') AS emails 
FROM Person.BusinessEntityAddress AS BEA  
INNER JOIN Person.Address AS A ON BEA.AddressID = A.AddressID
INNER JOIN Person.EmailAddress AS EA ON BEA.BusinessEntityID = EA.BusinessEntityID 
GROUP BY City;
GO

Veja a seguir o conjunto de resultados.

Os emails retornados na coluna de emails podem ser usados diretamente para enviar emails ao grupo de pessoas que trabalham em algumas cidades específicas.

F. Gerar uma lista classificada de emails por cidades

Semelhante ao exemplo anterior, a seguinte consulta localiza os endereços de email de funcionários, os agrupa por cidade e classifica os emails em ordem alfabética:

USE AdventureWorks2022;
GO

SELECT TOP 10 City, STRING_AGG(CONVERT(NVARCHAR(max), EmailAddress), ';') WITHIN GROUP (ORDER BY EmailAddress ASC) AS Emails 
FROM Person.BusinessEntityAddress AS BEA  
INNER JOIN Person.Address AS A ON BEA.AddressID = A.AddressID
INNER JOIN Person.EmailAddress AS EA ON BEA.BusinessEntityID = EA.BusinessEntityID 
GROUP BY City;
GO

Veja a seguir o conjunto de resultados.

Próximas etapas

Saiba mais sobre as funções Transact-SQL nos seguintes artigos:

• STRING_ESCAPE (Transact-SQL)
• STUFF (Transact-SQL)
• CONCAT (Transact-SQL)
• CONCAT_WS (Transact-SQL)
• Funções de agregação (Transact-SQL)
• Funções de cadeia de caracteres (Transact-SQL)