jay_api 29.8.0 → 29.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00a7a3dd5e1e7e2bf232e6f06c8ce6b6e39a31693f4ec2921fb56a1f14e70f63
-  data.tar.gz: 405c629691a82be4e5da822b4875494cf365195e8ccfb9653986e143cc8707f5
+  metadata.gz: 29f1af4da5bd52cd5012da50bc4933a30cd8d3d7682d4301bab18dfb429d090c
+  data.tar.gz: 86924bc855b991f2678cce3d3f023e8958f3beb725fb154429ad5667c705b78c
 SHA512:
-  metadata.gz: a469997825b9876cf81c4e5944414928fe27d9c58233478556cc2923086c4837ebe5ba36033aa2a57765f05000af68f150c88978b5a3fd636769b9dddd3db6a2
-  data.tar.gz: 70e767866d629bb49eb1c2a4fd0f64ed204c68c0c1b5da704125be0c6fa29926e41ddfd1160c9ee98b78f23d99df1484d749d4ebb2ec83594823c6f778048419
+  metadata.gz: d4401b8bea8090b4f21182689b336d65256efe4136327c23f1418aa93a88b8bd3d15c364423838b8e29709f2edc4ebae5d99953a8125bd97ae268b4a2fc2de46
+  data.tar.gz: ce39feece636e38b932e3b100f814f7ecba3fb3c7c870a6c8a7d12cbba4c24e5c9c32646b6ede2d59f86f73f434b617364b65eaf88a5722582ce9b28c54cc9ad

data/CHANGELOG.md

@@ -8,6 +8,23 @@ Please mark backwards incompatible changes with an exclamation mark at the start
 
 ## [Unreleased]
 
+## [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
+- The `JayAPI::Elasticsearch::Count` class.
+- The `#count` method to the `Indexable` module. The method returns the number
+  of documents in the `Index` or `Indexes`. A query can be provided to filter
+  the documents that are counted.
+
 ## [29.8.0] - 2026-07-06
 
 ### Deprecated

data/lib/jay_api/elasticsearch/client.rb

@@ -53,6 +53,22 @@ module JayAPI
         retry_request { transport_client.search(**args) }
       end
 
+      # Calls Elasticsearch::Client's #count method and retries the connection
+      # a few times when certain Elasticsearch::Error::ServerError are raised.
+      # @see Elasticsearch::API::Cat::Actions#count for information about the
+      #   required arguments.
+      # @return [Hash] The response from Elasticsearch, which contains the count
+      #   of documents in the index matching the given query (if any). An
+      #   example of this response is shown below:
+      #
+      #   {
+      #     "count" => 24097688,
+      #     "_shards" => { "total"=>5, "successful"=>5, "skipped"=>0, "failed"=>0 }
+      #   }
+      def count(**args)
+        retry_request { transport_client.count(**args) }
+      end
+
       # Calls the Elasticsearch::Client's #bulk method and retries the connection a few times if
       # a ServerError occurs.
       # @see Elasticsearch::Client#index for information about the arguments and the returned value.

