FORMAT (Transact-SQL)

Artikel
08/13/2024

Gilt für: SQL Server Azure SQL-Datenbank Azure SQL Managed Instance Azure Synapse Analytics SQL Analytics-Endpunkt in Microsoft Fabric Warehouse in Microsoft Fabric

Gibt einen mit dem angegebenen Format und der optionalen Kultur formatierten Wert zurück. Verwenden Sie die Funktion für gebietsschemabezogene FORMAT Formatierung von Datums-/Uhrzeit- und Zahlenwerten als Zeichenfolgen. Für allgemeine Datentypkonvertierungen verwenden CAST oder CONVERT.

Transact-SQL-Syntaxkonventionen

Syntax

FORMAT( value , format [ , culture ] )

Hinweis

Informationen zum Anzeigen der Transact-SQL-Syntax für SQL Server 2014 (12.x) und früher finden Sie unter Dokumentation zu früheren Versionen.

Argumente

value

Ausdruck eines unterstützten Datentyps, der formatiert werden soll. Eine Liste gültiger Typen finden Sie in der Tabelle im Abschnitt "Hinweise ".

format

nvarchar -Formatmuster.

Das Formatargument muss eine gültige .NET Framework-Formatzeichenfolge enthalten, entweder als Standardformatzeichenfolge (z "C" . B. oder "D") oder als Muster von benutzerdefinierten Zeichen für Datumsangaben und numerische Werte (z. B "MMMM DD, yyyy (dddd)". ). Zusammengesetzte Formatierungen werden nicht unterstützt.

Ausführliche Erläuterungen zu diesen Formatierungsmustern können Sie der .NET Framework-Dokumentation zur allgemeinen Zeichenfolgenformatierung sowie zu benutzerdefinierten Datums- und Uhrzeitformaten und benutzerdefinierten Zahlenformaten entnehmen. Weitere Informationen finden Sie unter Formatieren von Typen in .NET.

culture

Optionales nvarchar -Argument, das eine Kultur angibt.

Wenn das Kulturargument nicht angegeben wird, wird die Sprache der aktuellen Sitzung verwendet. Diese Sprache wird entweder implizit oder explizit mithilfe der SET LANGUAGE Anweisung festgelegt. kultur akzeptiert jede Kultur, die von .NET Framework als Argument unterstützt wird. Sie ist nicht auf die sprachen beschränkt, die von SQL Server explizit unterstützt werden. Wenn das Kulturargument ungültig ist, FORMAT wird ein Fehler ausgelöst.

Rückgabetypen

nvarchar oder NULL.

Die Länge des Rückgabewerts wird von formatbestimmt.

Hinweise

FORMATgibt für andere Fehler als eine ungültige Kultur zurückNULL. Wird beispielsweise zurückgegeben, NULL wenn der im Format angegebene Wert ungültig ist.

Die FORMAT Funktion ist nicht deterministisch.

FORMAT basiert auf dem Vorhandensein der .NET Framework Common Language Runtime (CLR).

Diese Funktion kann nicht entfernt werden, da sie vom Vorhandensein der CLR abhängt. Die Remoteausführung einer Funktion, die die CLR erfordert, kann einen Fehler auf dem Remoteserver auslösen.

FORMAT basiert auf CLR-Formatierungsregeln, die diktieren, dass Doppelpunkte und Punkte escapen müssen. Wenn daher die Formatzeichenfolge (zweiter Parameter) einen Doppelpunkt oder Punkt enthält, muss der Doppelpunkt oder punkt mit umgekehrtem Schrägstrich escapet werden, wenn ein Eingabewert (erster Parameter) den Zeitdatentyp aufweist. Weitere Informationen finden Sie unter D: FORMAT mit time-Datentypen.

In der folgenden Tabelle sind zulässige Datentypen für das value -Argument sowie die entsprechenden .NET Framework-Zuordnungstypen aufgeführt.

Category	type	.NET-Typ
Numeric	bigint	`Int64`
Numeric	int	`Int32`
Numeric	smallint	`Int16`
Numeric	tinyint	`Byte`
Numeric	decimal	`SqlDecimal`
Numeric	numeric	`SqlDecimal`
Numeric	float	`Double`
Numeric	real	`Single`
Numeric	smallmoney	`Decimal`
Numeric	money	`Decimal`
Datum und Uhrzeit	date	`DateTime`
Datum und Uhrzeit	time	`TimeSpan`
Datum und Uhrzeit	datetime	`DateTime`
Datum und Uhrzeit	smalldatetime	`DateTime`
Datum und Uhrzeit	datetime2	`DateTime`
Datum und Uhrzeit	datetimeoffset	`DateTimeOffset`

Beispiele

A. Einfaches Beispiel für FORMAT

Im folgenden Beispiel wird ein einfaches, für andere Kulturen formatiertes Datum zurückgegeben.

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

Hier ist das Resultset.

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 mit benutzerdefinierten Formatierungszeichenfolgen

Im folgenden Beispiel ist das Formatieren von numerischen Werten durch Angeben eines benutzerdefinierten Formats dargestellt. Im Beispiel wird davon ausgegangen, dass das aktuelle Datum der 9. August 2024 ist. Weitere Informationen zu diesen und anderen benutzerdefinierten Formaten finden Sie unter Benutzerdefinierte Zahlenformatzeichenfolgen.

DECLARE @d DATE = GETDATE();

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

Hier ist das Resultset.

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

C. FORMAT mit numerischen Typen

Im folgenden Beispiel werden fünf Zeilen aus der Tabelle in der Sales.CurrencyRate AdventureWorks2022 Datenbank zurückgegeben. Die Spalte EndOfDateRate wird als Typgeld in der Tabelle gespeichert. In diesem Beispiel wird die Spalte unformatiert zurückgegeben und wird dann durch Angeben der Typen für das .NET-Zahlenformat, das allgemeine Format und das Währungsformat formatiert. Weitere Informationen zu diesen und anderen Zahlenformaten finden Sie unter Benutzerdefinierte Zahlenformatzeichenfolgen.

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;

Hier ist das Resultset.

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 diesem Beispiel wird die deutsche Kultur (de-de) angegeben.

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 mit time-Datentypen

FORMAT gibt in diesen Fällen zurück NULL , da . sie : nicht escaped sind.

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 gibt eine formatierte Zeichenfolge zurück, da . und : mit Escapezeichen versehen sind.

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 gibt eine formatierte aktuelle Uhrzeit zurück, wobei AM oder PM angegeben ist.

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

Format gibt die angegebene Uhrzeit zurück, wobei AM angezeigt wird.

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 gibt die angegebene Uhrzeit zurück, wobei PM angezeigt wird.

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 gibt die angegebene Uhrzeit im 24-Stunden-Format zurück.

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

Teilen über

FORMAT (Transact-SQL)

Syntax

Argumente

value

format

culture

Rückgabetypen

Hinweise

Beispiele

A. Einfaches Beispiel für FORMAT

B. FORMAT mit benutzerdefinierten Formatierungszeichenfolgen

C. FORMAT mit numerischen Typen

D: FORMAT mit time-Datentypen

Feedback

Zusätzliche Ressourcen

Teilen über

FORMAT (Transact-SQL)

Syntax

Argumente

value

format

culture

Rückgabetypen

Hinweise

Beispiele

A. Einfaches Beispiel für FORMAT

B. FORMAT mit benutzerdefinierten Formatierungszeichenfolgen

C. FORMAT mit numerischen Typen

D: FORMAT mit time-Datentypen

Zugehöriger Inhalt

Feedback

Zusätzliche Ressourcen