Skip to content

Commit 1b45c81

Browse files
fang-xing-esqlfang-xing-esql
committed
[ES|QL][DOCS] Add docs for date_period and time_duration (#116368)
* add docs for date_period and time_duration
1 parent 8a1231c commit 1b45c81

File tree

5 files changed

+143
-30
lines changed

5 files changed

+143
-30
lines changed

‎docs/reference/esql/esql-language.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Detailed reference documentation for the {esql} language:
1414
* <<esql-enrich-data>>
1515
* <<esql-process-data-with-dissect-and-grok>>
1616
* <<esql-implicit-casting>>
17+
* <<esql-time-spans>>
1718

1819
include::esql-syntax.asciidoc[]
1920
include::esql-commands.asciidoc[]
@@ -23,3 +24,4 @@ include::multivalued-fields.asciidoc[]
2324
include::esql-process-data-with-dissect-grok.asciidoc[]
2425
include::esql-enrich-data.asciidoc[]
2526
include::implicit-casting.asciidoc[]
27+
include::time-spans.asciidoc[]

‎docs/reference/esql/esql-syntax.asciidoc‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -157,21 +157,15 @@ FROM employees
157157
==== Timespan literals
158158

159159
Datetime intervals and timespans can be expressed using timespan literals.
160-
Timespan literals are a combination of a number and a qualifier. These
161-
qualifiers are supported:
162-
163-
* `millisecond`/`milliseconds`/`ms`
164-
* `second`/`seconds`/`sec`/`s`
165-
* `minute`/`minutes`/`min`
166-
* `hour`/`hours`/`h`
167-
* `day`/`days`/`d`
168-
* `week`/`weeks`/`w`
169-
* `month`/`months`/`mo`
170-
* `quarter`/`quarters`/`q`
171-
* `year`/`years`/`yr`/`y`
160+
Timespan literals are a combination of a number and a temporal unit. The
161+
supported temporal units are listed in <<esql-time-spans-table, time span unit>>.
162+
More examples of the usages of time spans can be found in
163+
<<esql-time-spans, Use time spans in ES|QL>>.
164+
172165

173166
Timespan literals are not whitespace sensitive. These expressions are all valid:
174167

175168
* `1day`
176169
* `1 day`
177170
* `1 day`
171+

‎docs/reference/esql/functions/binary.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ Supported types:
8787

8888
include::types/greater_than_or_equal.asciidoc[]
8989

90+
[[esql-add]]
9091
==== Add `+`
9192
[.text-center]
9293
image::esql/functions/signature/add.svg[Embedded,opts=inline]
@@ -98,6 +99,7 @@ Supported types:
9899

99100
include::types/add.asciidoc[]
100101

102+
[[esql-subtract]]
101103
==== Subtract `-`
102104
[.text-center]
103105
image::esql/functions/signature/sub.svg[Embedded,opts=inline]

‎docs/reference/esql/implicit-casting.asciidoc‎

Lines changed: 22 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<titleabbrev>Implicit casting</titleabbrev>
66
++++
77

8-
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.
8+
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.
99

1010
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.
1111

@@ -18,7 +18,10 @@ FROM employees
1818
| LIMIT 1
1919
----
2020

21-
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.
21+
[discrete]
22+
[[esql-implicit-casting-example]]
23+
==== Implicit casting example
24+
Implicit casting automatically converts string literals to the target data type. This allows users to specify string values for types like `date`, `date_period`, `time_duration`, `ip` and `version` in their queries.
2225

2326
The first query can be coded without calling the `to_datetime` function, as follows:
2427

@@ -31,35 +34,36 @@ FROM employees
3134
| LIMIT 1
3235
----
3336

34-
[float]
35-
=== Implicit casting support
37+
[discrete]
38+
[[esql-implicit-casting-supported-operations]]
39+
==== Operations that support implicit casting
3640

3741
The following table details which {esql} operations support implicit casting for different data types.
3842

3943
[%header.monospaced.styled,format=dsv,separator=|]
4044
|===
41-
||ScalarFunction*|Operator*|<<esql-group-functions, GroupingFunction>>|<<esql-agg-functions, AggregateFunction>>
42-
|DATE|Y|Y|Y|N
43-
|IP|Y|Y|Y|N
44-
|VERSION|Y|Y|Y|N
45-
|BOOLEAN|Y|Y|Y|N
46-
|DATE_PERIOD/TIME_DURATION|Y|N|Y|N
45+
|ScalarFunctions|Operators|<<esql-group-functions, GroupingFunctions>>|<<esql-agg-functions, AggregateFunctions>>
46+
DATE|Y|Y|Y|N
47+
DATE_PERIOD/TIME_DURATION|Y|N|Y|N
48+
IP|Y|Y|Y|N
49+
VERSION|Y|Y|Y|N
50+
BOOLEAN|Y|Y|Y|N
4751
|===
4852

49-
ScalarFunction* includes:
53+
ScalarFunctions includes:
5054

51-
<<esql-conditional-functions-and-expressions, Conditional Functions and Expressions>>
55+
* <<esql-conditional-functions-and-expressions, Conditional Functions and Expressions>>
5256

53-
<<esql-date-time-functions, Date and Time Functions>>
57+
* <<esql-date-time-functions, Date and Time Functions>>
5458

55-
<<esql-ip-functions, IP Functions>>
59+
* <<esql-ip-functions, IP Functions>>
5660

5761

58-
Operator* includes:
62+
Operators includes:
5963

60-
<<esql-binary-operators, Binary Operators>>
64+
* <<esql-binary-operators, Binary Operators>>
6165

62-
<<esql-unary-operators, Unary Operator>>
66+
* <<esql-unary-operators, Unary Operator>>
6367

64-
<<esql-in-operator, IN>>
68+
* <<esql-in-operator, IN>>
6569

‎docs/reference/esql/time-spans.asciidoc‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
[[esql-time-spans]]
2+
=== {esql} time spans
3+
4+
++++
5+
<titleabbrev>Time spans</titleabbrev>
6+
++++
7+
8+
Time spans represent intervals between two datetime values. There are currently two supported types of time spans:
9+
10+
* `DATE_PERIOD` specifies intervals in years, quarters, months, weeks and days
11+
* `TIME_DURATION` specifies intervals in hours, minutes, seconds and milliseconds
12+
13+
A time span requires two elements: an integer value and a temporal unit.
14+
15+
Time spans work with grouping functions such as <<esql-bucket, BUCKET>>, scalar functions such as <<esql-date_trunc, DATE_TRUNC>> and arithmetic operators such as <<esql-add, `+`>> and <<esql-subtract, `-`>>. Convert strings to time spans using <<esql-to_dateperiod, TO_DATEPERIOD>>, <<esql-to_timeduration, TO_TIMEDURATION>>, or the cast operators `::DATE_PERIOD`, `::TIME_DURATION`.
16+
17+
[discrete]
18+
[[esql-time-spans-examples]]
19+
==== Examples of using time spans in {esql}
20+
21+
22+
With `BUCKET`:
23+
[source.merge.styled,esql]
24+
----
25+
include::{esql-specs}/bucket.csv-spec[tag=docsBucketWeeklyHistogramWithSpan]
26+
----
27+
[%header.monospaced.styled,format=dsv,separator=|]
28+
|===
29+
include::{esql-specs}/bucket.csv-spec[tag=docsBucketWeeklyHistogramWithSpan-result]
30+
|===
31+
32+
33+
With `DATE_TRUNC`:
34+
[source.merge.styled,esql]
35+
----
36+
include::{esql-specs}/date.csv-spec[tag=docsDateTrunc]
37+
----
38+
[%header.monospaced.styled,format=dsv,separator=|]
39+
|===
40+
include::{esql-specs}/date.csv-spec[tag=docsDateTrunc-result]
41+
|===
42+
43+
44+
With `+` and/or `-`:
45+
[source.merge.styled,esql]
46+
----
47+
include::{esql-specs}/date.csv-spec[tag=docsNowWhere]
48+
----
49+
[%header.monospaced.styled,format=dsv,separator=|]
50+
|===
51+
include::{esql-specs}/date.csv-spec[tag=docsNowWhere-result]
52+
|===
53+
54+
55+
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 `-`.
56+
[source, esql]
57+
----
58+
POST /_query
59+
{
60+
"query": """
61+
FROM employees
62+
| EVAL x = hire_date + ?timespan::DATE_PERIOD, y = hire_date - TO_DATEPERIOD(?timespan)
63+
""",
64+
"params": [{"timespan" : "1 day"}]
65+
}
66+
----
67+
68+
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`.
69+
[source, esql]
70+
----
71+
POST /_query
72+
{
73+
"query": """
74+
FROM employees
75+
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
76+
| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, ?timespan)
77+
| SORT week
78+
""",
79+
"params": [{"timespan" : "1 week"}]
80+
}
81+
----
82+
83+
[source, esql]
84+
----
85+
POST /_query
86+
{
87+
"query": """
88+
FROM employees
89+
| KEEP first_name, last_name, hire_date
90+
| EVAL year_hired = DATE_TRUNC(?timespan, hire_date)
91+
""",
92+
"params": [{"timespan" : "1 year"}]
93+
}
94+
----
95+
96+
[discrete]
97+
[[esql-time-spans-table]]
98+
==== Supported temporal units
99+
[%header.monospaced.styled,format=dsv,separator=|]
100+
|===
101+
Temporal Units|Valid Abbreviations
102+
year|y, yr, years
103+
quarter|q, quarters
104+
month|mo, months
105+
week|w, weeks
106+
day|d, days
107+
hour|h, hours
108+
minute|min, minutes
109+
second|s, sec, seconds
110+
millisecond|ms, milliseconds
111+
|===

0 commit comments

Comments
 (0)