jay_api 29.7.0 → 29.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 469981ee390e1c409ff7e4e3faef1d9fb3579e87c9f1e2262f1664ba8d4731c3
-  data.tar.gz: 0f9b84be25dfc1a2f318edb8ae462714553e7898c278e1da0b9e38d211049719
+  metadata.gz: e0a1faee742a3503bae215225c1a111f9cb21b21e94ffb83b10fcd16d14f71e1
+  data.tar.gz: b39ed836b7bef2233a3833d9b9e56f5234f4b542fd10f1a4fb7fc35b85e85e37
 SHA512:
-  metadata.gz: 23f0fd77caa519085f05b6efeff92c128895a912ffa3e75d83703f3b4a7b27cf76e39dfcb42652461fc730c3ff790df67913f0d7f52926ab8bebec86cf02196b
-  data.tar.gz: 48c2c4d5c97ef87fe7ce9ca0809d4b650549db40b654bb7b856438462b6b1c482bdd83f5c11840428fac5f51fc51cbc08cf43bec996f22abdf2e08a4f87050f8
+  metadata.gz: 4963d63c87ed8d756e94984ec635d53cb4db539e6fba42632be2ecd8f5cf79443485ededadaddf9f15988414db7e37b07b515f2d37529fcc074de8d57bf6f2f4
+  data.tar.gz: 9db8b8d9600477ded9c07058d26af30de56153717adc5cdd9dc179bd0b2893225936fbdecb2281a0d5e06859ad6797eee3554d89e3531d88d449042040f266d2

data/CHANGELOG.md

@@ -8,6 +8,27 @@ Please mark backwards incompatible changes with an exclamation mark at the start
 
 ## [Unreleased]
 
+## [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
+- The `Elasticsearch::QueryBuilder::Script` class is now deprecated, please
+  use `Elasticsearch::Script` instead.
+
+### Added
+- The `#update` method to `JayAPI::Elasticsearch::Client`.
+- The `QueryClauses::IDs` class and the corresponding `#ids` method to the
+  `MatchClauses` module. This allows the use of Elasticsearch's
+  [ids](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-ids-query)
+  query with the Query Builder.
+
 ## [29.7.0] - 2026-04-28
 
 ### Added

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.
@@ -96,6 +112,14 @@ module JayAPI
       def cluster
         @cluster ||= ::JayAPI::Elasticsearch::Cluster.new(transport_client)
       end
+
+      # Calls the +Elasticsearch::Client+'s #update method forwarding the given
+      # parameters. If the request fails, additional retries will be performed.
+      # @see Elasticsearch::API::Actions#update for more info about the
+      #   arguments and the return value.
+      def update(**args)
+        retry_request { transport_client.update(**args) }
+      end
     end
   end
 end

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

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'active_support'
+require 'active_support/core_ext/object/blank'
+
 require_relative 'indexable'
 require_relative 'indices/settings'
 require_relative 'errors/writable_index_error'
@@ -52,6 +55,46 @@ module JayAPI
         super.first
       end
 
