jay_api 29.3.1 → 29.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4dc3e0a1c55fc4d24d117a2c24f415dfcd4d481c41bcc698ab22b9680b2c1ff
-  data.tar.gz: b8402e498357724ad86f0516d82e937049176cdb54476c49dab03bf7a941ce15
+  metadata.gz: f997e23215ab5ee73c077534d19889c9b91ae5c877a77859b75f454e555bb105
+  data.tar.gz: f0250fc57649d863fde276f3e753b9d8aecff90c0bd286a1a97fb12b447b1c33
 SHA512:
-  metadata.gz: 77770aca2b7203de9a0e76c5293b21db21ff4f6fb13c4f02f19b3cd3740af58033aacf82f24131b2ed2aa20a1bfec22c9d29d837735fd5ad40081a5642e82e95
-  data.tar.gz: fbe4d05866d4b6f8b41a3b1ca1a458c22f59352d748619b459b20518a476fc4811ff11253b456c00b13787d8a47f38f4868b914a786ef8a3033f0bef6ca413a0
+  metadata.gz: bf6ba31a0f5960479de755757d6479b0c9373cc4b4e9e99ee55d853ba90417d1161b02d88d2103d8c86cd13a028f725293c3f13422c0422c51e0d64b6a906a40
+  data.tar.gz: ad81742c20b6a93b973972ee49b814ea61b3ecaac8ce0945aceac05dbd8020ec2c9d4dca701c261dadc7eeffbb3e40658ba6476ba015662217e0a8509785235f

data/CHANGELOG.md

@@ -8,6 +8,42 @@ Please mark backwards incompatible changes with an exclamation mark at the start
 
 ## [Unreleased]
 
+## [29.5.0] - 2026-02-23
+
+### Fixed
+- A `NameError` that was being raised when `jay_api/elasticsearch/client` was
+  required without requiring `elasticsearch`.
+- A `NoMethodError` that was being raised by `Elasticsearch::Stats::Indices`
+  when `active_support/core_ext/string` hadn't been loaded.
+
+### Added
+- The `#force_merge` method to the `Elasticsearch::Index` class. This method
+  starts a Forced Segment Merge on the index.
+- The `#totals` method to `Elasticsearch::Stats::Index`, this gives the caller
+  access to the index's total metrics.
+- The `Elasticsearch::Stats::Index::Totals` class. The class contains information
+  about an index's total metrics, for example, total number of documents, total
+  size, etc.
+- The `#settings` method to the `Elasticsearch::Index` class. This gives the
+  caller access to the index's settings.
+- The `Elasticsearch::Indices::Settings::Blocks` class. The class encapsulates
+  an index's blocks settings (for example, whether the index is read-only).
+- The `Elasticsearch::Indices::Settings` class. The class encapsulates an
+  index's settings.
+- It is now possible to configure the type used by the `RSpec::TestDataCollector`
+  class when pushing documents to Elasticsearch. If no type is specified in the
+  configuration the default type will be used.
+- Allow the `Elasticsearch::Index` and `Elasticsearch::Indexes`'s `#push` method
+  to receive a `type` parameter, just like `#index` does.
+
+## [29.4.0] - 2026-01-28
+
+### Added
+- Support for the `bucket_selector` pipeline aggregation in
+  `Elasticsearch::QueryBuilder::Aggregations`. This allows filtering
+  buckets based on computed metrics (e.g., filtering terms buckets by
+  aggregated values).
+
 ## [29.3.1] - 2025-12-15
 
 ### Fixed
@@ -35,7 +71,7 @@ Please mark backwards incompatible changes with an exclamation mark at the start
   allows boolean clauses to be nested.
 - `QueryBuilder#sort` can now receive either the direction of the sorting (`asc`
   or `desc`) or a `Hash` with advanced sorting options. These are relayed
-  directly to Elasticsearch. 
+  directly to Elasticsearch.
 
 ## [29.0.0] - 2025-08-28
 

data/lib/jay_api/elasticsearch/client.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'elasticsearch/api/namespace/tasks'
+require 'timeout'
 require 'elasticsearch/transport/transport/errors'
 require 'faraday/error'
 require 'forwardable'

