Guinguette Marais Poitevin

No SQL Server, pode usar a função T-SQL FORMAT() para retornar valores tais como números e datas como strings formatadas.

Fornece o valor a ser formatado, e especifica o formato a usar. A função aceita um argumento opcional que lhe permite especificar uma cultura a utilizar ao formatar o valor.

Sintaxe

A sintaxe é assim:

FORMAT ( value, format )

Onde value é o valor que pretende formatar, e format é uma cadeia de formatação válida que especifica o formato desejado.

O opcional culture argumento pode ser usado para especificar uma cultura. Se omitido, é utilizada a língua da sessão actual.

O FORMAT função é não determinista.

Exemplo 1 – Formatar um número

Há um exemplo de formatação de um número:

SELECT FORMAT(1, 'N') AS Result;

Resultado:

+----------+| Result ||----------|| 1.00 |+----------+

Neste caso, utilizei N como cadeia de formatação. Este é um especificador de formato numérico padrão para a saída do valor como um número. Este especificador de formato particular resulta na formatação da saída com dígitos integrais e decimais, separadores de grupo, e um separador decimal com sinal negativo opcional. Este especificador de formato é insensível a maiúsculas e minúsculas, por isso ou N ou n está bem.

Exemplo 2 – Formatar para uma Moeda

Aqui está um exemplo de formatação de um número como moeda:

SELECT FORMAT(1, 'C') AS Result;

Resultado:

+----------+| Result ||----------|| $1.00 |+----------+

Mais Formatos Numéricos

Há muito mais cadeias de formato que podem ser utilizadas com a função FORMAT(). Por exemplo, há cadeias de formato para percentagens, ponto fixo, exponencial (científico), hexadecimal, e muito mais.

As cadeias de formato numérico são separadas em padrão e personalizadas.

Os dois artigos seguintes listam todas as cadeias de formato numérico, incluindo exemplos:

• Cordas de Formato Numérico Padrão
• Cordas de Formato Numérico Personalizado

Veja também Como Formatar Números no SQL Server para mais exemplos de formatação de números.

Exemplo 3 – Formatar uma Data

Aqui está um exemplo de formatação de uma data:

SELECT GETDATE() AS 'Unformatted Date', FORMAT( GETDATE(), 'D') AS 'Formatted Date';

Resultado:

+-------------------------+------------------------+| Unformatted Date | Formatted Date ||-------------------------+------------------------|| 2019-05-08 06:16:55.613 | Wednesday, May 8, 2019 |+-------------------------+------------------------+

Neste caso, utilizei D que especifica um padrão de data longo.

Outros formatos de datas

Há muitas mais cadeias de formatos que podem ser usadas para formatar datas. Tal como com as cadeias de formato numérico, as cadeias de formato de data e hora são separadas em formato padrão e personalizado, de modo a poder construir os seus próprios formatos personalizados, ou pode confiar num formato padrão.

Os dois artigos seguintes listam todas as cadeias de formato de data e hora, incluindo exemplos:

• Cadeia de Formato de Data e Hora Padrão
• Cadeia de Formato de Data e Hora Padrão

Também ver Como Formatar a Data & Hora no SQL Server para mais exemplos.

Exemplo 4 – O Argumento de Cultura Opcional

Aqui está um exemplo de utilização do culture argumento para devolver um valor em várias moedas:

SELECT FORMAT(1, 'C', 'fr-FR') AS 'France', FORMAT(1, 'C', 'th-TH') AS 'Thailand', FORMAT(1, 'C', 'ja-JP') AS 'Japan';

Resultado:

+----------+------------+---------+| France | Thailand | Japan ||----------+------------+---------|| 1,00 € | ฿1.00 | ¥1 |+----------+------------+---------+

A função FORMAT() aceita qualquer cultura suportada pela .NET Framework como argumento; não se limita às línguas explicitamente suportadas pelo SQL Server.

Se não fornecer este argumento, é utilizada a língua da sessão actual.

Para mais exemplos, ver Como as definições de língua podem afectar o seu FORMAT() Resultados.

Exemplo 5 – Argumento de cultura inválida

Se fornecer uma cultura inválida, receberá um erro:

SELECT FORMAT(1, 'C', 'oop-SS!') AS 'Oops!';

Resultado:

The culture parameter 'oop-SS!' provided in the function call is not supported.

Exemplo 6 – Valor do Formato Inválido

