Skip to content

Commit ff23fec

Browse files
kibanamachinestratoula
kibanamachine
and
stratoula
authored
[ES|QL] Update function metadata (#237569)
This PR updates the function definitions and inline docs based on the latest metadata from Elasticsearch. --------- Co-authored-by: Stratoula <[email protected]>
1 parent 6993c7e commit ff23fec

File tree

12 files changed

+942
-44
lines changed

12 files changed

+942
-44
lines changed

‎src/platform/packages/private/kbn-language-documentation/src/sections/generated/aggregation_functions.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,8 @@ export const functions = {
137137
### COUNT DISTINCT
138138
Returns the approximate number of distinct values.
139139
140+
Note: [Counts are approximate](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-agg-count-distinct-approximate).
141+
140142
\`\`\`esql
141143
FROM hosts
142144
| STATS COUNT_DISTINCT(ip0), COUNT_DISTINCT(ip1)

‎src/platform/packages/private/kbn-language-documentation/src/sections/generated/scalar_functions.tsx‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1087,6 +1087,36 @@ export const functions = {
10871087
),
10881088
},
10891089
// Do not edit manually... automatically generated by scripts/generate_esql_docs.ts
1090+
{
1091+
label: i18n.translate('languageDocumentation.documentationESQL.knn', {
1092+
defaultMessage: 'KNN',
1093+
}),
1094+
preview: true,
1095+
license: undefined,
1096+
description: (
1097+
<Markdown
1098+
openLinksInNewTab
1099+
readOnly
1100+
enableSoftLineBreaks
1101+
markdownContent={i18n.translate('languageDocumentation.documentationESQL.knn.markdown', {
1102+
defaultMessage: `
1103+
### KNN
1104+
Finds the k nearest vectors to a query vector, as measured by a similarity metric. knn function finds nearest vectors through approximate search on indexed dense_vectors or semantic_text fields.
1105+
1106+
\`\`\`esql
1107+
from colors metadata _score
1108+
| where knn(rgb_vector, [0, 120, 0])
1109+
| sort _score desc, color asc
1110+
\`\`\`
1111+
`,
1112+
description:
1113+
'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
1114+
ignoreTag: true,
1115+
})}
1116+
/>
1117+
),
1118+
},
1119+
// Do not edit manually... automatically generated by scripts/generate_esql_docs.ts
10901120
{
10911121
label: i18n.translate('languageDocumentation.documentationESQL.kql', {
10921122
defaultMessage: 'KQL',
@@ -3751,6 +3781,39 @@ export const functions = {
37513781
ROW rad = [1.57, 3.14, 4.71]
37523782
| EVAL deg = TO_DEGREES(rad)
37533783
\`\`\`
3784+
`,
3785+
description:
3786+
'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
3787+
ignoreTag: true,
3788+
}
3789+
)}
3790+
/>
3791+
),
3792+
},
3793+
// Do not edit manually... automatically generated by scripts/generate_esql_docs.ts
3794+
{
3795+
label: i18n.translate('languageDocumentation.documentationESQL.to_dense_vector', {
3796+
defaultMessage: 'TO_DENSE_VECTOR',
3797+
}),
3798+
preview: true,
3799+
license: undefined,
3800+
description: (
3801+
<Markdown
3802+
openLinksInNewTab
3803+
readOnly
3804+
enableSoftLineBreaks
3805+
markdownContent={i18n.translate(
3806+
'languageDocumentation.documentationESQL.to_dense_vector.markdown',
3807+
{
3808+
defaultMessage: `
3809+
### TO DENSE VECTOR
3810+
Converts a multi-valued input of numbers, or a hexadecimal string, to a dense_vector.
3811+
3812+
\`\`\`esql
3813+
row ints = [1, 2, 3]
3814+
| eval vector = to_dense_vector(ints)
3815+
| keep vector
3816+
\`\`\`
37543817
`,
37553818
description:
37563819
'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',

‎src/platform/packages/private/kbn-language-documentation/src/sections/generated/timeseries_aggregation_functions.tsx‎

Lines changed: 144 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ export const functions = {
3333
label: i18n.translate('languageDocumentation.documentationESQL.absent_over_time', {
3434
defaultMessage: 'ABSENT_OVER_TIME',
3535
}),
36-
preview: false,
36+
preview: true,
3737
license: undefined,
3838
description: (
3939
<Markdown
@@ -66,7 +66,7 @@ export const functions = {
6666
label: i18n.translate('languageDocumentation.documentationESQL.avg_over_time', {
6767
defaultMessage: 'AVG_OVER_TIME',
6868
}),
69-
preview: false,
69+
preview: true,
7070
license: undefined,
7171
description: (
7272
<Markdown
@@ -98,7 +98,7 @@ export const functions = {
9898
label: i18n.translate('languageDocumentation.documentationESQL.count_distinct_over_time', {
9999
defaultMessage: 'COUNT_DISTINCT_OVER_TIME',
100100
}),
101-
preview: false,
101+
preview: true,
102102
license: undefined,
103103
description: (
104104
<Markdown
@@ -132,7 +132,7 @@ export const functions = {
132132
label: i18n.translate('languageDocumentation.documentationESQL.count_over_time', {
133133
defaultMessage: 'COUNT_OVER_TIME',
134134
}),
135-
preview: false,
135+
preview: true,
136136
license: undefined,
137137
description: (
138138
<Markdown
@@ -151,6 +151,41 @@ export const functions = {
151151
| STATS count=count(count_over_time(network.cost))
152152
BY cluster, time_bucket = bucket(@timestamp,1minute)
153153
\`\`\`
154+
`,
155+
description:
156+
'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
157+
ignoreTag: true,
158+
}
159+
)}
160+
/>
161+
),
162+
},
163+
// Do not edit manually... automatically generated by scripts/generate_esql_docs.ts
164+
{
165+
label: i18n.translate('languageDocumentation.documentationESQL.delta', {
166+
defaultMessage: 'DELTA',
167+
}),
168+
preview: true,
169+
license: undefined,
170+
description: (
171+
<Markdown
172+
openLinksInNewTab
173+
readOnly
174+
enableSoftLineBreaks
175+
markdownContent={i18n.translate(
176+
'languageDocumentation.documentationESQL.delta.markdown',
177+
{
178+
defaultMessage: `
179+
### DELTA
180+
Calculates the absolute change of a gauge field in a time window.
181+
182+
Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command
183+
184+
\`\`\`esql
185+
TS k8s
186+
| WHERE pod == "one"
187+
| STATS tx = sum(delta(network.bytes_in)) BY cluster, time_bucket = bucket(@timestamp, 10minute)
188+
\`\`\`
154189
`,
155190
description:
156191
'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -165,7 +200,7 @@ export const functions = {
165200
label: i18n.translate('languageDocumentation.documentationESQL.first_over_time', {
166201
defaultMessage: 'FIRST_OVER_TIME',
167202
}),
168-
preview: false,
203+
preview: true,
169204
license: undefined,
170205
description: (
171206
<Markdown
@@ -183,6 +218,103 @@ export const functions = {
183218
TS k8s
184219
| STATS max_cost=max(first_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
185220
\`\`\`
221+
`,
222+
description:
223+
'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
224+
ignoreTag: true,
225+
}
226+
)}
227+
/>
228+
),
229+
},
230+
// Do not edit manually... automatically generated by scripts/generate_esql_docs.ts
231+
{
232+
label: i18n.translate('languageDocumentation.documentationESQL.idelta', {
233+
defaultMessage: 'IDELTA',
234+
}),
235+
preview: true,
236+
license: undefined,
237+
description: (
238+
<Markdown
239+
openLinksInNewTab
240+
readOnly
241+
enableSoftLineBreaks
242+
markdownContent={i18n.translate(
243+
'languageDocumentation.documentationESQL.idelta.markdown',
244+
{
245+
defaultMessage: `
246+
### IDELTA
247+
Calculates the idelta of a gauge. idelta is the absolute change between the last two data points (it ignores all but the last two data points in each time period). This function is very similar to delta, but is more responsive to recent changes.
248+
249+
\`\`\`esql
250+
TS k8s
251+
| STATS events = sum(idelta(events_received)) by pod, time_bucket = bucket(@timestamp, 10minute)
252+
\`\`\`
253+
`,
254+
description:
255+
'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
256+
ignoreTag: true,
257+
}
258+
)}
259+
/>
260+
),
261+
},
262+
// Do not edit manually... automatically generated by scripts/generate_esql_docs.ts
263+
{
264+
label: i18n.translate('languageDocumentation.documentationESQL.increase', {
265+
defaultMessage: 'INCREASE',
266+
}),
267+
preview: true,
268+
license: undefined,
269+
description: (
270+
<Markdown
271+
openLinksInNewTab
272+
readOnly
273+
enableSoftLineBreaks
274+
markdownContent={i18n.translate(
275+
'languageDocumentation.documentationESQL.increase.markdown',
276+
{
277+
defaultMessage: `
278+
### INCREASE
279+
Calculates the absolute increase of a counter field in a time window.
280+
281+
\`\`\`esql
282+
TS k8s
283+
| WHERE pod == "one"
284+
| STATS increase_bytes_in = sum(increase(network.total_bytes_in)) BY cluster, time_bucket = bucket(@timestamp, 10minute)
285+
\`\`\`
286+
`,
287+
description:
288+
'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
289+
ignoreTag: true,
290+
}
291+
)}
292+
/>
293+
),
294+
},
295+
// Do not edit manually... automatically generated by scripts/generate_esql_docs.ts
296+
{
297+
label: i18n.translate('languageDocumentation.documentationESQL.irate', {
298+
defaultMessage: 'IRATE',
299+
}),
300+
preview: true,
301+
license: undefined,
302+
description: (
303+
<Markdown
304+
openLinksInNewTab
305+
readOnly
306+
enableSoftLineBreaks
307+
markdownContent={i18n.translate(
308+
'languageDocumentation.documentationESQL.irate.markdown',
309+
{
310+
defaultMessage: `
311+
### IRATE
312+
Calculates the irate of a counter field. irate is the per-second rate of increase between the last two data points (it ignores all but the last two data points in each time period). This function is very similar to rate, but is more responsive to recent changes in the rate of increase.
313+
314+
\`\`\`esql
315+
TS k8s | WHERE pod == "one"
316+
| STATS irate_bytes_in = sum(irate(network.total_bytes_in)) BY cluster, time_bucket = bucket(@timestamp, 10minute)
317+
\`\`\`
186318
`,
187319
description:
188320
'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -197,7 +329,7 @@ export const functions = {
197329
label: i18n.translate('languageDocumentation.documentationESQL.last_over_time', {
198330
defaultMessage: 'LAST_OVER_TIME',
199331
}),
200-
preview: false,
332+
preview: true,
201333
license: undefined,
202334
description: (
203335
<Markdown
@@ -229,7 +361,7 @@ export const functions = {
229361
label: i18n.translate('languageDocumentation.documentationESQL.max_over_time', {
230362
defaultMessage: 'MAX_OVER_TIME',
231363
}),
232-
preview: false,
364+
preview: true,
233365
license: undefined,
234366
description: (
235367
<Markdown
@@ -261,7 +393,7 @@ export const functions = {
261393
label: i18n.translate('languageDocumentation.documentationESQL.min_over_time', {
262394
defaultMessage: 'MIN_OVER_TIME',
263395
}),
264-
preview: false,
396+
preview: true,
265397
license: undefined,
266398
description: (
267399
<Markdown
@@ -293,7 +425,7 @@ export const functions = {
293425
label: i18n.translate('languageDocumentation.documentationESQL.present_over_time', {
294426
defaultMessage: 'PRESENT_OVER_TIME',
295427
}),
296-
preview: false,
428+
preview: true,
297429
license: undefined,
298430
description: (
299431
<Markdown
@@ -326,7 +458,7 @@ export const functions = {
326458
label: i18n.translate('languageDocumentation.documentationESQL.rate', {
327459
defaultMessage: 'RATE',
328460
}),
329-
preview: false,
461+
preview: true,
330462
license: undefined,
331463
description: (
332464
<Markdown
@@ -336,7 +468,7 @@ export const functions = {
336468
markdownContent={i18n.translate('languageDocumentation.documentationESQL.rate.markdown', {
337469
defaultMessage: `
338470
### RATE
339-
Calculates the rate of a counter field.
471+
Calculates the per-second average rate of increase of a [counter](docs-content://manage-data/data-store/data-streams/time-series-data-stream-tsds.md#time-series-metric). Rate calculations account for breaks in monotonicity, such as counter resets when a service restarts, and extrapolate values within each bucketed time interval. Rate is the most appropriate aggregate function for counters. It is only allowed in a [STATS](https://www.elastic.co/docs/reference/query-languages/esql/commands/stats-by) command under a [\`TS\`](https://www.elastic.co/docs/reference/query-languages/esql/commands/ts) source command, to be properly applied per time series.
340472
341473
\`\`\`esql
342474
TS k8s
@@ -355,7 +487,7 @@ export const functions = {
355487
label: i18n.translate('languageDocumentation.documentationESQL.sum_over_time', {
356488
defaultMessage: 'SUM_OVER_TIME',
357489
}),
358-
preview: false,
490+
preview: true,
359491
license: undefined,
360492
description: (
361493
<Markdown

‎src/platform/packages/shared/kbn-esql-ast/src/commands_registry/commands/fork/autocomplete.test.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -327,7 +327,11 @@ describe('FORK Autocomplete', () => {
327327
'FROM a | FORK (STATS AVG(',
328328
[
329329
...getFieldNamesByType(AVG_TYPES),
330-
...getFunctionSignaturesByReturnType(Location.STATS, AVG_TYPES, { scalar: true }),
330+
...getFunctionSignaturesByReturnType(
331+
Location.STATS,
332+
[...AVG_TYPES, 'aggregate_metric_double'],
333+
{ scalar: true }
334+
),
331335
],
332336
mockCallbacks
333337
);

‎src/platform/packages/shared/kbn-esql-ast/src/commands_registry/commands/stats/autocomplete.test.ts‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,12 @@ export const EXPECTED_FIELD_AND_FUNCTION_SUGGESTIONS = [
6767
];
6868

6969
// types accepted by the AVG function
70-
export const AVG_TYPES: Array<FieldType & FunctionReturnType> = ['double', 'integer', 'long'];
70+
export const AVG_TYPES: Array<FieldType & FunctionReturnType> = [
71+
'double',
72+
'integer',
73+
'long',
74+
'aggregate_metric_double',
75+
];
7176

7277
export const EXPECTED_FOR_FIRST_EMPTY_EXPRESSION = [
7378
'BY ',
@@ -378,6 +383,7 @@ describe('STATS Autocomplete', () => {
378383
'keyword',
379384
'date_nanos',
380385
'unsigned_long',
386+
'aggregate_metric_double',
381387
],
382388
{
383389
scalar: true,
@@ -399,9 +405,13 @@ describe('STATS Autocomplete', () => {
399405
'from a | stats avg(b) by stringField',
400406
[
401407
...getFieldNamesByType(AVG_TYPES),
402-
...getFunctionSignaturesByReturnType(Location.EVAL, AVG_TYPES, {
403-
scalar: true,
404-
}),
408+
...getFunctionSignaturesByReturnType(
409+
Location.EVAL,
410+
[...AVG_TYPES, 'aggregate_metric_double'],
411+
{
412+
scalar: true,
413+
}
414+
),
405415
],
406416
mockCallbacks,
407417
mockContext,

0 commit comments

Comments
 (0)