Make TDigestState configurable

docs/changelog/96794.yaml

@@ -0,0 +1,5 @@
+pr: 96794
+summary: Make TDigestState configurable
+area: Aggregations
+type: enhancement
+issues: []

docs/reference/aggregations/metrics/boxplot-aggregation.asciidoc

@@ -166,6 +166,35 @@ GET latency/_search
 
 include::percentile-aggregation.asciidoc[tags=t-digest]
 
+==== Execution hint
+
+The default implementation of TDigest is optimized for performance, scaling to millions or even
+billions of sample values while maintaining acceptable accuracy levels (close to 1% relative error
+for millions of samples in some cases). There's an option to use an implementation optimized
+for accuracy by setting parameter `execution_hint` to value `high_accuracy`:
+
+[source,console]
+--------------------------------------------------
+GET latency/_search
+{
+  "size": 0,
+  "aggs": {
+    "load_time_boxplot": {
+      "boxplot": {
+        "field": "load_time",
+        "execution_hint": "high_accuracy"    <1>
+      }
+    }
+  }
+}
+--------------------------------------------------
+// TEST[setup:latency]
+
+<1> Optimize TDigest for accuracy, at the expense of performance
+
+This option can lead to improved accuracy (relative error close to 0.01% for millions of samples in some
+cases) but then percentile queries take 2x-10x longer to complete.
+
 ==== Missing value
 
 The `missing` parameter defines how documents that are missing a value should be treated.

docs/reference/aggregations/metrics/percentile-aggregation.asciidoc

@@ -306,6 +306,38 @@ TDigest roughly 64KB in size. In practice data tends to be more random and
 the TDigest will use less memory.
 // end::t-digest[]
 
