Skip to content

Commit f4ab6c2

Browse files
costincostin
committed
DOC: Enhance SQL Functions documentation
Split function section into multiple chapters Add String functions Add (small) section on Conversion/Cast functions Add missing aggregation functions Enable documentation testing (was disabled by accident). While at it, fix failing tests Improve spec tests to allow multi-line queries (useful for docs) Add ability to ignore a spec test (name should end with -Ignore) (cherry picked from commit 443f9ca)
1 parent c47be78 commit f4ab6c2

File tree

16 files changed

+1413
-534
lines changed

16 files changed

+1413
-534
lines changed

‎docs/reference/sql/functions/aggs.asciidoc

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
[[sql-functions-aggs]]
4+
=== Aggregate Functions
5+
6+
Functions for computing a _single_ result from a set of input values.
7+
{es-sql} supports aggregate functions only alongside <<sql-syntax-group-by,grouping>> (implicit or explicit).
8+
9+
==== General Purpose
10+
11+
[[sql-functions-aggs-avg]]
12+
===== `AVG`
13+
14+
*Input*: Numeric, *Output*: `double`
15+
16+
https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (arithmetic mean) of input values.
17+
18+
19+
["source","sql",subs="attributes,callouts,macros"]
20+
----
21+
include-tagged::{sql-specs}/docs.csv-spec[aggAvg]
22+
----
23+
24+
[[sql-functions-aggs-count]]
25+
===== `COUNT`
26+
27+
*Input*: Any, *Output*: `bigint`
28+
29+
Total number (count) of input values.
30+
31+
["source","sql",subs="attributes,callouts,macros"]
32+
----
33+
include-tagged::{sql-specs}/docs.csv-spec[aggCountStar]
34+
----
35+
36+
[[sql-functions-aggs-count-distinct]]
37+
===== `COUNT(DISTINCT)`
38+
39+
*Input*: Any, *Output*: `bigint`
40+
41+
Total number of _distinct_ values in input values.
42+
43+
["source","sql",subs="attributes,callouts,macros"]
44+
----
45+
include-tagged::{sql-specs}/docs.csv-spec[aggCountDistinct]
46+
----
47+
48+
[[sql-functions-aggs-max]]
49+
===== `MAX`
50+
51+
*Input*: Numeric, *Output*: Same as input
52+
53+
Maximum value across input values.
54+
55+
["source","sql",subs="attributes,callouts,macros"]
56+
----
57+
include-tagged::{sql-specs}/docs.csv-spec[aggMax]
58+
----
59+
60+
[[sql-functions-aggs-min]]
61+
===== `MIN`
62+
63+
*Input*: Numeric, *Output*: Same as input
64+
65+
Minimum value across input values.
66+
67+
["source","sql",subs="attributes,callouts,macros"]
68+
----
69+
include-tagged::{sql-specs}/docs.csv-spec[aggMin]
70+
----
71+
72+
[[sql-functions-aggs-sum]]
73+
===== `SUM`
74+
75+
*Input*: Numeric, *Output*: `bigint` for integer input, `double` for floating points
76+
77+
Sum of input values.
78+
79+
["source","sql",subs="attributes,callouts,macros"]
80+
----
81+
include-tagged::{sql-specs}/docs.csv-spec[aggSum]
82+
----
83+
84+
==== Statistics
85+
86+
[[sql-functions-aggs-kurtosis]]
87+
===== `KURTOSIS`
88+
89+
*Input*: Numeric, *Output*: `double`
90+
91+
https://en.wikipedia.org/wiki/Kurtosis[Quantify] the shape of the distribution of input values.
92+
93+
["source","sql",subs="attributes,callouts,macros"]
94+
----
95+
include-tagged::{sql-specs}/docs.csv-spec[aggKurtosis]
96+
----
97+
98+
[[sql-functions-aggs-percentile]]
99+
===== `PERCENTILE`
100+
101+
*Input*: Numeric, *Output*: `double`
102+
103+
The nth https://en.wikipedia.org/wiki/Percentile[percentile] of input values.
104+
105+
["source","sql",subs="attributes,callouts,macros"]
106+
----
107+
include-tagged::{sql-specs}/docs.csv-spec[aggPercentile]
108+
----
109+
110+
[[sql-functions-aggs-percentile-rank]]
111+
===== `PERCENTILE_RANK`
112+
113+
*Input*: Numeric, *Output*: `double`
114+
115+
The https://en.wikipedia.org/wiki/Percentile_rank[percentile rank] of input values of input values.
116+
117+
["source","sql",subs="attributes,callouts,macros"]
118+
----
119+
include-tagged::{sql-specs}/docs.csv-spec[aggPercentileRank]
120+
----
121+
122+
[[sql-functions-aggs-skewness]]
123+
===== `SKEWNESS`
124+
125+
*Input*: Numeric, *Output*: `double`
126+
127+
https://en.wikipedia.org/wiki/Skewness[Quantify] the asymmetric distribution of input values.
128+
129+
["source","sql",subs="attributes,callouts,macros"]
130+
----
131+
include-tagged::{sql-specs}/docs.csv-spec[aggSkewness]
132+
----
133+
134+
[[sql-functions-aggs-stddev-pop]]
135+
===== `STDDEV_POP`
136+
137+
*Input*: Numeric, *Output*: `double`
138+
139+
https://en.wikipedia.org/wiki/Standard_deviations[Population standard deviation] of input values.
140+
141+
["source","sql",subs="attributes,callouts,macros"]
142+
----
143+
include-tagged::{sql-specs}/docs.csv-spec[aggStddevPop]
144+
----
145+
146+
[[sql-functions-aggs-sum-squares]]
147+
===== `SUM_OF_SQUARES`
148+
149+
*Input*: Numeric, *Output*: `double`
150+
151+
https://en.wikipedia.org/wiki/Total_sum_of_squares[Sum of squares] of input values.
152+
153+
["source","sql",subs="attributes,callouts,macros"]
154+
----
155+
include-tagged::{sql-specs}/docs.csv-spec[aggSumOfSquares]
156+
----
157+
158+
[[sql-functions-aggs-var-pop]]
159+
===== `VAR_POP`
160+
161+
*Input*: Numeric, *Output*: `double`
162+
163+
https://en.wikipedia.org/wiki/Variance[Population] variance of input values.
164+
165+
["source","sql",subs="attributes,callouts,macros"]
166+
----
167+
include-tagged::{sql-specs}/docs.csv-spec[aggVarPop]
168+
----