data/lib/jay_api/elasticsearch/count.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module JayAPI
+  module Elasticsearch
+    # Lightweight wrapper around an Elasticsearch count response.
+    #
+    # It behaves like a numeric value for comparisons and arithmetic while
+    # preserving access to the original response payload.
+    class Count
+      extend Forwardable
+
+      include Comparable
+
+      def_delegators :count, :to_i, :to_int
+
+      # @param [Hash] data The raw Elasticsearch response that includes the
+      #   +count+ value.
+      def initialize(data)
+        @data = data
+      end
+
+      # The count returned by Elasticsearch.
+      # @return [Integer] The raw count value from the response payload.
+      def count
+        @count ||= data['count']
+      end
+
+      # Coerces another value so arithmetic operations can be performed with
+      # the receiver.
+      # @param [Numeric, #to_int] other The other operand.
+      # @return [Array(Numeric, Integer)] A two-element array in the form
+      #   expected by Ruby coercion.
+      # @raise [TypeError] If +other+ cannot be coerced into an +Integer+.
+      # :reek:FeatureEnvy :reek:ManualDispatch -- Not much that can be done here, since this is a coercion method.
+      def coerce(other)
+        if other.is_a?(Numeric)
+          [other, to_int]
+        elsif other.respond_to?(:to_int)
+          [other.to_int, to_int]
+        else
+          raise TypeError, "#{other.class} cannot be coerced into Integer"
+        end
+      end
+
+      # Compares this count with another numeric value.
+      # @param [Numeric, #to_int] other The value to compare with.
+      # @return [-1, 0, 1, nil] Comparison result, or +nil+ when the values are
+      #   not comparable.
+      # :reek:ManualDispatch -- Relies on the other object responding to +to_int+.
+      def <=>(other)
+        if other.is_a?(Numeric)
+          to_int <=> other
+        elsif other.respond_to?(:to_int)
+          to_int <=> other.to_int
+        else
+          super
+        end
+      end
+
+      # Adds another value to the receiver's count.
+      # @param [Numeric, #to_int] other The value to add.
+      # @return [Numeric] The arithmetic result.
+      def +(other)
+        other, this = coerce(other)
+        this + other
+      end
+
+      # Subtracts another value from the receiver's count.
+      # @param [Numeric, #to_int] other The value to subtract.
+      # @return [Numeric] The arithmetic result.
+      def -(other)
+        other, this = coerce(other)
+        this - other
+      end
+
+      # Multiplies the receiver's count by another value.
+      # @param [Numeric, #to_int] other The value to multiply by.
+      # @return [Numeric] The arithmetic result.
+      def *(other)
+        other, this = coerce(other)
+        this * other
+      end
+
+      # Divides the receiver's count by another value.
+      # @param [Numeric, #to_int] other The divisor.
+      # @return [Numeric] The arithmetic result.
+      def /(other)
+        other, this = coerce(other)
+        this / other
+      end
+
+      # @return [String] The count converted to a string.
+      def to_s
+        count.to_s
+      end
+
+      private
+
+      attr_reader :data
+    end
+  end
+end

data/lib/jay_api/elasticsearch/indexable.rb

@@ -8,6 +8,7 @@ require 'logging'
 
 require_relative 'async'
 require_relative 'batch_counter'
+require_relative 'count'
 require_relative 'errors/elasticsearch_error'
 require_relative 'query_results'
 require_relative 'response'
@@ -106,6 +107,18 @@ module JayAPI
         query_results(query, response, batch_counter, type)
       end
 
+      # @return [JayAPI::Elasticsearch::Count] The count of documents in the
+      #   index(es) matching the given query (if any).
+      # @raise [Elasticsearch::Transport::Transport::ServerError] If the
+      #   query or the connection to Elasticsearch fail.
+      def count(query: nil)
+        body = query ? { query: query } : nil
+
+        JayAPI::Elasticsearch::Count.new(
+          client.count(**{ index: index_names, body: body }.compact)
+        )
+      end
+
       # Sends whatever is currently in the send queue to the Elasticsearch
       # instance and clears the queue.
       def flush

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/elasticsearch.rb

@@ -5,6 +5,7 @@ require_relative 'elasticsearch/batch_counter'
 require_relative 'elasticsearch/client'
 require_relative 'elasticsearch/client_factory'
 require_relative 'elasticsearch/cluster'
+require_relative 'elasticsearch/count'
 require_relative 'elasticsearch/errors'
 require_relative 'elasticsearch/index'
 require_relative 'elasticsearch/indexes'

data/lib/jay_api/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jay_api
 version: !ruby/object:Gem::Version
-  version: 29.8.0
+  version: 29.10.0
 platform: ruby
 authors:
 - Accenture-Industry X
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-06 00:00:00.000000000 Z
+date: 2026-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -122,6 +122,7 @@ files:
 - lib/jay_api/elasticsearch/client.rb
 - lib/jay_api/elasticsearch/client_factory.rb
 - lib/jay_api/elasticsearch/cluster.rb
+- lib/jay_api/elasticsearch/count.rb
 - lib/jay_api/elasticsearch/errors.rb
 - lib/jay_api/elasticsearch/errors/elasticsearch_error.rb
 - lib/jay_api/elasticsearch/errors/end_of_query_results_error.rb
@@ -168,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