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

MICROSECONDS_DIFF

説明​

MICROSECONDS_DIFF 関数は、二つの日時値の差をマイクロ秒単位で計算します。結果は、開始時刻から終了時刻までの間にある完全なマイクロ秒数です。DATETIME 型と TIMESTAMP_NS 型に対応し、異なる型の引数も組み合わせて指定できます。

構文​

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

パラメータ​

パラメータ説明
<date_or_time_expr1>終了時刻。型は DATETIME または TIMESTAMP_NS です。対応する形式については、日時の変換とTIMESTAMP_NS の変換を参照してください。
<date_or_time_expr2>開始時刻。DATETIME 型、TIMESTAMP_NS 型、または有効な日時文字列を指定します。

戻り値​

二つの時刻の差をマイクロ秒単位で表す BIGINT 型の値を返します。

  • <date_or_time_expr1> が <date_or_time_expr2> より後の場合、正の数を返します。
  • <date_or_time_expr1> が <date_or_time_expr2> より前の場合、負の数を返します。
  • 二つの時刻がマイクロ秒部分を含めて同じ場合、0 を返します。
  • 完全な一マイクロ秒に満たないナノ秒の端数は、ゼロ方向に切り捨てます。ナノ秒単位の正確な差を求めるには、NANOSECONDS_DIFFを使用してください。
  • いずれかの引数が NULL の場合、NULL を返します。

例​

-- Calculate the microsecond difference between two datetime values
SELECT MICROSECONDS_DIFF('2020-12-25 21:00:00.623000', '2020-12-25 21:00:00.123000');

+------------------------------------------------------------------------------+
| MICROSECONDS_DIFF('2020-12-25 21:00:00.623000','2020-12-25 21:00:00.123000') |
+------------------------------------------------------------------------------+
|                                                                       500000 |
+------------------------------------------------------------------------------+

--If the end time is earlier than the start time, a negative number is returned.
SELECT MICROSECONDS_DIFF('2023-10-01 12:00:00.500000', '2023-10-01 12:00:00.800000');
+-------------------------------------------------------------------------------+
| MICROSECONDS_DIFF('2023-10-01 12:00:00.500000', '2023-10-01 12:00:00.800000') |
+-------------------------------------------------------------------------------+
|                                                                       -300000 |
+-------------------------------------------------------------------------------+

-- TIMESTAMP_NS values can be compared at nanosecond precision; incomplete microseconds are truncated
SELECT MICROSECONDS_DIFF(
    CAST('2025-01-02 03:04:05.123457788' AS TIMESTAMP_NS),
    CAST('2025-01-02 03:04:05.123456789' AS TIMESTAMP_NS)
);
+----------------------------------------------------------------------------------------------------+
| MICROSECONDS_DIFF(CAST('2025-01-02 03:04:05.123457788' AS TIMESTAMP_NS), CAST('2025-01-02 03:04:05.123456789' AS TIMESTAMP_NS)) |
+----------------------------------------------------------------------------------------------------+
|                                                                                                  0 |
+----------------------------------------------------------------------------------------------------+

-- Input type is date, time part defaults to 00:00:00.000000
SELECT MICROSECONDS_DIFF('2023-10-01 12:00:00.500000', '2023-10-01');
+---------------------------------------------------------------+
| MICROSECONDS_DIFF('2023-10-01 12:00:00.500000', '2023-10-01') |
+---------------------------------------------------------------+
|                                                   43200500000 |
+---------------------------------------------------------------+

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

--- datetime is same,return 0
 SELECT MICROSECONDS_DIFF('2025-08-11 15:30:00.123456', '2025-08-11 15:30:00.123456');
+-------------------------------------------------------------------------------+
| MICROSECONDS_DIFF('2025-08-11 15:30:00.123456', '2025-08-11 15:30:00.123456') |
+-------------------------------------------------------------------------------+
|                                                                             0 |
+-------------------------------------------------------------------------------+
Report issue