[ES|QL] Add a standard deviation function (#116531) (#117398)

Uses Welford's online algorithm, as well as the parallel version, to calculate standard deviation.
elastic · Nov 22, 2024 · 04849b0 · 04849b0
1 parent 4174c89
commit 04849b0
Show file tree

Hide file tree

Showing 38 changed files with 2,869 additions and 6 deletions.
diff --git a/docs/changelog/116531.yaml b/docs/changelog/116531.yaml
@@ -0,0 +1,5 @@
+pr: 116531
+summary: "Add a standard deviation aggregating function: STD_DEV"
+area: ES|QL
+type: enhancement
+issues: []
diff --git a/docs/reference/esql/functions/aggregation-functions.asciidoc b/docs/reference/esql/functions/aggregation-functions.asciidoc
@@ -17,6 +17,7 @@ The <<esql-stats-by>> command supports these aggregate functions:
 * <<esql-min>>
 * <<esql-percentile>>
 * experimental:[] <<esql-st_centroid_agg>>
+* <<esql-std_dev>>
 * <<esql-sum>>
 * <<esql-top>>
 * <<esql-values>>
@@ -32,6 +33,7 @@ include::layout/median_absolute_deviation.asciidoc[]
 include::layout/min.asciidoc[]
 include::layout/percentile.asciidoc[]
 include::layout/st_centroid_agg.asciidoc[]
+include::layout/std_dev.asciidoc[]
 include::layout/sum.asciidoc[]
 include::layout/top.asciidoc[]
 include::layout/values.asciidoc[]

diff --git a/docs/reference/esql/functions/description/std_dev.asciidoc b/docs/reference/esql/functions/description/std_dev.asciidoc
diff --git a/docs/reference/esql/functions/examples/std_dev.asciidoc b/docs/reference/esql/functions/examples/std_dev.asciidoc
diff --git a/docs/reference/esql/functions/kibana/definition/std_dev.json b/docs/reference/esql/functions/kibana/definition/std_dev.json
diff --git a/docs/reference/esql/functions/kibana/docs/std_dev.md b/docs/reference/esql/functions/kibana/docs/std_dev.md
diff --git a/docs/reference/esql/functions/layout/std_dev.asciidoc b/docs/reference/esql/functions/layout/std_dev.asciidoc
diff --git a/docs/reference/esql/functions/parameters/std_dev.asciidoc b/docs/reference/esql/functions/parameters/std_dev.asciidoc
diff --git a/docs/reference/esql/functions/signature/std_dev.svg b/docs/reference/esql/functions/signature/std_dev.svg
diff --git a/docs/reference/esql/functions/types/std_dev.asciidoc b/docs/reference/esql/functions/types/std_dev.asciidoc
diff --git a/x-pack/plugin/esql/compute/build.gradle b/x-pack/plugin/esql/compute/build.gradle
@@ -608,6 +608,27 @@ tasks.named('stringTemplates').configure {
     it.outputFile = "org/elasticsearch/compute/aggregation/RateDoubleAggregator.java"
   }
 
+  File stdDevAggregatorInputFile = file("src/main/java/org/elasticsearch/compute/aggregation/X-StdDevAggregator.java.st")
+  template {
+    it.properties = intProperties
+    it.inputFile = stdDevAggregatorInputFile
+    it.outputFile = "org/elasticsearch/compute/aggregation/StdDevIntAggregator.java"
+  }
+  template {
+    it.properties = longProperties
+    it.inputFile = stdDevAggregatorInputFile
+    it.outputFile = "org/elasticsearch/compute/aggregation/StdDevLongAggregator.java"
+  }
+  template {
+    it.properties = floatProperties
+    it.inputFile = stdDevAggregatorInputFile
+    it.outputFile = "org/elasticsearch/compute/aggregation/StdDevFloatAggregator.java"
+  }
+  template {
+    it.properties = doubleProperties
+    it.inputFile = stdDevAggregatorInputFile
+    it.outputFile = "org/elasticsearch/compute/aggregation/StdDevDoubleAggregator.java"
+  }
 
   File topAggregatorInputFile = new File("${projectDir}/src/main/java/org/elasticsearch/compute/aggregation/X-TopAggregator.java.st")
   template {

diff --git a/.../src/main/generated-src/org/elasticsearch/compute/aggregation/StdDevDoubleAggregator.java b/.../src/main/generated-src/org/elasticsearch/compute/aggregation/StdDevDoubleAggregator.java
diff --git a/...e/src/main/generated-src/org/elasticsearch/compute/aggregation/StdDevFloatAggregator.java b/...e/src/main/generated-src/org/elasticsearch/compute/aggregation/StdDevFloatAggregator.java
diff --git a/...ute/src/main/generated-src/org/elasticsearch/compute/aggregation/StdDevIntAggregator.java b/...ute/src/main/generated-src/org/elasticsearch/compute/aggregation/StdDevIntAggregator.java