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

MICROSECONDS_ADD

Описание​

Функция MICROSECONDS_ADD добавляет указанное количество микросекунд к входному значению даты и времени и возвращает полученное значение даты и времени. Функция поддерживает обработку значений типов DATETIME или TIMESTAMPTZ с точностью до микросекунд.

Эта функция работает так же, как функция date_add в MySQL при использовании MICROSECOND в качестве единицы измерения.

Синтаксис​

MICROSECONDS_ADD(`<datetime_like_type>`, `<delta>`)

Параметры​

ПараметрОписание
<datetime_like_type>Входное значение даты и времени типа DATETIME или TIMESTAMPTZ. О форматах см. преобразование timestamptz, преобразование datetime
<delta>Количество добавляемых микросекунд, тип BIGINT. 1 секунда = 1,000,000 микросекунд.

Возвращаемое значение​

Возвращает результат добавления указанного количества микросекунд <delta> к исходному времени <datetime_like_type>. Тип возвращаемого значения совпадает с типом первого параметра.

  • Если первый параметр имеет тип TIMESTAMPTZ, возвращается TIMESTAMPTZ.

  • Если первый параметр имеет тип DATETIME, возвращается DATETIME.

  • Если <delta> имеет отрицательное значение, функция вычитает соответствующее количество микросекунд из исходного времени (то есть MICROSECONDS_ADD(basetime, -n) эквивалентно MICROSECONDS_SUB(basetime, n)).

  • Если результат вычисления выходит за допустимый диапазон типа DATETIME (от 0000-01-01 00:00:00 до 9999-12-31 23:59:59.999999), возникает исключение.

  • Если любой из параметров равен NULL, возвращается NULL.

Примеры​

-- Add microseconds
SELECT NOW(3) AS current_time, MICROSECONDS_ADD(NOW(3), 100000000) AS after_add;

+-------------------------+----------------------------+
| current_time            | after_add                  |
+-------------------------+----------------------------+
| 2025-08-11 14:49:16.368 | 2025-08-11 14:50:56.368000 |
+-------------------------+----------------------------+

-- Add negative microseconds, equivalent to subtracting
SELECT MICROSECONDS_ADD('2023-10-01 12:00:00.500000', -300000) AS after_add;
+----------------------------+
| after_add                  |
+----------------------------+
| 2023-10-01 12:00:00.200000 |
+----------------------------+

-- Input type is date, time part defaults to 00:00:00.000000
SELECT MICROSECONDS_ADD('2023-10-01', -300000);
+-----------------------------------------+
| MICROSECONDS_ADD('2023-10-01', -300000) |
+-----------------------------------------+
| 2023-09-30 23:59:59.700000              |
+-----------------------------------------+

-- Example of TimeStampTz type, SET time_zone = '+08:00'
SELECT MICROSECONDS_ADD('2024-12-25 12:34:56.123+04:00', '765800');
+-------------------------------------------------------------+
| MICROSECONDS_ADD('2024-12-25 12:34:56.123+04:00', '765800') |
+-------------------------------------------------------------+
| 2024-12-25 16:34:56.888800+08:00                            |
+-------------------------------------------------------------+

-- Calculation result exceeds datetime range, throws error
SELECT MICROSECONDS_ADD('9999-12-31 23:59:59.999999', 2000000) AS after_add;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation microseconds_add of 9999-12-31 23:59:59.999999, 2000000 out of range

-- Any input parameter is NULL, returns NULL
SELECT MICROSECONDS_ADD('2023-10-01 12:00:00.500000', NULL);
+-----------------------------------------------------+
| MICROSECONDS_ADD('2023-10-01 12:00:00.500000',NULL) |
+-----------------------------------------------------+
| NULL                                                |
+-----------------------------------------------------+

Report issue