[ES|QL][DOCS] Add docs for date_period and time_duration

docs/reference/esql/esql-language.asciidoc

@@ -14,6 +14,7 @@ Detailed reference documentation for the {esql} language:
 * <<esql-enrich-data>>
 * <<esql-process-data-with-dissect-and-grok>>
 * <<esql-implicit-casting>>
+* <<esql-time-spans>>
 
 include::esql-syntax.asciidoc[]
 include::esql-commands.asciidoc[]
@@ -23,3 +24,4 @@ include::multivalued-fields.asciidoc[]
 include::esql-process-data-with-dissect-grok.asciidoc[]
 include::esql-enrich-data.asciidoc[]
 include::implicit-casting.asciidoc[]
+include::time-spans.asciidoc[]

docs/reference/esql/esql-syntax.asciidoc

@@ -175,3 +175,5 @@ Timespan literals are not whitespace sensitive. These expressions are all valid:
 * `1day`
 * `1 day`
 * `1       day`
+
+More examples of the usages of time spans can be found in <<esql-time-spans, Use time spans in ES|QL>>.

docs/reference/esql/time-spans.asciidoc

@@ -0,0 +1,72 @@
+[[esql-time-spans]]
+=== {esql} time spans
+
+++++
+<titleabbrev>Time spans</titleabbrev>
+++++
+
+Time spans provide a way of describing a specific period of time that separates two datetime values. There are currently two supported types of time spans, `DATE_PERIOD` specifies intervals in years, quarters, months, weeks and days, and `TIME_DURATION` specifies intervals in hours, minutes, seconds and milliseconds.
+
+The time span contains two elements, an integer value and a temporal unit, both of them are required when specifying a time span.
+
+Time spans are often used in datetime related grouping functions like <<esql-bucket, BUCKET>>, scalar functions like <<esql-date_trunc, DATE_TRUNC>> and arithmetic operators like `+` and `-`. There are conversions functions that can convert string literals to time spans, <<esql-to_dateperiod, TO_DATEPERIOD>>, <<esql-to_timeduration, TO_TIMEDURATION>> and their corresponding cast operators `::DATE_PERIOD` and `::TIME_DURATION`.
+
+[float]
+=== Examples of using time spans in {esql}
+
+With `BUCKET`
+[source, esql]
+----
+FROM employees
+| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 1 week)
+| SORT week
+----
+
+With `DATE_TRUNC`
+[source, esql]
+----
+FROM employees
+| EVAL x = date_trunc(240 hours, hire_date)
+----
+
+With `+` and/or `-`
+[source, esql]
+----
+FROM employees
+| EVAL x = hire_date + 1 month - 1 day
+----
+
+When a time span is provided as a name parameter in string format, `TO_DATEPERIOD`, `::DATE_PERIOD`, `TO_TIMEDURATION` or `::TIME_DURATION` can be used to convert it to its corresponding time span value.
+[source, esql]
+----
+POST /_query
+{
+   "query": """
+   FROM employees
+   | EVAL x = hire_date + ?timespan::DATE_PERIOD, y = hire_date - TO_DATEPERIOD(?timespan)
+   """,
+   "params": [{"timespan" : "1 day"}]
+}
+----
+
+
+[float]
+=== Supported Temporal Units
+
+The supported temporal units are listed in the following table
+
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+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
+|===
+
+