すべてのプロダクト
Search

このプロダクト

    MaxCompute:TO_CHAR

    ドキュメントセンター

    MaxCompute:TO_CHAR

    最終更新日:Dec 17, 2025

    TO_CHAR 関数は、さまざまなデータ型の値を STRING 型に変換します。BOOLEAN、BIGINT、DECIMAL、または DOUBLE 型の値を文字列に変換します。また、指定された書式に基づいて日付の値を文字列に書式設定します。

    BOOLEAN、BIGINT、DECIMAL、DOUBLE 型の変換

    TO_CHAR 関数を使用して、BOOLEAN、BIGINT、DECIMAL、または DOUBLE 型の値を STRING 型に変換できます。

    構文

    STRING TO_CHAR(BOOLEAN|BIGINT|DOUBLE|DECIMAL <value>)

-- 標準的な例
-- 123 を返します。
SELECT TO_CHAR(123);

    パラメーター

    value：必須。BOOLEAN、BIGINT、DECIMAL、または DOUBLE 型の値。

    戻り値

    STRING 型の値を返します。次のルールが適用されます：

    • value が BOOLEAN、BIGINT、DECIMAL、または DOUBLE 型でない場合、エラーが返されます。

    • value が NULL の場合、NULL が返されます。

    例

    基本的な例

    • 例 1：値を STRING 型に変換します。

      -- 123 を返します。
SELECT TO_CHAR(123);

    • 例 2：入力パラメーターが NULL の場合、戻り値は NULL です。

      -- NULL を返します。
SELECT TO_CHAR(NULL);

    日付型の変換

    TO_CHAR 関数を使用して、指定された書式とタイムゾーンに基づいて、日付または時刻の値を STRING 値に書式設定できます。

    構文

    日付または時刻のデータ型を入力パラメーターとして使用する場合、TO_CHAR 関数は次の 2 つのシグネチャをサポートします。必要に応じてシグネチャを選択してください。

    • シグネチャ 1：指定された書式に基づいて、DATE または DATETIME 値を STRING 値に変換します。

      STRING TO_CHAR(DATE|DATETIME <date>, STRING <format>)

-- 標準的な例
-- 2025-03-05 を返します。
SELECT TO_CHAR(DATETIME '2025-03-05 14:30:00', 'yyyy-mm-dd');

    • シグネチャ 2：指定された書式とタイムゾーンに基づいて、TIMESTAMP または TIMESTAMP_NTZ 値を STRING 値に変換します。

      STRING TO_CHAR(TIMESTAMP|TIMESTAMP_NTZ <date>, STRING <format>[, STRING <time_zone>])

