CONCAT_WS (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
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 ] ... )
Argumentos
separator
Uma expression de qualquer tipo de caractere (char, nchar, nvarchar ou varchar).
argument1, argument2 [ , argumentN ]
Uma expressão de qualquer valor de cadeia de caracteres. 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. Para obter mais informações sobre conversões de tipo de dados e comportamento, veja CONCAT (Transact-SQL).
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 NULL, ele 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. Para obter mais informações, veja o Exemplo C.
Exemplos
R. Concatenar valores com separador
Este exemplo concatena três colunas da tabela sys.databases, separando os valores com um hífen cercado por espaços (-).
SELECT CONCAT_WS(' - ', database_id, recovery_model_desc, containment_desc) AS DatabaseInfo
FROM sys.databases;
Veja a seguir o conjunto de resultados.
DatabaseInfo
-----------------
1 - SIMPLE - NONE
2 - SIMPLE - NONE
3 - FULL - NONE
4 - SIMPLE - NONE
B. Ignorar valores NULL
Este exemplo ignora os valores NULL na lista de argumentos e usa um valor separador de vírgula (,).
SELECT CONCAT_WS(',', '1 Microsoft Way', NULL, NULL, 'Redmond', 'WA', 98052) AS Address;
Veja a seguir o conjunto de resultados.
Address
--------------------------------
1 Microsoft Way,Redmond,WA,98052
C. Gerar 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;
Veja a seguir o conjunto de resultados.
DatabaseInfo
-------------
1,SIMPLE,NONE
2,SIMPLE,NONE
3,FULL,NONE
4,SIMPLE,NONE
CONCAT_WS ignora os valores de NULL nas colunas. Encapsule uma coluna anulável com a função ISNULL e forneça um valor padrão. Por exemplo:
SELECT STRING_AGG(
CONCAT_WS(',', database_id, ISNULL(recovery_model_desc, ''),
ISNULL(containment_desc, 'N/A')
), CHAR(13)) AS DatabaseInfo
FROM sys.databases;