カテゴリ：

変換関数

TO_CHAR , TO_VARCHAR

入力式を文字列に変換します。 NULL 入力の場合、出力は NULLです。

これらの関数は同義語です。

構文

TO_CHAR( <expr> )
TO_CHAR( <numeric_expr> [, '<format>' ] )
TO_CHAR( <date_or_time_expr> [, '<format>' ] )
TO_CHAR( <binary_expr> [, '<format>' ] )

TO_VARCHAR( <expr> )
TO_VARCHAR( <numeric_expr> [, '<format>' ] )
TO_VARCHAR( <date_or_time_expr> [, '<format>' ] )
TO_VARCHAR( <binary_expr> [, '<format>' ] )

引数

必須：

expr

任意のデータ型の式です。

numeric_expr

数値式です。

date_or_time_expr

DATE、 TIME、または TIMESTAMP型の式です。

binary_expr

BINARY または VARBINARY型の式です。

オプション：

format

出力文字列の形式です。

  • numeric_expr には、数値式の解釈に使用される SQL 形式モデルを指定します。詳細については、 SQL 形式モデル をご参照ください。

  • date_or_time_expr には、文字列を解析または生成するために期待される形式を指定します。詳細については、 変換関数の日付と時刻の形式 をご参照ください。

    デフォルトは、次のセッションパラメーターの現在の値です。

  • binary_expr には、文字列を生成する形式を指定します。（例:「HEX」、「BASE64」または「UTF-8」）。

    詳細については、 サポートされているバイナリ形式の概要 をご参照ください。

戻り値

この関数は VARCHAR データ型の値または NULL を返します。

使用上の注意

  • VARIANT、 ARRAY、または OBJECT 入力の場合、出力は JSON ドキュメントまたは JSON 基本値を含む文字列です（ただし VARIANT または OBJECT に XML タグが含まれている場合、出力はXMLドキュメントを含む文字列です）。

    • VARIANT に保存された文字列はそのまま保存されます（JSON 文字列に変換されません）。

    • JSON null 値は、単語「null」を含む文字列に変換されます。

例

以下の例では、数値、タイムスタンプ、日付を文字列に変換しています。

数値を変換する例

数値を指定された 形式 で文字列に変換します。

CREATE OR REPLACE TABLE convert_numbers_to_strings(column1 NUMBER);

INSERT INTO convert_numbers_to_strings VALUES
  (-12.391),
  (0),
  (-1),
  (0.10),
  (0.01),
  (3987),
  (1.111);

SELECT column1 AS orig_value,
       TO_CHAR(column1, '">"$99.0"<"') AS D2_1,
       TO_CHAR(column1, '">"B9,999.0"<"') AS D4_1,
       TO_CHAR(column1, '">"TME"<"') AS TME,
       TO_CHAR(column1, '">"TM9"<"') AS TM9,
       TO_CHAR(column1, '">"0XXX"<"') AS X4,
       TO_CHAR(column1, '">"S0XXX"<"') AS SX4
  FROM convert_numbers_to_strings;

+------------+----------+------------+-------------+------------+--------+---------+
| ORIG_VALUE | D2_1     | D4_1       | TME         | TM9        | X4     | SX4     |
|------------+----------+------------+-------------+------------+--------+---------|
|    -12.391 | >-$12.4< | >   -12.4< | >-1.2391E1< | >-12.391<  | >FFF4< | >-000C< |
|      0.000 | >  $0.0< | >      .0< | >0E0<       | >0.000<    | >0000< | >+0000< |
|     -1.000 | > -$1.0< | >    -1.0< | >-1E0<      | >-1.000<   | >FFFF< | >-0001< |
|      0.100 | >  $0.1< | >      .1< | >1E-1<      | >0.100<    | >0000< | >+0000< |
|      0.010 | >  $0.0< | >      .0< | >1E-2<      | >0.010<    | >0000< | >+0000< |
|   3987.000 | > $##.#< | > 3,987.0< | >3.987E3<   | >3987.000< | >0F93< | >+0F93< |
|      1.111 | >  $1.1< | >     1.1< | >1.111E0<   | >1.111<    | >0001< | >+0001< |
+------------+----------+------------+-------------+------------+--------+---------+

出力は、指定された形式に基づいて値がどのように文字列に変換されるかを示しています。

  • > と < シンボルは、出力に含まれる文字列リテラルです。スペースが挿入されている場所がわかりやすくなります。

  • D2_1 列には、数字の前に $ のある値が表示されます。

    • 3987 値の場合は、形式の桁位置よりも数字の整数部分の桁数が多いため、すべての桁が # として出力され、オーバーフローを示します。

    • 0.10、 0.01、 1.111 の値の場合は、数値の端数部分の桁数が形式の桁数よりも多いため、端数値は切り捨てられます。

  • D4_1 の列は、ゼロ値が整数部の空白として表現されていることを示しています。

    • 0、 0.10、 0.01 の値の場合、セパレーターの前のゼロはスペースで置き換えられます。

    • 0.10、 0.01、 1.111 の値の場合は、数値の端数部分の桁数が形式の桁数よりも多いため、端数値は切り捨てられます。

  • TME 列は科学的表記法での値を示しています。

  • TM9 列は、数値の値に応じて整数または小数で表示されます。

  • X4 列は、小数部を除いた16進数で値を表示します。

  • SX4 列は、数値の絶対値を16進数で示し、数値記号（+ または -）を含みます。

この例では、対数値を文字列に変換します。

SELECT TO_VARCHAR(LOG(3,4));

+----------------------+
| TO_VARCHAR(LOG(3,4)) |
|----------------------|
| 1.261859507          |
+----------------------+

タイムスタンプと日付を変換する例

TIMESTAMP 値を指定した形式の文字列に変換します。

SELECT TO_VARCHAR('2024-04-05 01:02:03'::TIMESTAMP, 'mm/dd/yyyy, hh24:mi hours');

+---------------------------------------------------------------------------+
| TO_VARCHAR('2024-04-05 01:02:03'::TIMESTAMP, 'MM/DD/YYYY, HH24:MI HOURS') |
|---------------------------------------------------------------------------|
| 04/05/2024, 01:02 hours                                                   |
+---------------------------------------------------------------------------+

DATE 値をデフォルト形式の文字列に変換します。

SELECT TO_VARCHAR('03-April-2024'::DATE);

+-----------------------------------+
| TO_VARCHAR('03-APRIL-2024'::DATE) |
|-----------------------------------|
| 2024-04-03                        |
+-----------------------------------+

DATE 値を指定した形式の文字列に変換します。

SELECT TO_VARCHAR('03-April-2024'::DATE, 'yyyy.mm.dd');

+-------------------------------------------------+
| TO_VARCHAR('03-APRIL-2024'::DATE, 'YYYY.MM.DD') |
|-------------------------------------------------|
| 2024.04.03                                      |
+-------------------------------------------------+