FORMAT (Transact-SQL)

Anwendungsbereich: JaSQL Server (alle unterstützten Versionen) JaAzure SQL-Datenbank JaVerwaltete Azure SQL-Instanz JaAzure Synapse Analytics

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

Symbol für Themenlink Transact-SQL-Syntaxkonventionen

Syntax

FORMAT( value, format [, culture ] )  

Hinweis

Informationen zum Anzeigen der Transact-SQL-Syntax für SQL Server 2014 oder 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 folgenden Abschnitt mit Hinweisen.

format
nvarchar -Formatmuster.

Das format -Argument muss eine gültige .NET Framework-Formatzeichenfolge enthalten, entweder als Standardformatzeichenfolge (z. B. "C" oder "D") oder als ein Muster aus benutzerdefinierten Zeichen für Datumsangaben und numerische Werte (z. B. "MMMM-DD, yyyy (dddd)"). Kombinierte Formatierung wird 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. Ein guter Ausgangspunkt ist das Thema zu "Formatierungstypen".

culture
Optionales nvarchar -Argument, das eine Kultur angibt.

Wenn das culture -Argument nicht angegeben wurde, wird die Sprache der aktuellen Sitzung verwendet. Diese Sprache ist entweder implizit definiert oder wird explizit mit der Anweisung SET LANGUAGE festgelegt. culture lässt alle von .NET Framework unterstützten Kulturen als Argument zu und ist auf die explizit durch SQL Server unterstützten Sprachen beschränkt. Wenn das culture -Argument nicht gültig ist, löst FORMAT einen Fehler aus.

Rückgabetypen

nvarchar oder NULL.

Die Länge des Rückgabewerts wird von format bestimmt.

Bemerkungen

FORMAT gibt bei Fehlern, bei denen es sich nicht um eine culture handelt, die nicht valid ist, NULL zurück. NULL wird z. B. zurückgegeben, wenn der in format angegebene Wert nicht gültig ist.

Die FORMAT-Funktion ist nicht deterministisch.

Für FORMAT muss die .NET Framework-Common Language Runtime (CLR) vorhanden sein.

Diese Funktion kann nicht remote ausgeführt werden, da sie die Existenz der CLR voraussetzt. Die Remoteausführung einer Funktion, die die CLR erfordert, kann einen Fehler auf dem Remoteserver auslösen.

FORMAT basiert auf den CLR-Formatierungsregeln, die vorgeben, dass Doppelpunkte und Punkte mit Escapezeichen versehen werden müssen. Wenn die Formatzeichenfolge (der zweite Parameter) einen Doppelpunkt oder Punkt enthält, muss dieser daher mit einem umgekehrten Schrägstrich versehen werden, wenn ein Eingabewert (erster Parameter) den Datentyp time 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' ) 'Great Britain English'  
      ,FORMAT( @d, 'd', 'de-de' ) 'German'  
      ,FORMAT( @d, 'd', 'zh-cn' ) 'Simplified Chinese (PRC)';  
  
SELECT FORMAT( @d, 'D', 'en-US' ) 'US English'  
      ,FORMAT( @d, 'D', 'en-gb' ) 'Great Britain English'  
      ,FORMAT( @d, 'D', 'de-de' ) 'German'  
      ,FORMAT( @d, 'D', 'zh-cn' ) 'Chinese (Simplified PRC)';  

Hier ist das Resultset.

US English  Great Britain English German     Simplified Chinese (PRC)  
----------  --------------------- ---------- ------------------------  
11/22/2020  22/11/2020            22.11.2020 2020/11/22 
  
US English                  Great Britain English  German                      Chinese (Simplified PRC)  
--------------------------- ---------------------- --------------------------  ---------------------------------------  
Sunday, November 22, 2020   22 November 2020       Sonntag, 22. November 2020  2020年11月22日  
  

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 27. September 2012 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  
----------  -------------  
22/11/2020  123-45-6789  
  

C. FORMAT mit numerischen Typen

Im folgenden Beispiel werden fünf Zeilen aus der Sales.CurrencyRate-Tabelle in der AdventureWorks2012-Datenbank zurückgegeben. Die Spalte EndOfDateRate wird als money -Typ 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 'Number 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 Kultur "Deutsch" (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 €  
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 mit time-Datentypen

FORMAT gibt in diesen Fällen NULL zurück, da . und : nicht mit Escapezeichen versehen 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 mit Angabe von AM oder PM zurück.

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 mit der Angabe AM zurück.

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 mit der Angabe PM zurück.

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

Weitere Informationen