data/lib/jay_api/elasticsearch/errors/writable_index_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative '../../errors/error'
+
+module JayAPI
+  module Elasticsearch
+    module Errors
+      # An error to be raised when an attempt is made to perform force_merge
+      # over an index which hasn't been set to be read-only.
+      class WritableIndexError < ::JayAPI::Errors::Error; end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/errors.rb

@@ -6,6 +6,7 @@ require_relative 'errors/query_execution_error'
 require_relative 'errors/query_execution_failure'
 require_relative 'errors/query_execution_timeout'
 require_relative 'errors/search_after_error'
+require_relative 'errors/writable_index_error'
 
 module JayAPI
   module Elasticsearch

data/lib/jay_api/elasticsearch/index.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative 'indexable'
+require_relative 'indices/settings'
+require_relative 'errors/writable_index_error'
 
 module JayAPI
   module Elasticsearch
@@ -49,6 +51,36 @@ module JayAPI
       def index(data, type: DEFAULT_DOC_TYPE)
         super.first
       end
+
+      # @return [JayAPI::Elasticsearch::Indices::Settings] The settings for the
+      #   index.
+      def settings
+        # DO NOT MEMOIZE! Leave it to the caller.
+        ::JayAPI::Elasticsearch::Indices::Settings.new(client.transport_client, index_name)
+      end
+
+      # Starts a Forced Segment Merge process on the index.
+      #
+      # ⚠️ For big indexes this process can take a very long time, make sure to
+      #    adjust the timeout when creating the client.
+      # @param [Boolean] only_expunge_deletes Specifies whether the operation
+      #   should only remove deleted documents.
+      # @raise [JayAPI::Elasticsearch::Errors::WritableIndexError] If the index
+      #   is writable (hasn't been set to read-only).
+      # @return [Hash] A +Hash+ with the result of the index merging process,
+      #   it looks like this:
+      #
+      #   { "_shards" => { "total" => 10, "successful" => 10, "failed" => 0 } }
+      def force_merge(only_expunge_deletes: nil)
+        unless settings.blocks.write_blocked?
+          raise ::JayAPI::Elasticsearch::Errors::WritableIndexError,
+                "Write block for '#{index_name}' has not been enabled. " \
+                "Please enable the index's write block before performing a segment merge"
+        end
+
+        params = { index: index_name, only_expunge_deletes: }.compact
+        client.transport_client.indices.forcemerge(**params)
+      end
     end
   end
 end

data/lib/jay_api/elasticsearch/indexable.rb

@@ -48,9 +48,13 @@ module JayAPI
       # Pushes a record into the index. (This does not send the record to the
       # Elasticsearch instance, only puts it into the send queue).
       # @param [Hash] data The data to be pushed to the index.
-      def push(data)
+      # @param [String, nil] type The type of the document. When set to +nil+
+      #   the decision is left to Elasticsearch's API. Which will normally
+      #   default to +_doc+.
+      def push(data, type: DEFAULT_DOC_TYPE)
+        validate_type(type)
         index_names.each do |index_name|
-          batch << { index: { _index: index_name, _type: 'nested', data: data } }
+          batch << { index: { _index: index_name, _type: type, data: data }.compact }
         end
 
         flush! if batch.size >= batch_size
@@ -78,8 +82,7 @@ module JayAPI
       # For information on the contents of this Hash please see:
       # https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html#docs-index-api-response-body
       def index(data, type: DEFAULT_DOC_TYPE)
-        raise ArgumentError, "Unsupported type: '#{type}'" unless SUPPORTED_TYPES.include?(type)
-
+        validate_type(type)
         index_names.map { |index_name| client.index index: index_name, type: type, body: data }
       end
 
@@ -220,6 +223,15 @@ module JayAPI
       def async
         @async ||= JayAPI::Elasticsearch::Async.new(self)
       end
+
+      # @param [String, nil] type The type of the document. When set to +nil+
+      #   the decision is left to Elasticsearch's API. Which will normally
+      #   default to +_doc+.
+      # @raise [ArgumentError] When the given +type+ is not one of the
+      #   +SUPPORTED_TYPES+
+      def validate_type(type)
+        raise ArgumentError, "Unsupported type: '#{type}'" unless SUPPORTED_TYPES.include?(type)
+      end
     end
   end
 end

