docs

Author: jan-elastic

docs/reference/query-languages/esql/_snippets/commands/layout/change_point.md

@@ -0,0 +1,57 @@
+## `CHANGE_POINT` [esql-change_point]
+
+:::{note}
+The `CHANGE_POINT` function requires a [platinum license](https://www.elastic.co/subscriptions).
+:::
+
+::::{warning}
+This functionality is in technical preview and may be
+changed or removed in a future release. Elastic will work to fix any
+issues, but features in technical preview are not subject to the support
+SLA of official GA features.
+::::
+
+
+The `CHANGE_POINT` processing command detects spikes, dips, and change points in a metric.
+
+**Syntax**
+
+```esql
+CHANGE_POINT value [ON key] [AS type_name, pvalue_name]
+```
+
+**Parameters**
+
+`value`
+:   The column with the metric in which you want to detect a change point.
+
+`key`
+:   The column with the key to order the values by. If not specified, `@timestamp` is used.
+
+`type_name`
+:   The name of the output column with the change point type. If not specified, `type` is used.
+
+`pvalue_name`
+:   The name of the output column with the p-value that indicates how extreme the change point is. If not specified, `pvalue` is used.
+
+**Description**
+
+`CHANGE_POINT` detects spikes, dips, and change points in a metric. The command adds columns to
+the table with the change point type and p-value, that indicates how extreme the change point is
+(lower values indicate greater changes).
+
+The possible change point types are:
+* `dip`: a significant dip occurs at this change point
+* `distribution_change`: the overall distribution of the values has changed significantly
+* `spike`: a significant spike occurs at this point
+* `step_change`: the change indicates a statistically significant step up or down in value distribution
+* `trend_change`: there is an overall trend change occurring at this point
+
+::::{note}
+There must be at least 22 values for change point detection. Fewer than 1,000 is preferred.
+::::
+
+**Example**
+
+:::{include} ../examples/change_point.csv-spec/docsStepChange.md
+:::

docs/reference/query-languages/esql/commands/processing-commands.md

@@ -17,6 +17,9 @@ mapped_pages:
 :::{include} ../_snippets/lists/processing-commands.md
 :::
 
+:::{include} ../_snippets/commands/layout/change_point.md
+:::
+
 :::{include} ../_snippets/commands/layout/dissect.md
 :::
 

x-pack/plugin/esql/qa/testFixtures/src/main/resources/change_point.csv-spec

@@ -1198,3 +1198,22 @@ true        | 1             | null         | null
 true        | 1             | null         | null         
 true        | 1             | null         | null         
 ;
+
+
+docsStepChange
+required_capability: change_point
+
+// tag::docsStepChange[]
+ROW key = [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25]
+| MV_EXPAND key
+| EVAL value = CASE(key<13, 0, 42)
+| CHANGE_POINT value ON key
+| WHERE type IS NOT NULL
+// end::docsStepChange[]
+;
+
+// tag::docsStepChange-result[]
+key:integer | value:integer | type:keyword | pvalue:double
+13          | 42            | step_change  | 0.0
+// tag::docsStepChange-result[]
+;