FORMAT (Transact-SQL)

Retourne une valeur mise en forme avec la culture facultative et le format spécifiés dans SQL Server 2012. Utilisez la fonction FORMAT pour la mise en forme comme chaînes de valeurs de date/heure et de valeurs numériques compatibles avec les paramètres régionaux. Pour les conversions de type de données général, continuez à utiliser CAST ou CONVERT.

Conventions de la syntaxe Transact-SQL

Syntaxe

FORMAT ( value, format [, culture ] )

Arguments

• value
  Expression d'un type de données pris en charge à mettre en forme. Pour obtenir la liste des types valides, consultez la table dans la section Notes ci-dessous.

• format
  Modèle de format nvarchar.

  L'argument format doit contenir une chaîne de format .NET Framework valide, comme chaîne de format standard (par exemple, « C » ou « D ») ou comme modèle de caractères personnalisés pour les dates et les valeurs numériques (par exemple, « MMMM JJ, aaaa (jjjj) »). La mise en forme composite n'est pas prise en charge. Pour une explication complète de ces modèles de mise en forme, consultez la documentation du .NET Framework sur la mise en forme de chaîne en général, sur les formats de date et d'heure personnalisés et sur les formats de nombres personnalisés. La rubrique « Mise en forme des types » constitue un bon point de départ.

• culture
  Argument facultatif nvarchar spécifiant une culture.

  Si l'argument culture n'est pas fourni, la langue de la session active est utilisée. Cette langue est définie implicitement, ou explicitement à l'aide de l'instruction SET LANGUAGE. L'argument culture accepte n'importe quelle culture prise en charge par le .NET Framework comme argument ; il n'est pas limité aux langues explicitement prises en charge par SQL Server. Si l'argument culture n'est pas valide, FORMAT génère une erreur.

Types des valeurs retournés

nvarchar ou NULL.

La longueur de la valeur de retour est déterminée par format.

Notes

FORMAT retourne NULL pour les erreurs autres que culture qui n'est pas valid. Par exemple, NULL est retourné si la valeur spécifiée dans format n'est pas valide.

FORMAT repose sur la présence du CLR (Common Langage Runtime) .NET Framework.

Cette fonction ne peut pas être exécutée à distance car elle dépend de la présence du CLR. L'exécution à distance d'une fonction qui nécessite le CLR provoquerait une erreur sur le serveur distant.

Le tableau suivant répertorie les types de données acceptables pour l'argument value, ainsi que leurs types équivalents de mappage .NET Framework.

Catégorie	Type	Type .NET
Numérique	bigint	Int64
Numérique	int	Int32
Numérique	smallint	Int16
Numérique	tinyint	Byte
Numérique	decimal	SqlDecimal
Numérique	numeric	SqlDecimal
Numérique	float	Double
Numérique	real	Single
Numérique	smallmoney	Décimal
Numérique	money	Décimal
Date et heure	date	DateTime
Date et heure	time	TimeSpan
Date et heure	datetime	DateTime
Date et heure	smalldatetime	DateTime
Date et heure	datetime2	DateTime
Date et heure	datetimeoffset	DateTimeOffset

Exemples

A. Exemple FORMAT simple

L'exemple suivant retourne une date simple mise en forme pour différentes cultures.

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

Voici l'ensemble des résultats.

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 avec chaînes de format personnalisées

L'exemple suivant montre la mise en forme des valeurs numériques en spécifiant un format personnalisé. Pour plus d'informations sur ces formats et d'autres formats personnalisés, consultez Chaînes de format numérique personnalisées.

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

Voici l'ensemble des résultats.

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

(1 row(s) affected)

C. FORMAT avec types numériques

L'exemple suivant retourne 5 lignes de la table Sales.CurrencyRate. La colonne EndOfDateRate est stockée comme type money dans la table. Dans cet exemple, la colonne est retournée dépourvue de mise en forme, puis mise en forme en spécifiant les types de formats Number, General et Currency .NET. Pour plus d'informations sur ces formats et d'autres formats numériques, consultez Chaînes de format numérique standard.

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;

Voici l'ensemble des résultats.

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)

Cet exemple spécifie la culture allemande (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)

Voir aussi

Référence

CAST et CONVERT (Transact-SQL)