+      # Updates a document by ID.
+      # @param [String] id The ID of the document to update.
+      # @param [Hash, nil] doc The partial document to update the existing
+      #   document with. If +nil+ is given, the +script+ parameter must be
+      #   provided. If both +doc+ and +script+ are given, the +doc+ parameter
+      #   will be ignored by Elasticsearch.
+      # @param [JayAPI::Elasticsearch::Script, Hash, nil] script The script to
+      #   update the existing document with. If +nil+ is given, the +doc+
+      #   parameter must be provided. It's recommended to use a
+      #   +JayAPI::Elasticsearch::Script+ object, but a Hash can also be used.
+      # @return [Hash] A Hash containing information about the updated document.
+      #   An example of such Hash is:
+      #
+      #  {
+      #     "_index" : "xyz01_build_properties",
+      #     "_type" : "_doc",
+      #     "_id" : "ns4AAZ8BXEjZhYMmw-8y",
+      #     "_version" : 7,
+      #     "result" : "updated",
+      #     "_shards" : {
+      #       "total" : 2,
+      #       "successful" : 2,
+      #       "failed" : 0
+      #     },
+      #     "_seq_no" : 11,
+      #     "_primary_term" : 1
+      #   }
+      #
+      # For information on how to use the script and about the contents of the
+      # returned Hash please see:
+      # https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-update
+      # @raise [ArgumentError] If both +doc+ and +script+ are +nil+.
+      # @raise [Elasticsearch::Transport::Transport::ServerError] If the
+      #   update fails.
+      def update(id:, doc: nil, script: nil)
+        raise ArgumentError, "Either 'doc' or 'script' must be provided" if doc.blank? && script.blank?
+
+        client.update(index: index_name, id:, body: { doc: doc, script: script&.to_h }.compact)
+      end
+
       # @return [JayAPI::Elasticsearch::Indices::Settings] The settings for the
       #   index.
       def settings

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/aggregations/bucket_selector.rb

@@ -19,8 +19,8 @@ module JayAPI
           #   The keys are the names of the script variables, the values the
           #   paths to the metrics (relative to the parent aggregation).
           #   The script will receive these variables in its +params+.
-          # @param [JayAPI::Elasticsearch::QueryBuilder::Script] script
-          #   Script used to decide whether to keep each bucket.
+          # @param [JayAPI::Elasticsearch::Script] script Script used to decide
+          #   whether to keep each bucket.
           # @param [String, nil] gap_policy Optional gap policy (e.g. "skip",
           #   "insert_zeros").
           def initialize(name, buckets_path:, script:, gap_policy: nil)

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

@@ -19,10 +19,9 @@ module JayAPI
           # @param [String] name The name used by Elasticsearch to identify each
           #   of the aggregations.
           # @param [String] field The field whose unique values should be counted.
