Fonctionnement de la fonction FORMAT() dans SQL Server (T-SQL)

Dans SQL Server, vous pouvez utiliser le T-SQL FORMAT() fonction pour renvoyer des valeurs telles que des nombres et des dates sous forme de chaînes formatées.

Vous fournissez la valeur à formater et vous spécifiez le format à utiliser. La fonction accepte un argument facultatif qui vous permet de spécifier une culture à utiliser lors du formatage de la valeur.

Syntaxe

La syntaxe ressemble à ceci :

FORMAT ( value, format [, culture ] )

Où value est la valeur que vous voulez formater, et format est une chaîne de format valide qui spécifie le format souhaité.

La culture facultative L'argument peut être utilisé pour spécifier une culture. Si omis, la langue de la session en cours est utilisée.

Le FORMAT la fonction est non déterministe.

Exemple 1 - Formater un nombre

Voici un exemple de formatage d'un nombre :

SELECT FORMAT(1, 'N') AS Result;

Résultat :

+----------+
| Result   |
|----------|
| 1.00     |
+----------+

Dans ce cas, j'ai utilisé N comme chaîne de format. Il s'agit d'un spécificateur de format numérique standard pour afficher la valeur sous forme de nombre. Ce spécificateur de format particulier entraîne le formatage de la sortie avec des chiffres entiers et décimaux, des séparateurs de groupe et un séparateur décimal avec un signe négatif facultatif. Ce spécificateur de format est insensible à la casse, donc soit N ou n ça va.

Exemple 2 – Formater en devise

Voici un exemple de formatage d'un nombre en tant que devise :

SELECT FORMAT(1, 'C') AS Result;

Résultat :

+----------+
| Result   |
|----------|
| $1.00    |
+----------+

Plus de formats numériques

Il existe de nombreuses autres chaînes de format qui peuvent être utilisées avec le FORMAT() une fonction. Par exemple, il existe des chaînes de format pour les pourcentages, la virgule fixe, l'exponentiel (scientifique), l'hexadécimal, etc.

Les chaînes de format numérique sont séparées en standard et personnalisé.

Les deux articles suivants répertorient toutes les chaînes de format numérique, y compris des exemples :

• Chaînes de format numérique standard
• Chaînes de format numérique personnalisées

Voir également Comment formater des nombres dans SQL Server pour plus d'exemples de formatage de nombres.

Exemple 3 - Formater une date

Voici un exemple de formatage d'une date :

SELECT 
  GETDATE() AS 'Unformatted Date',
  FORMAT( GETDATE(), 'D') AS 'Formatted Date';

Résultat :

+-------------------------+------------------------+
| Unformatted Date        | Formatted Date         |
|-------------------------+------------------------|
| 2019-05-08 06:16:55.613 | Wednesday, May 8, 2019 |
+-------------------------+------------------------+

Dans ce cas, j'ai utilisé D qui spécifie un modèle de date longue.

Plus de formats de date

Il existe de nombreuses autres chaînes de format pouvant être utilisées pour formater les dates. Comme pour les chaînes de format numérique, les chaînes de format de date et d'heure sont séparées en format standard et personnalisé, vous pouvez donc créer vos propres formats personnalisés ou vous fier à un format standard.

Les deux articles suivants répertorient toutes les chaînes de format de date et d'heure, y compris des exemples :

• Chaînes de format de date et d'heure standard
• Chaînes de format de date et d'heure personnalisées

Voir également Comment formater la date et l'heure dans SQL Server pour plus d'exemples.

Exemple 4 – La culture facultative Argumentation

Voici un exemple d'utilisation de la culture argument pour renvoyer une valeur dans différentes devises :

SELECT 
    FORMAT(1, 'C', 'fr-FR') AS 'France', 
    FORMAT(1, 'C', 'th-TH') AS 'Thailand', 
    FORMAT(1, 'C', 'ja-JP') AS 'Japan';

Résultat :

+----------+------------+---------+
| France   | Thailand   | Japan   |
|----------+------------+---------|
| 1,00 €   | ฿1.00      | ¥1      |
+----------+------------+---------+

Le FORMAT() La fonction accepte toute culture prise en charge par le .NET Framework comme argument; il n'est pas limité aux langages explicitement pris en charge par SQL Server.

Si vous ne fournissez pas cet argument, la langue de la session en cours est utilisée.

Pour plus d'exemples, consultez Comment les paramètres de langue peuvent affecter votre FORMAT() Résultats.

Exemple 5 :culture non valide Argumentation

