FORMAT (Transact-SQL)

Articolo
11/04/2024

Si applica a: SQL Server database SQL di Azure Istanza gestita di SQL di Azure Azure Synapse Analytics Endpoint di analisi SQL in Microsoft Fabric Warehouse in Microsoft Fabric

Restituisce un valore formattato con il formato specificato e impostazioni cultura facoltative. Usare la funzione per la FORMAT formattazione compatibile con le impostazioni locali dei valori di data/ora e numero come stringhe. Per le conversioni generali dei tipi di dati, usare CAST o CONVERT.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

FORMAT( value , format [ , culture ] )

Argomenti

value

Espressione di un tipo di dati supportato da formattare. Per un elenco di tipi validi, vedere la tabella nella sezione Osservazioni .

format

Schema di formattazione nvarchar.

L'argomento format deve contenere una stringa di formato .NET Framework valida, ad esempio o come modello di caratteri personalizzati per date e valori numerici, ad esempio "C" "D""MMMM DD, yyyy (dddd)". La formattazione composita non è supportata.

Per una spiegazione completa di questi schemi di formattazione, vedere la documentazione di .NET Framework sulla formattazione di stringhe in formati di data e ora generali e personalizzati e in formati di numero personalizzati. Per altre informazioni, vedere Formattazione di tipi.

Impostazioni cultura

Argomento nvarchar facoltativo che specifica le impostazioni cultura.

Se l'argomento delle impostazioni cultura non viene specificato, viene usata la lingua della sessione corrente. Questo linguaggio viene impostato in modo implicito o esplicito usando l'istruzione SET LANGUAGE . le impostazioni cultura accettano impostazioni cultura supportate da .NET Framework come argomento. Non è limitato ai linguaggi supportati in modo esplicito da SQL Server. Se l'argomento delle impostazioni cultura non è valido, FORMAT genera un errore.

Tipi restituiti

nvarchar o Null

La lunghezza del valore restituito viene determinata da format.

Osservazioni:

FORMAT restituisce NULL per errori diversi da impostazioni cultura non valide. Ad esempio, NULL viene restituito se il valore specificato in formato non è valido.

La FORMAT funzione è non deterministica.

FORMAT si basa sulla presenza di .NET Framework Common Language Runtime (CLR).

Questa funzione non può essere remota perché dipende dalla presenza di CLR. L'esecuzione in modalità remota di una funzione che richiede CLR potrebbe provocare un errore sul server remoto.

FORMAT si basa su regole di formattazione CLR, che determinano che i due punti e i punti devono essere preceduti da un carattere di escape. Pertanto, quando la stringa di formato (secondo parametro) contiene due punti o punti, i due punti o il punto devono essere preceduti da un carattere di escape con barra rovesciata quando un valore di input (primo parametro) è del tipo di dati time . Vedere D. FORMAT con tipi di dati ora.

Nella tabella seguente vengono elencati i tipi di dati accettabili per l'argomento value, insieme con i tipi equivalenti di mapping per .NET Framework.

Categoria	Type	Tipo .NET
Numerico	bigint	`Int64`
Numerico	int	`Int32`
Numerico	smallint	`Int16`
Numerico	tinyint	`Byte`
Numerico	decimal	`SqlDecimal`
Numerico	numeric	`SqlDecimal`
Numeric	float	`Double`
Numerico	real	`Single`
Numerico	smallmoney	`Decimal`
Numerico	money	`Decimal`
Data e ora	date	`DateTime`
Data e ora	time	`TimeSpan`
Data e ora	datetime	`DateTime`
Data e ora	smalldatetime	`DateTime`
Data e ora	datetime2	`DateTime`
Data e ora	datetimeoffset	`DateTimeOffset`

Esempi

R. Esempio semplice di FORMAT

Nell'esempio seguente viene restituita una data semplice nel formato per impostazioni cultura diverse.

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

Il set di risultati è il seguente.

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 con stringhe di formattazione personalizzate

Nell'esempio seguente vengono illustrati i valori numerici di formattazione specificando un formato personalizzato. Nell'esempio si presuppone che la data corrente sia il 9 agosto 2024. Per altre informazioni su questi e altri formati personalizzati, vedere Stringhe di formato numerico personalizzato.

DECLARE @d AS DATE = GETDATE();

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

Il set di risultati è il seguente.

Date         Custom Number
-----------  --------------
09/08/2024   123-45-6789

C. FORMAT con tipi numerici

Nell'esempio seguente vengono restituite cinque righe della Sales.CurrencyRate tabella nel AdventureWorks2022 database. La colonna EndOfDateRate viene archiviata come tipo money nella tabella. In questo esempio, la colonna viene restituita senza formattazione e viene quindi formattata specificando i tipi di formato di numero, valuta e generico di .NET. Per altre informazioni su questi e altri formati numerici, vedere Stringhe di formato numerico 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;

Il set di risultati è il seguente.

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

In questo esempio vengono specificate le impostazioni cultura tedesche (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. D. FORMAT con tipi di dati ora

FORMAT restituisce NULL in questi casi perché . e : non sono preceduti da escape.

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 restituisce una stringa formattata in quanto . e : sono preceduti dal carattere di escape.

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 restituisce un'ora corrente formattata con AM o PM specificato.

SELECT FORMAT(SYSDATETIME(), N'hh:mm tt'); --> returns 03:46 PM
SELECT FORMAT(SYSDATETIME(), N'hh:mm t');  --> returns 03:46 P

Il formato restituisce l'ora specificata, visualizzando 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

Il formato restituisce l'ora specificata, visualizzando 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 restituisce l'ora specificata in formato 24 ore.

SELECT FORMAT(CAST('2018-01-01 14:00' AS DATETIME2), N'HH:mm'); --> returns 14:00

Condividi tramite

FORMAT (Transact-SQL)

Sintassi

Argomenti

value

format

Impostazioni cultura

Tipi restituiti

Osservazioni:

Esempi

R. Esempio semplice di FORMAT

B. FORMAT con stringhe di formattazione personalizzate

C. FORMAT con tipi numerici

D. D. FORMAT con tipi di dati ora

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

FORMAT (Transact-SQL)

Sintassi

Argomenti

value

format

Impostazioni cultura

Tipi restituiti

Osservazioni:

Esempi

R. Esempio semplice di FORMAT

B. FORMAT con stringhe di formattazione personalizzate

C. FORMAT con tipi numerici

D. D. FORMAT con tipi di dati ora

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive