jay_api 29.9.0 → 29.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0a1faee742a3503bae215225c1a111f9cb21b21e94ffb83b10fcd16d14f71e1
-  data.tar.gz: b39ed836b7bef2233a3833d9b9e56f5234f4b542fd10f1a4fb7fc35b85e85e37
+  metadata.gz: af422ade60e62cb63cd97d8fd51892cd9876143e8fee61da5ac64666ad70e4ed
+  data.tar.gz: bb7c1cbf24070575ea3db15d5056e7b22389b62e1199c7243c5243aa07722cf6
 SHA512:
-  metadata.gz: 4963d63c87ed8d756e94984ec635d53cb4db539e6fba42632be2ecd8f5cf79443485ededadaddf9f15988414db7e37b07b515f2d37529fcc074de8d57bf6f2f4
-  data.tar.gz: 9db8b8d9600477ded9c07058d26af30de56153717adc5cdd9dc179bd0b2893225936fbdecb2281a0d5e06859ad6797eee3554d89e3531d88d449042040f266d2
+  metadata.gz: ce6602395fb91182c762e7bcf6d32a2391731087af461b6b67a6f2ed2d563b65bd46f011eae1bd04f0ee45e337749567098257616c41265d46b70a39d6b3d33c
+  data.tar.gz: 8344f2770b7c707a045d01159ff71c91fefe3058a742177e1a670a707a956fc9bd190b512f1ae56f23c70f39287eeac633e73367ef57fd02745f07d0e8135fd3

data/CHANGELOG.md

@@ -8,6 +8,22 @@ 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
+- The `JayAPI::Elasticsearch::QueryBuilder::QueryClauses::Prefix` class and the
+  corresponding `#prefix` method to the `MatchClauses` module. This allows the
+  use of Elasticsearch's
+  [prefix](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-prefix-query.html)
+  query with the Query Builder.
+
 ## [29.9.0] - 2026-08-04
 
 ### 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/elasticsearch/query_builder/query_clauses/match_clauses.rb

@@ -5,6 +5,7 @@ require_relative 'ids'
 require_relative 'match_all'
 require_relative 'match_none'
 require_relative 'match_phrase'
+require_relative 'prefix'
 require_relative 'query_string'
 require_relative 'range'
 require_relative 'regexp'
@@ -31,6 +32,16 @@ module JayAPI
             self << ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::MatchPhrase.new(**params)
           end
 
+          # Adds a +JayAPI::Elasticsearch::QueryBuilder::QueryClauses::Prefix+
+          # clause to the Query Clauses set.
+          # @param [Hash] params The parameters for the +Prefix+ class.
+          # @return [self] Returns itself so that other methods can be chained.
+          # @raise [JayAPI::Elasticsearch::QueryBuilder::Errors::QueryBuilderError]
+          #   If an error occurs when trying to add the query clause to the set.
+          def prefix(**params)
+            self << ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::Prefix.new(**params)
+          end
+
           # Adds a +JayAPI::Elasticsearch::QueryBuilder::QueryClauses::QueryString+
           # clause to the Query Clauses set.
           # @param [Hash] params The parameters for the +QueryString+ class

data/lib/jay_api/elasticsearch/query_builder/query_clauses/prefix.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'query_clause'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class QueryClauses
+        # Represents a +Prefix+ query in Elasticsearch
+        # More information about this type of query can be found here:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-prefix-query.html
+        class Prefix < ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::QueryClause
+          attr_reader :field, :value
+
+          # @param [String, Symbol] field The field where the prefix query
+          #   should be applied.
+          # @param [String] value The prefix to be found in +field+
+          def initialize(field:, value:)
+            super()
+            @field = field
+            @value = value
+          end
+
+          # @return [Hash] The Hash that represents this query (in
+          #   Elasticsearch's format)
+          def to_h
+            {
+              prefix: {
+                field => {
+                  value: value
+                }
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/query_results.rb

@@ -24,7 +24,8 @@ module JayAPI
       # @param [JayAPI::Elasticsearch::Indexable] index The Elasticsearch
       #   index or indexes over which the query should be performed.
       # @param [Hash] query The query that produced the results.
-      # @param [JayAPI::Elasticsearch::Results] response An object containing Docs retrieved from Elasticsearch.
+      # @param [JayAPI::Elasticsearch::Response] response An object containing
+      #   Docs retrieved from Elasticsearch.
       # @param [JayAPI::Elasticsearch::BatchCounter] batch_counter An object keeping track of the current batch.
       def initialize(index:, query:, response:, batch_counter: nil)
         @index = index

data/lib/jay_api/version.rb

@@ -2,5 +2,5 @@
 
 module JayAPI
   # JayAPI gem's semantic version
-  VERSION = '29.9.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.9.0
+  version: 29.11.0
 platform: ruby
 authors:
 - Accenture-Industry X
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -169,6 +169,7 @@ files:
 - lib/jay_api/elasticsearch/query_builder/query_clauses/match_none.rb
 - lib/jay_api/elasticsearch/query_builder/query_clauses/match_phrase.rb
 - lib/jay_api/elasticsearch/query_builder/query_clauses/negator.rb
+- lib/jay_api/elasticsearch/query_builder/query_clauses/prefix.rb
 - lib/jay_api/elasticsearch/query_builder/query_clauses/query_clause.rb
 - lib/jay_api/elasticsearch/query_builder/query_clauses/query_string.rb
 - lib/jay_api/elasticsearch/query_builder/query_clauses/range.rb