[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

@@ -157,21 +157,15 @@ FROM employees
 ==== Timespan literals
 
 Datetime intervals and timespans can be expressed using timespan literals.
-Timespan literals are a combination of a number and a qualifier. These
-qualifiers are supported:
-
-* `millisecond`/`milliseconds`/`ms`
-* `second`/`seconds`/`sec`/`s`
-* `minute`/`minutes`/`min`
-* `hour`/`hours`/`h`
-* `day`/`days`/`d`
-* `week`/`weeks`/`w`
-* `month`/`months`/`mo`
-* `quarter`/`quarters`/`q`
-* `year`/`years`/`yr`/`y`
+Timespan literals are a combination of a number and a temporal unit. The
+supported temporal units are listed in <<esql-time-spans-table, time span unit>>.
+More examples of the usages of time spans can be found in
+<<esql-time-spans, Use time spans in ES|QL>>.
+
 
 Timespan literals are not whitespace sensitive. These expressions are all valid:
 
 * `1day`
 * `1 day`
 * `1       day`
+

docs/reference/esql/functions/binary.asciidoc

@@ -87,6 +87,7 @@ Supported types:
 
 include::types/greater_than_or_equal.asciidoc[]
 
+[[esql-add]]
 ==== Add `+`
 [.text-center]
 image::esql/functions/signature/add.svg[Embedded,opts=inline]
@@ -98,6 +99,7 @@ Supported types:
 
 include::types/add.asciidoc[]
 
+[[esql-subtract]]
 ==== Subtract `-`
 [.text-center]
 image::esql/functions/signature/sub.svg[Embedded,opts=inline]

docs/reference/esql/implicit-casting.asciidoc

@@ -5,7 +5,7 @@
 <titleabbrev>Implicit casting</titleabbrev>
 ++++
 
-Often users will input `date`, `ip`, `version`, `date_period` or `time_duration` as simple strings in their queries for use in predicates, functions, or expressions. {esql} provides <<esql-type-conversion-functions, type conversion functions>> to explicitly convert these strings into the desired data types.
+Often users will input `date`, `date_period`, `time_duration`, `ip` or `version` as simple strings in their queries for use in predicates, functions, or expressions. {esql} provides <<esql-type-conversion-functions, type conversion functions>> to explicitly convert these strings into the desired data types.
 
 Without implicit casting users must explicitly code these `to_X` functions in their queries, when string literals don't match the target data types they are assigned or compared to. Here is an example of using `to_datetime` to explicitly perform a data type conversion.
 
@@ -18,7 +18,9 @@ FROM employees
 | LIMIT 1
 ----
 
-Implicit casting improves usability, by automatically converting string literals to the target data type. This is most useful when the target data type is `date`, `ip`, `version`, `date_period` or `time_duration`. It is natural to specify these as a string in queries.
+
+==== Implicit casting example
+Implicit casting improves usability, by automatically converting string literals to the target data type. This is most useful when the target data type is `date`, `date_period`, `time_duration`, `ip` or `version`. It is natural to specify these as a string in queries.
 
 The first query can be coded without calling the `to_datetime` function, as follows:
 
@@ -31,35 +33,34 @@ FROM employees
 | LIMIT 1
 ----
 
-[float]
-=== Implicit casting support
+==== Operations that support implicit casting
 
 The following table details which {esql} operations support implicit casting for different data types.
 
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-||ScalarFunction*|Operator*|<<esql-group-functions, GroupingFunction>>|<<esql-agg-functions, AggregateFunction>>
-|DATE|Y|Y|Y|N
-|IP|Y|Y|Y|N
-|VERSION|Y|Y|Y|N
-|BOOLEAN|Y|Y|Y|N
-|DATE_PERIOD/TIME_DURATION|Y|N|Y|N
+|ScalarFunctions|Operators|<<esql-group-functions, GroupingFunctions>>|<<esql-agg-functions, AggregateFunctions>>
+DATE|Y|Y|Y|N
+DATE_PERIOD/TIME_DURATION|Y|N|Y|N
+IP|Y|Y|Y|N
+VERSION|Y|Y|Y|N
+BOOLEAN|Y|Y|Y|N
 |===
 
-ScalarFunction* includes:
+ScalarFunctions includes:
 
-<<esql-conditional-functions-and-expressions, Conditional Functions and Expressions>>
+* <<esql-conditional-functions-and-expressions, Conditional Functions and Expressions>>
 
-<<esql-date-time-functions, Date and Time Functions>>
+* <<esql-date-time-functions, Date and Time Functions>>
 
-<<esql-ip-functions, IP Functions>>
+* <<esql-ip-functions, IP Functions>>
 
 
-Operator* includes:
+Operators includes:
 
-<<esql-binary-operators, Binary Operators>>
+* <<esql-binary-operators, Binary Operators>>
 
-<<esql-unary-operators, Unary Operator>>
+* <<esql-unary-operators, Unary Operator>>
 
-<<esql-in-operator, IN>>
+* <<esql-in-operator, IN>>
 

docs/reference/esql/time-spans.asciidoc

@@ -0,0 +1,106 @@
+[[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` specifying intervals in years, quarters, months, weeks and days, and `TIME_DURATION` specifying intervals in hours, minutes, seconds and milliseconds.
+
+The time span contains two elements, an integer value and a temporal unit, both 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 <<esql-add, `+`>> and <<esql-subtract, `-`>>. 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 <<esql-cast-operator, cast operators>> `::DATE_PERIOD` and `::TIME_DURATION`.
+
+==== Examples of using time spans in {esql}
+
+
+With `BUCKET`:
+[source.merge.styled,esql]
+----
+include::{esql-specs}/bucket.csv-spec[tag=docsBucketWeeklyHistogramWithSpan]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/bucket.csv-spec[tag=docsBucketWeeklyHistogramWithSpan-result]
+|===
+
+
+With `DATE_TRUNC`:
+[source.merge.styled,esql]
+----
+include::{esql-specs}/date.csv-spec[tag=docsDateTrunc]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/date.csv-spec[tag=docsDateTrunc-result]
+|===
+
+
+With `+` and/or `-`:
+[source.merge.styled,esql]
+----
+include::{esql-specs}/date.csv-spec[tag=docsNowWhere]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/date.csv-spec[tag=docsNowWhere-result]
+|===
+
+
+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 it to its corresponding time span value in arithmetic operations like `+` and/or `-`.
+[source, esql]
+----
+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 converted automatically to its corresponding time span value in grouping functions and scalar functions, like `BUCKET` and `DATE_TRUNC`.
+[source, esql]
+----
+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"}]
+}
+----
+
+[source, esql]
+----
+POST /_query
+{
+   "query": """
+   FROM employees
+   | KEEP first_name, last_name, hire_date
+   | EVAL year_hired = DATE_TRUNC(?timespan, hire_date)
+   """,
+   "params": [{"timespan" : "1 year"}]
+}
+----
+
+
+[[esql-time-spans-table]]
+==== Supported temporal units
+[%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
+|===