Skip to main content
Use the datetime_add function in APL to calculate a new datetime by adding a specified number of date parts to a base datetime value. You can add years, months, weeks, days, hours, minutes, seconds, or smaller units. Use negative values to subtract. You can use datetime_add to shift timestamps forward or backward for time-window comparisons, expiration calculations, and timezone adjustments. Use it when you want to:
  • Project future or past timestamps relative to an event.
  • Define time ranges around a known incident or deadline.
  • Shift trace or log timestamps for timezone normalization.

​
For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.
In Splunk SPL, you typically use relative_time(_time, "+1mon") to shift a timestamp by a calendar unit. In APL, the datetime_add function takes the date part as a string, the number of units, and the base datetime as separate arguments.
... | eval new_time=relative_time(_time, "+1mon")
In ANSI SQL, you typically use DATEADD(month, 1, timestamp_column) or equivalent interval arithmetic to shift a timestamp. In APL, datetime_add uses the same conceptual pattern with a string-based part name.
SELECT DATEADD(month, 1, timestamp_column) AS new_time FROM events;

​
Usage

​
Syntax

datetime_add(part, value, datetime)

​
Parameters

NameTypeDescription
partstringThe unit of time to add: 'year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond'.
valueintThe number of units to add. Use a negative value to subtract.
datetimedatetimeThe base datetime value.

​
Returns

A datetime value after adding the specified interval to the base datetime.

​
Use case examples

Project what the time is 1 hour after each request to estimate cache expiration windows.Query
['sample-http-logs']
| extend future_time = datetime_add('hour', 1, _time)
| project _time, future_time, method, status
Run in PlaygroundOutput
_timefuture_timemethodstatus
2025-01-15T10:00:00Z2025-01-15T11:00:00ZGET200
2025-01-15T10:05:00Z2025-01-15T11:05:00ZPOST201
2025-01-15T10:12:00Z2025-01-15T11:12:00ZGET404
This query adds 1 hour to each request timestamp, which is useful for estimating when cached responses expire.
  • datetime_diff: Calculates the difference between two datetime values. Use when you need to measure elapsed time rather than shift a timestamp.
  • ago: Subtracts a timespan from the current UTC time. Use for simple relative time filters based on now().
  • now: Returns the current UTC time.
  • startofmonth: Returns the start of the month for a datetime, useful for month-boundary calculations.
  • endofmonth: Returns the end of the month for a datetime.