data/lib/jay_api/elasticsearch/indices/settings/blocks.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module JayAPI
+  module Elasticsearch
+    module Indices
+      class Settings
+        # Represents the block settings of an Elasticsearch index.
+        class Blocks
+          attr_reader :settings
+
+          # @param [JayAPI::Elasticsearch::Indices::Settings] settings The
+          #   parent +Settings+ object.
+          def initialize(settings)
+            @settings = settings
+          end
+
+          # @return [Boolean] True if the Index's write block has been set to
+          #   true, false otherwise.
+          def write_blocked?
+            blocks_settings.fetch('write') == 'true'
+          end
+
+          # Sets the index's +write+ block to the given value. When the +write+
+          # block is set to +true+ the index's data is read-only, but the
+          # index's settings can still be changed. This allows maintenance tasks
+          # to still be performed on the index.
+          # @param [Boolean] value The new value for the +write+ block of the
+          #   index.
+          # @raise [Elasticsearch::Transport::Transport::Errors::ServerError] If
+          #   an error occurs when trying to set the value of the block.
+          def write=(value)
+            unless [true, false].include?(value)
+              raise ArgumentError, "Expected 'value' to be true or false, #{value.class} given"
+            end
+
+            return if write_blocked? == value
+
+            settings.transport_client.indices.put_settings(
+              index: settings.index_name,
+              body: { 'blocks.write' => value }
+            )
+          end
+
+          private
+
+          # @return [Hash] The block settings of the index. Something like this:
+          #
+          #  { 'read_only_allow_delete' => 'false', 'write' => 'false' }
+          #
+          # @raise [KeyError] If the index's settings do not contain a "blocks"
+          #   section.
+          def blocks_settings
+            settings.all.fetch('blocks')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/indices/settings.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'settings/blocks'
+
+module JayAPI
+  module Elasticsearch
+    module Indices
+      # Represents the settings of an Elasticsearch Index.
+      class Settings
+        attr_reader :transport_client, :index_name
+
+        # @param [Elasticsearch::Transport::Client] transport_client Elasticsearch's
+        #   transport client.
+        # @param [String] index_name The name of the index this class will be
+        #   handling settings for.
+        def initialize(transport_client, index_name)
+          @transport_client = transport_client
+          @index_name = index_name
+        end
+
+        # @return [Hash] A Hash with all the settings for the index. It looks
+        #   like this:
+        #
+        #   {
+        #     "number_of_shards" => "5",
+        #     "blocks" => { "read_only_allow_delete" => "false", "write" => "false" },
+        #     "provided_name" => "xyz01_tests",
+        #     "creation_date" => "1588701800423",
+        #     "number_of_replicas" => "1",
+        #     "uuid" => "VFx2e5t0Qgi-1zc2PUkYEg",
+        #     "version" => { "created" => "7010199", "upgraded" => "7100299"}
+        #   }
+        #
+        # @raise [Elasticsearch::Transport::Transport::Errors::ServerError] If
+        #   an error occurs when trying to get the index's settings.
+        # @raise [KeyError] If any of the expected hierarchical elements in the
+        #   response are missing.
+        def all
+          transport_client.indices.get_settings(index: index_name)
+                          .fetch(index_name).fetch('settings').fetch('index')
+        end
+
+        # @return [JayAPI::Elasticsearch::Indices::Settings::Blocks] The blocks
+        #   settings for the given index.
+        def blocks
+          @blocks ||= ::JayAPI::Elasticsearch::Indices::Settings::Blocks.new(self)
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/indices.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'indices/settings'
+
+module JayAPI
+  module Elasticsearch
+    # Namespace for sub-elements of Elasticsearch's indices
+    module Indices; end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'aggregation'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class Aggregations
+        # Represents a +bucket_selector+ pipeline aggregation in Elasticsearch.
+        # Docs:
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-bucket-selector-aggregation.html
+        class BucketSelector < ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation
+          attr_reader :buckets_path, :script, :gap_policy
+
+          # @param [String] name The name used by Elasticsearch to identify the
+          #   aggregation.
+          # @param [Hash] buckets_path Path(s) to the metric or metrics
+          #   over which the bucket_selector aggregation's script will operate.
+          #   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 [String, nil] gap_policy Optional gap policy (e.g. "skip",
+          #   "insert_zeros").
+          def initialize(name, buckets_path:, script:, gap_policy: nil)
+            super(name)
+
+            @buckets_path = buckets_path
+            @script       = script
+            @gap_policy   = gap_policy
+          end
+
+          # Bucket selector is a pipeline agg and cannot have nested aggregations.
+          # @raise [JayAPI::Elasticsearch::QueryBuilder::Aggregations::Errors::AggregationsError]
+          def aggs
+            no_nested_aggregations('Bucket Selector')
+          end
+
+          # @return [self] A copy of the receiver.
+          def clone
+            self.class.new(
+              name,
+              buckets_path: buckets_path.is_a?(Hash) ? buckets_path.dup : buckets_path,
+              script:, # Script is immutable-ish, ok to reuse
+              gap_policy:
+            )
+          end
+
+          # @return [Hash] The Hash representation of the +Aggregation+.
+          #   Properly formatted for Elasticsearch.
+          def to_h
+            super do
+              {
+                bucket_selector: {
+                  buckets_path: buckets_path,
+                  script: script.to_h,
+                  gap_policy: gap_policy
+                }.compact
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -9,6 +9,7 @@ require_relative 'aggregations/composite'
 require_relative 'aggregations/date_histogram'
 require_relative 'aggregations/filter'
 require_relative 'aggregations/scripted_metric'
+require_relative 'aggregations/bucket_selector'
 require_relative 'aggregations/sum'
 require_relative 'aggregations/max'
 require_relative 'aggregations/terms'
@@ -86,6 +87,16 @@ module JayAPI
           )
         end
 
