STRING_AGG (Transact-SQL)

Artigo
01/17/2025

Aplica-se a: SQL Server 2017 (14.x) e posterior Banco de Dados SQL do Azure Instância Gerenciada SQL do Azure ponto de extremidade do Azure Synapse Analytics SQL Analytics no Microsoft Fabric Warehouse no 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

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 nvarchar ou tipos de varchar durante a concatenação. Os tipos que não são de cadeia de caracteres são convertidos em tipo de nvarchar.

separador

Uma expressão de nvarchar ou tipo de varchar que é usado 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 input for string type (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	Resultado
nvarchar(max)	nvarchar(max)
varchar(max)	varchar(max)
nvarchar(1..4000)	nvarchar(4000)
varchar(1.8000)	varchar(8000)
int, bigint, smallint, tinyint, numérico, flutuar, real , bit, decimal, smallmoney, money, datetime, datetime2	nvarchar(4000)

Comentários

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 tipo varchar, o separador não pode ser tipo 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 função ISNULL como demonstrado no exemplo B .

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

Observação

<order_clause> está disponível com nível de compatibilidade de banco de dados 110 e superior.

Exemplos

Os exemplos de código Transact-SQL neste artigo usam o banco de dados de exemplo ou , que você pode baixar da home page Microsoft SQL Server Samples and Community Projects.

Um. 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.

Observação

Se estiver usando o Editor de Consultas do SQL Server Management Studio, a opção Resultados para de 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 separados por vírgula sem `NULL` valores

O exemplo a seguir substitui valores nulos 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(FirstName, 'N/A')), ',') AS csv
FROM Person.Person;
GO

Aqui está um conjunto de resultados cortado.

csv
-----
Syed,Catherine,Kim,Kim,Kim,Hazem,Sam,Humberto,Gustavo,Pilar,Pilar, ...

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)
...

Observação

Se estiver usando o Editor de Consultas do Management Studio, a opção Results to Grid não poderá implementar o retorno de carro. Alterne para Resultados para de texto para ver o conjunto de resultados corretamente.

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.

artigoId	título	Etiquetas
`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`

Observação

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.

Observação

Os resultados são mostrados aparados.

Cidade	E-mails
`Ballard`	`paige28@adventure-works.com`;`joshua24@adventure-works.com`;`javier12@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.com`;`lawrence1@adventure-works.com`;...
`Bell Gardens`	`christy8@adventure-works.com`
`Bellevue`	`min0@adventure-works.com`;`gigi0@adventure-works.com`;`terry18@adventure-works.com`;...
`Bellflower`	`philip0@adventure-works.com`;`emma34@adventure-works.com`;`jorge8@adventure-works.com`;...
`Bellingham`	`christopher23@adventure-works.com`;`frederick7@adventure-works.com`;`omar0@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.

Observação

Os resultados são mostrados aparados.

Cidade	E-mails
`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.com`;`george0@adventure-works.com`;...
`Boulogne-Billancourt`	`allen12@adventure-works.com`;`bethany15@adventure-works.com`;`carl5@adventure-works.com`;...
`Berkshire`	`barbara41@adventure-works.com`;`brenda4@adventure-works.com`;`carrie14@adventure-works.com`;...
`Berks`	`adriana6@adventure-works.com`;`alisha13@adventure-works.com`;`arthur19@adventure-works.com`;...

Partilhar via

STRING_AGG (Transact-SQL)

Sintaxe

Argumentos

expressão

separador

<order_clause>

Tipos de devolução

Comentários

Exemplos

Um. Gerar lista de nomes separados em novas linhas

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

C. Gerar valores separados por vírgulas

E. Gerar lista de e-mails por cidades

F. Gere uma lista ordenada de e-mails por cidades

Comentários

Recursos adicionais

Partilhar via

STRING_AGG (Transact-SQL)

Sintaxe

Argumentos

expressão

separador

<order_clause>

Tipos de devolução

Comentários

Exemplos

Um. Gerar lista de nomes separados em novas linhas

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

C. Gerar valores separados por vírgulas

D. Retornar artigos de notícias com tags relacionadas

E. Gerar lista de e-mails por cidades

F. Gere uma lista ordenada de e-mails por cidades

Conteúdo relacionado

Comentários

Recursos adicionais

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