mirrors
/
elasticsearch
mirror of https://mirror.osredm.com/root/elasticsearch.git
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add doc for min/max_over_time (#130269) 

Add the initial docs structure for the TS command and time-series aggregation.
More content will be added later.
This commit is contained in:
Nhat Nguyen 2025-06-28 10:28:31 -07:00 committed by GitHub
parent debb95acfe
commit d887e7de9d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
38 changed files with 778 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
docs/reference/query-languages/esql/_snippets/commands/layout/ts.md Normal file
View File

@ -0,0 +1,28 @@
## `TS` [esql-ts]
The `TS` command is similar to the `FROM` source command,
but with two key differences: it targets only [time-series indices](docs-content://manage-data/data-store/data-streams/time-series-data-stream-tsds.md)
and enables the use of time-series aggregation functions
with the [STATS](/reference/query-languages/esql/commands/processing-commands.md#esql-stats-by) command.
**Syntax**
```esql
TS index_pattern [METADATA fields]
```
**Parameters**
`index_pattern`
: A list of indices, data streams or aliases. Supports wildcards and date math.
`fields`
: A comma-separated list of [metadata fields](/reference/query-languages/esql/esql-metadata-fields.md) to retrieve.
**Examples**
```esql
TS metrics
| STATS sum(last_over_time(memory_usage))
```

11
docs/reference/query-languages/esql/_snippets/functions/description/avg_over_time.md generated Normal file
View File

@ -0,0 +1,11 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Description**
The average over time of a numeric field.
::::{note}
Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds
::::

11
docs/reference/query-languages/esql/_snippets/functions/description/max_over_time.md generated Normal file
View File

@ -0,0 +1,11 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Description**
The maximum over time value of a field.
::::{note}
Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds
::::

11
docs/reference/query-languages/esql/_snippets/functions/description/min_over_time.md generated Normal file
View File

@ -0,0 +1,11 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Description**
The minimum over time value of a field.
::::{note}
Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds
::::

17
docs/reference/query-languages/esql/_snippets/functions/examples/avg_over_time.md generated Normal file
View File

@ -0,0 +1,17 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Example**
```esql
TS k8s
| STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
```
| max_cost:double | cluster:keyword | time_bucket:datetime |
| --- | --- | --- |
| 12.375 | prod | 2024-05-10T00:17:00.000Z |
| 12.375 | qa | 2024-05-10T00:01:00.000Z |
| 12.25 | prod | 2024-05-10T00:19:00.000Z |
| 12.0625 | qa | 2024-05-10T00:06:00.000Z |

17
docs/reference/query-languages/esql/_snippets/functions/examples/max_over_time.md generated Normal file
View File

@ -0,0 +1,17 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Example**
```esql
TS k8s
| STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
```
| cost:double | cluster:keyword | time_bucket:datetime |
| --- | --- | --- |
| 32.75 | qa | 2024-05-10T00:17:00.000Z |
| 32.25 | staging | 2024-05-10T00:09:00.000Z |
| 31.75 | qa | 2024-05-10T00:06:00.000Z |
| 29.0 | prod | 2024-05-10T00:19:00.000Z |

16
docs/reference/query-languages/esql/_snippets/functions/examples/min_over_time.md generated Normal file
View File

@ -0,0 +1,16 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Example**
```esql
TS k8s
| STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
```
| cost:double | cluster:keyword | time_bucket:datetime |
| --- | --- | --- |
| 29.0 | prod | 2024-05-10T00:19:00.000Z |
| 27.625 | qa | 2024-05-10T00:06:00.000Z |
| 24.25 | qa | 2024-05-10T00:09:00.000Z |

26
docs/reference/query-languages/esql/_snippets/functions/layout/avg_over_time.md generated Normal file
View File

@ -0,0 +1,26 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
## `AVG_OVER_TIME` [esql-avg_over_time]
```{applies_to}
stack: unavailable
```
**Syntax**
:::{image} ../../../images/functions/avg_over_time.svg
:alt: Embedded
:class: text-center
:::
:::{include} ../parameters/avg_over_time.md
:::
:::{include} ../description/avg_over_time.md
:::
:::{include} ../types/avg_over_time.md
:::
:::{include} ../examples/avg_over_time.md
:::

26
docs/reference/query-languages/esql/_snippets/functions/layout/max_over_time.md generated Normal file
View File

@ -0,0 +1,26 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
## `MAX_OVER_TIME` [esql-max_over_time]
```{applies_to}
stack: unavailable
```
**Syntax**
:::{image} ../../../images/functions/max_over_time.svg
:alt: Embedded
:class: text-center
:::
:::{include} ../parameters/max_over_time.md
:::
:::{include} ../description/max_over_time.md
:::
:::{include} ../types/max_over_time.md
:::
:::{include} ../examples/max_over_time.md
:::

26
docs/reference/query-languages/esql/_snippets/functions/layout/min_over_time.md generated Normal file
View File

@ -0,0 +1,26 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
## `MIN_OVER_TIME` [esql-min_over_time]
```{applies_to}
stack: unavailable
```
**Syntax**
:::{image} ../../../images/functions/min_over_time.svg
:alt: Embedded
:class: text-center
:::
:::{include} ../parameters/min_over_time.md
:::
:::{include} ../description/min_over_time.md
:::
:::{include} ../types/min_over_time.md
:::
:::{include} ../examples/min_over_time.md
:::

7
docs/reference/query-languages/esql/_snippets/functions/parameters/avg_over_time.md generated Normal file
View File

@ -0,0 +1,7 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Parameters**
`number`
: Expression that outputs values to average.

7
docs/reference/query-languages/esql/_snippets/functions/parameters/max_over_time.md generated Normal file
View File

@ -0,0 +1,7 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Parameters**
`field`
:

7
docs/reference/query-languages/esql/_snippets/functions/parameters/min_over_time.md generated Normal file
View File

@ -0,0 +1,7 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Parameters**
`field`
:

10
docs/reference/query-languages/esql/_snippets/functions/types/avg_over_time.md generated Normal file
View File

@ -0,0 +1,10 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Supported types**
| number | result |
| --- | --- |
| double | double |
| integer | double |
| long | double |

17
docs/reference/query-languages/esql/_snippets/functions/types/max_over_time.md generated Normal file
View File

@ -0,0 +1,17 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Supported types**
| field | result |
| --- | --- |
| boolean | boolean |
| date | date |
| date_nanos | date_nanos |
| double | double |
| integer | integer |
| ip | ip |
| keyword | keyword |
| long | long |
| text | keyword |
| version | version |

17
docs/reference/query-languages/esql/_snippets/functions/types/min_over_time.md generated Normal file
View File

@ -0,0 +1,17 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
**Supported types**
| field | result |
| --- | --- |
| boolean | boolean |
| date | date |
| date_nanos | date_nanos |
| double | double |
| integer | integer |
| ip | ip |
| keyword | keyword |
| long | long |
| text | keyword |
| version | version |

3
docs/reference/query-languages/esql/_snippets/lists/aggregation-functions.md
View File

@ -1,10 +1,13 @@
* [`AVG`](../../functions-operators/aggregation-functions.md#esql-avg)
* [unavailable] [`AVG_OVER_TIME`](../../functions-operators/aggregation-functions.md#esql-avg_over_time)
* [`COUNT`](../../functions-operators/aggregation-functions.md#esql-count)
* [`COUNT_DISTINCT`](../../functions-operators/aggregation-functions.md#esql-count_distinct)
* [`MAX`](../../functions-operators/aggregation-functions.md#esql-max)
* [unavailable] [`MAX_OVER_TIME`](../../functions-operators/aggregation-functions.md#esql-max_over_time)
* [`MEDIAN`](../../functions-operators/aggregation-functions.md#esql-median)
* [`MEDIAN_ABSOLUTE_DEVIATION`](../../functions-operators/aggregation-functions.md#esql-median_absolute_deviation)
* [`MIN`](../../functions-operators/aggregation-functions.md#esql-min)
* [unavailable] [`MIN_OVER_TIME`](../../functions-operators/aggregation-functions.md#esql-min_over_time)
* [`PERCENTILE`](../../functions-operators/aggregation-functions.md#esql-percentile)
* [preview] [`ST_CENTROID_AGG`](../../functions-operators/aggregation-functions.md#esql-st_centroid_agg)
* [preview] [`ST_EXTENT_AGG`](../../functions-operators/aggregation-functions.md#esql-st_extent_agg)

1
docs/reference/query-languages/esql/_snippets/lists/source-commands.md
View File

@ -1,3 +1,4 @@
* [`FROM`](../../commands/source-commands.md#esql-from)
* [`TS`](../../commands/source-commands.md#esql-ts)
* [`ROW`](../../commands/source-commands.md#esql-row)
* [`SHOW`](../../commands/source-commands.md#esql-show)

3
docs/reference/query-languages/esql/commands/source-commands.md
View File

@ -20,6 +20,9 @@ An {{esql}} source command produces a table, typically with data from {{es}}. An
:::{include} ../_snippets/commands/layout/from.md
:::
:::{include} ../_snippets/commands/layout/ts.md
:::
:::{include} ../_snippets/commands/layout/row.md
:::

9
docs/reference/query-languages/esql/functions-operators/aggregation-functions.md
View File

@ -15,6 +15,9 @@ The [`STATS`](/reference/query-languages/esql/commands/processing-commands.md#es
:::{include} ../_snippets/functions/layout/avg.md
:::
:::{include} ../_snippets/functions/layout/avg_over_time.md
:::
:::{include} ../_snippets/functions/layout/count.md
:::
@ -24,6 +27,9 @@ The [`STATS`](/reference/query-languages/esql/commands/processing-commands.md#es
:::{include} ../_snippets/functions/layout/max.md
:::
:::{include} ../_snippets/functions/layout/max_over_time.md
:::
:::{include} ../_snippets/functions/layout/median.md
:::
@ -33,6 +39,9 @@ The [`STATS`](/reference/query-languages/esql/commands/processing-commands.md#es
:::{include} ../_snippets/functions/layout/min.md
:::
:::{include} ../_snippets/functions/layout/min_over_time.md
:::
:::{include} ../_snippets/functions/layout/percentile.md
:::

1
docs/reference/query-languages/esql/images/functions/avg_over_time.svg generated Normal file
View File

@ -0,0 +1 @@
<svg version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="372" height="46" viewbox="0 0 372 46"><defs><style type="text/css">.c{fill:none;stroke:#222222;}.k{fill:#000000;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}.s{fill:#e4f4ff;stroke:#222222;}.syn{fill:#8D8D8D;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}</style></defs><path class="c" d="M0 31h5m176 0h10m32 0h10m92 0h10m32 0h5"/><rect class="s" x="5" y="5" width="176" height="36"/><text class="k" x="15" y="31">AVG_OVER_TIME</text><rect class="s" x="191" y="5" width="32" height="36" rx="7"/><text class="syn" x="201" y="31">(</text><rect class="s" x="233" y="5" width="92" height="36" rx="7"/><text class="k" x="243" y="31">number</text><rect class="s" x="335" y="5" width="32" height="36" rx="7"/><text class="syn" x="345" y="31">)</text></svg>
Side by Side

After

Width:  |  Height:  |  Size: 1016 B

1
docs/reference/query-languages/esql/images/functions/max_over_time.svg generated Normal file
View File

@ -0,0 +1 @@
<svg version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="360" height="46" viewbox="0 0 360 46"><defs><style type="text/css">.c{fill:none;stroke:#222222;}.k{fill:#000000;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}.s{fill:#e4f4ff;stroke:#222222;}.syn{fill:#8D8D8D;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}</style></defs><path class="c" d="M0 31h5m176 0h10m32 0h10m80 0h10m32 0h5"/><rect class="s" x="5" y="5" width="176" height="36"/><text class="k" x="15" y="31">MAX_OVER_TIME</text><rect class="s" x="191" y="5" width="32" height="36" rx="7"/><text class="syn" x="201" y="31">(</text><rect class="s" x="233" y="5" width="80" height="36" rx="7"/><text class="k" x="243" y="31">field</text><rect class="s" x="323" y="5" width="32" height="36" rx="7"/><text class="syn" x="333" y="31">)</text></svg>
Side by Side

After

Width:  |  Height:  |  Size: 1015 B

1
docs/reference/query-languages/esql/images/functions/min_over_time.svg generated Normal file
View File

@ -0,0 +1 @@
<svg version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="360" height="46" viewbox="0 0 360 46"><defs><style type="text/css">.c{fill:none;stroke:#222222;}.k{fill:#000000;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}.s{fill:#e4f4ff;stroke:#222222;}.syn{fill:#8D8D8D;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}</style></defs><path class="c" d="M0 31h5m176 0h10m32 0h10m80 0h10m32 0h5"/><rect class="s" x="5" y="5" width="176" height="36"/><text class="k" x="15" y="31">MIN_OVER_TIME</text><rect class="s" x="191" y="5" width="32" height="36" rx="7"/><text class="syn" x="201" y="31">(</text><rect class="s" x="233" y="5" width="80" height="36" rx="7"/><text class="k" x="243" y="31">field</text><rect class="s" x="323" y="5" width="32" height="36" rx="7"/><text class="syn" x="333" y="31">)</text></svg>
Side by Side

After

Width:  |  Height:  |  Size: 1015 B

50
docs/reference/query-languages/esql/kibana/definition/functions/avg_over_time.json generated Normal file
View File

@ -0,0 +1,50 @@
{
"comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.",
"type" : "time_series_agg",
"name" : "avg_over_time",
"description" : "The average over time of a numeric field.",
"note" : "Available with the TS command in snapshot builds",
"signatures" : [
{
"params" : [
{
"name" : "number",
"type" : "double",
"optional" : false,
"description" : "Expression that outputs values to average."
}
],
"variadic" : false,
"returnType" : "double"
},
{
"params" : [
{
"name" : "number",
"type" : "integer",
"optional" : false,
"description" : "Expression that outputs values to average."
}
],
"variadic" : false,
"returnType" : "double"
},
{
"params" : [
{
"name" : "number",
"type" : "long",
"optional" : false,
"description" : "Expression that outputs values to average."
}
],
"variadic" : false,
"returnType" : "double"
}
],
"examples" : [
"TS k8s\n| STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)"
],
"preview" : false,
"snapshot_only" : true
}

134
docs/reference/query-languages/esql/kibana/definition/functions/max_over_time.json generated Normal file
View File

@ -0,0 +1,134 @@
{
"comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.",
"type" : "time_series_agg",
"name" : "max_over_time",
"description" : "The maximum over time value of a field.",
"note" : "Available with the TS command in snapshot builds",
"signatures" : [
{
"params" : [
{
"name" : "field",
"type" : "boolean",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "boolean"
},
{
"params" : [
{
"name" : "field",
"type" : "date",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "date"
},
{
"params" : [
{
"name" : "field",
"type" : "date_nanos",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "date_nanos"
},
{
"params" : [
{
"name" : "field",
"type" : "double",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "double"
},
{
"params" : [
{
"name" : "field",
"type" : "integer",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "integer"
},
{
"params" : [
{
"name" : "field",
"type" : "ip",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "ip"
},
{
"params" : [
{
"name" : "field",
"type" : "keyword",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "keyword"
},
{
"params" : [
{
"name" : "field",
"type" : "long",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "long"
},
{
"params" : [
{
"name" : "field",
"type" : "text",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "keyword"
},
{
"params" : [
{
"name" : "field",
"type" : "version",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "version"
}
],
"examples" : [
"TS k8s\n| STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)"
],
"preview" : false,
"snapshot_only" : true
}

134
docs/reference/query-languages/esql/kibana/definition/functions/min_over_time.json generated Normal file
View File

@ -0,0 +1,134 @@
{
"comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.",
"type" : "time_series_agg",
"name" : "min_over_time",
"description" : "The minimum over time value of a field.",
"note" : "Available with the TS command in snapshot builds",
"signatures" : [
{
"params" : [
{
"name" : "field",
"type" : "boolean",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "boolean"
},
{
"params" : [
{
"name" : "field",
"type" : "date",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "date"
},
{
"params" : [
{
"name" : "field",
"type" : "date_nanos",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "date_nanos"
},
{
"params" : [
{
"name" : "field",
"type" : "double",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "double"
},
{
"params" : [
{
"name" : "field",
"type" : "integer",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "integer"
},
{
"params" : [
{
"name" : "field",
"type" : "ip",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "ip"
},
{
"params" : [
{
"name" : "field",
"type" : "keyword",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "keyword"
},
{
"params" : [
{
"name" : "field",
"type" : "long",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "long"
},
{
"params" : [
{
"name" : "field",
"type" : "text",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "keyword"
},
{
"params" : [
{
"name" : "field",
"type" : "version",
"optional" : false,
"description" : ""
}
],
"variadic" : false,
"returnType" : "version"
}
],
"examples" : [
"TS k8s\n| STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)"
],
"preview" : false,
"snapshot_only" : true
}

10
docs/reference/query-languages/esql/kibana/docs/functions/avg_over_time.md generated Normal file
View File

@ -0,0 +1,10 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
### AVG OVER TIME
The average over time of a numeric field.
```esql
TS k8s
| STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
```
Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

10
docs/reference/query-languages/esql/kibana/docs/functions/max_over_time.md generated Normal file
View File

@ -0,0 +1,10 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
### MAX OVER TIME
The maximum over time value of a field.
```esql
TS k8s
| STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
```
Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

10
docs/reference/query-languages/esql/kibana/docs/functions/min_over_time.md generated Normal file
View File

@ -0,0 +1,10 @@
% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
### MIN OVER TIME
The minimum over time value of a field.
```esql
TS k8s
| STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
```
Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

24
x-pack/plugin/esql/qa/testFixtures/src/main/resources/k8s-timeseries.csv-spec
View File

@ -169,13 +169,19 @@ null | three | 2024-05-10T00:01:00.000
max_over_time
required_capability: metrics_command
required_capability: max_over_time
TS k8s | STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute) | SORT cost DESC, time_bucket DESC, cluster | LIMIT 10;
// tag::max_over_time[]
TS k8s
| STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
// end::max_over_time[]
| SORT cost DESC, time_bucket DESC, cluster | LIMIT 10;
// tag::max_over_time-result[]
cost:double | cluster:keyword | time_bucket:datetime
32.75 | qa | 2024-05-10T00:17:00.000Z
32.25 | staging | 2024-05-10T00:09:00.000Z
31.75 | qa | 2024-05-10T00:06:00.000Z
29.0 | prod | 2024-05-10T00:19:00.000Z
// end::max_over_time-result[]
28.625 | qa | 2024-05-10T00:09:00.000Z
24.625 | qa | 2024-05-10T00:18:00.000Z
23.25 | qa | 2024-05-10T00:11:00.000Z
@ -187,12 +193,18 @@ cost:double | cluster:keyword | time_bucket:datetime
min_over_time
required_capability: metrics_command
required_capability: min_over_time
TS k8s | STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute) | SORT cost DESC, time_bucket DESC, cluster | LIMIT 10;
// tag::min_over_time[]
TS k8s
| STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
// end::min_over_time[]
| SORT cost DESC, time_bucket DESC, cluster | LIMIT 10;
// tag::min_over_time-result[]
cost:double | cluster:keyword | time_bucket:datetime
29.0 | prod | 2024-05-10T00:19:00.000Z
27.625 | qa | 2024-05-10T00:06:00.000Z
24.25 | qa | 2024-05-10T00:09:00.000Z
// end::min_over_time-result[]
23.125 | staging | 2024-05-10T00:08:00.000Z
22.5 | prod | 2024-05-10T00:13:00.000Z
18.625 | qa | 2024-05-10T00:04:00.000Z
@ -205,13 +217,19 @@ cost:double | cluster:keyword | time_bucket:datetime
max_of_avg_over_time
required_capability: metrics_command
required_capability: avg_over_time
TS k8s | STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute) | SORT max_cost DESC, time_bucket DESC, cluster | LIMIT 10;
// tag::avg_over_time[]
TS k8s
| STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
// end::avg_over_time[]
| SORT max_cost DESC, time_bucket DESC, cluster | LIMIT 10;
// tag::avg_over_time-result[]
max_cost:double | cluster:keyword | time_bucket:datetime
12.375 | prod | 2024-05-10T00:17:00.000Z
12.375 | qa | 2024-05-10T00:01:00.000Z
12.25 | prod | 2024-05-10T00:19:00.000Z
12.0625 | qa | 2024-05-10T00:06:00.000Z
// end::avg_over_time-result[]
11.875 | prod | 2024-05-10T00:15:00.000Z
11.875 | qa | 2024-05-10T00:09:00.000Z
11.625 | prod | 2024-05-10T00:12:00.000Z

7
x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionType.java
View File

@ -21,6 +21,13 @@ public enum FunctionType {
* For example, {@code MAX} in {@code | STATS MAX(LENGTH(string))}.
*/
AGGREGATE,
/**
* Functions that can only appear in the aggregate" position of a {@code STATS}
* started with TS.
* For example, {@code MAX_OVER_TIME} in {@code | STATS MAX(MAX_OVER_TIME(string))}.
*/
TIME_SERIES_AGGREGATE,
/**
* Functions that can only appear in the "grouping" position of a {@code STATS}.
* For example, {@code CATEGORIZE} in {@code | STATS MAX(a) BY CATEGORIZE(message)}.

12
x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AvgOverTime.java
View File

@ -14,6 +14,9 @@ import org.elasticsearch.xpack.esql.core.expression.Literal;
import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
import org.elasticsearch.xpack.esql.core.tree.Source;
import org.elasticsearch.xpack.esql.core.type.DataType;
import org.elasticsearch.xpack.esql.expression.function.Example;
import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo;
import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle;
import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
import org.elasticsearch.xpack.esql.expression.function.FunctionType;
import org.elasticsearch.xpack.esql.expression.function.Param;
@ -33,7 +36,14 @@ public class AvgOverTime extends TimeSeriesAggregateFunction {
AvgOverTime::new
);
@FunctionInfo(returnType = "double", description = "The average over time of a numeric field.", type = FunctionType.AGGREGATE)
@FunctionInfo(
returnType = "double",
description = "The average over time of a numeric field.",
type = FunctionType.TIME_SERIES_AGGREGATE,
appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.UNAVAILABLE) },
note = "Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds",
examples = { @Example(file = "k8s-timeseries", tag = "avg_over_time") }
)
public AvgOverTime(
Source source,
@Param(

8
x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MaxOverTime.java
View File

@ -14,6 +14,9 @@ import org.elasticsearch.xpack.esql.core.expression.Literal;
import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
import org.elasticsearch.xpack.esql.core.tree.Source;
import org.elasticsearch.xpack.esql.core.type.DataType;
import org.elasticsearch.xpack.esql.expression.function.Example;
import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo;
import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle;
import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
import org.elasticsearch.xpack.esql.expression.function.FunctionType;
import org.elasticsearch.xpack.esql.expression.function.Param;
@ -36,7 +39,10 @@ public class MaxOverTime extends TimeSeriesAggregateFunction {
@FunctionInfo(
returnType = { "boolean", "double", "integer", "long", "date", "date_nanos", "ip", "keyword", "long", "version" },
description = "The maximum over time value of a field.",
type = FunctionType.AGGREGATE
type = FunctionType.TIME_SERIES_AGGREGATE,
appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.UNAVAILABLE) },
note = "Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds",
examples = { @Example(file = "k8s-timeseries", tag = "max_over_time") }
)
public MaxOverTime(
Source source,

8
x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MinOverTime.java
View File

@ -14,6 +14,9 @@ import org.elasticsearch.xpack.esql.core.expression.Literal;
import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
import org.elasticsearch.xpack.esql.core.tree.Source;
import org.elasticsearch.xpack.esql.core.type.DataType;
import org.elasticsearch.xpack.esql.expression.function.Example;
import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo;
import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle;
import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
import org.elasticsearch.xpack.esql.expression.function.FunctionType;
import org.elasticsearch.xpack.esql.expression.function.Param;
@ -36,7 +39,10 @@ public class MinOverTime extends TimeSeriesAggregateFunction {
@FunctionInfo(
returnType = { "boolean", "double", "integer", "long", "date", "date_nanos", "ip", "keyword", "long", "version" },
description = "The minimum over time value of a field.",
type = FunctionType.AGGREGATE
type = FunctionType.TIME_SERIES_AGGREGATE,
appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.UNAVAILABLE) },
note = "Available with the [TS](/reference/query-languages/esql/commands/source-commands.md#esql-ts) command in snapshot builds",
examples = { @Example(file = "k8s-timeseries", tag = "min_over_time") }
)
public MinOverTime(
Source source,

1
x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java
View File

@ -1058,6 +1058,7 @@ public abstract class DocsV3Support {
builder.field("type", switch (info.type()) {
case SCALAR -> "scalar";
case AGGREGATE -> "agg";
case TIME_SERIES_AGGREGATE -> "time_series_agg";
case GROUPING -> "grouping";
});
}

35
x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/aggregate/AvgOverTimeTests.java Normal file
View File

@ -0,0 +1,35 @@
/*
* Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
* or more contributor license agreements. Licensed under the Elastic License
* 2.0; you may not use this file except in compliance with the Elastic License
* 2.0.
*/
package org.elasticsearch.xpack.esql.expression.function.aggregate;
import com.carrotsearch.randomizedtesting.annotations.Name;
import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
import org.elasticsearch.xpack.esql.core.expression.Expression;
import org.elasticsearch.xpack.esql.core.tree.Source;
import org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase;
import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
import java.util.List;
import java.util.function.Supplier;
public class AvgOverTimeTests extends AbstractFunctionTestCase {
public AvgOverTimeTests(@Name("TestCase") Supplier<TestCaseSupplier.TestCase> testCaseSupplier) {
this.testCase = testCaseSupplier.get();
}
@ParametersFactory
public static Iterable<Object[]> parameters() {
return AvgTests.parameters();
}
@Override
protected Expression build(Source source, List<Expression> args) {
return new AvgOverTime(source, args.get(0));
}
}

34
x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MaxOverTimeTests.java Normal file
View File

@ -0,0 +1,34 @@
/*
* Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
* or more contributor license agreements. Licensed under the Elastic License
* 2.0; you may not use this file except in compliance with the Elastic License
* 2.0.
*/
package org.elasticsearch.xpack.esql.expression.function.aggregate;
import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
import org.elasticsearch.xpack.esql.core.expression.Expression;
import org.elasticsearch.xpack.esql.core.tree.Source;
import org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase;
import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
import java.util.List;
import java.util.function.Supplier;
public class MaxOverTimeTests extends AbstractFunctionTestCase {
public MaxOverTimeTests(Supplier<TestCaseSupplier.TestCase> testCaseSupplier) {
testCase = testCaseSupplier.get();
}
@ParametersFactory
public static Iterable<Object[]> parameters() {
return MinTests.parameters();
}
@Override
protected Expression build(Source source, List<Expression> args) {
return new MinOverTime(source, args.get(0));
}
}

34
x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/aggregate/MinOverTimeTests.java Normal file
View File

@ -0,0 +1,34 @@
/*
* Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
* or more contributor license agreements. Licensed under the Elastic License
* 2.0; you may not use this file except in compliance with the Elastic License
* 2.0.
*/
package org.elasticsearch.xpack.esql.expression.function.aggregate;
import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
import org.elasticsearch.xpack.esql.core.expression.Expression;
import org.elasticsearch.xpack.esql.core.tree.Source;
import org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase;
import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
import java.util.List;
import java.util.function.Supplier;
public class MinOverTimeTests extends AbstractFunctionTestCase {
public MinOverTimeTests(Supplier<TestCaseSupplier.TestCase> testCaseSupplier) {
testCase = testCaseSupplier.get();
}
@ParametersFactory
public static Iterable<Object[]> parameters() {
return MaxTests.parameters();
}
@Override
protected Expression build(Source source, List<Expression> args) {
return new MaxOverTime(source, args.get(0));
}
}