+        # Adds an +bucket_selector+ type aggregation. For information about the parameters
+        # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::BucketSelector#initialize
+        def bucket_selector(name, buckets_path:, script:, gap_policy: nil)
+          add(
+            ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::BucketSelector.new(
+              name, buckets_path:, script:, gap_policy:
+            )
+          )
+        end
+
         # Adds a +max+ type aggregation. For information about the parameters
         # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::Max#initialize
         def max(name, field:)

data/lib/jay_api/elasticsearch/stats/index/totals.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module JayAPI
+  module Elasticsearch
+    class Stats
+      class Index
+        # Contains information about an index's totals (docs, used space, etc).
+        class Totals
+          # @param [Hash] data The data under the index's +total+ key.
+          def initialize(data)
+            @data = data
+          end
+
+          # @return [Integer] The total number of documents in the index.
+          def docs_count
+            @docs_count ||= docs.fetch('count')
+          end
+
+          # @return [Integer] The total number of deleted documents in the index.
+          def deleted_docs
+            @deleted_docs ||= docs.fetch('deleted')
+          end
+
+          # @return [Float] A number between 0 and 1 that represents the ratio
+          #   of between deleted documents and total documents in the index.
+          def deleted_ratio
+            @deleted_ratio ||= calculate_deleted_ratio
+          end
+
+          private
+
+          attr_reader :data
+
+          # @return [Hash] The information about the documents in the index.
+          #   Looks something like this:
+          #
+          #   { "count" => 530626, "deleted" => 11 }
+          #
+          # @raise [KeyError] If the given data doesn't have a +docs+ key.
+          def docs
+            @docs ||= data.fetch('docs')
+          end
+
+          # @return [Float] A number between 0 and 1 that represents the ratio
+          #   of between deleted documents and total documents in the index.
+          def calculate_deleted_ratio
+            if docs_count.zero?
+              return deleted_docs.zero? ? 0.0 : 1.0
+            end
+
+            deleted_docs / docs_count.to_f
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/stats/index.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'index/totals'
+
 module JayAPI
   module Elasticsearch
     class Stats
@@ -13,6 +15,17 @@ module JayAPI
           @name = name
           @data = data
         end
