FORMAT (Transact-SQL)

Artigo
11/04/2024

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics Ponto de extremidade de análises SQL no Microsoft Fabric Warehouse no Microsoft Fabric

Retorna um valor formatado com o formato e a cultura opcional especificados. Use a FORMAT função para formatação com reconhecimento de localidade de valores de data/hora e número como cadeias de caracteres. Para conversões gerais de tipo de dados, use CAST ou CONVERT.

Convenções de sintaxe de Transact-SQL

Sintaxe

FORMAT( value , format [ , culture ] )

Argumentos

value

Expressão de um tipo de dados com suporte para formatação. Para obter uma lista de tipos válidos, consulte a tabela na seção Comentários .

format

Padrão de formato nvarchar.

O argumento format deve conter uma cadeia de caracteres de formato válida do .NET Framework, como uma cadeia de caracteres de formato padrão (por exemplo, "C" ou "D"), ou como um padrão de caracteres personalizados para datas e valores numéricos (por exemplo, "MMMM DD, yyyy (dddd)"). Não há suporte para formatação composta.

Para obter uma explicação completa sobre esses padrões de formatação, veja a documentação do .NET Framework sobre formatação de cadeias de caracteres em geral, formatos personalizados de data e hora e formatos personalizados de número. Para obter mais informações, consulte Tipos de formatação.

cultura

Argumento nvarchar opcional especificando uma cultura.

Se o argumento culture não for fornecido, o idioma da sessão atual será usado. Essa linguagem é definida implícita ou explicitamente usando a SET LANGUAGE instrução. culture aceita qualquer cultura com suporte do .NET Framework como um argumento; ela não se limita às linguagens explicitamente compatíveis com o SQL Server. Se o argumento culture não for válido, FORMAT gerará um erro.

Tipos de retorno

nvarchar ou nulo

A extensão do valor retornado é determinada pelo format.

Comentários

FORMAT retorna NULL para erros diferentes de uma cultura que não é válida. Por exemplo, NULL será retornado se o valor especificado no formato não for válido.

A FORMAT função é não determinística.

FORMAT depende da presença do CLR (Common Language Runtime) do .NET Framework.

Essa função não pode ser remota, pois depende da presença do CLR. Tornar remota uma função que exige o CLR pode provocar um erro no servidor remoto.

FORMAT depende de regras de formatação CLR, que determinam que dois-pontos e pontos devem ser escapados. Portanto, quando a cadeia de caracteres de formato (segundo parâmetro) contém dois-pontos ou ponto, os dois-pontos ou ponto devem ser escapados com barra invertida quando um valor de entrada (primeiro parâmetro) for do tipo de dados de hora . Veja D. FORMAT com tipos de dados de tempo.

A tabela a seguir lista os tipos de dados aceitáveis para o argumento value, junto com os tipos equivalentes de mapeamento do .NET Framework.

Categoria	Type	Tipo .NET
Numérico	bigint	`Int64`
Numérico	int	`Int32`
Numérico	smallint	`Int16`
Numérico	tinyint	`Byte`
Numérico	decimal	`SqlDecimal`
Numérico	numeric	`SqlDecimal`
Numérico	float	`Double`
Numérico	real	`Single`
Numérico	smallmoney	`Decimal`
Numérico	money	`Decimal`
Data e hora	date	`DateTime`
Data e hora	time	`TimeSpan`
Data e hora	datetime	`DateTime`
Data e hora	smalldatetime	`DateTime`
Data e hora	datetime2	`DateTime`
Data e hora	datetimeoffset	`DateTimeOffset`

Exemplos

a. Exemplo de FORMAT simples

O exemplo a seguir retorna uma data simples formatada para culturas diferentes.

DECLARE @d AS DATE = '11/22/2020';

SELECT FORMAT(@d, 'd', 'en-US') AS 'US English',
       FORMAT(@d, 'd', 'en-gb') AS 'British English',
       FORMAT(@d, 'd', 'de-de') AS 'German',
       FORMAT(@d, 'd', 'zh-cn') AS 'Chinese Simplified (PRC)';

SELECT FORMAT(@d, 'D', 'en-US') AS 'US English',
       FORMAT(@d, 'D', 'en-gb') AS 'British English',
       FORMAT(@d, 'D', 'de-de') AS 'German',
       FORMAT(@d, 'D', 'zh-cn') AS 'Chinese Simplified (PRC)';

Veja a seguir o conjunto de resultados.

US English   British English  German      Simplified Chinese (PRC)
-----------  ---------------- ----------- -------------------------
8/9/2024     09/08/2024       09.08.2024  2024/8/9

US English              British English  German                    Chinese (Simplified PRC)
----------------------- ---------------- ------------------------  -------------------------
Friday, August 9, 2024  09 August 2024   Freitag, 9. August 2024   2024年8月9日

B. FORMAT com cadeias de caracteres de formatação personalizadas

O exemplo a seguir mostra os valores numéricos da formatação especificando um formato personalizado. O exemplo pressupõe que a data atual seja 9 de agosto de 2024. Para obter mais informações sobre esses e outros formatos personalizados, veja Cadeias de caracteres de formato numérico personalizado.

DECLARE @d AS DATE = GETDATE();