-          # @param [JayAPI::Elasticsearch::QueryBuilder::Script] script If a
-          #   script is given the aggregation will count the unique values
-          #   returned by the script instead of the unique values in a specific
-          #   field.
+          # @param [JayAPI::Elasticsearch::Script] script If a script is given
+          #   the aggregation will count the unique values returned by the
+          #   script instead of the unique values in a specific field.
           # @param [Integer] size By default the aggregation returns the top 10
           #   unique values (the ones with the higher frequency). By specifying
           #   a size this can be changed.

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'query_clause'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class QueryClauses
+        # Represents an IDs query in Elasticsearch.
+        # Information about this type of query can be found here:
+        # https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-ids-query
+        class IDs < ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::QueryClause
+          attr_reader :ids
+
+          # @param [Array<String>] ids The ids of the documents to match.
+          def initialize(ids:)
+            super()
+
+            @ids = ids
+          end
+
+          # @return [Hash] The Hash that represents this query (in
+          #   Elasticsearch's DSL)
+          def to_h
+            {
+              ids: {
+                values: ids
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'exists'
+require_relative 'ids'
 require_relative 'match_all'
 require_relative 'match_none'
 require_relative 'match_phrase'
@@ -116,6 +117,18 @@ module JayAPI
             self << ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::Regexp.new(**params)
           end
 
+          # Adds a +JayAPI::Elasticsearch::QueryBuilder::QueryClauses::IDs+
+          # clause to the Query Clauses set.
+          # @param [Hash] params The parameters for the +IDs+ class'
+          #   constructor.
+          # @see JayAPI::Elasticsearch::QueryBuilder::QueryClauses::IDs#initialize
+          # @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 ids(**params)
+            self << ::JayAPI::Elasticsearch::QueryBuilder::QueryClauses::IDs.new(**params)
+          end
+
           # Adds a +JayAPI::Elasticsearch::QueryBuilder::QueryClauses::MatchAll+
           # clause to the Query Clauses set.
           # @return [self] Returns itself, so that other methods can be chained.

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

@@ -1,36 +1,15 @@
 # frozen_string_literal: true
 
+require_relative '../script'
+
 module JayAPI
   module Elasticsearch
     class QueryBuilder
       # Represents a scripted element in a query. This scripted element can be
       # used in different places. It can be used in a query clause, but can
       # also be used to create custom aggregations.
-      class Script
-        attr_reader :source, :lang, :params
-
-        # @param [String] source The source for the script element.
-        # @param [String] lang The language the script is written in.
-        # @param [Hash] params A +Hash+ with key-value pairs for the script's
-        #   parameters.
-        def initialize(source:, lang: 'painless', params: nil)
-          @source = source
-          @lang = lang
-
-          # Keeps the parameters from being modified from the outside after the
-          # class has been initialized.
-          @params = params.dup.freeze
-        end
-
-        # @return [Hash] The hash representation of the scripted element.
-        def to_h
-          {
-            source: source,
-            lang: lang,
-            params: params
-          }.compact
-        end
-      end
+      # @deprecated Use +JayAPI::Elasticsearch::Script+ instead.
+      Script = JayAPI::Elasticsearch::Script
     end
   end
 end

data/lib/jay_api/elasticsearch/script.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module JayAPI
+  module Elasticsearch
+    # Represents a scripted element in Elasticsearch. This scripted element
+    # can be used in different places. It can be used in a query clause, but can
+    # also be used to create custom aggregations or when updating documents.
+    class Script
+      attr_reader :source, :lang, :params
+
+      # @param [String] source The source for the script element.
+      # @param [String] lang The language the script is written in.
+      # @param [Hash] params A +Hash+ with key-value pairs for the script's
+      #   parameters.
+      def initialize(source:, lang: 'painless', params: nil)
+        @source = source
+        @lang = lang
+
+        # Keeps the parameters from being modified from the outside after the
+        # class has been initialized.
+        @params = params.dup.freeze
+      end
+
+      # @return [Hash] The hash representation of the scripted element.
+      def to_h
+        {
+          source: source,
+          lang: lang,
+          params: params
+        }.compact
+      end
+    end
+  end
+end

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'
@@ -13,6 +14,7 @@ require_relative 'elasticsearch/mixins'
 require_relative 'elasticsearch/query_builder'
 require_relative 'elasticsearch/query_results'
 require_relative 'elasticsearch/response'
+require_relative 'elasticsearch/script'
 require_relative 'elasticsearch/search_after_results'
 require_relative 'elasticsearch/stats'
 require_relative 'elasticsearch/tasks'

data/lib/jay_api/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jay_api
 version: !ruby/object:Gem::Version
-  version: 29.7.0
+  version: 29.9.0
 platform: ruby
 authors:
 - Accenture-Industry X
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-28 00:00:00.000000000 Z
+date: 2026-08-04 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
@@ -162,6 +163,7 @@ files:
 - lib/jay_api/elasticsearch/query_builder/query_clauses.rb
 - lib/jay_api/elasticsearch/query_builder/query_clauses/bool.rb
 - lib/jay_api/elasticsearch/query_builder/query_clauses/exists.rb
+- lib/jay_api/elasticsearch/query_builder/query_clauses/ids.rb
 - lib/jay_api/elasticsearch/query_builder/query_clauses/match_all.rb
 - lib/jay_api/elasticsearch/query_builder/query_clauses/match_clauses.rb
 - lib/jay_api/elasticsearch/query_builder/query_clauses/match_none.rb
@@ -177,6 +179,7 @@ files:
 - lib/jay_api/elasticsearch/query_builder/script.rb
 - lib/jay_api/elasticsearch/query_results.rb
 - lib/jay_api/elasticsearch/response.rb
+- lib/jay_api/elasticsearch/script.rb
 - lib/jay_api/elasticsearch/search_after_results.rb
 - lib/jay_api/elasticsearch/stats.rb
 - lib/jay_api/elasticsearch/stats/errors/stats_data_not_available.rb