diff --git a/docs/documentation.yml b/docs/documentation.yml index ed8fc2ad..b936bf30 100644 --- a/docs/documentation.yml +++ b/docs/documentation.yml @@ -144,6 +144,7 @@ toc: - BucketScriptAggregation - BucketSelectorAggregation - SerialDifferencingAggregation + - BucketSortAggregation - name: Matrix Aggregations - MatrixStatsAggregation - name: Score Functions diff --git a/src/aggregations/pipeline-aggregations/bucket-sort-aggregation.js b/src/aggregations/pipeline-aggregations/bucket-sort-aggregation.js new file mode 100644 index 00000000..2a6650d3 --- /dev/null +++ b/src/aggregations/pipeline-aggregations/bucket-sort-aggregation.js @@ -0,0 +1,73 @@ +'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. + * + * @param {Array} 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. + * + * @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. + * + * @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; diff --git a/src/aggregations/pipeline-aggregations/index.js b/src/aggregations/pipeline-aggregations/index.js index d508d851..24724a36 100644 --- a/src/aggregations/pipeline-aggregations/index.js +++ b/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'); diff --git a/src/index.d.ts b/src/index.d.ts index 6a31b405..8098bba2 100644 --- a/src/index.d.ts +++ b/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 The list of fields to sort on + */ + sort(sort: Array): 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. diff --git a/src/index.js b/src/index.js index b82285a0..6f38094e 100644 --- a/src/index.js +++ b/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); diff --git a/test/aggregations-test/bucket-sort-agg.test.js b/test/aggregations-test/bucket-sort-agg.test.js new file mode 100644 index 00000000..7fe43f38 --- /dev/null +++ b/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); +}); diff --git a/test/index.test.js b/test/index.test.js index 2367731b..16154027 100644 --- a/test/index.test.js +++ b/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);