No entanto, para outros erros, a função retorna NULL. Por exemplo, eis o que acontece se eu fornecer um valor inválido para ser formatado:

SELECT FORMAT(GETDATE(), 'C') AS 'Result';

Result:

+----------+| Result ||----------|| NULL |+----------+

Neste caso, estava a tentar formatar uma data numa moeda, e portanto o resultado foi NULL.

Tipos de dados válidos

FORMAT() baseia-se na presença do .NET Framework Common Language Runtime (CLR), e utiliza as regras de formatação CLR.

Os seguintes tipos de dados podem ser formatados com a função FORMAT(). Esta lista contém os tipos de dados aceitáveis para a cadeia de entrada juntamente com os seus tipos .NET Framework mapping equivalent types.

>bigint>Int64

Numérico

Category	Type	.Tipo de rede
Numérico
Numérico	int	Int32
Numeric	smallint	Int16
Numeric	tinyint	Byte
Numérico	decimal	SqlDecimal
Numérico	numérico	SqlDecimal
Numérico	float	Duplo
Numérico	real	Single
smallmoney	Decimal
Numérico	money	Decimal
Date and Time	date	DateTime
Date and Time	time	TimeSpan
Date and Time	dateTime	DateTime
Date and Time	smalldatetime	DateTime
Date and Time	datetime2	DateTime
Date and Time	datetimeoffset	DateTimeOffset

Escaping Colons and Periods for the ‘time’ Data Type

Ao usar FORMAT, colons e períodos devem ser evitados (isto obedece às regras de formatação do CLR). Portanto, quando a cadeia de formato (segundo parâmetro) contém um ponto ou dois pontos, o ponto ou ponto deve ser contornado com uma barra invertida quando um valor de entrada (primeiro parâmetro) é do tipo de dados de tempo.

Exemplo:

SELECT CAST('12:15' AS time) AS 'Unformatted Data', FORMAT(CAST('12:15' AS time), N'hh.mm') AS 'Unescaped', FORMAT(CAST('12:15' AS time), N'hh\.mm') AS 'Escaped';

Result:

+--------------------+-------------+-----------+| Unformatted Data | Unescaped | Escaped ||--------------------+-------------+-----------|| 12:15:00 | NULL | 12.15 |+--------------------+-------------+-----------+

Então, tal como esperado, a cadeia de caracteres não escalonada retorna NULL.

Como mencionado, isto só se aplica ao tipo de dados de tempo. Se alterarmos o valor de entrada para um tipo de dados diferente, não precisamos de o escapar:

SELECT CAST('12:15' AS datetime) AS 'Unformatted Data', FORMAT(CAST('12:15' AS datetime), N'hh.mm') AS 'Unescaped', FORMAT(CAST('12:15' AS datetime), N'hh.mm') AS 'Escaped';

Result:

+-------------------------+-------------+-----------+| Unformatted Data | Unescaped | Escaped ||-------------------------+-------------+-----------|| 1900-01-01 12:15:00.000 | 12.15 | 12.15 |+-------------------------+-------------+-----------+

Neste caso, o valor de entrada é a data/hora, e portanto, o resultado é óptimo sem escapar a ela.

Também se pode usar a barra invertida para escapar a qualquer outro carácter que se queira incluir na cadeia de resultados, que de outra forma seria interpretado como um especificador de formato. Preceder um carácter com uma barra invertida significa que o seguinte carácter é um carácter literal que deve ser incluído na cadeia de resultados inalterado.

Numa cadeia de formato de data e hora personalizada, o dfFghHKmMstyz:, ou / os caracteres são interpretados como especificadores de formato personalizados e não como caracteres literais.

Numa cadeia de formato numérico personalizado, o #0.,%, e ‰ os símbolos são interpretados como especificadores de formato e não como caracteres literais. As maiúsculas e minúsculas E assim como os símbolos + e - também podem ser interpretados como especificadores de formato, dependendo da sua posição dentro da cadeia de formato.

Se precisar de incluir uma barra invertida na cadeia de resultados, escape com outra barra invertida.

Remoting

A função FORMAT() não pode ser removida uma vez que depende da presença da CLR. Remotar uma função que requer o CLR, pode causar um erro no servidor remoto.

When to Use the FORMAT() Function

Microsoft recomenda que a função FORMAT() seja utilizada para formatação locale-aware de data/hora e valores numéricos como strings, e que para as conversões gerais do tipo de dados, deve ser utilizada a função CAST() ou a função CONVERT().