TO_CHAR (SQL)
Synopsis
TO_CHAR(expression,format) TO_CHAR(expression) TOCHAR(...)
説明
-
TO_CHAR(expression,format) は、日付、時刻、タイムスタンプ (日付と時刻)、または数式を、指定された形式文字列に応じて文字列に変換します。
以下の文は、現在の日付を 'MONTH DD, YYYY' の形式に変換します。ここで、MONTH は完全な月名、DD は 2 桁の日、YYYY は 4 桁の年数です。
SELECT TO_CHAR(CURRENT_DATE,'MONTH DD, YYYY')
例 :
TO_CHAR(expression) は、日付、時刻、タイムスタンプ、または数式を、式のタイプの既定の論理モード形式に応じて変換します。
-
日付式と時刻式は、InterSystems SQL の論理 $HOROLOG 形式に変換します。これは、日付と時刻を表す 2 つのコンマ区切り整数の文字列です。最初の整数は 1840 年 12 月 31 日からの日数です。2 番目の整数は、現在の日付の午前 0 時からの秒数です。
-
タイムスタンプ式は YYYY-MM-DD HH:MI:SS 形式に変換されます。
-
数式は整数に変換されます。先頭のゼロとプラス記号は削除され、数は最初の非数値文字 (コンマやピリオドなど) で切り捨てられます。
以下の文は、タイムスタンプとして表される現在の日付と時刻を、YYYY-MM-DD HH:MI:SS 形式の文字列に変換します。
SELECT TO_CHAR(CURRENT_TIMESTAMP)
-
-
TOCHAR(...) は、TO_CHAR(...) と同等です。
引数
expression
format で指定された形式に従って文字列に変換される、論理日付、時刻、タイムスタンプ、または数の式。expression が NULL の場合、TO_CHAR は NULL を返します。
日付式
日付式を変換するには、expression は数値または $HOROLOG 形式の文字列である必要があります。
expression が無効な日付 (February 30 など) である場合、InterSystems IRIS® は、SQLCODE -400 エラーを発行します。
expression が 1840 年 12 月 31 日以前の日付を表している場合、日付を変換するには、ユリウス日付形式 (format 引数 = 'J') を使用する必要があります。詳細は、"ユリウス日の変換" を参照してください。
時刻式
時刻式を変換するには、expression が以下の形式のいずれかである必要があります。
-
$HOROLOG 時刻整数 ($HOROLOG の時刻コンポーネント)。ここで expression は、0 ~ 86399 の範囲の有効な論理時刻整数です。日付と時刻の両方のコンポーネントを含む (64701,42152 など) 完全な $HOROLOG 値を指定しないでください。TO_CHAR 時刻変換では、$HOROLOG の最初のコンポーネントである日付コンポーネントのみをフォーマットされた時刻文字列に変換し、2 番目のコンポーネントである時刻コンポーネントは無視します。
-
論理タイムスタンプ値。expression の値は (文字列データ型ではなく) YYYY-MM-DD hh:mm:ss 形式の %TimeStampOpens in a new tab データ型である必要があります。format で時刻形式のみを指定する場合、TO_CHAR は、タイムスタンプの日付コンポーネントを無視し、時刻コンポーネントのみを変換します。例えば、SYSDATE は論理タイムスタンプです。
-
ODBC 標準時刻形式の時刻値。expression の値は hh:mm:ss 形式にする必要がありますが、文字列になります。
-
現在の NLS ロケール設定を使用したローカル時刻形式による時刻値。例えば、NLS TimeSeparator が “^” に設定されている場合、expression の値は hh^mm^ss 形式の文字列になります。
expression が無効な時刻 (6:61 P.M. など) である場合、InterSystems IRIS は、SQLCODE -400 エラーを発行します。
タイムスタンプ式
タイムスタンプ式を変換するには、expression は、YYYY-MM-DD HH:MI:SS の形式にするか、以下の有効なバリアントのいずれかにする必要があります。
-
10 より小さい月および日付の値の場合、先頭のゼロはオプションです。先頭のゼロが省略された場合、返される日付でもゼロが省略されます。
-
秒の値は省略できますが、その場所を示すコロンは指定する必要があります (HH:MI: など)。返される時刻では、秒は既定で 00 となります。
-
秒の値には、秒の小数部を含めることができます (HH:MI:SS.fff など)。返される時刻では、秒の小数部は切り捨てられます。
-
format に時間の形式を指定しなくても、タイムスタンプには時間の部分を含める必要があります。
expression が正しいタイムスタンプの形式でない場合、TO_CHAR はそれを整数と解釈し、整数でない文字が最初に出現したところで解釈を終了します。
format が日付またはタイムスタンプ形式の場合、TO_CHAR は expression を $HOROLOG 日付整数と解釈します。例えば、2010-03-23 12-15:23 では、時刻の値の部分に誤ってハイフンが使用されていますが、これは $HOROLOG 日付の 2010 (1846-07-03 12:00:00 AM) と解釈されます。
expression が無効な日付または時刻 (February 30、6:61 P.M など) である場合、InterSystems IRIS は、SQLCODE -400 エラーを発行します。
数式
数式を変換するには、expression は、数値データ型または数値文字列にする必要があります。TO_CHAR では文字列を最初の非数値整数で切り捨てます。先頭に数値のない文字列は 0 と解釈されます。
format
expression 変換用に日付、タイムスタンプ、または数の形式を指定する文字コード。
-
format に無効な日付、時刻、またはタイムスタンプ・コードの要素を指定した場合 (YYYYY、MIN、HH48 など)、TO_CHAR は無効なコード要素の形式コード・リテラルを返します。その他すべての有効なコード要素については、日付、時刻、またはタイムスタンプの変換値を返します。
-
TO_CHAR が format コード要素を認識できない場合 (format が空文字列の場合など) や数字の形式における桁数が expression 値より小さい場合、TO_CHAR は元の文字の代わりにシャープ記号 (#) を返します。これは、expression が少なくとも 2 桁の整数で始まる場合に当てはまります。そうでない場合、TO_CHAR は NULL を返します。
以下の表に、有効な形式コードを示します。これらを、それぞれの式のタイプ (日付、時刻、日付と時刻 (タイムスタンプ)、数) で指定できます。
形式コード | 意味 |
---|---|
D | 曜日 (1 ~ 7)。既定では、1 が日曜日 (週の最初の日) ですが、この指定は構成可能です。詳細は、"DAYOFWEEK" 関数を参照してください。 |
DD | 2 桁の日付 (01 ~ 31)。 |
DY |
現在のロケールの WeekdayAbbr プロパティによって指定される日の略名。 既定値 : Sun Mon Tue Wed Thu Fri Sat |
DAY |
現在のロケールの WeekdayName プロパティが指定する曜日名。 既定値 : Sunday Monday Tuesday Wednesday Thursday Friday Saturday |
MM | 2 桁の月数 (01 ~ 12、01 = 1 月)。 |
MON |
現在のロケールの MonthAbbr プロパティによって指定される月の略名。 既定値 (大文字と小文字の区別なし) : Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec |
MONTH |
現在のロケールの MonthName プロパティによって指定される正式な月名。 既定値 (大文字と小文字の区別なし) : January February March April May June July August September October November December |
YYYY | 4 桁の年数。 |
YYY | 下 3 桁の年数。 |
YY | 下 2 桁の年数。 |
Y | 下 1 桁の年数。 |
RRRR | 4 桁の年数。 |
RR | 下 2 桁の年数。 |
DDD | 年間通算日 (指定された年の 1 月 1 日からの日数) |
J | ユリウス日 (紀元前 4712 年 1 月 1 日からの日数)。詳細は、"ユリウス日の変換" を参照してください。 |
YYYYMMDD、DDMMYYYY、および YYYYMM の形式文字列を除いて、区切り文字は日付形式要素間で必要です。最後の形式では年と月の値が返され、月の日付は無視されます。
format のコード定義に説明のあるロケールは、ObjectScript の $ZDATE と $ZDATEH のドキュメントに記述されているロケールと同じです。
形式コード | 意味 |
---|---|
HH | 時 (1 ~ 12) |
HH12 | 時 (1 ~ 12) |
HH24 | 時 (0 ~ 23) |
MI | 分 (0 ~ 59) |
SS | 秒 (0 ~ 59) |
SSSSS | 午前 0 時 00 分からの秒数 (0 ~ 86388) |
AM と PM | 午前/午後のインジケータ (AM = 午前、PM = 午後)。適切な AM または PM の接尾語が付加された 12 時間形式に時刻値を変換します。返される AM または PM の接尾語は、指定した形式コードからではなく、時刻値から導出されます。format では、AM または PM のいずれかを使用できます。これらは、機能的には同じです。 |
時刻を文字列に変換する際、format はこの表に示した時刻形式コードのみを含む文字列である必要があります。format に他のコードが含まれる場合、TO_CHAR は expression を代わりに日付として解釈します。
タイムスタンプをフォーマットされた日付/時刻文字列に変換する際、format は "日付形式" または "時刻形式" の表に示した日付/時刻形式コードを含む文字列である必要があります。この変換を実行するには、expression は、有効な論理タイムスタンプ値である必要があります。
形式コード | 説明 | 例 |
---|---|---|
9 |
指定された桁数の値を返します。
|
9999 |
0 |
先頭または末尾のゼロを付けて返します。 |
09999 99990 |
$ | 先頭に $ を付けて値を返します。正の数の場合、ドル記号の前には空白が入ります。 | $9999 |
B | 整数部がゼロの場合、(format 引数の 0 の有無にかかわらず) 固定小数点の整数部に空白を返します。 | B9999 |
S |
正の場合は先頭または末尾のプラス記号 "+" を付け、負の場合は先頭または末尾のマイナス記号 "-" を付けて値を返します。 |
S9999 9999S |
D | 指定された位置に小数点区切り文字を配置して返します。使用される DecimalSeparator は、ロケールで定義されたものと同じです。既定はピリオド "." です。format 引数内には、"D" は 1 つしか許可されません。 | 99D99 |
G | 指定された位置に数値グループ・セパレータを配置して返します。使用される NumericGroupSeparator は、ロケールで定義されたものと同じです。既定はコンマ "," です。小数点区切りの右側に数値グループ・セパレータが出現することはありません。 | 9G999 |
FM | 先頭や末尾に空白がない値を返します。 | FM90.9 |
, | 指定された位置にコンマを付けて返します。10 進法の右側にコンマが表れることはありません。format 引数をコンマで始めることはできません。 | 9,999 |
. | 指定した位置に 10 進小数点 (ピリオド ".") を返します。format 引数内には、"." は 1 つしか許可されません。 | 99.99 |
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
代替案
ObjectScript で同等の変換を実行するには、TOCHAR()Opens in a new tab メソッドを使用します。
$SYSTEM.SQL.Functions.TOCHAR(expression,format)