FORMAT (Transact-SQL)
S’applique à : 
SQL Server base de données Azure SQL Azure SQL Managed Instance Azure Synapse Analytics Point de terminaison analytique SQL dans Microsoft Fabric Entrepôt dans Microsoft Fabric
Retourne une valeur mise en forme avec la culture facultative et le format spécifiés. Utilisez la fonction pour la FORMAT mise en forme prenant en charge les paramètres régionaux des valeurs de date/heure et de nombre en tant que chaînes. Pour les conversions de types de données générales, utilisez 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 le tableau de la section Remarques .
format
Modèle de format nvarchar.
L’argument de format doit contenir une chaîne de format .NET Framework valide, soit sous forme de chaîne de format standard (par exemple, "C" soit "D"), soit comme modèle de caractères personnalisés pour les dates et les valeurs numériques (par exemple, "MMMM DD, yyyy (dddd)"). La mise en forme composite n’est pas prise en charge.
Pour obtenir une explication complète de ces modèles de mise en forme, consultez la documentation du .NET Framework sur la mise en forme des chaînes en général, sur les formats de date et d’heure personnalisés et sur les formats de nombres personnalisés. Pour plus d’informations, consultez Mise en forme des types.
culture
Argument nvarchar facultatif spécifiant une culture.
Si l’argument de culture n’est pas fourni, la langue de la session active est utilisée. Ce langage est défini implicitement ou explicitement à l’aide de l’instruction SET LANGUAGE . la culture accepte toute culture prise en charge par le .NET Framework en tant qu’argument ; elle n’est pas limitée aux langages explicitement pris en charge par SQL Server. Si l’argument de culture n’est pas valide, FORMAT déclenche une erreur.
Types de retour
nvarchar ou NULL
La longueur de la valeur renvoyée est déterminée par format.
Notes
FORMAT retourne NULL des erreurs autres qu’une culture qui n’est pas valide. Par exemple, NULL est retourné si la valeur spécifiée au format n’est pas valide.
La FORMAT fonction n’est pas déterministe.
FORMAT s’appuie sur la présence du Common Language Runtime (CLR) du .NET Framework.
Cette fonction ne peut pas être distante, car elle dépend de la présence du CLR. L’exécution à distance d’une fonction qui nécessite le CLR peut provoquer une erreur sur le serveur distant.
FORMAT s’appuie sur les règles de mise en forme CLR, qui dictent que les points et les points doivent être échappés. Par conséquent, lorsque la chaîne de format (deuxième paramètre) contient un signe deux-points ou un point, le signe deux-points ou la période doit être échappé avec une barre oblique inverse lorsqu’une valeur d’entrée (premier paramètre) est du type de données time . Consultez D. FORMAT avec types de données time.
Le tableau suivant répertorie les types de données acceptables pour l’argument value, ainsi que leurs types équivalents de mappage .NET Framework.
| Category | 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 | Decimal |
| Numérique | money | Decimal |
| 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
R. Exemple FORMAT simple
L'exemple suivant retourne une date simple mise en forme pour différentes cultures.
DECLARE @d AS DATE = '11/22/2020';
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)';
Voici le jeu de résultats.
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. 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é. L’exemple suppose que la date actuelle est le 9 août 2024. Pour plus d’informations sur ces formats et d’autres formats personnalisés, consultez Chaînes de format numérique personnalisées.
DECLARE @d AS DATE = GETDATE();
SELECT FORMAT(@d, 'dd/MM/yyyy', 'en-US') AS 'Date',
FORMAT(123456789, '###-##-####') AS 'Custom Number';
Voici le jeu de résultats.
Date Custom Number
----------- --------------
09/08/2024 123-45-6789
C. FORMAT avec types numériques
L’exemple suivant retourne cinq lignes de la Sales.CurrencyRate table dans la AdventureWorks2022 base de données. La colonne EndOfDateRate est stockée en tant qu’argent de type 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.
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;
Voici le jeu de 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
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 €
D. FORMAT avec types de données time
FORMAT retourne NULL dans ces cas parce que . et : ne sont pas échappés.
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 retourne une chaîne mise en forme, car . et : sont échappés.
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
Le format retourne une heure actuelle mise en forme avec AM ou PM spécifié.
SELECT FORMAT(SYSDATETIME(), N'hh:mm tt'); --> returns 03:46 PM
SELECT FORMAT(SYSDATETIME(), N'hh:mm t'); --> returns 03:46 P
Le format retourne l’heure spécifiée, affichant 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
Le format retourne l’heure spécifiée, affichant 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
Le format retourne l’heure spécifiée au format 24 heures.
SELECT FORMAT(CAST('2018-01-01 14:00' AS DATETIME2), N'HH:mm'); --> returns 14:00