FORMAT (Transact-SQL)

项目
05/23/2023

适用于：SQL Server Azure SQL 数据库 Azure SQL 托管实例 Azure Synapse Analytics Microsoft Fabric 中的 SQL 分析终结点 Microsoft Fabric 中的仓库

返回以指定的格式和可选的区域性格式化的值。使用 FORMAT 函数将日期/时间和数字值格式化为识别区域设置的字符串。对于一般的数据类型转换，请使用 CAST 或 CONVERT。

语法

FORMAT( value, format [, culture ] )

注意

若要查看 SQL Server 2014 (12.x) 及更早版本的 Transact-SQL 语法，请参阅早期版本文档。

参数

value
支持格式化的数据类型的表达式。有关有效类型的列表，请参阅下面“备注”部分中的表。

format
nvarchar 格式模式。

format 参数必须包含一个有效的 .NET Framework 格式字符串，要么作为标准格式字符串（例如，“C”或“D”），要么作为日期值和数值的自定义字符模式（例如，“MMMM DD, yyyy (dddd)”）。不支持组合格式。有关这些格式模式的完整解释，请查阅有关常规字符串格式、自定义日期和时间格式以及自定义数字格式的 .NET Framework 文档。一个好的起点是主题“格式类型”。

区域性
指定区域性的可选 nvarchar 参数。

如果未提供 culture 参数，则使用当前会话的语言。可以使用 SET LANGUAGE 语句隐式或显式设置此语言。 culture 接受 .NET Framework 支持的任何区域性作为参数；它不局限于 SQL Server 显式支持的语言。如果 culture 参数无效，FORMAT 将引发错误。

返回类型

nvarchar 或 Null

返回值的长度由 format 确定。

备注

FORMAT 将返回 NULL 错误，而不是非 valid 的 culture 。例如，如果 format 中指定的值无效，则返回 NULL 。

FORMAT 函数具有不确定性。

FORMAT 依赖于 .NET Framework 公共语言运行时 (CLR) 的存在。

此函数无法进行远程处理，因为它依赖于 CLR 的存在。远程处理需要 CLR 的函数可能导致在远程服务器上出现错误。

FORMAT 依赖于 CLR 格式设置规则，规则规定冒号和句点必须进行转义。因此，当格式字符串（第二个参数）包含冒号或句点时，如果输入值（第一个参数）属于 time 数据类型，则冒号或句点必须使用反斜杠转义。请参阅时间数据类型的 D. FORMAT。

下表列出了 value 参数可接受的数据类型，其中还有相关的 .NET Framework 映射等效类型。

类别	类型	.NET 类型
Numeric	bigint	Int64
Numeric	int	Int32
Numeric	smallint	Int16
Numeric	tinyint	Byte
Numeric	Decimal	SqlDecimal
Numeric	numeric	SqlDecimal
Numeric	FLOAT	Double
Numeric	real	Single
Numeric	smallmoney	Decimal
Numeric	money	Decimal
日期和时间	date	DateTime
日期和时间	time	TimeSpan
日期和时间	datetime	DateTime
日期和时间	smalldatetime	DateTime
日期和时间	datetime2	DateTime
日期和时间	datetimeoffset	DateTimeOffset

示例

A. 简单 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

以下示例通过指定自定义格式显示格式数值。该示例假定当前日期为 2020 年 11 月 22 日。有关这些格式和其他自定义格式的详细信息，请参阅自定义数字格式字符串。

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

下面的示例返回 AdventureWorks2022 数据库的 Sales.CurrencyRate 表中的 5 个行。 EndOfDateRate 列在该表中作为 money 类型存储。在本示例中，该列以非格式化形式返回，然后通过指定 .NET 数字格式、常规格式和货币格式类型进行格式化。有关这些格式和其他数字格式的详细信息，请参阅标准数字格式字符串。

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. 时间数据类型的 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

Format 返回指定了 AM 或 PM 的格式化当前时间

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

Format 返回显示 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 返回显示 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 返回采用 24 小时格式的指定时间

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