FORMAT (Transact-SQL)

Article
08/13/2024

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 ] )

Remarque

Pour afficher la syntaxe Transact-SQL pour SQL Server 2014 (12.x) et versions antérieures, consultez la Documentation sur les versions antérieures.

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

Voici le jeu de résultats obtenu.

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 DATE = GETDATE();

SELECT FORMAT(@d, 'dd/MM/yyyy', 'en-US') AS 'Date',
    FORMAT(123456789, '###-##-####') AS 'Custom Number';

Voici le jeu de résultats obtenu.

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 obtenu.

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 &euro;
2              1.55          1,55            1,5500          1,55 &euro;
3              1.9419        1,94            1,9419          1,94 &euro;
4              1.4683        1,47            1,4683          1,47 &euro;
5              8.2784        8,28            8,2784          8,28 &euro;

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

Partage via

FORMAT (Transact-SQL)

Syntaxe

Arguments

value

format

culture

Types de retour

Notes

Exemples

R. Exemple FORMAT simple

B. FORMAT avec chaînes de format personnalisées

C. FORMAT avec types numériques

D. FORMAT avec types de données time

Commentaires

Ressources supplémentaires

Partage via

FORMAT (Transact-SQL)

Syntaxe

Arguments

value

format

culture

Types de retour

Notes

Exemples

R. Exemple FORMAT simple

B. FORMAT avec chaînes de format personnalisées

C. FORMAT avec types numériques

D. FORMAT avec types de données time

Contenu connexe

Commentaires

Ressources supplémentaires