FORMATO (Transact-SQL)

Artigo
12/21/2024

se aplica a:SQL Server 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

Retorna um valor formatado com o formato especificado e a cultura opcional. Use a função FORMAT 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.

Transact-SQL convenções de sintaxe

Sintaxe

FORMAT( value , format [ , culture ] )

Argumentos

valor

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

formato

nvarchar padrão de formato.

O formato argumento deve conter uma cadeia de caracteres de formato .NET Framework válida, 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 desses padrões de formatação, consulte a documentação do .NET Framework sobre formatação de cadeia de caracteres em geral, formatos de data e hora personalizados e formatos de número personalizados. Para obter mais informações, consulte Tipos de formatação.

cultura

Opcional nvarchar argumento especificando uma cultura.

Se a cultura argumento não for fornecida, o idioma da sessão atual será usado. Essa linguagem é definida implicitamente ou explicitamente usando a instrução SET LANGUAGE. cultura aceita qualquer cultura suportada pelo .NET Framework como argumento; ele não está limitado aos idiomas explicitamente suportados pelo SQL Server. Se a cultura argumento não for válido, FORMAT gerará um erro.

Tipos de devolução

nvarchar ou null

O comprimento do valor de retorno é determinado pelo formato .

Comentários

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

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

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

Esta função não pode ser remota, pois depende da presença do CLR. A comunicação remota de uma função que requer o CLR pode causar 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) é do tempo tipo de dados. Consulte D. FORMATAR com tipos de dados de tempo.

A tabela a seguir lista os tipos de dados aceitáveis para o valor argumento juntamente com seus tipos equivalentes de mapeamento do .NET Framework.

Categoria	Tipo	Tipo .NET
Numérico	bigint	`Int64`
Numérico	int	`Int32`
Numérico	pequeno	`Int16`
Numérico	minúsculo	`Byte`
Numérico	decimal	`SqlDecimal`
Numérico	numérico	`SqlDecimal`
Numérico	flutuar	`Double`
Numérico	real	`Single`
Numérico	dinheiro pequeno	`Decimal`
Numérico	dinheiro	`Decimal`
Data e Hora	data	`DateTime`
Data e Hora	tempo	`TimeSpan`
Data e Hora	datetime	`DateTime`
Data e Hora	smalldatetime	`DateTime`
Data e Hora	datetime2	`DateTime`
Data e Hora	datetimeoffset	`DateTimeOffset`

Exemplos

Um. Exemplo de FORMATO simples

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

DECLARE @d AS DATE = '08/09/2024';

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)';

Aqui está 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. FORMATAR com cadeias de formatação personalizadas

O exemplo a seguir mostra a formatação de valores numéricos especificando um formato personalizado. O exemplo pressupõe que a data atual é 9 de agosto de 2024. Para obter mais informações sobre esses e outros formatos personalizados, consulte Custom Numeric Format Strings.

DECLARE @d AS DATE = GETDATE();

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

Aqui está o conjunto de resultados.

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

C. FORMATO com tipos numéricos

O exemplo a seguir retorna cinco linhas da tabela Sales.CurrencyRate no banco de dados AdventureWorks2022. A coluna EndOfDateRate é armazenada como tipo dinheiro na tabela. Neste exemplo, a coluna é retornada sem formatação e, em seguida, formatada especificando os tipos de formato .NET Number, General format e Currency. Para obter mais informações sobre esses e outros formatos numéricos, consulte 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;

Aqui está 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. FORMATO com tipos de dados de tempo

FORMAT retorna NULL nesses casos, porque . e : não escapam.

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 o . e o : são escapados.

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

E. Formatar com separadores de vírgulas para números grandes

O exemplo a seguir mostra como formatar números grandes com separadores de vírgula.

SELECT FORMAT(1234567.89, 'N0') AS FormattedNumber;

Aqui está o conjunto de resultados.

1,234,568

Este exemplo usa o especificador de formato N. O especificador N é usado para valores numéricos, e o número de casas decimais pode ser ajustado alterando a cadeia de caracteres de formato (por exemplo, N2 para duas casas decimais).

FORMAT ( value, format_string [, culture ] )

Parâmetros

value: O valor para formatar.
format_string: Uma cadeia de caracteres que especifica o formato a ser aplicado.
culture: (Opcional) Uma cadeia de caracteres que especifica a cultura a ser usada para formatação.

SELECT FORMAT(1234567.89, 'N0') AS FormattedNumber;

1,234,568

Partilhar via

FORMATO (Transact-SQL)

Sintaxe

Argumentos

valor

formato

cultura

Tipos de devolução

Comentários

Exemplos

Um. Exemplo de FORMATO simples

B. FORMATAR com cadeias de formatação personalizadas

C. FORMATO com tipos numéricos

D. FORMATO com tipos de dados de tempo

E. Formatar com separadores de vírgulas para números grandes

Parâmetros

Comentários

Recursos adicionais

Partilhar via

FORMATO (Transact-SQL)

Sintaxe

Argumentos

valor

formato

cultura

Tipos de devolução

Comentários

Exemplos

Um. Exemplo de FORMATO simples

B. FORMATAR com cadeias de formatação personalizadas

C. FORMATO com tipos numéricos

D. FORMATO com tipos de dados de tempo

E. Formatar com separadores de vírgulas para números grandes

Parâmetros

Conteúdo relacionado

Comentários

Recursos adicionais