jay_api 29.10.0 → 29.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29f1af4da5bd52cd5012da50bc4933a30cd8d3d7682d4301bab18dfb429d090c
-  data.tar.gz: 86924bc855b991f2678cce3d3f023e8958f3beb725fb154429ad5667c705b78c
+  metadata.gz: af422ade60e62cb63cd97d8fd51892cd9876143e8fee61da5ac64666ad70e4ed
+  data.tar.gz: bb7c1cbf24070575ea3db15d5056e7b22389b62e1199c7243c5243aa07722cf6
 SHA512:
-  metadata.gz: d4401b8bea8090b4f21182689b336d65256efe4136327c23f1418aa93a88b8bd3d15c364423838b8e29709f2edc4ebae5d99953a8125bd97ae268b4a2fc2de46
-  data.tar.gz: ce39feece636e38b932e3b100f814f7ecba3fb3c7c870a6c8a7d12cbba4c24e5c9c32646b6ede2d59f86f73f434b617364b65eaf88a5722582ce9b28c54cc9ad
+  metadata.gz: ce6602395fb91182c762e7bcf6d32a2391731087af461b6b67a6f2ed2d563b65bd46f011eae1bd04f0ee45e337749567098257616c41265d46b70a39d6b3d33c
+  data.tar.gz: 8344f2770b7c707a045d01159ff71c91fefe3058a742177e1a670a707a956fc9bd190b512f1ae56f23c70f39287eeac633e73367ef57fd02745f07d0e8135fd3

data/CHANGELOG.md

@@ -8,6 +8,13 @@ Please mark backwards incompatible changes with an exclamation mark at the start
 
 ## [Unreleased]
 
+## [29.11.0] - 2026-09-03
+
+### Added
+- The `_source` parameter for Elasticsearch's `TopHits` aggregation.
+- The `sort` parameter for Elasticsearch's `TopHits` aggregation.
+- The `missing` parameter for Elasticsearch's `Terms` aggregation.
+
 ## [29.10.0] - 2026-08-21
 
 ### Added

data/lib/jay_api/elasticsearch/query_builder/aggregations/terms.rb

@@ -14,7 +14,7 @@ module JayAPI
         # Information about this type of aggregation can be found in:
         # https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html
         class Terms < ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation
-          attr_reader :field, :script, :size, :order
+          attr_reader :field, :script, :size, :order, :missing
 
           # @param [String] name The name used by Elasticsearch to identify each
           #   of the aggregations.
@@ -29,9 +29,15 @@ module JayAPI
           #   aggregation. By default, the +terms+ aggregation orders terms by
           #   descending document +_count+. This can be changed by providing a
           #   custom +order+ hash.
+          # @param [String] missing The value to use for documents that are
+          #   missing a value in the given +field+ or for whom the +script+
+          #   returns +null+. When +missing+ is not given, such documents are
+          #   ignored.
           # @raise [ArgumentError] If neither a +field+ nor a +script+ are given
           #   or if both of them are given. Only one should be present.
-          def initialize(name, field: nil, script: nil, size: nil, order: nil)
+          # rubocop:disable Metrics/ParameterLists -- Constraint by Elasticsearch's design
+          # :reek:LongParameterList -- Constraint by Elasticsearch's design
+          def initialize(name, field: nil, script: nil, size: nil, order: nil, missing: nil)
             if (field.present? && script.present?) || (field.blank? && script.blank?)
               raise ArgumentError, "Either 'field' or 'script' must be provided"
             end
@@ -42,13 +48,16 @@ module JayAPI
             @script = script
             @size = size
             @order = order
+            @missing = missing
           end
 
+          # rubocop:enable Metrics/ParameterLists
+
           # @return [self] A copy of the receiver.
           def clone
-            self.class.new(name, field: field, script: script, size: size, order: order&.deep_dup).tap do |copy|
-              copy.aggregations = aggregations.clone
-            end
+            self.class.new(
+              name, field: field, script: script, size: size, order: order&.deep_dup, missing: missing
+            ).tap { |copy| copy.aggregations = aggregations.clone }
           end
 
           # @return [Hash] The Hash representation of the +Aggregation+.
@@ -60,7 +69,8 @@ module JayAPI
                   field: field,
                   size: size,
                   script: script&.to_h,
-                  order: order
+                  order: order,
+                  missing: missing
                 }.compact
               }
             end

data/lib/jay_api/elasticsearch/query_builder/aggregations/top_hits.rb

@@ -15,20 +15,32 @@ module JayAPI
         # Information on this type of aggregation can be found here:
         # https://www.elastic.co/docs/reference/aggregations/search-aggregations-metrics-top-hits-aggregation
         class TopHits < ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation
-          attr_reader :size
+          attr_reader :size, :sort, :_source
 
           # @param [String] name The name used by Elasticsearch to identify each
           #   of the aggregations.
           # @param [String] size The number of hits that will be returned.
-          def initialize(name, size:)
+          # @param [Hash] sort How to sort the documents to determine the top
+          #   hits. When not specified the documents are sorted by the score of
+          #   the main query.
+          # @param [FalseClass, String, Array<String>, Hash] _source Expression
+          #   used for source filtering.
+          # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-fields.html#source-filtering
+          #   Elasticsearch's documentation for more information on what kind of
+          #   expressions are allowed.
+          # rubocop:disable-next Lint/UnderscorePrefixedVariableName -- to match Elasticsearch's name
+          def initialize(name, size:, sort: nil, _source: nil)
             super(name)
 
             @size = size
+            @sort = sort
+            @_source = _source
           end
 
           # @return [self] A copy of the receiver.
           def clone
-            copy = self.class.new(name, size: size)
+            optional_params = { sort: sort.deep_dup, _source: _source.deep_dup }.compact
+            copy = self.class.new(name, size: size, **optional_params)
             copy.aggregations = aggregations.clone
             copy
           end
@@ -39,8 +51,10 @@ module JayAPI
             super do
               {
                 top_hits: {
-                  size: size
-                }
+                  size: size,
+                  sort: sort.deep_dup,
+                  _source: _source.deep_dup
+                }.compact
               }
             end
           end

data/lib/jay_api/elasticsearch/query_builder/aggregations.rb

@@ -32,11 +32,9 @@ module JayAPI
 
         # Adds a +terms+ type aggregation. For information about the parameters
         # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::Terms#initialize
-        def terms(name, field: nil, script: nil, size: nil, order: nil)
+        def terms(name, **params)
           add(
-            ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Terms.new(
-              name, field: field, script: script, size: size, order: order
-            )
+            ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Terms.new(name, **params)
           )
         end
 
@@ -72,8 +70,8 @@ module JayAPI
 
         # Adds a +top_hits+ type aggregation. For more information about the parameters
         # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::TopHits#initialize
-        def top_hits(name, size:)
-          add(::JayAPI::Elasticsearch::QueryBuilder::Aggregations::TopHits.new(name, size: size))
+        def top_hits(name, **params)
+          add(::JayAPI::Elasticsearch::QueryBuilder::Aggregations::TopHits.new(name, **params))
         end
 
         # Adds an +scripted_metric+ type aggregation. For information about the parameters

data/lib/jay_api/version.rb

@@ -2,5 +2,5 @@
 
 module JayAPI
   # JayAPI gem's semantic version
-  VERSION = '29.10.0'
+  VERSION = '29.11.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jay_api
 version: !ruby/object:Gem::Version
-  version: 29.10.0
+  version: 29.11.0
 platform: ruby
 authors:
 - Accenture-Industry X
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-21 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport