FORMAT (Transact-SQL)FORMAT (Transact-SQL)

Anwendungsbereich:Applies to: JaSQL ServerSQL Server (alle unterstützten Versionen) yesSQL ServerSQL Server (all supported versions) JaAzure SQL-DatenbankAzure SQL DatabaseYesAzure SQL-DatenbankAzure SQL Database JaVerwaltete Azure SQL-InstanzAzure SQL Managed InstanceYesVerwaltete Azure SQL-InstanzAzure SQL Managed Instance JaAzure Synapse AnalyticsAzure Synapse AnalyticsyesAzure Synapse AnalyticsAzure Synapse AnalyticsAnwendungsbereich:Applies to: JaSQL ServerSQL Server (alle unterstützten Versionen) yesSQL ServerSQL Server (all supported versions) JaAzure SQL-DatenbankAzure SQL DatabaseYesAzure SQL-DatenbankAzure SQL Database JaVerwaltete Azure SQL-InstanzAzure SQL Managed InstanceYesVerwaltete Azure SQL-InstanzAzure SQL Managed Instance JaAzure Synapse AnalyticsAzure Synapse AnalyticsyesAzure Synapse AnalyticsAzure Synapse Analytics

Gibt einen mit dem angegebenen Format und der optionalen Kultur formatierten Wert zurück.Returns a value formatted with the specified format and optional culture. Verwenden Sie die FORMAT-Funktion für die gebietsschemabasierte Formatierung von Datums-/Uhrzeitwerten sowie numerischen Werten als Zeichenfolgen.Use the FORMAT function for locale-aware formatting of date/time and number values as strings. Für allgemeine Datentypkonvertierungen verwenden Sie CAST oder CONVERT.For general data type conversions, use CAST or CONVERT.

Symbol für Themenlink Transact-SQL-SyntaxkonventionenTopic link icon Transact-SQL Syntax Conventions

SyntaxSyntax

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.To view Transact-SQL syntax for SQL Server 2014 and earlier, see Previous versions documentation.

ArgumenteArguments

valuevalue
Ausdruck eines unterstützten Datentyps, der formatiert werden soll.Expression of a supported data type to format. Eine Liste gültiger Typen finden Sie in der Tabelle im folgenden Abschnitt mit Hinweisen.For a list of valid types, see the table in the following Remarks section.

formatformat
nvarchar -Formatmuster.nvarchar format pattern.

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)").The format argument must contain a valid .NET Framework format string, either as a standard format string (for example, "C" or "D"), or as a pattern of custom characters for dates and numeric values (for example, "MMMM DD, yyyy (dddd)"). Kombinierte Formatierung wird nicht unterstützt.Composite formatting is not supported. 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.For a full explanation of these formatting patterns, consult the .NET Framework documentation on string formatting in general, custom date and time formats, and custom number formats. Ein guter Ausgangspunkt ist das Thema zu "Formatierungstypen".A good starting point is the topic, "Formatting Types."

cultureculture
Optionales nvarchar -Argument, das eine Kultur angibt.Optional nvarchar argument specifying a culture.

Wenn das culture -Argument nicht angegeben wurde, wird die Sprache der aktuellen Sitzung verwendet.If the culture argument is not provided, the language of the current session is used. Diese Sprache ist entweder implizit definiert oder wird explizit mit der Anweisung SET LANGUAGE festgelegt.This language is set either implicitly, or explicitly by using the SET LANGUAGE statement. culture lässt alle von .NET Framework unterstützten Kulturen als Argument zu und ist auf die explizit durch SQL ServerSQL Server unterstützten Sprachen beschränkt.culture accepts any culture supported by the .NET Framework as an argument; it is not limited to the languages explicitly supported by SQL ServerSQL Server. Wenn das culture -Argument nicht gültig ist, löst FORMAT einen Fehler aus.If the culture argument is not valid, FORMAT raises an error.

RückgabetypenReturn Types

nvarchar oder NULL.nvarchar or null

Die Länge des Rückgabewerts wird von formatbestimmt.The length of the return value is determined by the format.

BemerkungenRemarks

FORMAT gibt bei Fehlern, bei denen es sich nicht um eine culture handelt, die nicht validist, NULL zurück.FORMAT returns NULL for errors other than a culture that is not valid. NULL wird z. B. zurückgegeben, wenn der in format angegebene Wert nicht gültig ist.For example, NULL is returned if the value specified in format is not valid.

Die FORMAT-Funktion ist nicht deterministisch.The FORMAT function is nondeterministic.

Für FORMAT muss die .NET Framework-Common Language Runtime (CLR) vorhanden sein.FORMAT relies on the presence of the .NET Framework Common Language Runtime (CLR).

Diese Funktion kann nicht remote ausgeführt werden, da sie die Existenz der CLR voraussetzt.This function cannot be remoted since it depends on the presence of the CLR. Die Remoteausführung einer Funktion, die die CLR erfordert, kann einen Fehler auf dem Remoteserver auslösen.Remoting a function that requires the CLR, could cause an error on the remote server.

FORMAT basiert auf den CLR-Formatierungsregeln, die vorgeben, dass Doppelpunkte und Punkte mit Escapezeichen versehen werden müssen.FORMAT relies upon CLR formatting rules, which dictate that colons and periods must be escaped. 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.Therefore, when the format string (second parameter) contains a colon or period, the colon or period must be escaped with backslash when an input value (first parameter) is of the time data type. Weitere Informationen finden Sie unter D: FORMAT mit time-Datentypen.See D. FORMAT with time data types.

In der folgenden Tabelle sind zulässige Datentypen für das value -Argument sowie die entsprechenden .NET Framework-Zuordnungstypen aufgeführt.The following table lists the acceptable data types for the value argument together with their .NET Framework mapping equivalent types.

