TO_CHAR (SQL)

expression

format で指定された形式に従って文字列に変換される、論理日付、時刻、タイムスタンプ、または数の式。expression が NULL の場合、TO_CHAR は NULL を返します。

format

expression 変換用に日付、タイムスタンプ、または数の形式を指定する文字コード。

• format に無効な日付、時刻、またはタイムスタンプ・コードの要素を指定した場合 (YYYYY、MIN、HH48 など)、TO_CHAR は無効なコード要素の形式コード・リテラルを返します。その他すべての有効なコード要素については、日付、時刻、またはタイムスタンプの変換値を返します。

• TO_CHAR が format コード要素を認識できない場合 (format が空文字列の場合など) や数字の形式における桁数が expression 値より小さい場合、TO_CHAR は元の文字の代わりにシャープ記号 (#) を返します。これは、expression が少なくとも 2 桁の整数で始まる場合に当てはまります。そうでない場合、TO_CHAR は NULL を返します。

以下の表に、有効な形式コードを示します。これらを、それぞれの式のタイプ (日付、時刻、日付と時刻 (タイムスタンプ)、数) で指定できます。

YYYYMMDD、DDMMYYYY、および YYYYMM の形式文字列を除いて、区切り文字は日付形式要素間で必要です。最後の形式では年と月の値が返され、月の日付は無視されます。

format のコード定義に説明のあるロケールは、ObjectScript の $ZDATE と $ZDATEH のドキュメントに記述されているロケールと同じです。

時刻を文字列に変換する際、format はこの表に示した時刻形式コードのみを含む文字列である必要があります。format に他のコードが含まれる場合、TO_CHAR は expression を代わりに日付として解釈します。

タイムスタンプをフォーマットされた日付/時刻文字列に変換する際、format は "日付形式" または "時刻形式" の表に示した日付/時刻形式コードを含む文字列である必要があります。この変換を実行するには、expression は、有効な論理タイムスタンプ値である必要があります。

format では、小数区切りおよび数値グループ・セパレータを、リテラル文字として、またはロケールの DecimalSeparator と NumericGroupSeparator の現在の値として指定できます。現在のロケール値は ObjectScript を使用して以下のように確認できます。

  write ##class(%SYS.NLS.Format).GetFormatItem("DecimalSeparator"),!
  write ##class(%SYS.NLS.Format).GetFormatItem("NumericGroupSeparator")

format に含まれる整数桁数が入力数値式より小さい場合、TO_CHAR は数値を返さず、複数のシャープ記号 (##) の文字列を返します。シャープ記号の数は、現在の format 引数の長さに 1 を加えたものです。

format に含まれる小数桁数が入力数値式より小さい場合、TO_CHAR は指定された桁数に数値を丸めます。10 進形式が指定されていない場合、TO_CHAR は数値を整数に丸めます。

日付をフォーマットされた日付文字列に変換する

以下の文では、TO_CHAR を使用して、$HOROLOG 日付整数または完全な $HOROLOG 文字列値を、フォーマットされた日付文字列または日付と時刻の文字列に変換します。

SELECT
  TO_CHAR(66256,'YYYY-MM-DD') AS Date2FormattedDate,
  TO_CHAR(66256,'YYYY-MM-DD HH24:MI:SS') AS Date2FormattedDateTime,
  TO_CHAR('66256,50278','YYYY-MM-DD') AS DateTime2FormattedDate,
  TO_CHAR('66256,50278','YYYY-MM-DD HH24:MI:SS') AS DateTime2FormattedDateTime

以下の文では、各 TO_CHAR 呼び出しは日付整数を取り、format 文字列引数に従ってフォーマットされた日付文字列を返します。

SELECT
  TO_CHAR(66256,'MM/DD/YYYY'),         /* returns 02/22/2018 */
  TO_CHAR(66256,'DAY MONTH DD, YYYY')  /* returns Thursday February 22, 2018 */

以下の文は、日付整数をフォーマットされた日付文字列に変換します。無効な format 文字は、リテラルとして出力文字列に渡されます。これは文字列 The date 05/27/2022 should be noted を返します。

SELECT TO_CHAR(66256,'The date MM/DD/YYYY should be noted')

以下の文は、日付式を、指定された年の 1 月 1 日からの経過日数として定義された、その年の日数に変換します。この構文を使用するには、日付式を $HOROLOG 形式にする必要があります。2 番目の TO_CHAR 呼び出しの時刻値は無視されます。2 つの TO_CHAR 呼び出しでは、年間通算日形式の要素 (DDD) と年要素 (YYYY および YY) は、異なる順序で表示されます。

SELECT
  TO_CHAR('66235','DDD days into YYYY'),
  TO_CHAR('66235,12345','Year YY: DDD days elapsed')

以下の文では、TO_CHAR は、セパレータをマイナス記号と解釈するため、正しくない日付値を返します。したがって、この式は 2022 – 5 – 2 = 2015 と評価されます。これは、$HOROLOG 整数形式で日付 1846-07–08 に対応します。

SELECT TO_CHAR(2022-05-02,'YYYY-MM-DD') -- Incorrect usage

時刻をフォーマットされた時刻文字列に変換する

以下の文では、'66256' が時刻値 05:58:21 PM と解釈されます。

SELECT TO_CHAR('64701','HH12:MI:SS PM')

以下の文では、2 つの論理タイムスタンプの時刻部分をフォーマットされた時刻文字列に変換します。format は秒の小数部をサポートしていないため、expression の秒の小数部は切り捨てられます。

SELECT TO_CHAR(SYSDATE,'HH12:MI:SS PM'),
       TO_CHAR(CURRENT_TIMESTAMP(6),'HH12:MI:SS PM')

タイムスタンプをフォーマットされた日付と時刻の文字列に変換する

以下の文は、現在のシステム日付 (タイムスタンプ) と、システム日付を表示するためにこのタイムスタンプを 2 つの異なるフォーマットで変換した値を返します。

SELECT
  SYSDATE,
  TO_CHAR(SYSDATE,'MM/DD/YYYY HH:MI:SS'),
  TO_CHAR(SYSDATE,'DD MONTH YYYY at SSSSS seconds')

format 文字列で使用されている、形式コードでない文字列はすべて、結果文字列のその位置に戻されます。

数をフォーマットされた数値文字列に変換する

以下の文は、数値 1000 をさまざまな桁数の形式コードの文字列に変換します。

• 最初の変換では、数値の桁数は、指定された桁の形式コードより多くなります。TO_CHAR は、数値の桁数に等しいシャープ記号を返します。

• 2 番目の変換では、数値の桁数は、指定された桁の形式コードと同じになります。TO_CHAR は、数値を文字列形式で返します。数値は符号なしの正の整数であるため、TO_CHAR は数値文字列の先頭にゼロを付加します。

• 3 番目の変換では、数値の桁数は、指定された桁の形式コードより少なくなります。TO_CHAR は、文字列形式で数値を返し、先頭に2 つのゼロを付加します。1 つは、数値が符号なしの正の整数であるため、もう 1 つは余分な桁の形式コード用です。

SELECT
  TO_CHAR(1000,'999'),  -- '####'
  TO_CHAR(1000,'9999'), -- ' 1000'
  TO_CHAR(1000,'99999') -- '  1000'

以下の文は、区切り文字の使用例を示しています。

• 最初の変換は、文字列 ' 1,000.00' を返します。

• 2 番目の変換も同じ値を返しますが、区切り文字はロケールの設定により表示が異なります。

SELECT
  TO_CHAR(1000,'9,999.99'),
  TO_CHAR(1000,'9G999D99')

以下の文は、正の符号と負の符号の使用例を示しています。先頭の空白は、符号の形式がない場合に正の数の前にのみ表示されます。先頭の空白は、符号の配置にかかわらず、負の数の前、または符号付きの数値の前には表示されません。

SELECT 
  TO_CHAR(10,'99.99'),   -- ' 10.00'
  TO_CHAR(-10,'99.99'),  -- '-10.00'
  TO_CHAR(10,'S99.99'),  -- '+10.00'
  TO_CHAR(-10,'S99.99'), -- '-10.00'
  TO_CHAR(10,'99.99S'),  -- '10.00+'
  TO_CHAR(-10,'99.99S')  -- '10.00-'

以下の文は、"FM" 形式の使用例を示します。これは、符号なしの正の数に対し、既定の先頭の空白をオーバーライドします。

SELECT 
  TO_CHAR(12345678.90,'99,999,999.99'),  -- ' 12,345,678,90'
  TO_CHAR(12345678.90,'FM99,999,999.99') -- '12,345,678,90'

以下の文は、先頭のドル記号の使用例を示しています。ドル記号の前には必ず符号または空白文字が入ります。

SELECT 
  TO_CHAR(1234567890,'$9G999G999G999'),  -- ' $1,234,567,890'
  TO_CHAR(1234567890,'S$9G999G999G999'), -- '+$1,234,567,890'
  TO_CHAR(12345678.90,'$99G999G999D99')  -- ' $1,234,567,8.90'

以下の文は、format 引数が入力数値式より小数桁数が小さい場合の動作を示します。返される数字は、それぞれ、1234567.5 と 1234568 に丸められます。

SELECT
  TO_CHAR(1234567.4999,'9999999.9'),
  TO_CHAR(1234567.91,'9999999')

ユリウス日の変換

ユリウス日付形式を使用すると、1840 年 12 月 31 日より前の日付を文字列に変換できます。この形式を使用するには、TO_CHAR の format 引数を 'J' または 'j' に指定します。この形式を使用して、データ型 %DateOpens in a new tab または %TimeStampOpens in a new tab の日付値を、必要に応じて先頭にゼロを付けた 7 桁のユリウス日の整数に変換します。以下に例を示します。

SELECT
  TO_CHAR('1776-07-04','J') AS UnitedStatesStart, --2369916
  TO_CHAR('-0031-09-02','J') AS RomanEmpireStart  --1709980

返される整数は、紀元前 4712 年 1 月 1 日からの日数です。ユリウス日に変換できる expression の最大値は '9999-12-31' (ユリウス日のカウント 5373484) です。最小値は '-4712-01-01' (ユリウス日のカウント 0000001) です。

既定では、%DateOpens in a new tab データ型は 1840 年 12 月 31 日より前の日付を表しません。ただし、このデータ型の MINIVAL パラメータを再定義すると、それより前の日付を西暦 1 年 1 月 1 日まで、負の整数として表すことができます。この負の整数による日付の表記には、ここで説明するユリウス日付形式とは互換性がありません。詳細は、"データ型" を参照してください。

ユリウス日のカウント値 1721424 は、ユリウス暦の 1 年 1 月 1 日 (1–01–01) を返します。ユリウス日のカウント値がこの値より小さい場合は、BCE (紀元前) の日付が返されます。これは、年の前にマイナス記号を付けて表示されます。

TO_CHAR では、日付式に対応するユリウス日のカウントを返すことができます。TO_DATE では、以下の例のように、ユリウス日のカウントに対応する日付式を返すことができます。

SELECT 
  TO_CHAR('1776-07-04','J') AS JulianCount, -- 2369916
  TO_DATE(2369916,'J') AS JulianDate        -- 1776-07-04

関連する SQL 関数

• TO_CHAR は、日付整数、タイムスタンプ、または数を文字列に変換します。

• TO_DATE は、日付に対して逆の操作を実行します。これは、フォーマットされた日付文字列を日付整数に変換します。

• TO_TIMESTAMP は、タイムスタンプに対して逆の操作を実行します。これは、フォーマットされた日付/時刻文字列を標準のタイムスタンプに変換します。

• TO_NUMBER は、数値に対して逆の操作を実行します。これは、数値文字列を数値に変換します。

• CAST および CONVERT は、DATE、TIMESTAMP、および NUMBER の各データ型に対して変換を実行します。