feat: Implement 'Bucket Sort Aggregation'

docs/documentation.yml

@@ -144,6 +144,7 @@ toc:
   - BucketScriptAggregation
   - BucketSelectorAggregation
   - SerialDifferencingAggregation
+  - BucketSortAggregation
   - name: Matrix Aggregations
   - MatrixStatsAggregation
   - name: Score Functions

src/aggregations/pipeline-aggregations/bucket-sort-aggregation.js

@@ -0,0 +1,115 @@
+'use strict';
+
+const PipelineAggregationBase = require('./pipeline-aggregation-base');
+
+const ES_REF_URL =
+    'https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-bucket-sort-aggregation.html';
+
+/**
+ * A parent pipeline aggregation which sorts the buckets of its parent
+ * multi-bucket aggregation. Zero or more sort fields may be specified
+ * together with the corresponding sort order. Each bucket may be sorted
+ * based on its _key, _count or its sub-aggregations. In addition, parameters
+ * from and size may be set in order to truncate the result buckets.
+ *
+ * [Elasticsearch reference](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-bucket-sort-aggregation.html)
+ *
+ * @example
+ * const reqBody = esb.requestBodySearch()
+ *     .agg(
+ *         esb.bucketSortAggregation('sort')
+ *             .sort([
+ *                  esb.sort('user', 'desc')
+ *              ])
+ *              .from(5)
+ *              .size(10)
+ *         )
+ *     );
+ *
+ * @param {string} name The name which will be used to refer to this aggregation.
+ *
+ * @extends PipelineAggregationBase
+ */
+class BucketSortAggregation extends PipelineAggregationBase {
+    // eslint-disable-next-line require-jsdoc
+    constructor(name) {
+        super(name, 'bucket_sort', ES_REF_URL);
+    }
+
+    /**
+     * Sets the list of fields to sort on. Optional.
+     *
+     * [Elasticsearch reference](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-bucket-sort-aggregation.html#id-1.9.5.55.4.6)
+     *
+     * @example
+     * const reqBody = esb.requestBodySearch()
+     *     .agg(
+     *         esb.bucketSortAggregation('sort')
+     *             .sort([
+     *                  esb.sort('user', 'desc')
+     *              ])
+     *              .from(5)
+     *              .size(10)
+     *         )
+     *     );
+     *
+     * @param {Array<Sort>} sort The list of fields to sort on
+     * @returns {BucketSortAggregation} returns `this` so that calls can be chained
+     */
+    sort(sort) {
+        this._aggsDef.sort = sort;
+        return this;
+    }
+
+    /**
+     * Sets the value buckets in positions prior to which will be truncated. Optional.
+     *
+     * [Elasticsearch reference](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-bucket-sort-aggregation.html#id-1.9.5.55.4.6)
+     *
+     * @example
+     * const reqBody = esb.requestBodySearch()
+     *     .agg(
+     *         esb.bucketSortAggregation('sort')
+     *             .sort([
+     *                  esb.sort('user', 'desc')
+     *              ])
+     *              .from(5)
+     *              .size(10)
+     *         )
+     *     );
+     *
+     * @param {number} from Buckets in positions prior to the set value will be truncated.
+     * @returns {BucketSortAggregation} returns `this` so that calls can be chained
+     */
+    from(from) {
+        this._aggsDef.from = from;
+        return this;
+    }
+
+    /**
+     * Sets the number of buckets to return. Optional.
+     *
+     * [Elasticsearch reference](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-bucket-sort-aggregation.html#id-1.9.5.55.4.6)
+     *
+     * @example
+     * const reqBody = esb.requestBodySearch()
+     *     .agg(
+     *         esb.bucketSortAggregation('sort')
+     *             .sort([
+     *                  esb.sort('user', 'desc')
+     *              ])
+     *              .from(5)
+     *              .size(10)
+     *         )
+     *     );
+     *
+     * @param {number} size The number of buckets to return.
+     * @returns {BucketSortAggregation} returns `this` so that calls can be chained
+     */
+    size(size) {
+        this._aggsDef.size = size;
+        return this;
+    }
+}
+
+module.exports = BucketSortAggregation;

src/aggregations/pipeline-aggregations/index.js

@@ -15,3 +15,4 @@ exports.CumulativeSumAggregation = require('./cumulative-sum-aggregation');
 exports.BucketScriptAggregation = require('./bucket-script-aggregation');
 exports.BucketSelectorAggregation = require('./bucket-selector-aggregation');
 exports.SerialDifferencingAggregation = require('./serial-differencing-aggregation');
