FORMAT (Transact-SQL)

项目
08/13/2024

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

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

Transact-SQL 语法约定

语法

FORMAT( value , format [ , culture ] )

注意

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

参数

value

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

format

nvarchar 格式模式。

格式参数必须包含有效的 .NET Framework 格式字符串，可以是标准格式字符串（例如，"C"或"D"），或者是日期和数值的自定义字符模式（例如，"MMMM DD, yyyy (dddd)"）。不支持复合格式。

有关这些格式模式的完整解释，请查阅有关常规字符串格式、自定义日期和时间格式以及自定义数字格式的 .NET Framework 文档。有关详细信息，请参阅类型格式设置。

区域性

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

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

返回类型

nvarchar 或 Null

返回值的长度由 format 确定。

注解

FORMATNULL返回非区域性无效的错误。例如，如果以格式指定的值无效，NULL则返回该值。

该 FORMAT 函数是不确定的。

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

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

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

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

类别	类型	.NET 类型
Numeric	bigint	`Int64`
数字	int	`Int32`
数字	smallint	`Int16`
数字	tinyint	`Byte`
数字	decimal	`SqlDecimal`
数字	numeric	`SqlDecimal`
数字	float	`Double`
数字	real	`Single`
数字	smallmoney	`Decimal`
数字	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)
-----------  ---------------- ----------- -------------------------
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

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

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 数字格式、常规格式和货币格式类型进行格式化。有关这些格式和其他数字格式的详细信息，请参阅标准数字格式字符串。

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

格式返回带格式的当前时间，并指定 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)

语法

参数

value

format

区域性

返回类型

注解

示例

A. 简单 FORMAT 示例

B. 使用自定义格式字符串执行 FORMAT

C. 用于数值类型的 FORMAT

D. 时间数据类型的 D. FORMAT

反馈

其他资源

通过

FORMAT (Transact-SQL)

语法

参数

value

format

区域性

返回类型

注解

示例

A. 简单 FORMAT 示例

B. 使用自定义格式字符串执行 FORMAT

C. 用于数值类型的 FORMAT

D. 时间数据类型的 D. FORMAT

相关内容

反馈

其他资源