elasticsearch/docs/reference/query-languages/esql/esql-time-spans.md

navigation_title	mapped_pages
Time spans	https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-time-spans.html

{{esql}} time spans [esql-time-spans]

Time spans represent intervals between two datetime values. There are currently two supported types of time spans:

• DATE_PERIOD specifies intervals in years, quarters, months, weeks and days
• TIME_DURATION specifies intervals in hours, minutes, seconds and milliseconds

A time span requires two elements: an integer value and a temporal unit.

Time spans work with grouping functions such as BUCKET, scalar functions such as DATE_TRUNC and arithmetic operators such as + and -. Convert strings to time spans using TO_DATEPERIOD, TO_TIMEDURATION, or the cast operators ::DATE_PERIOD, ::TIME_DURATION.

Examples of using time spans in {{esql}} [esql-time-spans-examples]

With BUCKET:

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 1 week)
| SORT week

hires_per_week:long	week:date
2	1985-02-18T00:00:00.000Z
1	1985-05-13T00:00:00.000Z
1	1985-07-08T00:00:00.000Z
1	1985-09-16T00:00:00.000Z
2	1985-10-14T00:00:00.000Z
4	1985-11-18T00:00:00.000Z

With DATE_TRUNC:

FROM employees
| KEEP first_name, last_name, hire_date
| EVAL year_hired = DATE_TRUNC(1 year, hire_date)

first_name:keyword	last_name:keyword	hire_date:date	year_hired:date
Alejandro	McAlpine	1991-06-26T00:00:00.000Z	1991-01-01T00:00:00.000Z
Amabile	Gomatam	1992-11-18T00:00:00.000Z	1992-01-01T00:00:00.000Z
Anneke	Preusig	1989-06-02T00:00:00.000Z	1989-01-01T00:00:00.000Z

With + and/or -:

FROM sample_data
| WHERE @timestamp > NOW() - 1 hour

@timestamp:date	client_ip:ip	event_duration:long	message:keyword

When a time span is provided as a named parameter in string format, TO_DATEPERIOD, ::DATE_PERIOD, TO_TIMEDURATION or ::TIME_DURATION can be used to convert to its corresponding time span value for arithmetic operations like + and/or -.

POST /_query
{
   "query": """
   FROM employees
   | EVAL x = hire_date + ?timespan::DATE_PERIOD, y = hire_date - TO_DATEPERIOD(?timespan)
   """,
   "params": [{"timespan" : "1 day"}]
}

When a time span is provided as a named parameter in string format, it can be automatically converted to its corresponding time span value in grouping functions and scalar functions, like BUCKET and DATE_TRUNC.

POST /_query
{
   "query": """
   FROM employees
   | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
   | STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, ?timespan)
   | SORT week
   """,
   "params": [{"timespan" : "1 week"}]
}

POST /_query
{
   "query": """
   FROM employees
   | KEEP first_name, last_name, hire_date
   | EVAL year_hired = DATE_TRUNC(?timespan, hire_date)
   """,
   "params": [{"timespan" : "1 year"}]
}

Supported temporal units [esql-time-spans-table]

Temporal Units	Valid Abbreviations
year	y, yr, years
quarter	q, quarters
month	mo, months
week	w, weeks
day	d, days
hour	h, hours
minute	min, minutes
second	s, sec, seconds
millisecond	ms, milliseconds