Skip to content

datetime_add

Syntax

datetime_add(x1 x2, unit)
datetime_add(x1, x2, unit)

Parameters

x1
A numeric value representing a date or datetime in the format YYYYMMDD or YYYYMMDDHH.
x2
A numeric value (positive or negative) indicating the number of increments to add.
unit
A string surrounded by quotes specifying the increment type. Valid types are:
  • "y" - years
  • "m" - months
  • "d" - days
  • "w" - weeks
  • "h" - hours

Returns

Returns a numeric value representing the resulting date or datetime after adding the specified amount of time.

Description

The datetime_add function adds a specified time to a given date or datetime. It can be used to perform date arithmetic, such as adding/subtracting days, weeks, months, or years to/from a date, or adding/subtracting hours to a datetime.

The function requires a valid date or datetime as the first parameter, an increment value as the second parameter, and a string specifying the unit of time to add as the third parameter.

Negative values are considered valid, and allow for subtraction from a datetime.

Adding a month will try to preserve the date if the date is a valid date for the resulting month. If it's not a valid date (e.g. February 31st), it will be capped to the last day of the month. Adding a week will always add 7 days.

This action will return an error if the first parameter (x1) is not in the correct format (YYYYMMDD or YYYYMMDDHH). Decimal values for parameter x1 will also result in an error.

Examples

datetime_add(20240101 5, "d")  # Returns 20240106 (5 days after January 1, 2024)
datetime_add(2024010110, -3, "h") # Returns 2024010107 (3 hours before January 1, 2024, 10:00)
datetime_add(20240101, 2, "w") # Returns 20240115 (2 weeks after January 1, 2024)

See Also