FORMAT (Transact-SQL)

Статья
11/04/2024

Область применения: SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure конечную точку аналитики SQL Azure Synapse Analytics в хранилище Microsoft Fabric в Microsoft Fabric

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

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

Синтаксис

FORMAT( value , format [ , culture ] )

Аргументы

значение

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

format

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

Аргумент формата должен содержать допустимую строку форматирования платформа .NET Framework как стандартную строку формата (например, "C" или"D") или в виде шаблона пользовательских символов для дат и числовых значений (например, "MMMM DD, yyyy (dddd)"). Составное форматирование не поддерживается.

Полные сведения об этих шаблонах форматирования приведены в разделах документации по .NET Framework, посвященных форматированию строк в целом, пользовательским форматам даты и времени, а также пользовательским форматам чисел. Дополнительные сведения см. в статье Типы форматирования в .NET.

Язык и региональные параметры

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

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

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

nvarchar или NULL

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

Замечания

FORMATвозвращает NULL ошибки, отличные от языка и региональных параметров, которые недопустимы. Например, возвращается, NULL если значение, указанное в формате , недопустимо.

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

FORMATзависит от наличия среды CLR платформа .NET Framework.

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

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

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

Категория	Тип	Тип .NET
Числовое	bigint	`Int64`
Числовое	int	`Int32`
Числовое	smallint	`Int16`
Числовое	tinyint	`Byte`
Числовое	десятичное	`SqlDecimal`
Числовое	numeric	`SqlDecimal`
Числовое	float	`Double`
Числовое	real	`Single`
Числовое	smallmoney	`Decimal`
Числовое	money	`Decimal`
Дата и время	date	`DateTime`
Дата и время	time	`TimeSpan`
Дата и время	datetime	`DateTime`
Дата и время	smalldatetime	`DateTime`
Дата и время	datetime2	`DateTime`
Дата и время	datetimeoffset	`DateTimeOffset`

Примеры

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

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

DECLARE @d AS DATE = '11/22/2020';

SELECT FORMAT(@d, 'd', 'en-US') AS 'US English',
       FORMAT(@d, 'd', 'en-gb') AS 'British English',
       FORMAT(@d, 'd', 'de-de') AS 'German',
       FORMAT(@d, 'd', 'zh-cn') AS 'Chinese Simplified (PRC)';

SELECT FORMAT(@d, 'D', 'en-US') AS 'US English',
       FORMAT(@d, 'D', 'en-gb') AS 'British English',
       FORMAT(@d, 'D', 'de-de') AS 'German',
       FORMAT(@d, 'D', 'zh-cn') AS 'Chinese Simplified (PRC)';

Вот результирующий набор.

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 с пользовательскими строками форматирования

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

DECLARE @d AS DATE = GETDATE();

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

Вот результирующий набор.

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

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

В следующем примере возвращаются пять строк из Sales.CurrencyRate таблицы в AdventureWorks2022 базе данных. Столбец EndOfDateRate хранится в виде денег типа в таблице. В этом примере столбец возвращается неформатированным, затем форматируется в формате .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 &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 с типами данных времени

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

Поделиться через

FORMAT (Transact-SQL)

Синтаксис

Аргументы

значение

format

Язык и региональные параметры

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

Замечания

Примеры

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

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

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

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

Обратная связь

Дополнительные ресурсы

Поделиться через

FORMAT (Transact-SQL)

Синтаксис

Аргументы

значение

format

Язык и региональные параметры

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

Замечания

Примеры

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

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

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

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

Связанный контент

Обратная связь

Дополнительные ресурсы