に最終更新
TIME_FORMAT
説明
TIME_FORMAT 関数は、指定した書式文字列に従って時刻値を文字列に変換します。TIME、DATETIME、TIMESTAMP_NS、TIMESTAMPTZ 型の値をサポートします。
この関数は、MySQL の time_format 関数 と同じ動作をします。
構文
TIME_FORMAT(<time_or_datetime_expr>, <format>)
パラメータ
| パラメータ | 説明 |
|---|---|
<time_or_datetime_expr> | 有効な TIME、DATETIME、TIMESTAMP_NS、または TIMESTAMPTZ 型の値。 |
<format> | 時刻の出力書式を指定する varchar 型の値。書式文字列に日付用またはサポートされていない書式指定子が含まれる場合、NULL を返します。 |
サポートされる書式指定子：
| 書式指定子 | 説明 |
|---|---|
| %f | マイクロ秒（000000-999999） |
| %n | ナノ秒（000000000-999999999）。精度が低い型では、不足する桁をゼロで埋めます。 |
| %H | 時（00-23） |
| %h | 時（01-12） |
| %I | 時（01-12） |
| %i | 分、数値（00-59） |
| %k | 時（0-23） |
| %l | 時（1-12） |
| %p | AM または PM |
| %r | 12 時間表記の時刻（hh:mm:ss の後に AM または PM） |
| %S | 秒（00-59） |
| %s | 秒（00-59） |
| %T | 24 時間表記の時刻（hh:mm:ss） |
| %% | リテラルの % 文字を表します。 |
戻り値
書式に従って整形された時刻文字列を Varchar 型で返します。
特別なケース：
time_or_datetime_exprまたはformatが NULL の場合、NULL を返します。format文字列に日付用の書式指定子が含まれる場合：%Y：0000を返します。%y、%m、%d：00を返します。%c、%e：0を返します。- その他の日付用書式指定子（
%a、%b、%D、%j、%M、%u、%U、%v、%V、%w、%W、%x、%X）：NULL を返します。
- 時刻値の時の部分が 23 を超える場合、書式指定子
%Hと%kは 23 より大きい値を出力します。その他の時を表す書式指定子は、時の値を 12 で割った余りを出力します。
例
SELECT TIME_FORMAT(
CAST('2024-02-29 12:34:56.123456789' AS TIMESTAMP_NS),
'%H:%i:%s.%n'
) AS result;
+--------------------+
| result |
+--------------------+
| 12:34:56.123456789 |
+--------------------+
SELECT * FROM test_time_format;
+------+-------------------+
| id | tm |
+------+-------------------+
| 1 | 00:00:00 |
| 2 | 00:00:00.123456 |
| 3 | 12:34:56 |
| 4 | 12:34:56.789012 |
| 5 | 23:59:59 |
| 6 | 23:59:59.999999 |
| 7 | 08:00:00 |
| 8 | 15:00:00 |
| 9 | 100:00:00 |
| 10 | 123:45:56 |
| 11 | 838:59:59.999999 |
| 12 | -00:00:01 |
| 13 | -12:34:56.000001 |
| 14 | -838:59:59.999999 |
+------+-------------------+
SELECT
id,
tm,
TIME_FORMAT(tm, '%H') AS '%H',
TIME_FORMAT(tm, '%k') AS '%k',
TIME_FORMAT(tm, '%h') AS '%h',
TIME_FORMAT(tm, '%I') AS '%I',
TIME_FORMAT(tm, '%l') AS '%l',
TIME_FORMAT(tm, '%i') AS '%i',
TIME_FORMAT(tm, '%s') AS '%s',
TIME_FORMAT(tm, '%S') AS '%S',
TIME_FORMAT(tm, '%f') AS '%f',
TIME_FORMAT(tm, '%p') AS '%p',
TIME_FORMAT(tm, '%r') AS '%r',
TIME_FORMAT(tm, '%T') AS '%T',
TIME_FORMAT(tm, '%H:%i:%s.%f') AS '%H:%i:%s.%f',
TIME_FORMAT(tm, '%k %H %l %I %h') AS '%k %H %l %I %h',
TIME_FORMAT(tm, '%T %r %h:%I') AS '%T %r %h:%I',
TIME_FORMAT(tm, '%l %k %I %H %h %p') AS '%l %k %I %H %h %p',
TIME_FORMAT(tm, '%f %s %i %T %r') AS '%f %s %i %T %r'
FROM test_time_format
ORDER BY id;
+------+-------------------+------+------+------+------+------+------+------+------+---------+------+--------------+-----------+------------------+-----------------+-----------------------------+--------------------+------------------------------------+
| id | tm | %H | %k | %h | %I | %l | %i | %s | %S | %f | %p | %r | %T | %H:%i:%s.%f | %k %H %l %I %h | %T %r %h:%I | %l %k %I %H %h %p | %f %s %i %T %r |
+------+-------------------+------+------+------+------+------+------+------+------+---------+------+--------------+-----------+------------------+-----------------+-----------------------------+--------------------+------------------------------------+
| 1 | 00:00:00 | 00 | 0 | 12 | 12 | 12 | 00 | 00 | 00 | 000000 | AM | 12:00:00 AM | 00:00:00 | 00:00:00.000000 | 0 00 12 12 12 | 00:00:00 12:00:00 AM 12:12 | 12 0 12 00 12 AM | 000000 00 00 00:00:00 12:00:00 AM |
| 2 | 00:00:00.123456 | 00 | 0 | 12 | 12 | 12 | 00 | 00 | 00 | 123456 | AM | 12:00:00 AM | 00:00:00 | 00:00:00.123456 | 0 00 12 12 12 | 00:00:00 12:00:00 AM 12:12 | 12 0 12 00 12 AM | 123456 00 00 00:00:00 12:00:00 AM |
| 3 | 12:34:56 | 12 | 12 | 12 | 12 | 12 | 34 | 56 | 56 | 000000 | PM | 12:34:56 PM | 12:34:56 | 12:34:56.000000 | 12 12 12 12 12 | 12:34:56 12:34:56 PM 12:12 | 12 12 12 12 12 PM | 000000 56 34 12:34:56 12:34:56 PM |
| 4 | 12:34:56.789012 | 12 | 12 | 12 | 12 | 12 | 34 | 56 | 56 | 789012 | PM | 12:34:56 PM | 12:34:56 | 12:34:56.789012 | 12 12 12 12 12 | 12:34:56 12:34:56 PM 12:12 | 12 12 12 12 12 PM | 789012 56 34 12:34:56 12:34:56 PM |
| 5 | 23:59:59 | 23 | 23 | 11 | 11 | 11 | 59 | 59 | 59 | 000000 | PM | 11:59:59 PM | 23:59:59 | 23:59:59.000000 | 23 23 11 11 11 | 23:59:59 11:59:59 PM 11:11 | 11 23 11 23 11 PM | 000000 59 59 23:59:59 11:59:59 PM |
| 6 | 23:59:59.999999 | 23 | 23 | 11 | 11 | 11 | 59 | 59 | 59 | 999999 | PM | 11:59:59 PM | 23:59:59 | 23:59:59.999999 | 23 23 11 11 11 | 23:59:59 11:59:59 PM 11:11 | 11 23 11 23 11 PM | 999999 59 59 23:59:59 11:59:59 PM |
| 7 | 08:00:00 | 08 | 8 | 08 | 08 | 8 | 00 | 00 | 00 | 000000 | AM | 08:00:00 AM | 08:00:00 | 08:00:00.000000 | 8 08 8 08 08 | 08:00:00 08:00:00 AM 08:08 | 8 8 08 08 08 AM | 000000 00 00 08:00:00 08:00:00 AM |
| 8 | 15:00:00 | 15 | 15 | 03 | 03 | 3 | 00 | 00 | 00 | 000000 | PM | 03:00:00 PM | 15:00:00 | 15:00:00.000000 | 15 15 3 03 03 | 15:00:00 03:00:00 PM 03:03 | 3 15 03 15 03 PM | 000000 00 00 15:00:00 03:00:00 PM |
| 9 | 100:00:00 | 100 | 100 | 04 | 04 | 4 | 00 | 00 | 00 | 000000 | AM | 04:00:00 AM | 100:00:00 | 100:00:00.000000 | 100 100 4 04 04 | 100:00:00 04:00:00 AM 04:04 | 4 100 04 100 04 AM | 000000 00 00 100:00:00 04:00:00 AM |
| 10 | 123:45:56 | 123 | 123 | 03 | 03 | 3 | 45 | 56 | 56 | 000000 | AM | 03:45:56 AM | 123:45:56 | 123:45:56.000000 | 123 123 3 03 03 | 123:45:56 03:45:56 AM 03:03 | 3 123 03 123 03 AM | 000000 56 45 123:45:56 03:45:56 AM |
| 11 | 838:59:59.999999 | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL |
| 12 | -00:00:01 | -00 | -0 | -12 | -12 | -12 | -00 | -01 | -01 | -000000 | -AM | -12:00:01 AM | -00:00:01 | -00:00:01.000000 | -0 00 12 12 12 | -00:00:01 12:00:01 AM 12:12 | -12 0 12 00 12 AM | -000000 01 00 00:00:01 12:00:01 AM |
| 13 | -12:34:56.000001 | -12 | -12 | -12 | -12 | -12 | -34 | -56 | -56 | -000001 | -PM | -12:34:56 PM | -12:34:56 | -12:34:56.000001 | -12 12 12 12 12 | -12:34:56 12:34:56 PM 12:12 | -12 12 12 12 12 PM | -000001 56 34 12:34:56 12:34:56 PM |
| 14 | -838:59:59.999999 | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL | NULL |
+------+-------------------+------+------+------+------+------+------+------+------+---------+------+--------------+-----------+------------------+-----------------+-----------------------------+--------------------+------------------------------------+
注：
838:59:59.999999と-838:59:59.999999は TIME 型の範囲 [-838:59:59, 838:59:59] を超えるため、TIME 型に変換できず、戻り値は NULL になります。
```sql
-- Placeholder for %Y, %y, %m, %d, %c, %e returns the corresponding number of digits 0
SELECT fmt, TIME_FORMAT('12:13:14.123456', fmt) AS res FROM test_format;
+------+------+
| fmt | res |
+------+------+
| %Y | 0000 |
| %y | 00 |
| %m | 00 |
| %d | 00 |
| %c | 0 |
| %e | 0 |
+------+------+
-- Other placeholders (`%D`, `%j`, `%M`, `%u`, `%U`, `%v`, `%V`, `%w`, `%W`, `%x`, `%X`) return NULL.
SELECT TIME_FORMAT('11:22:33', '%h:%i:%s, %j');
+-----------------------------------------+
| TIME_FORMAT('11:22:33', '%h:%i:%s, %j') |
+-----------------------------------------+
| NULL |
+-----------------------------------------+
-- If any parameter is NULL, then return NULL
SELECT TIME_FORMAT('12:34:56', NULL);
+-------------------------------+
| TIME_FORMAT('12:34:56', NULL) |
+-------------------------------+
| NULL |
+-------------------------------+