jay_api 28.1.0 → 28.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b2d35c2ed340724fe54f7f099ed3fb5f200249c72604b906a39ecdef13be6fb
-  data.tar.gz: 4da5c5a7dca36ea23ca6241ac5f44846558d620a60ce9382dff422ca3575f4fe
+  metadata.gz: 07ffb602dd7c52159b2142a00f06401d0326ae8e82e05ba24c61f96d35347d8c
+  data.tar.gz: 7f0f39ca31de378467d2914e3322fd83f6fad7a0b2185a30c94582d213d04439
 SHA512:
-  metadata.gz: 74414baf82a02115568311cfce173e990c3777da5d3a18eed084366048968f88c1a42e581a2652544cc9952ff1e32b135528c622cd2d30554a429c952b544aa2
-  data.tar.gz: 5bbe6985eb4d5b3bd1263f1ebd6d23f83afb2a9b5eb48bce31a710628bdd35f6051c0b643bcdaab8c22ffc977b90e4bd79e3b94468a9d8b0b0984065408df92a
+  metadata.gz: 8bc9fc4c9631aac5a504600ccabd68ff875e7027682f83b47830608a6578cc7a73702333be180b4dd9c7b5d9d637c32b1ef6d86a6519ba5ef8a40706b0a5d397
+  data.tar.gz: 290b96e8925ee9bbff77e469bdd8299291317639dfd37ea345e1fb88e608c45b1d799015dd6d94592a300e24a97d1aab34df7de4a3ebb8c7ef014b4a09b2e2ed

data/CHANGELOG.md

@@ -8,6 +8,18 @@ Please mark backwards incompatible changes with an exclamation mark at the start
 
 ## [Unreleased]
 
