メインコンテンツまでスキップ
に最終更新

MILLISECONDS_DIFF

説明​

MILLISECONDS_DIFF 関数は、二つの日時値の差をミリ秒単位で計算します。終了時刻から開始時刻を差し引いたミリ秒数を返します。この関数は DATETIME 型と TIMESTAMP_NS 型をサポートします。

構文​

MILLISECONDS_DIFF(`<date_or_time_expr1>`, `<date_or_time_expr2>`)

パラメータ​

パラメータ説明
<date_or_time_expr1>終了時刻。型は DATETIME または TIMESTAMP_NS です。
<date_or_time_expr2>開始時刻。型は DATETIME または TIMESTAMP_NS です。

戻り値​

二つの時刻の差をミリ秒単位で表す INT 型の値を返します。

  • <date_or_time_expr1> が <date_or_time_expr2> より後の時刻の場合、結果は正の値になります。
  • <date_or_time_expr1> が <date_or_time_expr2> より前の時刻の場合、結果は負の値になります。
  • 二つの時刻がミリ秒部分も含めて同じ場合、結果は 0 になります。
  • 入力が DATE 型で年月日のみを含む場合、時刻部分にはデフォルト値の 00:00:00.000 が設定されます。
  • 入力時刻にマイクロ秒が含まれる場合（例：'2023-01-01 00:00:00.123456'）、計算時にミリ秒精度に自動的に切り捨てられます（例：123 milliseconds）。
  • いずれかのパラメータが NULL の場合、NULL を返します。

使用例​

以下の例では、通常のミリ秒差、負の結果、マイクロ秒を含む入力、日付のみの入力、ヌル値、同一時刻の場合を順に示します。

-- Calculate millisecond difference
SELECT MILLISECONDS_DIFF('2020-12-25 21:00:00.623000', '2020-12-25 21:00:00.123000');
+-------------------------------------------------------------------------------+
| MILLISECONDS_DIFF('2020-12-25 21:00:00.623000', '2020-12-25 21:00:00.123000') |
+-------------------------------------------------------------------------------+
|                                                                           500 |
+-------------------------------------------------------------------------------+

-- End time is earlier than start time, returns negative value
SELECT MILLISECONDS_DIFF('2023-10-01 12:00:00.500', '2023-10-01 12:00:00.800');
+-------------------------------------------------------------------------+
| MILLISECONDS_DIFF('2023-10-01 12:00:00.500', '2023-10-01 12:00:00.800') |
+-------------------------------------------------------------------------+
|                                                                    -300 |
+-------------------------------------------------------------------------+

-- Input includes microseconds (automatically truncated to milliseconds)
SELECT MILLISECONDS_DIFF('2023-01-01 00:00:00.123456', '2023-01-01 00:00:00.000123');
+-------------------------------------------------------------------------------+
| MILLISECONDS_DIFF('2023-01-01 00:00:00.123456', '2023-01-01 00:00:00.000123') |
+-------------------------------------------------------------------------------+
|                                                                           123 |
+-------------------------------------------------------------------------------+

-- Input is of DATE type (default time is 00:00:00.000)
SELECT MILLISECONDS_DIFF('2023-10-02', '2023-10-01');
+-----------------------------------------------+
| MILLISECONDS_DIFF('2023-10-02', '2023-10-01') |
+-----------------------------------------------+
|                                      86400000 |
+-----------------------------------------------+

-- Any parameter is NULL, returns NULL
SELECT MILLISECONDS_DIFF('2023-01-01 00:00:00', NULL), MILLISECONDS_DIFF(NULL, '2023-01-01 00:00:00');
+------------------------------------------------+------------------------------------------------+
| milliseconds_diff('2023-01-01 00:00:00', NULL) | milliseconds_diff(NULL, '2023-01-01 00:00:00') |
+------------------------------------------------+------------------------------------------------+
| NULL                                           | NULL                                           |
+------------------------------------------------+------------------------------------------------+

-- Times are identical, returns 0
SELECT MILLISECONDS_DIFF('2025-08-11 15:30:00.123', '2025-08-11 15:30:00.123');
+-------------------------------------------------------------------------+
| MILLISECONDS_DIFF('2025-08-11 15:30:00.123', '2025-08-11 15:30:00.123') |
+-------------------------------------------------------------------------+
|                                                                       0 |
+-------------------------------------------------------------------------+
Report issue