+[[search-aggregations-metrics-percentile-aggregation-execution-hint]]
+==== Execution hint
+
+The default implementation of TDigest is optimized for performance, scaling to millions or even
+billions of sample values while maintaining acceptable accuracy levels (close to 1% relative error
+for millions of samples in some cases). There's an option to use an implementation optimized
+for accuracy by setting parameter `execution_hint` to value `high_accuracy`:
+
+[source,console]
+--------------------------------------------------
+GET latency/_search
+{
+  "size": 0,
+  "aggs": {
+    "load_time_outlier": {
+      "percentiles": {
+        "field": "load_time",
+        "tdigest": {
+          "execution_hint": "high_accuracy"    <1>
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// TEST[setup:latency]
+
+<1> Optimize TDigest for accuracy, at the expense of performance
+
+This option can lead to improved accuracy (relative error close to 0.01% for millions of samples in some
+cases) but then percentile queries take 2x-10x longer to complete.
+
 ==== HDR Histogram
 
 https://github.com/HdrHistogram/HdrHistogram[HDR Histogram] (High Dynamic Range Histogram) is an alternative implementation

docs/reference/aggregations/metrics/percentile-rank-aggregation.asciidoc

@@ -10,9 +10,10 @@ extracted from specific numeric or <<histogram,histogram fields>> in the documen
 
 [NOTE]
 ==================================================
-Please see <<search-aggregations-metrics-percentile-aggregation-approximation>>
-and <<search-aggregations-metrics-percentile-aggregation-compression>> for advice
-regarding approximation and memory use of the percentile ranks aggregation
+Please see <<search-aggregations-metrics-percentile-aggregation-approximation>>,
+<<search-aggregations-metrics-percentile-aggregation-compression>> and
+<<search-aggregations-metrics-percentile-aggregation-execution-hint>> for advice
+regarding approximation, performance and memory use of the percentile ranks aggregation
 ==================================================
 
 Percentile rank show the percentage of observed values which are below certain

libs/tdigest/src/main/java/org/elasticsearch/tdigest/Dist.java

@@ -30,30 +30,68 @@
 public class Dist {
 
     private static double cdf(final double x, final int length, Function<Integer, Double> elementGetter) {
+        if (length == 0) {
+            // no data to examine
+            return Double.NaN;
+        }
+        if (length == 1) {
+            double value = elementGetter.apply(0);
+            if (x < value) return 0;
+            if (x > value) return 1;
+            return 0.5;
+        }
+
         if (Double.compare(x, elementGetter.apply(0)) < 0) {
             return 0;
         }
 
-        double n1 = 0.5;
-        int n2 = 0;
-        for (int i = 1; i < length; i++) {
-            double value = elementGetter.apply(i);
-            int compareResult = Double.compare(value, x);
-            if (compareResult > 0) {
-                if (Double.compare(n2, 0) > 0) {
-                    return (n1 + 0.5 * n2) / length;
-                }
-                double previousValue = elementGetter.apply(i - 1);
-                double factor = (x - previousValue) / (value - previousValue);
-                return (n1 + factor) / length;
+        if (Double.compare(x, elementGetter.apply(0)) == 0) {
+            // we have one or more centroids == x, treat them as one
+            // dw will accumulate the weight of all of the centroids at x
+            double dw = 0;
+            for (int i = 0; i < length && Double.compare(elementGetter.apply(i), x) == 0; i++) {
+                dw += 1;
+            }
+            return dw / 2.0 / length;
+        }
+
+        if (x > elementGetter.apply(length - 1)) {
+            return 1;
+        }
+        if (x == elementGetter.apply(length - 1)) {
+            double dw = 0;
+            for (int i = length - 1; i >= 0 && Double.compare(elementGetter.apply(i), x) == 0; i--) {
+                dw += 1;
             }
-            if (compareResult < 0) {
-                n1++;
-            } else {
-                n2++;
+            return (length - dw / 2.0) / length;
+        }
+
+        // initially, we set left width equal to right width
+        double left = (elementGetter.apply(1) - elementGetter.apply(0)) / 2;
+        double weightSoFar = 0;
+
+        for (int i = 0; i < length - 1; i++) {
+            double right = (elementGetter.apply(i + 1) - elementGetter.apply(i)) / 2;
+            if (x < elementGetter.apply(i) + right) {
+                double value = (weightSoFar + AbstractTDigest.interpolate(x, elementGetter.apply(i) - left, elementGetter.apply(i) + right))
+                    / length;
+                return Math.max(value, 0.0);
             }
+            weightSoFar += 1;
+            left = right;
+        }
+
+        // for the last element, assume right width is same as left
+        int lastOffset = length - 1;
+        double right = (elementGetter.apply(lastOffset) - elementGetter.apply(lastOffset - 1)) / 2;
+        if (x < elementGetter.apply(lastOffset) + right) {
+            return (weightSoFar + AbstractTDigest.interpolate(
+                x,
+                elementGetter.apply(lastOffset) - right,
+                elementGetter.apply(lastOffset) + right
+            )) / length;
         }
-        return (length - 0.5 * n2) / length;
+        return 1;
     }
 
     public static double cdf(final double x, double[] data) {

libs/tdigest/src/main/java/org/elasticsearch/tdigest/HybridDigest.java

@@ -0,0 +1,193 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.tdigest;
+
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * Uses a {@link SortingDigest} implementation under the covers for small sample populations, then switches to {@link MergingDigest}.
+ * The {@link SortingDigest} is perfectly accurate and the fastest implementation for up to millions of samples, at the cost of increased
+ * memory footprint as it tracks all samples. Conversely, the {@link MergingDigest} pre-allocates its memory (tens of KBs) and provides
+ * better performance for hundreds of millions of samples and more, while accuracy stays bounded to 0.1-1% for most cases.
+ *
+ * This hybrid  approach provides the best of both worlds, i.e. speedy and accurate percentile calculations for small populations with
+ * bounded memory allocation and acceptable speed and accuracy for larger ones.
+ */
+public class HybridDigest extends AbstractTDigest {
+
+    // See MergingDigest's compression param.
+    private final double compression;
+
+    // Indicates the sample size over which it switches from SortingDigest to MergingDigest.
+    private final long maxSortingSize;
+
+    // This is set to null when the implementation switches to MergingDigest.
+    private SortingDigest sortingDigest = new SortingDigest();
+
+    // This gets initialized when the implementation switches to MergingDigest.
+    private MergingDigest mergingDigest;
+
+    /**
+     * Creates a hybrid digest that uses a {@link SortingDigest} for up to {@param maxSortingSize} samples,
+     * then switches to a {@link MergingDigest}.
+     *
+     * @param compression The compression factor for the MergingDigest
+     * @param maxSortingSize The sample size limit for switching from a {@link SortingDigest} to a {@link MergingDigest} implementation
+     */
+    HybridDigest(double compression, long maxSortingSize) {
+        this.compression = compression;
+        this.maxSortingSize = maxSortingSize;
+    }
+
+    /**
+     * Similar to the constructor above. The limit for switching from a {@link SortingDigest} to a {@link MergingDigest} implementation
+     * is calculated based on the passed compression factor.
+     *
+     * @param compression The compression factor for the MergingDigest
+     */
+    HybridDigest(double compression) {
+        // The default maxSortingSize is calculated so that the SortingDigest will have comparable size with the MergingDigest
+        // at the point where implementations switch, e.g. for default compression 100 SortingDigest allocates ~16kB and MergingDigest
+        // allocates ~15kB.
+        this(compression, Math.round(compression) * 20);
+    }
+
+    @Override
+    public void add(double x, int w) {
+        reserve(w);
+        if (mergingDigest != null) {
+            mergingDigest.add(x, w);
+        } else {
+            sortingDigest.add(x, w);
+        }
+    }
+
+    @Override
+    public void reserve(long size) {
+        if (mergingDigest != null) {
+            mergingDigest.reserve(size);
+            return;
+        }
+        // Check if we need to switch implementations.
+        assert sortingDigest != null;
+        if (sortingDigest.size() + size >= maxSortingSize) {
+            mergingDigest = new MergingDigest(compression);
+            for (double value : sortingDigest.values) {
+                mergingDigest.add(value);
+            }
+            mergingDigest.reserve(size);
+            // Release the allocated SortingDigest.
+            sortingDigest = null;
+        } else {
+            sortingDigest.reserve(size);
+        }
+    }
+
+    @Override
+    public void add(List<? extends TDigest> others) {
+        if (mergingDigest != null) {
+            mergingDigest.add(others);
+        } else {
+            sortingDigest.add(others);
+        }
+    }
+
+    @Override
+    public void compress() {
+        if (mergingDigest != null) {
+            mergingDigest.compress();
+        } else {
+            sortingDigest.compress();
+        }
+    }
+
+    @Override
+    public long size() {
+        if (mergingDigest != null) {
+            return mergingDigest.size();
+        }
+        return sortingDigest.size();
+    }
+
+    @Override
+    public double cdf(double x) {
+        if (mergingDigest != null) {
+            return mergingDigest.cdf(x);
+        }
+        return sortingDigest.cdf(x);
+    }
+
+    @Override
+    public double quantile(double q) {
+        if (mergingDigest != null) {
+            return mergingDigest.quantile(q);
+        }
+        return sortingDigest.quantile(q);
+    }
+
+    @Override
+    public Collection<Centroid> centroids() {
+        if (mergingDigest != null) {
+            return mergingDigest.centroids();
+        }
+        return sortingDigest.centroids();
+    }
+
+    @Override
+    public double compression() {
+        if (mergingDigest != null) {
+            return mergingDigest.compression();
+        }
+        return sortingDigest.compression();
+    }
+
+    @Override
+    public int centroidCount() {
+        if (mergingDigest != null) {
+            return mergingDigest.centroidCount();
+        }
+        return sortingDigest.centroidCount();
+    }
+
+    @Override
+    public double getMin() {
+        if (mergingDigest != null) {
+            return mergingDigest.getMin();
+        }
+        return sortingDigest.getMin();
+    }
+
+    @Override
+    public double getMax() {
+        if (mergingDigest != null) {
+            return mergingDigest.getMax();
+        }
+        return sortingDigest.getMax();
+    }
+
+    @Override
+    public int byteSize() {
+        if (mergingDigest != null) {
+            return mergingDigest.byteSize();
+        }
+        return sortingDigest.byteSize();
+    }
+}