FORMAT (Transact-SQL)

Применимо к:SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure Конечная точка аналитики Synapse Analyticsв Хранилище Microsoft Fabric в Microsoft Fabric

Возвращает значение в указанных формате и культуре (не обязательно). Для выполнения форматирования значения даты, времени и чисел с учетом локали в виде строк используется функция FORMAT. Для общих преобразований типов данных продолжайте использовать CAST и CONVERT.

Соглашения о синтаксисе Transact-SQL

Синтаксис

FORMAT( value, format [, culture ] )  

Примечание.

Сведения о синтаксисе Transact-SQL для SQL Server 2014 (12.x) и более ранних версиях см . в документации по предыдущим версиям.

Аргументы

значение
Выражение поддерживаемого типа данных для форматирования. Список допустимых типов см. в таблице в последующем разделе «Примечания».

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

Аргумент format должен содержать допустимую строку формата .NET Framework в виде стандартной строки формата (например, "C" или "D") либо в виде шаблона пользовательских символов, обозначающих даты и числовые значения (например, "ММММ ДД, гггг (дддд)"). Составное форматирование не поддерживается. Полные сведения об этих шаблонах форматирования приведены в разделах документации по .NET Framework, посвященных форматированию строк в целом, пользовательским форматам даты и времени, а также пользовательским форматам чисел. Хорошей отправной точкой является раздел Типы форматирования.

Язык и региональные параметры
Необязательный аргумент nvarchar, обозначающий язык и региональные параметры.

Если аргумент culture не указан, то используется язык текущего сеанса. Язык может быть задан неявно или явно с использованием инструкции SET LANGUAGE. язык и региональные параметры, поддерживаемые платформа .NET Framework в качестве аргумента, не ограничиваются языками, явно поддерживаемыми SQL Server. Если аргумент culture недопустим, то FORMAT выдаст ошибку.

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

nvarchar или NULL

Длина возвращаемого значения определяется аргументом format.

Замечания

Функция FORMAT возвращает значение NULL для ошибок, когда culture не является valid. Например, NULL возвращается, если значение, заданное в format, недопустимо.

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

Функция FORMAT предполагает наличие среды выполнения CLR платформы .NET Framework.

Эта функция не может работать удаленно, так как возможность ее работы зависит от наличия среды CLR. Удаленный вызов функции, требующей наличия среды CLR, может привести к ошибке на удаленном сервере.

Функция FORMAT использует правила форматирования среды CLR, согласно которым двоеточия и точки должны экранироваться. Поэтому когда строка форматирования (второй параметр) содержит двоеточие или точку, они должны быть экранированы обратной косой чертой, если входное значение (первый параметр) имеет тип данных time. См. пример Г. Использование функции FORMAT с типами данных времени.

В приведенной ниже таблице перечислены приемлемые типы данных для аргумента value, а также содержатся сведения об их сопоставлении с эквивалентными типами .NET Framework.

Категория Тип Тип .NET
Числовое bigint Int64
Числовое INT Int32
Числовое smallint Int16
Числовое tinyint Байт
Числовое десятичное SqlDecimal
Числовое numeric SqlDecimal
Числовое с плавающей запятой Двойной
Числовое real Одна
Числовое smallmoney Decimal
Числовое money Decimal
Дата и время Дата Дата/время
Дата и время время TimeSpan
Дата и время datetime Дата/время
Дата и время smalldatetime Дата/время
Дата и время datetime2 Дата/время
Дата и время datetimeoffset DateTimeOffset

Примеры

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

В следующем примере возвращается простой набор данных, отформатированный для различных языков и региональных параметров.

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

Результирующий набор:

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

B. Функция FORMAT с пользовательскими строками форматирования

В следующем примере показано форматирование числовых значений с помощью заданного пользовательского формата. В примере предполагается, что текущая дата — 22 ноября 2020 г. Дополнительные сведения об этих и других пользовательских форматах см. в статье Пользовательские строки форматирования чисел.

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

Результирующий набор:

Date        Custom Number  
----------  -------------  
22/11/2020  123-45-6789  
  

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

В следующем примере возвращается 5 строк из таблицы Sales.CurrencyRate в базе данных AdventureWorks2022. Столбец EndOfDateRate в таблице хранится как тип money. В этом примере столбец возвращается неформатированным, затем форматируется в формате .NET Number, формате типа General и Currency. Дополнительные сведения об этих и других числовых форматах см. в статье Стандартные строки форматирования чисел.

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;  

Результирующий набор:

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  
  

Этот пример задает немецкий язык и региональные параметры (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 €  
  

D. Использование функции FORMAT с типами данных времени

В этих случаях функция FORMAT возвращает значение NULL, так как символы . и : не экранированы.

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

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 или PM

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

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

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

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

См. также