FORMAT (Transact-SQL)
Область применения: SQL Server
База данных SQL Azure
Управляемый экземпляр 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.
Аргумент формата должен содержать допустимую строку форматирования платформа .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 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)
----------- ---------------- ----------- -------------------------
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 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
C. Функция 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 €
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