-- 標準的な例
-- 2025-07-20 07:30:00 を返します。
SELECT TO_CHAR(TIMESTAMP '2025-07-20 07:30:00', '%Y-%m-%d %H:%M:%S');

    パラメーター

    • date：必須。書式設定する日付値。サポートされているデータ型は、DATE、DATETIME、TIMESTAMP、および TIMESTAMP_NTZ です。

      バージョン 1.0 のデータ型エディションを使用する MaxCompute プロジェクトでは、このパラメーターが yyyy-mm-dd hh:mi:ss 形式 (例：2025-07-21 00:00:00) に一致する STRING 型である場合、暗黙的に DATETIME 型に変換されます。

    • format：必須。出力書式を指定する STRING。次の表に、日付と時刻の部分でサポートされている書式要素を示します。

      日付書式要素

      • %Y/yyyy/YYYY：世紀を含む年を 10 進数で表します。

      • %y：世紀を含まない年を 10 進数で表します (00-99)。

      • %m/mm/MM：月を 10 進数で表します (01-12)。

      • %B：月の英語のフルネーム (例：January)。

      • %b/%h：月の英語の短縮名 (例：Jan)。

      • %d/dd/DD：月の日を 10 進数で表します (01-31)。

      • %e：月の日を 10 進数で表します (1-31)。たとえば、月の 2 日目の場合、この書式は 2 を返しますが、dd は 02 を返します。

      • %F：%Y-%m-%d (yyyy-mm-dd) と同等です。

      • %j：年の通日を 10 進数で表します (001-366)。例：360。

      • %u：曜日を 10 進数で表します (1-7)。月曜日が 1 です。

      • %A：曜日の英語のフルネーム (例：Wednesday)。

      • %a：曜日の英語の短縮名 (例：Wed)。

      時刻書式要素

      • %p：AM または PM。

      • %H/hh/HH：時 (24 時間時計) を 10 進数で表します (00-23)。

      • %I：時 (12 時間時計) を 10 進数で表します (01-12)。

      • %l：時 (12 時間時計) を 10 進数で表します (1-12)。1 桁の時には先頭にスペースが付きます。

      • %M/mi/MI：分を 10 進数で表します (00-59)。

      • %S/ss/SS：秒を 10 進数で表します (00-60)。

      • %X：HH:MM:SS 書式の時刻と同等です。

      • %T：%H:%M:%S (hh-mi-ss) と同等です。

      • ff3：ミリ秒を 3 桁の 10 進数で表します (000-999)。これは秒の小数部を表します。

      • %E<number>S：秒の小数部の精度を <number> 桁で表します。たとえば、%E3S は 00.123 に一致します。

      • %E*S：秒の完全な小数部の精度 (6 桁) を表します。例：00.123456。

      • %Ez：数値タイムゾーン (+HH:MM または -HH:MM)。

    • time_zone：任意。タイムゾーンを指定する STRING。詳細については、「タイムゾーンリスト」をご参照ください。

      タイムゾーンを指定しない場合：

      • date が TIMESTAMP 型の場合、デフォルトで現在のセッションまたはプロジェクトのタイムゾーンが使用されます。

      • date が TIMESTAMP_NTZ 型の場合、デフォルトで UTC タイムゾーンが使用されます。

    戻り値

    STRING 値を返します。次のルールが適用されます：

    • date が DATE、DATETIME、TIMESTAMP、または TIMESTAMP_NTZ 型でない場合、エラーが返されます。

    • date が NULL の場合、エラーが返されます。

    • format が NULL の場合、NULL が返されます。

    例

    基本的な例

    • 例 1：入力パラメーターが DATE または DATETIME 型の場合。

      -- Today is 2023-12-25. を返します。
SELECT TO_CHAR(DATE "2023-12-25", "Today is yyyy-mm-dd");

-- Today is 20231225. を返します。
SELECT TO_CHAR(DATE "2023-12-25", "Today is %Y%m%d");

-- Today is 231225Monday. を返します。
SELECT TO_CHAR(DATE "2023-12-25", "Today is %y%m%d%A");

-- Today is 12 Month 25 Day. を返します。
SELECT TO_CHAR(DATE "2023-12-25", "Today is MM Month DD Day");

-- Alibaba Finance 2010-12*03. を返します。
SELECT TO_CHAR(DATETIME '2010-12-03 00:00:00','Alibaba Finance yyyy-mm*dd');

-- The time is 15:30:00. を返します。
SELECT TO_CHAR(DATETIME '2025-07-18 15:30:00','The time is %X');

-- It is now 3:30:00 PM. を返します。
SELECT TO_CHAR(DATETIME '2025-07-18 15:30:00','It is now %l:%M:%S %p');

-- The hour part is 03. を返します。
SELECT TO_CHAR(DATETIME '2025-07-18 15:30:00','The hour part is %I');

-- Day 189 of year 25, July(Jul|Jul), day 08(8), Tuesday(Tue), 15:30:00 PM. を返します。
SELECT TO_CHAR(DATETIME '2025-07-08 15:30:00','Day %j of year %y, %B(%b|%h), day dd(%e), %A(%a), %T %p');

-- The date 2025-07-08 is the 2nd day of the week. を返します。
SELECT TO_CHAR(DATETIME '2025-07-08 15:30:00','The date %F is the %u day of the week');

