TIMESTAMP_ADD

​

Syntax

​

Scalar

timestamp_add(unit, amount, value)

​

Timestampadd units (scalar)

timestampadd(unit, amount, value)

• TIMESTAMPADD uses a unit keyword such as DAY; do not quote it as a STRING literal.

​

Arguments

​

Scalar

​

Timestampadd units

​

Returns

• Type: TIMESTAMP, preserving the input’s time zone
• NULL behavior: Returns NULL if amount or value is NULL.

​

Properties

​

Usage notes

• Supported singular/plural units: year, quarter, month, week, day, hour, minute, second, millisecond, microsecond.
• Month/quarter/year operations use calendar-month arithmetic; shorter units use fixed microsecond durations.
• Numeric amounts are converted to BIGINT. Fractional amounts follow BIGINT conversion rules; the function does not preserve fractional units.

​

Examples

​

Basic example

SELECT timestamp_add('day',1,TIMESTAMP '2024-01-01 10:30:00') AS result;

​

Alias calling form: TIMESTAMPADD

SELECT timestampadd(DAY,1,TIMESTAMP '2024-01-01 10:30:00') AS result;

​

Limitations

• Do not use month, quarter or year units with timestamps before 1970-01-01 00:00:00 UTC that include fractional seconds. Those inputs can produce an incorrect calendar result.
• Keep month totals within the stated limits. Larger totals can produce incorrect results without an error.
• Fixed-duration calculations raise an error on overflow. Within the month-count limits, invalid calendar results also raise an error. Larger month counts can produce an incorrect result without an error or NULL.