+## [28.3.0] - 2025-06-05
+
+### Added
+- The `Aggregations::Composite` class and the `Aggregations#composite` method.
+  They make it possible to use Elasticsearch's `composite` aggregations.
+
+## [28.2.0] - 2025-05-30
+
+### Added
+- The `#nodes` method to the `Elasticsearch::Stats` class. This method gives the
+  user access to the node-related statistics of the Elasticsearch cluster.
+
 ## [28.1.0] - 2025-05-19
 
 ### Added

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/string/inflections'
+
+require_relative 'aggregation'
+require_relative 'sources/sources'
+require_relative 'errors/aggregations_error'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class Aggregations
+        # Represents a Composite aggregation in Elasticsearch. For more
+        # information about this type of aggregation:
+        # @see https://www.elastic.co/docs/reference/aggregations/search-aggregations-bucket-composite-aggregation
+        class Composite < ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Aggregation
+          attr_reader :size
+
+          # @param [String] name The name of the composite aggregation.
+          # @param [Integer] size The number of composite buckets to return.
+          # @yieldparam [JayAPI::Elasticsearch::QueryBuilder::Aggregations::Sources::Sources]
+          #   The collection of sources for the composite aggregation. This
+          #   should be used by the caller to add sources to the composite
+          #   aggregation.
+          # @raise [JayAPI::Elasticsearch::QueryBuilder::Aggregations::Errors::AggregationsError]
+          #   If the method is called without a block.
+          def initialize(name, size: nil, &block)
+            unless block
+              raise(::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Errors::AggregationsError,
+                    "The #{self.class.name.demodulize} aggregation must be initialized with a block")
+            end
+
+            super(name)
+            @size = size
+            block.call(sources)
+          end
+
+          # @return [self] A copy of the receiver. Sources and nested
+          #   aggregations are also cloned.
+          def clone
+            # rubocop:disable Lint/EmptyBlock (The sources will be assigned later)
+            copy = self.class.new(name, size: size) {}
+            # rubocop:enable Lint/EmptyBlock
+
+            copy.aggregations = aggregations.clone
+            copy.sources = sources.clone
+            copy
+          end
+
+          # @return [Hash] The Hash representation of the +Aggregation+.
+          #   Properly formatted for Elasticsearch.
+          def to_h
+            super do
+              {
+                composite: {
+                  sources: sources.to_a,
+                  size: size
+                }.compact
+              }
+            end
+          end
+
+          protected
+
+          attr_writer :sources # Used by the #clone method
+
+          # @return [JayAPI::Elasticsearch::QueryBuilder::Aggregations::Sources::Sources]
+          #   The collection of sources of the composite aggregation.
+          def sources
+            @sources ||= ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Sources::Sources.new
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'terms'
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class Aggregations
+        module Sources
+          # Represents the collection of sources for a Composite aggregation in
+          # Elasticsearch
+          class Sources
+            # Adds a +terms+ source to the collection.
+            # For information about the parameters:
+            # @see Sources::Terms#initialize
+            def terms(name, **kw_args)
+              sources.push(::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Sources::Terms.new(name, **kw_args))
+            end
+
+            # @return [Array<Hash>] Array representation of the collection of
+            #   sources of the composite aggregation.
+            def to_a
+              sources.map(&:to_h)
+            end
+
+            # @return [self] A copy of the receiver (not a shallow clone, it
+            #   clones all of the elements of the collection).
+            def clone
+              self.class.new.tap do |copy|
+                copy.sources.concat(sources.map(&:clone))
+              end
+            end
+
+            protected
+
+            # @return [Array<Object>] The array used to hold the collection of
+            #   sources.
+            def sources
+              @sources ||= []
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module JayAPI
+  module Elasticsearch
+    class QueryBuilder
+      class Aggregations
+        module Sources
+          # Represents a "Terms" value source for a Composite aggregation.
+          # More information about this type of value source can be found here:
+          # https://www.elastic.co/docs/reference/aggregations/search-aggregations-bucket-composite-aggregation#_terms
+          class Terms
+            attr_reader :name, :field, :order, :missing_bucket, :missing_order
+
+            # @param [String] name The name for the value source.
+            # @param [String] field The field for the value source.
+            # @param [String, nil] order The order in which the values coming
+            #   from this data source should be ordered, this can be either
+            #   "asc" or "desc"
+            # @param [Boolean] missing_bucket Whether or not a bucket for the
+            #   documents without a value in +field+ should be created.
+            # @param [String] missing_order Where to put the bucket for the
+            #   documents with a missing value, either "first" or "last".
+            def initialize(name, field:, order: nil, missing_bucket: nil, missing_order: nil)
+              @name = name
+              @field = field
+              @order = order
+              @missing_bucket = missing_bucket
+              @missing_order = missing_order
+            end
+
+            # @return [self] A copy of the receiver.
+            def clone
+              self.class.new(
+                name, field: field, order: order, missing_bucket: missing_bucket, missing_order: missing_order
+              )
+            end
+
+            # @return [Hash] The hash representation for the value source.
+            def to_h
+              {
+                name => {
+                  terms: {
+                    field: field,
+                    order: order,
+                    missing_bucket: missing_bucket,
+                    missing_order: missing_order
+                  }.compact
+                }
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,6 +5,7 @@ require 'forwardable'
 require_relative 'aggregations/aggregation'
 require_relative 'aggregations/avg'
 require_relative 'aggregations/cardinality'
+require_relative 'aggregations/composite'
 require_relative 'aggregations/date_histogram'
 require_relative 'aggregations/filter'
 require_relative 'aggregations/scripted_metric'
@@ -121,6 +122,16 @@ module JayAPI
           )
         end
 
+        # Adds a +composite+ aggregation. For more information about the parameters:
+        # @see JayAPI::Elasticsearch::QueryBuilder::Aggregations::Composite#initialize
+        def composite(name, size: nil, &block)
+          add(
+            ::JayAPI::Elasticsearch::QueryBuilder::Aggregations::Composite.new(
+              name, size: size, &block
+            )
+          )
+        end
+
         # Returns a Hash with the correct format for the current list of
         # aggregations. For example:
         #