-- NULL を返します。
SELECT TO_CHAR(DATE "2023-12-25", NULL);

    • 例 2：入力パラメーターが STRING 型の場合。

      バージョン 1.0 のデータ型エディションを使用する MaxCompute プロジェクトでは、date パラメーターが STRING 型で、その書式が yyyy-mm-dd hh:mi:ss 形式に一致する場合、暗黙的に DATETIME 型に変換されます。

      -- データ型エディションを 1.0 に設定します。
SET odps.sql.type.system.odps2=false;
SET odps.sql.hive.compatible=false;

-- 入力パラメーターは DATETIME 形式に一致する STRING 型です。
-- 20250718 を返します。
SELECT TO_CHAR('2025-07-18 00:00:00', 'yyyymmdd');

    • 例 3：入力パラメーターが TIMESTAMP 型の場合。

      パラメーターが TIMESTAMP 型の場合、タイムゾーンを指定できます。タイムゾーンを指定しない場合、デフォルトで現在のセッションまたはプロジェクトのタイムゾーンが使用されます。

      -- 現在のプロジェクトのタイムゾーンは Asia/Shanghai です。
SET odps.sql.timezone=Asia/Shanghai;

-- 2025-07-20 07:30:00.123456 を返します。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00.123456", "%Y-%m-%d %H:%M:%E*S");

-- 2025-07-20 07:30:00+08:00 を返します。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00", "%Y-%m-%d %H:%M:%S%Ez");

-- 2025-07-20 07:30:00 を返します。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00", "%Y-%m-%d %H:%M:%S", "Asia/Shanghai");
 
-- 20250720 06:30:00 を返します。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00", "yyyymmdd hh:mi:ss", "Asia/Bangkok");

-- 2025-07-20 09:30:00.123 を返します。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00.123456789", "%Y-%m-%d %H:%M:%S.ff3", "Australia/Sydney");

-- 2025-07-19 23:30:00 を返します。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00.123456", "%Y-%m-%d %H:%M:%S", "Etc/GMT");

-- 2025-07-19 23:30:00Saturday を返します。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00.123456", "%Y-%m-%d %H:%M:%S%A", "Etc/GMT");

-- NULL を返します。
SELECT TO_CHAR(TIMESTAMP "2025-07-20 07:30:00.123456", NULL, "Etc/GMT");

    • 例 4：入力パラメーターが TIMESTAMP_NTZ 型の場合。

      パラメーターが TIMESTAMP_NTZ 型の場合、タイムゾーンを指定できます。タイムゾーンを指定しない場合、デフォルトで UTC タイムゾーンが使用されます。

      -- The date and time is 2025-07-20 07:30:00.123456. を返します。
SELECT TO_CHAR(TIMESTAMP_NTZ "2025-07-20 07:30:00.123456" ,"The date and time is %Y-%m-%d %H:%M:%E6S");

-- 2025-07-20 07:30:00 を返します。
SELECT TO_CHAR(TIMESTAMP_NTZ "2025-07-20 07:30:00", "%Y-%m-%d %H:%M:%S", "Etc/GMT");

-- 2025-07-20 Sunday 15:30:00 を返します。
SELECT TO_CHAR(TIMESTAMP_NTZ "2025-07-20 07:30:00", "yyyy-mm-dd %A hh:mi:ss", "Asia/Shanghai");

-- 2025-07-20 14:30:00 and the millisecond part is 123. を返します。
SELECT TO_CHAR(TIMESTAMP_NTZ "2025-07-20 07:30:00.123456789", "yyyy-mm-dd hh:mi:ss and the millisecond part is ff3", "Asia/Bangkok");

-- NULL を返します。
SELECT TO_CHAR(TIMESTAMP_NTZ "2025-07-20 07:30:00",  NULL);

    関連関数

    TO_CHAR は日付関数および文字列関数です。

    • 日付の計算と変換に関連する関数の詳細については、「日付関数」をご参照ください。

    • 文字列の検索と変換に関する関数の詳細については、「文字列関数」をご参照ください。