FORMAT (Transact-SQL)
Aplica-se a:
SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse AnalyticsPonto de extremidade de análises SQL no Microsoft FabricWarehouse no Microsoft Fabric
Retorna um valor formatado com o formato e a cultura opcional especificados. 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 de tipos de dados gerais, use CAST ou CONVERT.
Convenções de sintaxe de Transact-SQL
Sintaxe
FORMAT( value, format [, culture ] )
Observação
Para exibir a sintaxe do Transact-SQL para o SQL Server 2014 (12.x) e versões anteriores, confira a Documentação das versões anteriores.
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 formato válido do .NET Framework, como uma cadeia de formato padrão (por exemplo, "C" ou "D") ou como um padrão de caracteres personalizados para obter datas e valores numéricos (por exemplo, "MMMM DD, aaaa (dddd)"). A formatação composta não tem suporte. 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. Um bom ponto de partida é o tópico, "Formatando tipos".
cultura
Argumento nvarchar opcional especificando uma cultura.
Se o argumento culture não for fornecido, o idioma da sessão atual será usado. Esse idioma é definido implícita ou explicitamente com o uso da instrução SET LANGUAGE. culture aceita qualquer cultura compatível com .NET Framework como um argumento. Ela não é limitada aos idiomas explicitamente compatíveis com 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 que não uma cultura que não é valid. Por exemplo, NULL será retornado se o valor especificado em format não for válido.
A função FORMAT é não determinística.
FORMAT conta com a presença do CLR (Common Language Runtime) do .NET Framework.
Essa função não pode ser remota, uma vez que ela 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 pontos e vírgulas e pontos finais devem ser ignorados. Portanto, quando a cadeia de caracteres de formato (segundo parâmetro) contém uma vírgula ou ponto, a vírgula ou o ponto devem ser precedidos por uma barra invertida quando um valor de entrada (primeiro parâmetro) é do tipo de dados time. 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 DATE = '11/22/2020';
SELECT FORMAT( @d, 'd', 'en-US' ) 'US English'
,FORMAT( @d, 'd', 'en-gb' ) 'British English'
,FORMAT( @d, 'd', 'de-de' ) 'German'
,FORMAT( @d, 'd', 'zh-cn' ) 'Chinese Simplified (PRC)';
SELECT FORMAT( @d, 'D', 'en-US' ) 'US English'
,FORMAT( @d, 'D', 'en-gb' ) 'British English'
,FORMAT( @d, 'D', 'de-de' ) 'German'
,FORMAT( @d, 'D', 'zh-cn' ) 'Chinese Simplified (PRC)';
Este é o conjunto de resultados.
US English British English German Simplified Chinese (PRC)
---------- --------------------- ---------- ------------------------
11/22/2020 22/11/2020 22.11.2020 2020/11/22
US English British English German Chinese (Simplified PRC)
--------------------------- ---------------------- -------------------------- ---------------------------------------
Sunday, November 22, 2020 22 November 2020 Sonntag, 22. November 2020 2020年11月22日
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 22 de novembro de 2020. Para obter mais informações sobre esses e outros formatos personalizados, veja Cadeias de caracteres de formato numérico personalizado.
DECLARE @d DATE = GETDATE();
SELECT FORMAT( @d, 'dd/MM/yyyy', 'en-US' ) AS 'Date'
,FORMAT(123456789,'###-##-####') AS 'Custom Number';
Este é o conjunto de resultados.
Date Custom Number
---------- -------------
22/11/2020 123-45-6789
C. FORMAT com tipos numéricos
O exemplo a seguir retorna 5 linhas da tabela Sales.CurrencyRate do banco de dados AdventureWorks2022. A coluna EndOfDateRate é armazenada como o 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;
Este é 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 €
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 €
D. FORMAT com tipos de dados de tempo
FORMAT retorna NULL nesses casos, porque . e : não são ignorados.
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 em formato 24 h
select FORMAT(CAST('2018-01-01 14:00' AS datetime2), N'HH:mm') -- returns 14:00
Consulte Também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de