Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Aplica-se a:
SQL Server 2017 (14.x) e versões posteriores Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSQL analytics endpoint in Microsoft FabricWarehouse em Microsoft FabricSQL database in Microsoft Fabric
Concatena os valores de expressões de cadeia de caracteres e coloca valores separadores entre elas. O separador não é adicionado no final da cadeia de caracteres.
Transact-SQL convenções de sintaxe
Syntax
STRING_AGG ( expression , separator ) [ <order_clause> ]
<order_clause> ::=
WITHIN GROUP ( ORDER BY <order_by_expression_list> [ ASC | DESC ] )
Arguments
expression
Uma expressão de qualquer tipo. As expressões são convertidas em tipos nvarchar ou varchar durante a concatenação. Os tipos não-string são convertidos para o tipo nvarchar .
separator
Uma expressão do tipo nvarchar ou varchar que é usada como separador para cadeias de caracteres concatenadas. Pode ser literal ou variável.
<order_clause>
Opcionalmente, especifique a ordem dos resultados concatenados usando WITHIN GROUP cláusula:
WITHIN GROUP ( ORDER BY <order_by_expression_list> [ ASC | DESC ] )
<order_by_expression_list>Uma lista de expressões não constantes que podem ser usadas para classificar resultados. Só é permitida uma
<order_by_expression_list>por consulta. A ordem de classificação padrão é crescente.
Tipos de devolução
O tipo de retorno depende do primeiro argumento (expressão). Se o argumento de entrada for do tipo string (nvarchar, varchar), o tipo de resultado será o mesmo que o tipo de entrada. A tabela a seguir lista as conversões automáticas:
| Tipo de expressão de entrada | Result |
|---|---|
| nvarchar(max) | nvarchar(max) |
| varchar(max) | varchar(max) |
| nvarchar(1..4000) | nvarchar(4000) |
| varchar(1..8000) | varchar(8000) |
|
int, bigint, smallint, tinyint, numérico, float, real, bit, decimal, smallmoney, dinheiro, datetime, datetime2 |
nvarchar(4000) |
Remarks
STRING_AGG é uma função agregada que pega todas as expressões de linhas e as concatena em uma única cadeia de caracteres. Os valores de expressão são implicitamente convertidos em tipos de cadeia de caracteres e, em seguida, 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.
Se a expressão de entrada for type varchar, o separador não poderá ser type nvarchar.
Os valores nulos são ignorados e o separador correspondente não é adicionado. Para retornar um espaço reservado para valores nulos, use a ISNULL função como demonstrado no exemplo B.
STRING_AGG está disponível em qualquer nível de compatibilidade.
Note
<order_clause> está disponível com nível de compatibilidade de banco de dados 110 e superior.
Examples
Os exemplos de código neste artigo usam o banco de dados de exemplo AdventureWorks2025 ou AdventureWorksDW2025, que pode ser descarregado da página inicial de Exemplos e Projetos da Comunidade do Microsoft SQL Server.
A. Gerar lista de nomes separados em novas linhas
O exemplo a seguir produz uma lista de nomes em uma única célula de resultado, separados por retornos de carro.
USE AdventureWorks2022;
GO
SELECT STRING_AGG(CONVERT (NVARCHAR (MAX), FirstName), CHAR(13)) AS csv
FROM Person.Person;
GO
Aqui está o conjunto de resultados.
csv
-----------
Syed
Catherine
Kim
Kim
Kim
Hazem
...
NULL valores encontrados em name células não são retornados no resultado.
Note
Se você usar o Editor de Consultas do SQL Server Management Studio, a opção Resultados para Grade não poderá implementar o retorno de carro. Alterne para Resultados para de texto para ver o conjunto de resultados corretamente. Os resultados para Texto são truncados para 256 caracteres por padrão. Para aumentar esse limite, altere a opção Número máximo de caracteres exibidos em cada coluna opção.
B. Gerar lista de nomes do meio separados por vírgula sem valores NULL
O exemplo a seguir substitui NULL valores por N/A e retorna os nomes separados por vírgulas em uma única célula de resultado.
USE AdventureWorks2022;
GO
SELECT STRING_AGG(CONVERT (NVARCHAR (MAX), ISNULL(MiddleName, 'N/A')), ',') AS csv
FROM Person.Person;
GO
Aqui está um conjunto de resultados cortado.
csv
-----
E,R.,N/A,N/A,B,E,N/A,N/A,N/A,N/A,G,B,N/A,C,J,L,P,N/A,M,N/A,N/A,N/A,L,J., ...
C. Gerar valores separados por vírgulas
USE AdventureWorks2022;
GO
SELECT STRING_AGG(CONVERT (NVARCHAR (MAX), CONCAT(FirstName, ' ', LastName, '(', ModifiedDate, ')')), CHAR(13)) AS names
FROM Person.Person;
GO
Aqui está um conjunto de resultados cortado.
names
-------
Ken Sánchez (Feb 8 2003 12:00AM)
Terri Duffy (Feb 24 2002 12:00AM)
Roberto Tamburello (Dec 5 2001 12:00AM)
Rob Walters (Dec 29 2001 12:00AM)
...
Note
Se você usar o Editor de Consultas do SQL Server Management Studio, a opção Resultados para Grade não poderá implementar o retorno de carro. Alterne para Resultados para de texto para ver o conjunto de resultados corretamente. Os resultados para Texto são truncados para 256 caracteres por padrão. Para aumentar esse limite, altere a opção Número máximo de caracteres exibidos em cada coluna opção.
D. Retornar artigos de notícias com tags relacionadas
Imagine um banco de dados onde os artigos e suas tags são separados em tabelas diferentes. Um desenvolvedor deseja retornar uma linha por cada artigo com todas as tags associadas. A consulta a seguir alcança esse resultado:
SELECT a.articleId,
title,
STRING_AGG(tag, ',') AS tags
FROM dbo.Article AS a
LEFT OUTER JOIN dbo.ArticleTag AS t
ON a.ArticleId = t.ArticleId
GROUP BY a.articleId, title;
GO
Aqui está o conjunto de resultados.
| articleId | title | tags |
|---|---|---|
172 |
Polls indicate close election results |
politics,polls,city council |
176 |
New highway expected to reduce congestion |
NULL |
177 |
Dogs continue to be more popular than cats |
polls,animals |
Note
A cláusula GROUP BY é necessária se a função STRING_AGG não for o único item na lista de SELECT.
E. Gerar lista de e-mails por cidades
A consulta a seguir localiza os endereços de e-mail dos funcionários e os agrupa 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
Aqui está o conjunto de resultados cortados.
| City | emails |
|---|---|
Ballard |
paige28@adventure-works.com;;joshua24@adventure-works.comjavier12@adventure-works.com; ... |
Baltimore |
gilbert9@adventure-works.com |
Barstow |
kristen4@adventure-works.com |
Basingstoke Hants |
dale10@adventure-works.com;heidi9@adventure-works.com |
Baytown |
kelvin15@adventure-works.com |
Beaverton |
billy6@adventure-works.com;;dalton35@adventure-works.comlawrence1@adventure-works.com; ... |
Bell Gardens |
christy8@adventure-works.com |
Bellevue |
min0@adventure-works.com;;gigi0@adventure-works.comterry18@adventure-works.com; ... |
Bellflower |
philip0@adventure-works.com;;emma34@adventure-works.comjorge8@adventure-works.com; ... |
Bellingham |
christopher23@adventure-works.com;;frederick7@adventure-works.comomar0@adventure-works.com; ... |
Os e-mails retornados na coluna de e-mails podem ser usados diretamente para enviar e-mails para grupos de pessoas que trabalham em algumas cidades específicas.
F. Gere uma lista ordenada de e-mails por cidades
Semelhante ao exemplo anterior, a consulta a seguir localiza os endereços de e-mail dos funcionários, agrupa-os por cidade e classifica os e-mails 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
Aqui está o conjunto de resultados cortados.
| City | Emails |
|---|---|
Barstow |
kristen4@adventure-works.com |
Basingstoke Hants |
dale10@adventure-works.com;heidi9@adventure-works.com |
Braintree |
mindy20@adventure-works.com |
Bell Gardens |
christy8@adventure-works.com |
Byron |
louis37@adventure-works.com |
Bordeaux |
ranjit0@adventure-works.com |
Carnation |
don0@adventure-works.com;;douglas0@adventure-works.comgeorge0@adventure-works.com; ... |
Boulogne-Billancourt |
allen12@adventure-works.com;;bethany15@adventure-works.comcarl5@adventure-works.com; ... |
Berkshire |
barbara41@adventure-works.com;;brenda4@adventure-works.comcarrie14@adventure-works.com; ... |
Berks |
adriana6@adventure-works.com;;alisha13@adventure-works.comarthur19@adventure-works.com; ... |