SELECT FORMAT(@d, 'dd/MM/yyyy', 'en-US') AS 'Date',
       FORMAT(123456789, '###-##-####') AS 'Custom Number';

Veja a seguir o conjunto de resultados.

Date         Custom Number
-----------  --------------
09/08/2024   123-45-6789

C. FORMAT com tipos numéricos

O exemplo a seguir retorna cinco linhas da Sales.CurrencyRate tabela no AdventureWorks2022 banco de dados. A coluna EndOfDateRate é armazenada como tipo money na tabela. Neste exemplo, a coluna é retornada sem formatação e formatada com a especificação do formato de número .NET, o formato Geral e os tipos de formato de Moeda. Para obter mais informações sobre esses e outros formatos numéricos, veja Cadeias de caracteres de formato numérico padrão.

SELECT TOP (5) CurrencyRateID,
               EndOfDayRate,
               FORMAT(EndOfDayRate, 'N', 'en-us') AS 'Numeric Format',
               FORMAT(EndOfDayRate, 'G', 'en-us') AS 'General Format',
               FORMAT(EndOfDayRate, 'C', 'en-us') AS 'Currency Format'
FROM Sales.CurrencyRate
ORDER BY CurrencyRateID;

Veja a seguir o conjunto de resultados.

CurrencyRateID EndOfDayRate  Numeric Format  General Format  Currency Format
-------------- ------------  --------------  --------------  ---------------
1              1.0002        1.00            1.0002          $1.00
2              1.55          1.55            1.5500          $1.55
3              1.9419        1.94            1.9419          $1.94
4              1.4683        1.47            1.4683          $1.47
5              8.2784        8.28            8.2784          $8.28

Este exemplo especifica a cultura alemã (de-de).

SELECT TOP (5) CurrencyRateID,
               EndOfDayRate,
               FORMAT(EndOfDayRate, 'N', 'de-de') AS 'Numeric Format',
               FORMAT(EndOfDayRate, 'G', 'de-de') AS 'General Format',
               FORMAT(EndOfDayRate, 'C', 'de-de') AS 'Currency Format'
FROM Sales.CurrencyRate
ORDER BY CurrencyRateID;

CurrencyRateID EndOfDayRate  Numeric Format  General Format  Currency Format
-------------- ------------  --------------  --------------  ---------------
1              1.0002        1,00            1,0002          1,00 &euro;
2              1.55          1,55            1,5500          1,55 &euro;
3              1.9419        1,94            1,9419          1,94 &euro;
4              1.4683        1,47            1,4683          1,47 &euro;
5              8.2784        8,28            8,2784          8,28 &euro;

D. FORMAT com tipos de dados de tempo

FORMAT retorna NULL nesses casos porque . e : não são escapados.

SELECT FORMAT(CAST('07:35' AS TIME), N'hh.mm'); --> returns NULL
SELECT FORMAT(CAST('07:35' AS TIME), N'hh:mm'); --> returns NULL

Format retorna uma cadeia de caracteres formatada porque . e : são ignorados.

SELECT FORMAT(CAST('07:35' AS TIME), N'hh\.mm'); --> returns 07.35
SELECT FORMAT(CAST('07:35' AS TIME), N'hh\:mm'); --> returns 07:35

Format retorna uma hora atual formatada com AM ou PM especificado.

SELECT FORMAT(SYSDATETIME(), N'hh:mm tt'); --> returns 03:46 PM
SELECT FORMAT(SYSDATETIME(), N'hh:mm t');  --> returns 03:46 P

Format retorna a hora especificada, exibindo AM.

SELECT FORMAT(CAST('2018-01-01 01:00' AS DATETIME2), N'hh:mm tt'); --> returns 01:00 AM
SELECT FORMAT(CAST('2018-01-01 01:00' AS DATETIME2), N'hh:mm t');  --> returns 01:00 A

Format retorna a hora especificada, exibindo PM.

SELECT FORMAT(CAST('2018-01-01 14:00' AS DATETIME2), N'hh:mm tt'); --> returns 02:00 PM
SELECT FORMAT(CAST('2018-01-01 14:00' AS DATETIME2), N'hh:mm t');  --> returns 02:00 P

Format retorna a hora especificada no formato de 24 horas.

SELECT FORMAT(CAST('2018-01-01 14:00' AS DATETIME2), N'HH:mm'); --> returns 14:00

Compartilhar via

FORMAT (Transact-SQL)

Sintaxe

Argumentos

value

format

cultura

Tipos de retorno

Comentários

Exemplos

a. Exemplo de FORMAT simples

B. FORMAT com cadeias de caracteres de formatação personalizadas

C. FORMAT com tipos numéricos

D. FORMAT com tipos de dados de tempo

Comentários

Recursos adicionais

Compartilhar via

FORMAT (Transact-SQL)

Sintaxe

Argumentos

value

format

cultura

Tipos de retorno

Comentários

Exemplos

a. Exemplo de FORMAT simples

B. FORMAT com cadeias de caracteres de formatação personalizadas

C. FORMAT com tipos numéricos

D. FORMAT com tipos de dados de tempo

Conteúdo relacionado

Comentários

Recursos adicionais