FORMAT (Transact-SQL)
適用対象: SQL Server
Azure SQL データベース
Azure SQL Managed Instance
Azure Synapse Analytics
Microsoft Fabric の SQL 分析エンドポイント
Microsoft Fabric のウェアハウス
指定した形式とオプションのカルチャを使用して書式設定された値を返します。 日付/時刻と数値のロケールに対応した書式を文字列として設定するには、 FORMAT
関数を使用します。 一般的なデータ型変換には、 CAST
または CONVERT
を使用します。
構文
FORMAT( value , format [ , culture ] )
Note
SQL Server 2014 (12.x) 以前のバージョンの Transact-SQL 構文を確認するには、以前のバージョンのドキュメントを参照してください。
引数
value
書式設定がサポートされているデータ型の式。 有効な型の一覧については、「 Remarks 」セクションの表を参照してください。
format
nvarchar 書式パターン。
format引数には、標準の書式指定文字列 ("C"
や"D"
など) として、または日付と数値のカスタム文字のパターン (たとえば、"MMMM DD, yyyy (dddd)"
) として、有効な .NET Framework 書式指定文字列を含める必要があります。 複合書式はサポートされていません。
これらの書式設定パターンの詳細については、一般的な文字列の書式設定、カスタム日付/時刻書式、およびカスタム数値書式に関する .NET Framework ドキュメントを参照してください。 詳細については、型の書式設定に関するページをご覧ください。
culture
カルチャを指定する省略可能な nvarchar 引数です。
引数 culture が指定されていない場合は、現在のセッションの言語が使用されます。 この言語は、暗黙的に設定されるか、 SET LANGUAGE
ステートメントを使用して明示的に設定されます。 culture .NET Framework でサポートされているカルチャを引数として受け入れます。SQL Server で明示的にサポートされている言語に限定されるわけではありません。 引数 culture が無効な場合、 FORMAT
はエラーを発生させます。
戻り値の型
nvarchar または null
戻り値の長さは format によって決まります。
解説
FORMAT
は、validではないカルチャ以外のエラーのNULL
を返します。 たとえば、format で指定された値が無効な場合、NULL
が返されます。
FORMAT
関数は非決定的です。
FORMAT
は、.NET Framework 共通言語ランタイム (CLR) の存在に依存します。
この関数は CLR の存在に依存するため、リモート化できません。 CLR が必要な関数をリモート処理すると、リモート サーバー上でエラーが発生する可能性があります。
FORMAT
は CLR 書式設定規則に依存します。これは、コロンとピリオドをエスケープする必要があることを示します。 したがって、書式指定文字列 (2 番目のパラメーター) にコロンまたはピリオドが含まれている場合、入力値 (最初のパラメーター) が time データ型の場合は、コロンまたはピリオドを円記号でエスケープする必要があります。 「D. 時刻データ型を使用する FORMAT」を参照してください。
value 引数の許容データ型の一覧を、.NET Framework にマッピングした同等の型と共に、次の表に示します。
カテゴリ | Type | .NET の種類 |
---|---|---|
数値 | 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
次の例では、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 €
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
Format は、指定した時刻を 24 時間形式で返します。
select FORMAT(CAST('2018-01-01 14:00' AS DATETIME2), N'HH:mm'); --> returns 14:00