+
+        # @return [JayAPI::Elasticsearch::Stats::Index::Totals] Information
+        #   about the index's total metrics.
+        # @raise [KeyError] If the given data doesn't have a +total+ key.
+        def totals
+          @totals ||= ::JayAPI::Elasticsearch::Stats::Index::Totals.new(data.fetch('total'))
+        end
+
+        private
+
+        attr_reader :data
       end
     end
   end

data/lib/jay_api/elasticsearch/stats/indices.rb

@@ -10,7 +10,7 @@ module JayAPI
       class Indices
         # A lambda used to select / reject system indices (indices whose name
         # starts with dot).
-        SYSTEM_SELECTOR = ->(name, _data) { name.starts_with?('.') }
+        SYSTEM_SELECTOR = ->(name, _data) { name.start_with?('.') }
 
         # @param [Hash{String=>Hash}] indices A +Hash+ with the information
         #   about the indices. Its keys are the names of the indices, its values

data/lib/jay_api/elasticsearch.rb

@@ -7,6 +7,7 @@ require_relative 'elasticsearch/client_factory'
 require_relative 'elasticsearch/errors'
 require_relative 'elasticsearch/index'
 require_relative 'elasticsearch/indexes'
+require_relative 'elasticsearch/indices'
 require_relative 'elasticsearch/query_builder'
 require_relative 'elasticsearch/query_results'
 require_relative 'elasticsearch/response'

data/lib/jay_api/rspec/test_data_collector.rb

@@ -79,7 +79,7 @@ module JayAPI
           }
         }
 
-        elasticsearch_index.push(data)
+        elasticsearch_index.push(data, **push_params)
       end
 
       # Executed by RSpec at the end of the test run. If the push is enabled,
@@ -94,6 +94,14 @@ module JayAPI
 
       attr_reader :push_enabled
 
+      # @return [Hash] Additional parameters for the Elasticsearch::Index#push.
+      def push_params
+        # The extraction of the parameters is done with a #slice to be able to
+        # differentiate between when the parameter is not specified (completely
+        # absent) or when the parameter has been specified as +nil+.
+        @push_params ||= configuration.to_h.slice(:type)
+      end
+
       # @return [Hash] The configuration set for Elasticsearch as a hash. If no
       #   value has been set for the batch size a reasonable default is set.
       # @raise [JayAPI::Errors::ConfigurationError] If no configuration for

data/lib/jay_api/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jay_api
 version: !ruby/object:Gem::Version
-  version: 29.3.1
+  version: 29.5.0
 platform: ruby
 authors:
 - Accenture-Industry X
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-15 00:00:00.000000000 Z
+date: 2026-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -128,13 +128,18 @@ files:
 - lib/jay_api/elasticsearch/errors/query_execution_failure.rb
 - lib/jay_api/elasticsearch/errors/query_execution_timeout.rb
 - lib/jay_api/elasticsearch/errors/search_after_error.rb
+- lib/jay_api/elasticsearch/errors/writable_index_error.rb
 - lib/jay_api/elasticsearch/index.rb
 - lib/jay_api/elasticsearch/indexable.rb
 - lib/jay_api/elasticsearch/indexes.rb
+- lib/jay_api/elasticsearch/indices.rb
+- lib/jay_api/elasticsearch/indices/settings.rb
+- lib/jay_api/elasticsearch/indices/settings/blocks.rb
 - lib/jay_api/elasticsearch/query_builder.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/aggregation.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/avg.rb
+- lib/jay_api/elasticsearch/query_builder/aggregations/bucket_selector.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/cardinality.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/composite.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/date_histogram.rb
@@ -173,6 +178,7 @@ files:
 - lib/jay_api/elasticsearch/stats.rb
 - lib/jay_api/elasticsearch/stats/errors/stats_data_not_available.rb
 - lib/jay_api/elasticsearch/stats/index.rb
+- lib/jay_api/elasticsearch/stats/index/totals.rb
 - lib/jay_api/elasticsearch/stats/indices.rb
 - lib/jay_api/elasticsearch/stats/node.rb
 - lib/jay_api/elasticsearch/stats/node/storage.rb