+exports.BucketSortAggregation = require('./bucket-sort-aggregation');

src/index.d.ts

@@ -6516,6 +6516,54 @@ declare namespace esb {
         bucketsPath?: string
     ): BucketSelectorAggregation;
 
+    /**
+     * A parent pipeline aggregation which sorts the buckets of its parent
+     * multi-bucket aggregation. Zero or more sort fields may be specified
+     * together with the corresponding sort order. Each bucket may be sorted
+     * based on its _key, _count or its sub-aggregations. In addition, parameters
+     * from and size may be set in order to truncate the result buckets.
+     *
+     * @param {string} name The name which will be used to refer to this aggregation.
+     * @extends PipelineAggregationBase
+     */
+    export class BucketSortAggregation extends PipelineAggregationBase {
+        constructor(name: string);
+
+        /**
+         * Sets the list of fields to sort on.
+         *
+         * @param {Array<Sort>} sort The list of fields to sort on
+         */
+        sort(sort: Array<Sort>): this;
+
+        /**
+         * Sets the value buckets in positions prior to which will be truncated.
+         *
+         * @param {number} from Buckets in positions prior to the set value will be truncated.
+         */
+        from(from: number): this;
+
+        /**
+         * Sets the number of buckets to return.
+         *
+         * @param {number} size The number of buckets to return.
+         */
+        size(size: number): this;
+    }
+
+    /**
+     * A parent pipeline aggregation which sorts the buckets of its parent
+     * multi-bucket aggregation. Zero or more sort fields may be specified
+     * together with the corresponding sort order. Each bucket may be sorted
+     * based on its _key, _count or its sub-aggregations. In addition, parameters
+     * from and size may be set in order to truncate the result buckets.
+     *
+     * @param {string} name The name which will be used to refer to this aggregation.
+     */
+    export function bucketSortAggregation(
+        name: string
+    ): BucketSortAggregation;
+
     /**
      * Serial differencing is a technique where values in a time series are
      * subtracted from itself at different time lags or periods.

src/index.js

@@ -134,7 +134,8 @@ const {
         CumulativeSumAggregation,
         BucketScriptAggregation,
         BucketSelectorAggregation,
-        SerialDifferencingAggregation
+        SerialDifferencingAggregation,
+        BucketSortAggregation
     },
     matrixAggregations: { MatrixStatsAggregation }
 } = require('./aggregations');
@@ -447,6 +448,9 @@ exports.maxBucketAggregation = constructorWrapper(MaxBucketAggregation);
 exports.MinBucketAggregation = MinBucketAggregation;
 exports.minBucketAggregation = constructorWrapper(MinBucketAggregation);
 
+exports.BucketSortAggregation = BucketSortAggregation;
+exports.bucketSortAggregation = constructorWrapper(BucketSortAggregation);
+
 exports.SumBucketAggregation = SumBucketAggregation;
 exports.sumBucketAggregation = constructorWrapper(SumBucketAggregation);
 

test/aggregations-test/bucket-sort-agg.test.js

@@ -0,0 +1,40 @@
+import test from 'ava';
+import { BucketSortAggregation, Sort } from '../../src';
+import { setsAggType } from '../_macros';
+
+const getInstance = () => new BucketSortAggregation('my_agg');
+
+test(setsAggType, BucketSortAggregation, 'bucket_sort');
+
+test('can be instantiated', t => {
+    const value = getInstance().toJSON();
+    const expected = {
+        my_agg: {
+            bucket_sort: {}
+        }
+    };
+    t.deepEqual(value, expected);
+});
+
+test('sort from and size are set', t => {
+    const value = getInstance()
+        .sort([new Sort('myField', 'desc')])
+        .from(5)
+        .size(10)
+        .toJSON();
+
+    const expected = {
+        my_agg: {
+            bucket_sort: {
+                sort: [
+                    {
+                        myField: 'desc'
+                    }
+                ],
+                from: 5,
+                size: 10
+            }
+        }
+    };
+    t.deepEqual(value, expected);
+});

test/index.test.js

@@ -319,6 +319,9 @@ test('aggregations are exported', t => {
     t.truthy(esb.BucketSelectorAggregation);
     t.truthy(esb.bucketSelectorAggregation);
 
+    t.truthy(esb.BucketSortAggregation);
+    t.truthy(esb.bucketSortAggregation);
+
     t.truthy(esb.SerialDifferencingAggregation);
     t.truthy(esb.serialDifferencingAggregation);