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

Применимо к:Applies to: даSQL ServerSQL Server (все поддерживаемые версии) yesSQL ServerSQL Server (all supported versions) ДаБаза данных SQL AzureAzure SQL DatabaseYesБаза данных SQL AzureAzure SQL Database ДаУправляемый экземпляр SQL AzureAzure SQL Managed InstanceYesУправляемый экземпляр SQL AzureAzure SQL Managed Instance даAzure Synapse AnalyticsAzure Synapse AnalyticsyesAzure Synapse AnalyticsAzure Synapse AnalyticsПрименимо к:Applies to: даSQL ServerSQL Server (все поддерживаемые версии) yesSQL ServerSQL Server (all supported versions) ДаБаза данных SQL AzureAzure SQL DatabaseYesБаза данных SQL AzureAzure SQL Database ДаУправляемый экземпляр SQL AzureAzure SQL Managed InstanceYesУправляемый экземпляр SQL AzureAzure SQL Managed Instance даAzure Synapse AnalyticsAzure Synapse AnalyticsyesAzure Synapse AnalyticsAzure Synapse Analytics

Возвращает значение в указанных формате и культуре (не обязательно).Returns a value formatted with the specified format and optional culture. Для выполнения форматирования значения даты, времени и чисел с учетом локали в виде строк используется функция FORMAT.Use the FORMAT function for locale-aware formatting of date/time and number values as strings. Для общих преобразований типов данных продолжайте использовать CAST и CONVERT.For general data type conversions, use CAST or CONVERT.

Значок ссылки на раздел Синтаксические обозначения в Transact-SQLTopic link icon Transact-SQL Syntax Conventions

СинтаксисSyntax

FORMAT ( value, format [, culture ] )  

Примечание

Ссылки на описание синтаксиса Transact-SQL для SQL Server 2014 и более ранних версий, см. в статье Документация по предыдущим версиям.To view Transact-SQL syntax for SQL Server 2014 and earlier, see Previous versions documentation.

АргументыArguments

valuevalue
Выражение поддерживаемого типа данных для форматирования.Expression of a supported data type to format. Список допустимых типов см. в таблице в последующем разделе «Примечания».For a list of valid types, see the table in the following Remarks section.

formatformat
Шаблон формата nvarchar.nvarchar format pattern.

Аргумент format должен содержать допустимую строку формата .NET Framework в виде стандартной строки формата (например, "C" или "D") либо в виде шаблона пользовательских символов, обозначающих даты и числовые значения (например, "ММММ ДД, гггг (дддд)").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)"). Составное форматирование не поддерживается.Composite formatting is not supported. Полные сведения об этих шаблонах форматирования приведены в разделах документации по .NET Framework, посвященных форматированию строк в целом, пользовательским форматам даты и времени, а также пользовательским форматам чисел.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. Хорошей отправной точкой является раздел Типы форматирования.A good starting point is the topic, "Formatting Types."

cultureculture
Необязательный аргумент nvarchar, обозначающий язык и региональные параметры.Optional nvarchar argument specifying a culture.

Если аргумент culture не указан, то используется язык текущего сеанса.If the culture argument is not provided, the language of the current session is used. Язык может быть задан неявно или явно с использованием инструкции SET LANGUAGE.This language is set either implicitly, or explicitly by using the SET LANGUAGE statement. В качестве аргумента culture принимает любой язык и региональные параметры, поддерживаемые .NET Framework; его применение не ограничивается языками, поддерживаемыми SQL ServerSQL Server.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. Если аргумент culture недопустим, то FORMAT выдаст ошибку.If the culture argument is not valid, FORMAT raises an error.

Типы возвращаемых данныхReturn Types

nvarchar или NULLnvarchar or null

Длина возвращаемого значения определяется аргументом format.The length of the return value is determined by the format.

RemarksRemarks

Функция FORMAT возвращает значение NULL для ошибок, когда culture не является valid.FORMAT returns NULL for errors other than a culture that is not valid. Например, NULL возвращается, если значение, заданное в format, недопустимо.For example, NULL is returned if the value specified in format is not valid.

Функция FORMAT не детерминирована.The FORMAT function is nondeterministic.

Функция FORMAT предполагает наличие среды выполнения CLR платформы .NET Framework.FORMAT relies on the presence of the .NET Framework Common Language Runtime (CLR).