Si vous fournissez une culture non valide, vous obtiendrez une erreur :

SELECT FORMAT(1, 'C', 'oop-SS!') AS 'Oops!';

Résultat :

The culture parameter 'oop-SS!' provided in the function call is not supported.

Exemple 6 - Valeur de format non valide

Cependant, pour les autres erreurs, la fonction renvoie NULL . Par exemple, voici ce qui se passe si je fournis une valeur non valide à formater :

SELECT FORMAT(GETDATE(), 'C') AS 'Result';

Résultat :

+----------+
| Result   |
|----------|
| NULL     |
+----------+

Dans ce cas, j'essayais de formater une date dans une devise, et donc le résultat était NULL .

Types de données valides

FORMAT() s'appuie sur la présence du .NET Framework Common Language Runtime (CLR) et utilise les règles de formatage CLR.

Les types de données suivants peuvent être formatés avec le FORMAT() une fonction. Cette liste contient les types de données acceptables pour la chaîne d'entrée ainsi que leurs types équivalents de mappage .NET Framework.

Échappement des deux-points et des points pour le type de données "heure"

Lors de l'utilisation de FORMAT , les deux-points et les points doivent être échappés (cela respecte les règles de formatage CLR). Par conséquent, lorsque la chaîne de format (deuxième paramètre) contient un deux-points ou un point, les deux-points ou le point doivent être échappés avec une barre oblique inverse lorsqu'une valeur d'entrée (premier paramètre) correspond à l'heure type de données.

Exemple :

SELECT 
  CAST('12:15' AS time) AS 'Unformatted Data',
  FORMAT(CAST('12:15' AS time), N'hh.mm') AS 'Unescaped',
  FORMAT(CAST('12:15' AS time), N'hh\.mm') AS 'Escaped';

Résultat :

+--------------------+-------------+-----------+
| Unformatted Data   | Unescaped   | Escaped   |
|--------------------+-------------+-----------|
| 12:15:00           | NULL        | 12.15     |
+--------------------+-------------+-----------+

Donc, comme prévu, la chaîne sans échappement renvoie NULL .

Comme mentionné, cela ne s'applique qu'au temps Type de données. Si nous changeons la valeur d'entrée en un type de données différent, nous n'avons pas besoin d'y échapper :

SELECT 
  CAST('12:15' AS datetime) AS 'Unformatted Data',
  FORMAT(CAST('12:15' AS datetime), N'hh.mm') AS 'Unescaped',
  FORMAT(CAST('12:15' AS datetime), N'hh.mm') AS 'Escaped';

Résultat :

+-------------------------+-------------+-----------+
| Unformatted Data        | Unescaped   | Escaped   |
|-------------------------+-------------+-----------|
| 1900-01-01 12:15:00.000 | 12.15       | 12.15     |
+-------------------------+-------------+-----------+

Dans ce cas, la valeur d'entrée est datetime , et donc, le résultat est bon sans y échapper.

Vous pouvez également utiliser la barre oblique inverse pour échapper tout autre caractère que vous souhaitez inclure dans la chaîne de résultat, qui serait autrement interprété comme un spécificateur de format. Précéder un caractère d'une barre oblique inverse signifie que le caractère suivant est un caractère littéral qui doit être inclus dans la chaîne de résultat sans modification.

Dans une chaîne de format de date et d'heure personnalisée, le d , f , F , g , h , H , K , m , M , s , t , y , z , : , ou / les caractères sont interprétés comme des spécificateurs de format personnalisés plutôt que comme des caractères littéraux.

Dans une chaîne de format numérique personnalisé, le # , 0 , . , , , % , et ‰ les symboles sont interprétés comme des spécificateurs de format plutôt que comme des caractères littéraux. Le E majuscule et minuscule ainsi que le + et - les symboles peuvent également être interprétés comme des spécificateurs de format, selon leur position dans la chaîne de format.

Si vous devez inclure une barre oblique inverse dans la chaîne de résultat, échappez-la avec une autre barre oblique inverse.

Distance

Le FORMAT() fonction non déportable car elle dépend de la présence du CLR. L'accès à distance à une fonction nécessitant le CLR peut entraîner une erreur sur le serveur distant.

Quand utiliser le FORMAT() Fonction

Microsoft recommande que le FORMAT() est utilisée pour le formatage sensible aux paramètres régionaux des valeurs de date/heure et de nombre sous forme de chaînes, et que pour les conversions générales de types de données, soit le CAST() fonction ou la fonction CONVERT() la fonction doit être utilisée à la place.