data/lib/jay_api/elasticsearch/stats/errors/stats_data_not_available.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative '../../../errors/error'
+
+module JayAPI
+  module Elasticsearch
+    class Stats
+      module Errors
+        # An error to be raised when a particular Stats element is requested for
+        # which there is no data in the response received from the cluster.
+        class StatsDataNotAvailable < ::JayAPI::Errors::Error; end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/stats/node/storage.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module JayAPI
+  module Elasticsearch
+    class Stats
+      class Node
+        # Holds storage information related to one of the nodes in the
+        # Elasticsearch cluster.
+        class Storage
+          TOTAL_KEY = 'total_in_bytes'
+          FREE_KEY = 'free_in_bytes'
+          AVAILABLE_KEY = 'available_in_bytes'
+
+          # @param [Hash] data Data about the Node's storage.
+          def initialize(data)
+            @data = data
+          end
+
+          # @return [Integer] The total size of the storage (in bytes)
+          def total
+            @total ||= data[TOTAL_KEY]
+          end
+
+          # @return [Integer] The total number of bytes that are free on the
+          #   node.
+          def free
+            @free ||= data[FREE_KEY]
+          end
+
+          # @return [Integer] The total number of bytes that are available on
+          #   the node. In general this is equal to #free, but not always.
+          def available
+            @available ||= data[AVAILABLE_KEY]
+          end
+
+          # @return [self] A new instance of the class with the added storage of
+          #   the receiver and +other+.
+          def +(other)
+            raise ArgumentError, "Cannot add #{self.class} and #{other.class} together" unless other.is_a?(self.class)
+
+            self.class.new(
+              TOTAL_KEY => total + other.total,
+              FREE_KEY => free + other.free,
+              AVAILABLE_KEY => available + other.available
+            )
+          end
+
+          private
+
+          attr_reader :data
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'errors/stats_data_not_available'
+require_relative 'node/storage'
+
+module JayAPI
+  module Elasticsearch
+    class Stats
+      # Holds information about one of the nodes in the Elasticsearch cluster.
+      class Node
+        attr_reader :name
+
+        # @param [String] name The name of the node.
+        # @param [Hash] data Information about the node.
+        def initialize(name, data)
+          @name = name
+          @data = data
+        end
+
+        # @return [JayAPI::Elasticsearch::Stats::Node::Storage] Storage
+        #   information about the node.
+        # @raise [JayAPI::Elasticsearch::Stats::Errors::StatsDataNotAvailable]
+        #   If there is no storage information for the node.
+        def storage
+          @storage ||= ::JayAPI::Elasticsearch::Stats::Node::Storage.new(fs_totals)
+        end
+
+        private
+
+        attr_reader :data
+
+        # @return [Hash] Aggregated information about the +Node+'s
+        #   filesystem.
+        # @raise [JayAPI::Elasticsearch::Stats::Errors::StatsDataNotAvailable]
+        #   If there is no filesystem information for the node.
+        def fs_totals
+          @fs_totals ||= data.dig('fs', 'total') || raise(
+            ::JayAPI::Elasticsearch::Stats::Errors::StatsDataNotAvailable,
+            "Filesystem data not available for node #{name}"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require_relative 'node'
+
+module JayAPI
+  module Elasticsearch
+    class Stats
+      # Provides access to the list of nodes returned by Elasticsearch's Stats API
+      class Nodes
+        extend Forwardable
+
+        def_delegator :nodes, :size
+
+        # @param [Hash] nodes Information about the nodes in the Elasticsearch
+        #   cluster.
+        def initialize(nodes)
+          @nodes = nodes
+        end
+
+        # @return [Enumerator::Lazy<JayAPI::Elasticsearch::Stats::Node>] A lazy
+        #   enumerator of +Node+ objects, one for each of the nodes.
+        def all
+          @all ||= with_lazy_instantiation { nodes }
+        end
+
+        private
+
+        attr_reader :nodes
+
+        def build_node(args)
+          ::JayAPI::Elasticsearch::Stats::Node.new(*args)
+        end
+
+        # Calls the given block and turns its return value into a lazy
+        # enumerator that instantiates a +Node+ object for each of the
+        # elements of the collection returned by the block.
+        # @return [Enumerator::Lazy<JayAPI::Elasticsearch::Stats::Node>]
+        def with_lazy_instantiation(&block)
+          block.call.lazy.map(&method(:build_node))
+        end
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/stats.rb

@@ -2,6 +2,8 @@
 
 require_relative 'stats/index'
 require_relative 'stats/indices'
+require_relative 'stats/node'
+require_relative 'stats/nodes'
 
 module JayAPI
   module Elasticsearch
@@ -21,19 +23,37 @@ module JayAPI
       #   to the Statistics API endpoint fails.
       def indices
         # DO NOT MEMOIZE! Leave it to the caller.
-        ::JayAPI::Elasticsearch::Stats::Indices.new(response['indices'])
+        ::JayAPI::Elasticsearch::Stats::Indices.new(indices_stats['indices'])
+      end
+
+      # @return [JayAPI::Elasticsearch::Stats::Nodes] Information about the
+      #   nodes that make up the Elasticsearch cluster.
+      # @raise [Elasticsearch::Transport::Transport::ServerError] If the request
+      #   to the Statistics API endpoint fails.
+      def nodes
+        # DO NOT MEMOIZE! Leave it to the caller.
+        ::JayAPI::Elasticsearch::Stats::Nodes.new(nodes_stats['nodes'])
       end
 
       private
 
-      # @return [Hash] The Hash with the statistics returned by the
-      #   Elasticsearch cluster.
+      # @return [Hash] The Hash with the index-related statistics returned by
+      #   the Elasticsearch cluster.
       # @raise [Elasticsearch::Transport::Transport::ServerError] If the
       #   request fails.
-      def response
+      def indices_stats
         # DO NOT MEMOIZE! Leave it to the caller.
         transport_client.indices.stats
       end
+
+      # @return [Hash] The Hash with the node-related statistics returned by the
+      #   Elasticsearch cluster.
+      # @raise [Elasticsearch::Transport::Transport::ServerError] If the
+      #   request fails.
+      def nodes_stats
+        # DO NOT MEMOIZE! Leave it to the caller.
+        transport_client.nodes.stats
+      end
     end
   end
 end

data/lib/jay_api/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jay_api
 version: !ruby/object:Gem::Version
-  version: 28.1.0
+  version: 28.3.0
 platform: ruby
 authors:
 - Accenture-Industry X
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-19 00:00:00.000000000 Z
+date: 2025-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -140,12 +140,15 @@ files:
 - 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/cardinality.rb
+- lib/jay_api/elasticsearch/query_builder/aggregations/composite.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/date_histogram.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/errors.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/errors/aggregations_error.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/filter.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/max.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/scripted_metric.rb
+- lib/jay_api/elasticsearch/query_builder/aggregations/sources/sources.rb
+- lib/jay_api/elasticsearch/query_builder/aggregations/sources/terms.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/sum.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/terms.rb
 - lib/jay_api/elasticsearch/query_builder/aggregations/top_hits.rb
@@ -172,8 +175,12 @@ files:
 - lib/jay_api/elasticsearch/response.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
 - lib/jay_api/elasticsearch/stats/index.rb
 - lib/jay_api/elasticsearch/stats/indices.rb
+- lib/jay_api/elasticsearch/stats/node.rb
+- lib/jay_api/elasticsearch/stats/node/storage.rb
+- lib/jay_api/elasticsearch/stats/nodes.rb
 - lib/jay_api/elasticsearch/tasks.rb
 - lib/jay_api/elasticsearch/time.rb
 - lib/jay_api/errors/configuration_error.rb