Перейти к содержимому
Последнее обновление

MICROSECONDS_DIFF

Описание​

Функция MICROSECONDS_DIFF вычисляет разницу в микросекундах между двумя значениями даты и времени. Результат представляет собой количество полных микросекунд в интервале между конечным и начальным временем. Поддерживаются DATETIME и TIMESTAMP_NS, в том числе аргументы разных типов.

Синтаксис​

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

Параметры​

ПараметрОписание
<date_or_time_expr1>Конечное время типа DATETIME или TIMESTAMP_NS. Поддерживаемые форматы см. в разделах преобразование datetime и преобразование 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