Эта функция не может работать удаленно, так как возможность ее работы зависит от наличия среды CLR.This function cannot be remoted since it depends on the presence of the CLR. Удаленный вызов функции, требующей наличия среды CLR, может привести к ошибке на удаленном сервере.Remoting a function that requires the CLR, could cause an error on the remote server.

Функция FORMAT использует правила форматирования среды CLR, согласно которым двоеточия и точки должны экранироваться.FORMAT relies upon CLR formatting rules, which dictate that colons and periods must be escaped. Поэтому когда строка форматирования (второй параметр) содержит двоеточие или точку, они должны быть экранированы обратной косой чертой, если входное значение (первый параметр) имеет тип данных time.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. См. пример Г. Использование функции FORMAT с типами данных времени.See D. FORMAT with time data types.

В приведенной ниже таблице перечислены приемлемые типы данных для аргумента value, а также содержатся сведения об их сопоставлении с эквивалентными типами .NET Framework.The following table lists the acceptable data types for the value argument together with their .NET Framework mapping equivalent types.

КатегорияCategory ТипType Тип .NET.NET type
ЧисловойNumeric BIGINTbigint Int64Int64
ЧисловойNumeric INTint Int32Int32
ЧисловойNumeric smallintsmallint Int16Int16
ЧисловойNumeric tinyinttinyint ByteByte
ЧисловойNumeric Decimaldecimal SqlDecimalSqlDecimal
ЧисловойNumeric NUMERICnumeric SqlDecimalSqlDecimal
ЧисловойNumeric FLOATfloat DoubleDouble
ЧисловойNumeric realreal ОдинSingle
ЧисловойNumeric smallmoneysmallmoney DecimalDecimal
ЧисловойNumeric moneymoney DecimalDecimal
Дата и времяDate and Time Датаdate Дата и времяDateTime
Дата и времяDate and Time timetime TimeSpanTimeSpan
Дата и времяDate and Time DATETIMEdatetime Дата и времяDateTime
Дата и времяDate and Time smalldatetimesmalldatetime Дата и времяDateTime
Дата и времяDate and Time datetime2datetime2 Дата и времяDateTime
Дата и времяDate and Time datetimeoffsetdatetimeoffset DateTimeOffsetDateTimeOffset

ПримерыExamples

A.A. Простой пример функции FORMATSimple FORMAT example

В следующем примере возвращается простой набор данных, отформатированный для различных языков и региональных параметров.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';  

Результирующий набор: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. Функция FORMAT с пользовательскими строками форматированияFORMAT with custom formatting strings

В следующем примере показано форматирование числовых значений с помощью заданного пользовательского формата.The following example shows formatting numeric values by specifying a custom format. В примере предполагается, что текущая дата — 27 сентября 2012 г.The example assumes that the current date is September 27, 2012. Дополнительные сведения об этих и других пользовательских форматах см. в статье Пользовательские строки форматирования чисел.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';  

Результирующий набор:Here is the result set.

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

В.C. Функция FORMAT с числовыми типамиFORMAT with numeric types

В приведенном ниже примере возвращаются 5 строк из таблицы Sales.CurrencyRate в базе данных AdventureWorks2012AdventureWorks2012.The following example returns 5 rows from the Sales.CurrencyRate table in the AdventureWorks2012AdventureWorks2012 database. Столбец EndOfDateRate в таблице хранится как тип money.The column EndOfDateRate is stored as type money in the table. В этом примере столбец возвращается неформатированным, затем форматируется в формате .NET Number, формате типа General и Currency.In this example, the column is returned unformatted and then formatted by specifying the .NET Number format, General format, and Currency format types. Дополнительные сведения об этих и других числовых форматах см. в статье Стандартные строки форматирования чисел.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;  

Результирующий набор: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)  
  

Этот пример задает немецкий язык и региональные параметры (de-de).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. Использование функции FORMAT с типами данных времениFORMAT with time data types

В этих случаях функция FORMAT возвращает значение NULL, так как символы . и : не экранированы.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 возвращает форматированную строку, так как символы . и : экранированы.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  

Формат возвращает текущее время в формате с AM или PMFormat 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

Формат возвращает заданное время с AMFormat 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

Формат возвращает заданное время с PMFormat 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

Формат возвращает заданное время в 24-часовом форматеFormat returns the specified time in 24h format

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

См. также:See Also