CONCAT_WS (Transact-SQL)

Aplica-se a: SQL Server 2017 (14.x) e versões posteriores Banco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse Analytics

Essa função retorna uma cadeia de caracteres resultante de concatenação ou junção de dois ou mais valores de cadeia de caracteres de ponta a ponta. Ele separa esses valores de cadeia de caracteres concatenados com o delimitador especificado no argumento da primeira função. (CONCAT_WS indica concatenar com separador.)

Sintaxe

CONCAT_WS ( separator, argument1, argument2 [, argumentN]... )

Observação

Para ver a sintaxe do Transact-SQL para o SQL Server 2014 e versões anteriores, confira a Documentação das versões anteriores.

Argumentos

separator Uma expressão de qualquer tipo de caractere (char, nchar, nvarchar ou varchar).

argument1, argument2, argumentN Uma expressão de qualquer tipo. A função CONCAT_WS exige, pelo menos, dois argumentos e, no máximo, 254 argumentos.

Tipos de retorno

Um valor de cadeia de caracteres cujos comprimento e tipo dependem da entrada.

Comentários

CONCAT_WS usa um número variável de argumentos de cadeia de caracteres e os concatena em uma única cadeia de caracteres. Ele separa esses valores de cadeia de caracteres concatenados com o delimitador especificado no argumento da primeira função. CONCAT_WS exige um argumento separador e um mínimo de dois outros argumentos de valor de cadeia de caracteres; caso contrário, CONCAT_WS gerará um erro. CONCAT_WS converte implicitamente todos os argumentos nos tipos de cadeia de caracteres antes da concatenação.

A conversão implícita em cadeias de caracteres segue as regras existentes para conversões de tipo de dados. Veja CONCAT (Transact-SQL) para saber mais sobre conversões de tipo de dados e comportamento.

Tratamento de valores NULL

CONCAT_WS ignora a configuração SET CONCAT_NULL_YIELDS_NULL {ON|OFF}.

Se CONCAT_WS receber argumentos com todos os valores nulo, retornará uma cadeia de caracteres vazia do tipo varchar(1).

CONCAT_WS ignora os valores nulos durante a concatenação e não adicionam o separador entre valores nulos. Portanto, CONCAT_WS pode tratar a concatenação de cadeias de caracteres que podem ter valores "em branco", por exemplo, um segundo campo de endereço. Veja o exemplo B para saber mais.

Se um cenário envolver valores nulos, separados por um delimitador, considere a função ISNULL. Veja o exemplo C para saber mais.

Exemplos

a. Concatenando valores com separador

Este exemplo concatena três colunas da tabela sys.databases, separando-os com um -.

SELECT CONCAT_WS( ' - ', database_id, recovery_model_desc, containment_desc) AS DatabaseInfo
FROM sys.databases;

Este é o conjunto de resultados.

DatabaseInfo
1 – SIMPLE – NONE
2 – SIMPLE – NONE
3 – FULL – NONE
4 – SIMPLE – NONE

B. Ignorando valores NULL

Este exemplo ignora valores NULL na lista de argumentos.

SELECT CONCAT_WS(',','1 Microsoft Way', NULL, NULL, 'Redmond', 'WA', 98052) AS Address;

Este é o conjunto de resultados.

Address
------------   
1 Microsoft Way,Redmond,WA,98052

C. Gerando dados formatados em CSV a partir da tabela

Este exemplo usa uma vírgula , como valor separador e adiciona o caractere de retorno de carro char(13) no formato de valores separados por coluna do conjunto de resultados.

SELECT 
STRING_AGG(CONCAT_WS( ',', database_id, recovery_model_desc, containment_desc), char(13)) AS DatabaseInfo
FROM sys.databases

Este é o conjunto de resultados.

DatabaseInfo
------------   
1,SIMPLE,NONE
2,SIMPLE,NONE
3,FULL,NONE 
4,SIMPLE,NONE 

CONCAT_WS ignora valores NULL nas colunas. Encapsule uma coluna anulável com a função ISNULL e forneça um valor padrão. Veja este exemplo para saber mais:

SELECT 
STRING_AGG(CONCAT_WS( ',', database_id, ISNULL(recovery_model_desc,''), ISNULL(containment_desc,'N/A')), char(13)) AS DatabaseInfo
FROM sys.databases;

Confira também

CONCAT (Transact-SQL)
FORMATMESSAGE (Transact-SQL)
QUOTENAME (Transact-SQL)
REPLACE (Transact-SQL)
REVERSE (Transact-SQL)
STRING_AGG (Transact-SQL)
STRING_ESCAPE (Transact-SQL)
STUFF (Transact-SQL)
TRANSLATE (Transact-SQL)
Funções de cadeia de caracteres (Transact-SQL)