‎docs/reference/sql/functions/date-time.asciidoc

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
[role="xpack"]
2+
[testenv="basic"]
3+
[[sql-functions-datetime]]
4+
=== Date and Time Functions
5+
6+
* Extract the year from a date (`YEAR`)
7+
8+
["source","sql",subs="attributes,callouts,macros"]
9+
--------------------------------------------------
10+
include-tagged::{sql-specs}/datetime.csv-spec[year]
11+
--------------------------------------------------
12+
13+
* Extract the month of the year from a date (`MONTH_OF_YEAR` or `MONTH`)
14+
15+
["source","sql",subs="attributes,callouts,macros"]
16+
--------------------------------------------------
17+
include-tagged::{sql-specs}/datetime.csv-spec[monthOfYear]
18+
--------------------------------------------------
19+
20+
* Extract the week of the year from a date (`WEEK_OF_YEAR` or `WEEK`)
21+
22+
["source","sql",subs="attributes,callouts,macros"]
23+
--------------------------------------------------
24+
include-tagged::{sql-specs}/datetime.csv-spec[weekOfYear]
25+
--------------------------------------------------
26+
27+
* Extract the day of the year from a date (`DAY_OF_YEAR` or `DOY`)
28+
29+
["source","sql",subs="attributes,callouts,macros"]
30+
--------------------------------------------------
31+
include-tagged::{sql-specs}/datetime.csv-spec[dayOfYear]
32+
--------------------------------------------------
33+
34+
* Extract the day of the month from a date (`DAY_OF_MONTH`, `DOM`, or `DAY`)
35+
36+
["source","sql",subs="attributes,callouts,macros"]
37+
--------------------------------------------------
38+
include-tagged::{sql-specs}/datetime.csv-spec[dayOfMonth]
39+
--------------------------------------------------
40+
41+
* Extract the day of the week from a date (`DAY_OF_WEEK` or `DOW`).
42+
Monday is `1`, Tuesday is `2`, etc.
43+
44+
["source","sql",subs="attributes,callouts,macros"]
45+
--------------------------------------------------
46+
include-tagged::{sql-specs}/datetime.csv-spec[dayOfWeek]
47+
--------------------------------------------------
48+
49+
* Extract the hour of the day from a date (`HOUR_OF_DAY` or `HOUR`).
50+
Monday is `1`, Tuesday is `2`, etc.
51+
52+
["source","sql",subs="attributes,callouts,macros"]
53+
--------------------------------------------------
54+
include-tagged::{sql-specs}/datetime.csv-spec[hourOfDay]
55+
--------------------------------------------------
56+
57+
* Extract the minute of the day from a date (`MINUTE_OF_DAY`).
58+
59+
["source","sql",subs="attributes,callouts,macros"]
60+
--------------------------------------------------
61+
include-tagged::{sql-specs}/datetime.csv-spec[minuteOfDay]
62+
--------------------------------------------------
63+
64+
* Extract the minute of the hour from a date (`MINUTE_OF_HOUR`, `MINUTE`).
65+
66+
["source","sql",subs="attributes,callouts,macros"]
67+
--------------------------------------------------
68+
include-tagged::{sql-specs}/datetime.csv-spec[minuteOfHour]
69+
--------------------------------------------------
70+
71+
* Extract the second of the minute from a date (`SECOND_OF_MINUTE`, `SECOND`).
72+
73+
["source","sql",subs="attributes,callouts,macros"]
74+
--------------------------------------------------
75+
include-tagged::{sql-specs}/datetime.csv-spec[secondOfMinute]
76+
--------------------------------------------------
77+
78+
* Extract
79+
80+
As an alternative, one can support `EXTRACT` to extract fields from datetimes.
81+
You can run any <<sql-functions-datetime,datetime function>>
82+
with `EXTRACT(<datetime_function> FROM <expression>)`. So
83+
84+
["source","sql",subs="attributes,callouts,macros"]
85+
--------------------------------------------------
86+
include-tagged::{sql-specs}/datetime.csv-spec[extractDayOfYear]
87+
--------------------------------------------------
88+
89+
is the equivalent to
90+
91+
["source","sql",subs="attributes,callouts,macros"]
92+
--------------------------------------------------
93+
include-tagged::{sql-specs}/datetime.csv-spec[dayOfYear]
94+
--------------------------------------------------

0 commit comments

Comments
 (0)