CategoryCategory typeType .NET-Typ.NET type
NumericNumeric BIGINTbigint Int64Int64
NumericNumeric INTint Int32Int32
NumericNumeric SMALLINTsmallint Int16Int16
NumericNumeric TINYINTtinyint ByteByte
NumericNumeric Decimaldecimal SqlDecimalSqlDecimal
NumericNumeric NUMERICnumeric SqlDecimalSqlDecimal
NumericNumeric floatfloat DoubleDouble
NumericNumeric realreal SingleSingle
NumericNumeric SMALLMONEYsmallmoney DecimalDecimal
NumericNumeric moneymoney DecimalDecimal
Datum und UhrzeitDate and Time datedate DatetimeDateTime
Datum und UhrzeitDate and Time timetime TimeSpanTimeSpan
Datum und UhrzeitDate and Time datetimedatetime DatetimeDateTime
Datum und UhrzeitDate and Time smalldatetimesmalldatetime DatetimeDateTime
Datum und UhrzeitDate and Time datetime2datetime2 DatetimeDateTime
Datum und UhrzeitDate and Time datetimeoffsetdatetimeoffset DateTimeOffsetDateTimeOffset

BeispieleExamples

A.A. Einfaches Beispiel für FORMATSimple FORMAT example

Im folgenden Beispiel wird ein einfaches, für andere Kulturen formatiertes Datum zurückgegeben.The following example returns a simple date formatted for different cultures.

DECLARE @d DATETIME = '10/01/2011';  
SELECT FORMAT ( @d, 'd', 'en-US' ) AS 'US English Result'  
      ,FORMAT ( @d, 'd', 'en-gb' ) AS 'Great Britain English Result'  
      ,FORMAT ( @d, 'd', 'de-de' ) AS 'German Result'  
      ,FORMAT ( @d, 'd', 'zh-cn' ) AS 'Simplified Chinese (PRC) Result';
  
SELECT FORMAT ( @d, 'D', 'en-US' ) AS 'US English Result'  
      ,FORMAT ( @d, 'D', 'en-gb' ) AS 'Great Britain English Result'  
      ,FORMAT ( @d, 'D', 'de-de' ) AS 'German Result'  
      ,FORMAT ( @d, 'D', 'zh-cn' ) AS 'Chinese (Simplified PRC) Result';  

Hier ist das Resultset.Here is the result set.

US English Result Great Britain English Result  German Result Simplified Chinese (PRC) Result  
----------------  ----------------------------- ------------- -------------------------------------  
10/1/2011         01/10/2011                    01.10.2011    2011/10/1  
  
(1 row(s) affected)  
  
US English Result            Great Britain English Result  German Result                    Chinese (Simplified PRC) Result  
---------------------------- ----------------------------- -----------------------------  ---------------------------------------  
Saturday, October 01, 2011   01 October 2011               Samstag, 1. Oktober 2011        2011年10月1日  
  
(1 row(s) affected)  

B.B. FORMAT mit benutzerdefinierten FormatierungszeichenfolgenFORMAT with custom formatting strings

Im folgenden Beispiel ist das Formatieren von numerischen Werten durch Angeben eines benutzerdefinierten Formats dargestellt.The following example shows formatting numeric values by specifying a custom format. Im Beispiel wird davon ausgegangen, dass das aktuelle Datum der 27. September 2012 ist.The example assumes that the current date is September 27, 2012. Weitere Informationen zu diesen und anderen benutzerdefinierten Formaten finden Sie unter Benutzerdefinierte Zahlenformatzeichenfolgen.For more information about these and other custom formats, see Custom Numeric Format Strings.

DECLARE @d DATETIME = GETDATE();  
SELECT FORMAT( @d, 'dd/MM/yyyy', 'en-US' ) AS 'DateTime Result'  
       ,FORMAT(123456789,'###-##-####') AS 'Custom Number Result';  

Hier ist das Resultset.Here is the result set.

DateTime Result  Custom Number Result  
--------------   --------------------  
27/09/2012       123-45-6789  
  
(1 row(s) affected)  

C.C. FORMAT mit numerischen TypenFORMAT with numeric types

Im folgenden Beispiel werden fünf Zeilen aus der Sales.CurrencyRate-Tabelle in der AdventureWorks2012AdventureWorks2012-Datenbank zurückgegeben.The following example returns 5 rows from the Sales.CurrencyRate table in the AdventureWorks2012AdventureWorks2012 database. Die Spalte EndOfDateRate wird als money -Typ in der Tabelle gespeichert.The column EndOfDateRate is stored as type money in the table. 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.In this example, the column is returned unformatted and then formatted by specifying the .NET Number format, General format, and Currency format types. Weitere Informationen zu diesen und anderen Zahlenformaten finden Sie unter Benutzerdefinierte Zahlenformatzeichenfolgen.For more information about these and other numeric formats, see Standard Numeric Format Strings.

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.Here is the result set.

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  
  
(5 row(s) affected)  
  

In diesem Beispiel wird die Kultur "Deutsch" (de-de) angegeben.This example specifies the German culture (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 €  
  
 (5 row(s) affected)  

D.D. FORMAT mit time-DatentypenFORMAT with time data types

FORMAT gibt in diesen Fällen NULL zurück, da . und : nicht mit Escapezeichen versehen sind.FORMAT returns NULL in these cases because . and : are not escaped.

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.Format returns a formatted string because the . and : are escaped.

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.Format returns a formatted current time with AM or PM specified

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.Format returns the specified time, displaying 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 gibt die angegebene Uhrzeit mit der Angabe PM zurück.Format returns the specified time, displaying 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 gibt die angegebene Uhrzeit im 24-Stunden-Format zurück.Format returns the specified time in 24h format

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

Weitere InformationenSee Also