FORMAT (Transact-SQL)

Retorna um valor formatado com o formato e a cultura opcional especificados no SQL Server 2012. 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 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 do 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, consulte 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".

• culture
  Argumento nvarchar opcional que especifica uma cultura.

  Se o argumento culture não for fornecido, o idioma da sessão atual será usado. Esse idioma é definido implicitamente ou explicitamente com a instrução SET LANGUAGE. culture aceita qualquer cultura com suporte do .NET Framework como um argumento. Ele não se limita aos idiomas com suporte explícito do SQL Server. Se o argumento culture não for válido, FORMAT gerará um erro.

Tipos de retorno

nvarchar ou nulo

O comprimento do valor de retorno é determinado por format.

Comentários

FORMAT retorna NULL para erros diferentes de culture que não seja valid. Por exemplo, NULL será retornado se o valor especificado em format não for válido.

FORMAT conta com a presença do CLR (Common Language Runtime) do .NET Framework.

Essa função não será remota uma vez que ela depende da presença do CLR. Uma função remota que exige o CLR provocará um erro no servidor remoto.

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	Tipo	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	Duplo
Numérico	real	Único
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 DATETIME = '10/01/2011';
SELECT FORMAT ( @d, 'd', 'en-US' ) AS 'US English Result'
      ,FORMAT ( @d, 'd', 'en-gb' ) AS 'Great Britain English Result'
      ,FORMAT ( @d, 'd', 'de-de' ) AS 'German Result'
      ,FORMAT ( @d, 'd', 'zh-cn' ) AS 'Simplified Chinese (PRC) Result'; 
  
SELECT FORMAT ( @d, 'D', 'en-US' ) AS 'US English Result'
      ,FORMAT ( @d, 'D', 'en-gb' ) AS 'Great Britain English Result'
      ,FORMAT ( @d, 'D', 'de-de' ) AS 'German Result'
      ,FORMAT ( @d, 'D', 'zh-cn' ) AS 'Chinese (Simplified PRC) Result'; 

Aqui está o conjunto de resultados.

US English Result Great Britain English Result  German Result Simplified Chinese (PRC) Result
----------------  ----------------------------- ------------- -------------------------------------
10/1/2011         01/10/2011                    01.10.2011    2011/10/1

(1 row(s) affected)

US English Result            Great Britain English Result  German Result                    Chinese (Simplified PRC) Result
---------------------------- ----------------------------- -----------------------------  ---------------------------------------
Saturday, October 01, 2011   01 October 2011               Samstag, 1. Oktober 2011        2011年10月1日

(1 row(s) affected)

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. Para obter mais informações sobre esses e outros formatos personalizados, consulte Cadeias de caracteres de formato numérico personalizado.

-- Current date is September 27 2012.
DECLARE @d DATETIME = GETDATE();
SELECT FORMAT( @d, 'dd/MM/yyyy', 'en-US' ) AS 'DateTime Result'
       ,FORMAT(123456789,'###-##-####') AS 'Custom Number Result';

Aqui está o conjunto de resultados.

DateTime Result  Custom Number Result
--------------   --------------------
27/09/2012       123-45-6789

(1 row(s) affected)

C. FORMAT com tipos numéricos

O exemplo a seguir retorna 5 linhas da tabela Sales.CurrencyRate. 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, consulte Cadeias de caracteres de formato numérico padrão.

USE AdventureWorks2012;
GO
SELECT TOP(5)CurrencyRateID, EndOfDayRate
            ,FORMAT(EndOfDayRate, 'N', 'en-us') AS 'Number 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

(5 row(s) affected)

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 €

 (5 row(s) affected)

Consulte também

Referência

CAST e CONVERT (Transact-SQL)