FORMAT (Transact-SQL)
S’applique à :
SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsPoint de terminaison analytique SQL dans Microsoft FabricEntrepôt dans Microsoft Fabric
Retourne une valeur mise en forme avec la culture facultative et le format spécifiés. 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 ] )
Remarque
Pour afficher la syntaxe Transact-SQL pour SQL Server 2014 (12.x) et versions antérieures, consultez Versions antérieures de la documentation.
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 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. La rubrique « Types de mise en forme » constitue un bon point de départ.
culture
Argument nvarchar facultatif spécifiant une culture.
Si l’argument culture n’est pas fourni, la langue de la session en cours est utilisée. Cette langue est défini implicitement, ou explicitement à l'aide de l'instruction SET LANGAGE. culture accepte n’importe quelle culture prise en charge par le .NET Framework comme argument ; elle n’est pas limitée aux langues explicitement prises en charge par SQL Server. Si l’argument culture n’est pas valide, FORMAT génère 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 pour des erreurs autres qu’un argument culture non valide. Par exemple, la valeur NULL est renvoyée si la valeur spécifiée dans format n’est pas valide.
La fonction FORMAT est non déterministe.
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 peut provoquer une erreur sur le serveur distant.
FORMAT repose sur les règles de mise en forme CLR, qui exigent l’échappement des deux-points et des points. Par conséquent, lorsque la chaîne format (second paramètre) contient un signe deux-points ou point, le signe deux-points ou point doit être précédé d’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 | Décimal | SqlDecimal |
| Numérique | numeric | SqlDecimal |
| Numérique | float | Double |
| Numérique | real | Unique |
| 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)
---------- --------------------- ---------- ------------------------
11/22/2020 22/11/2020 22.11.2020 2020/11/22
US English British English German Chinese (Simplified PRC)
--------------------------- ---------------------- -------------------------- ---------------------------------------
Sunday, November 22, 2020 22 November 2020 Sonntag, 22. November 2020 2020年11月22日
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 22 novembre 2020. 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
---------- -------------
22/11/2020 123-45-6789
C. FORMAT avec types numériques
L’exemple suivant retourne 5 lignes de la table Sales.CurrencyRate dans la base de données AdventureWorks2022. 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.
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 €
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 la valeur NULL dans ces cas, car . 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
Format retourne l’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
Format retourne l’heure spécifiée, en 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
Format retourne l’heure spécifiée, en 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
Format retourne l’heure spécifiée, au format de 24h
select FORMAT(CAST('2018-01-01 14:00' AS datetime2), N'HH:mm') -- returns 14:00
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour