ADD_MONTHS

​

Syntax

​

Scalar

add_months(value, months)

​

Arguments

​

Returns

• Type: DATE
• NULL behavior: NULL input or an unrepresentable output yields NULL.

​

Properties

​

Units

• Input unit: Calendar months
• Output unit: DATE

​

Usage notes

• Starting on the last day of a month preserves month-end in the target month.
• Fractional month counts are truncated toward zero. TIMESTAMP input returns a DATE, discarding the time of day.
• INTEGER and INT mean the same type; STRING means VARCHAR text. NULL can be used with a supported type. Cast NULL explicitly when its type would otherwise be unclear.

​

Examples

​

Basic example

SELECT add_months(DATE '2024-01-31',1) AS result;

​

Move backwards across a year boundary

SELECT add_months(DATE '2024-01-31', -2) AS earlier_date;

​

Limitations

• TIMESTAMP input produces DATE and loses its time of day. Query tools may still report TIMESTAMP.
• Keep month counts within the stated range. Very large counts and DECIMAL values with negative scale can overflow or produce unexpected results; an error or NULL result is not guaranteed.