jay_api 28.2.0 → 28.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60468cdd7dbfd248e2ca373126f6d3f3a0e9c0d23d169a7e9d98aebe9de3d91d
-  data.tar.gz: 58ad9adc3a1f77139660338f213a9c835d935fc7a968f5971fe900904c1ba649
+  metadata.gz: c1af59670e04b1508c6773538b8d9d0478f1971e80755ea526012eaa44f4717c
+  data.tar.gz: d23445b944fd8ef0cea8fd628536132fe2cd024ec315b286223b08ecb2c57452
 SHA512:
-  metadata.gz: 9a4c5a8ee131631eb7220b2c2cbf5eb4d9a081b3a0d817647c09d4027311629b78262b35707d8288418da5395d5bebdea11855d9a7f81b81f3d2566cc6156852
-  data.tar.gz: f596eeb92e9cecc97ffd2dccb9e93a2dfcf82524bd9bbed43b86ff2d3e60b011e6d9239923b2a4030ea1f0ab67c644028c3178c483de40455c2058c311e38e88
+  metadata.gz: f6805dc6330cdb960f50af2321112572f9959da7789e02c2810231df24b7a5176686754bb488234e4f64659dbdbdc078985564e5987780cd66e93aaca0e5d0e4
+  data.tar.gz: ad80fac10a256c1ff8061cc6822fe9d89763e86f9e710cf0b9e7a8f103f864d4dfd24051c90727fb7fc664a0251503a97515beb1d2cd890b3a4cd43a50066490

data/CHANGELOG.md

@@ -8,6 +8,18 @@ Please mark backwards incompatible changes with an exclamation mark at the start
 
 ## [Unreleased]
 
+## [28.4.0] - 2025-08-26
+
+### Added
+- The `Elasticsearch::Indexes` class. A class which allows multiple indexes to
+  be used (fed or queried) at the same time.
+
+## [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

data/lib/jay_api/elasticsearch/async.rb

@@ -19,8 +19,8 @@ module JayAPI
 
       def_delegators :index, :index_name
 
-      # @param [JayAPI::Elasticsearch::Index] index The elasticsearch index on
-      #   which to execute asynchronous operations
+      # @param [JayAPI::Elasticsearch::Indexable] index The elasticsearch
+      #   index or indexes on which to execute asynchronous operations
       def initialize(index)
         @index = index
       end

data/lib/jay_api/elasticsearch/index.rb

@@ -1,57 +1,28 @@
 # frozen_string_literal: true
 
-require 'active_support'
-require 'active_support/json' # Needed because ActiveSupport 6 doesn't include it's own JSON module. 🤦
-require 'active_support/core_ext/hash/indifferent_access'
-require 'active_support/core_ext/hash/keys'
-require 'elasticsearch'
-require 'logging'
-
-require_relative 'errors/elasticsearch_error'
-require_relative 'async'
-require_relative 'query_results'
-require_relative 'response'
-require_relative 'batch_counter'
-require_relative 'search_after_results'
+require_relative 'indexable'
 
 module JayAPI
   module Elasticsearch
     # Represents an Elasticsearch index. Allows data to be pushed to it one
     # record at a time or in batches of the specified size.
     class Index
-      attr_reader :client, :index_name, :batch_size
-
-      # Default type for documents indexed with the #index method.
-      DEFAULT_DOC_TYPE = 'nested'
+      include ::JayAPI::Elasticsearch::Indexable
 
-      # Supported document types (for the #index method)
-      SUPPORTED_TYPES = [DEFAULT_DOC_TYPE, nil].freeze
-
-      # :reek:ControlParameter (want to avoid the creating of the logger on method definition)
-      # Creates a new instance of the class.
       # @param [JayAPI::Elasticsearch::Client] client The Elasticsearch Client object.
       # @param [String] index_name The name of the Elasticsearch index.
-      # @param [Integer] batch_size The size of the batch. When this number of
-      #   items are pushed into the index they are flushed to the
-      #   Elasticsearch instance.
+      # @param [Integer] batch_size The size of the batch. When this many items
+      #   are pushed into the index they are flushed to the Elasticsearch
+      #   instance.
       # @param [Logging::Logger, nil] logger The logger object to use, if
       #   none is given a new one will be created.
       def initialize(client:, index_name:, batch_size: 100, logger: nil)
-        @logger = logger || Logging.logger[self]
-
-        @client = client
-        @index_name = index_name
-        @batch_size = batch_size
-
-        @batch = []
+        super(client: client, index_names: [index_name], batch_size: batch_size, logger: logger)
       end
 
-      # 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)
-        @batch << { index: { _index: index_name, _type: 'nested', data: data } }
-        flush! if @batch.size >= batch_size
+      # @return [String] The name of the Elasticsearch index.
+      def index_name
+        @index_name ||= index_names.first
       end
 
       # Sends a record to the Elasticsearch instance right away.
@@ -59,8 +30,8 @@ module JayAPI
       # @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+.
-      # @return [Hash] A hash with information about the created document. An
-      #   example of such Hash is:
+      # @return [Hash] A Hash containing information about the created document.
+      #   An example of such Hash is:
       #
       #  {
       #    "_index" => "xyz01_unit_test",
@@ -76,147 +47,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)
-
-        client.index index: index_name, type: type, body: data
-      end
-
-      # Performs a query on the index.
-      # For more information on how to build the query please refer to the
-      # Elasticsearch DSL query:
-      # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
-      # @param [Hash] query The query to perform.
-      # @param [JayAPI::Elasticsearch::BatchCounter, nil] batch_counter Object keeping track of batches.
-      # @param [Symbol, nil] type Type of query, at the moment either nil or :search_after.
-      # @return [JayAPI::Elasticsearch::QueryResults] The query results.
-      # @raise [Elasticsearch::Transport::Transport::ServerError] If the
-      #   query fails.
-      def search(query, batch_counter: nil, type: nil)
-        begin
-          response = Response.new(client.search(index: index_name, body: query))
-        rescue ::Elasticsearch::Transport::Transport::Errors::BadRequest
-          logger.error "The 'search' query is invalid: #{JSON.pretty_generate(query)}"
-          raise
-        end
-        query_results(query, response, batch_counter, type)
-      end
-
-      # Sends whatever is currently in the send queue to the Elasticsearch
-      # instance and clears the queue.
-      def flush
-        return unless @batch.any?
-
-        flush!
-      end
-
-      # Returns the number of elements currently on the send queue.
-      # @return [Integer] The number of items in the send queue.
-      def queue_size
-        @batch.size
-      end
-
-      # Delete the documents matching the given query from the Index.
-      # For more information on how to build the query please refer to the
-      # Elasticsearch DSL documentation:
-      # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
-      # https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html
-      # @param [Hash] query The delete query
-      # @param [Integer] slices Number of slices to cut the operation into for
-      #   faster processing (i.e., run the operation in parallel)
-      # @param [Boolean] wait_for_completion False if Elasticsearch should not
-      #   wait for completion and perform the request asynchronously, true if it
-      #   should wait for completion (i.e., run the operation asynchronously)
-      # @return [Hash] A Hash that details the results of the operation
-      # @example Returned Hash (with `wait_for_completion: true`):
-      #     {
-      #       took: 103,
-      #       timed_out: false,
-      #       total: 76,
-      #       deleted: 76,
-      #       batches: 1,
-      #       version_conflicts: 0,
-      #       noops: 0,
-      #       retries: { bulk: 0, search: 0 },
-      #       throttled_millis: 0,
-      #       requests_per_second: 1.0,
-      #       throttled_until_millis: 0,
-      #       failures: []
-      #     }
-      # @example Returned Hash (with `wait_for_completion: false`):
-      #     {
-      #       task: "B5oDyEsHQu2Q-wpbaMSMTg:577388264"
-      #     }
-      # @raise [Elasticsearch::Transport::Transport::ServerError] If the
-      #   query fails.
-      def delete_by_query(query, slices: nil, wait_for_completion: true)
-        request_params = { index: index_name, body: query }.tap do |params|
-          params.merge!(slices: slices) if slices
-          params.merge!(wait_for_completion: false) unless wait_for_completion
-        end
-
-        client.delete_by_query(**request_params).deep_symbolize_keys
-      end
-
-      # Deletes asynchronously the documents matching the given query from the
-      # Index.
-      # For more information on how to build the query please refer to the
-      # Elasticsearch DSL documentation:
-      # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
-      # https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html
-      # @param [Hash] query The delete query
-      # @param [Integer, String] slices Number of slices to cut the operation
-      #   into for faster processing (i.e., run the operation in parallel). Use
-      #   "auto" to make elasticsearch decide how many slices to divide into
-      # @return [Concurrent::Promise] The eventual value returned from the single
-      #   completion of the delete operation
-      def delete_by_query_async(query, slices: nil)
-        async.delete_by_query(query, slices: slices)
-      end
-
-      private
-
-      attr_reader :logger, :batch
-
-      # Flushes the current send queue to the Elasticsearch instance and
-      # clears the queue.
-      def flush!
-        logger.info "Pushing data to Elasticsearch (#{batch.size} records)..."
-        response = client.bulk body: batch
-
-        handle_errors(response) if response['errors']
-
-        logger.info 'Done'
-        @batch = []
-      end
-
-      # @param [Hash] query The elastic search query.
-      # @param [JayAPI::Elasticsearch::Response] response The response to the query.
-      # @param [JayAPI::Elasticsearch::BatchCounter, nil] batch_counter Object keeping track of batches.
-      # @param [Symbol, nil] type Type of query, at the moment either nil or :search_after.
-      # @return [QueryResults]
-      def query_results(query, response, batch_counter, type)
-        (type == :search_after ? SearchAfterResults : QueryResults).new(
-          index: self,
-          query: query,
-          response: response,
-          batch_counter: BatchCounter.create_or_update(batch_counter, query, response.size)
-        )
-      end
-
-      # Scans the Elasticsearch response in search for the first item that has
-      # en erroneous state and raises an error including the error details.
-      # @param [Hash] response The response returned by the Elasticsearch client.
-      # @raise [Errors::ElasticsearchError] Is always raised.
-      def handle_errors(response)
-        error_item = response['items'].find { |item| item['index']['error'] }
-
-        raise Errors::ElasticsearchError,
-              "An error occurred when pushing the data to Elasticsearch:\n#{error_item['index']['error'].inspect}"
-      end
-
-      # @return [JayAPI::Elasticsearch::Async]
-      def async
-        @async ||= JayAPI::Elasticsearch::Async.new(self)
+        super.first
       end
     end
   end

data/lib/jay_api/elasticsearch/indexable.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/json' # Needed because ActiveSupport 6 doesn't include it's own JSON module. 🤦
+require 'active_support/core_ext/hash/keys'
+require 'elasticsearch'
+require 'logging'
+
+require_relative 'async'
+require_relative 'batch_counter'
+require_relative 'errors/elasticsearch_error'
+require_relative 'query_results'
+require_relative 'response'
+require_relative 'search_after_results'
+
+module JayAPI
+  module Elasticsearch
+    # This module houses the Elasticsearch methods that can be used with a
+    # single or with multiple indexes. Its main purpose is to avoid code
+    # repetition between classes.
+    module Indexable
+      # Default type for documents indexed with the #index method.
+      DEFAULT_DOC_TYPE = 'nested'
+
+      # Supported document types (for the #index method)
+      SUPPORTED_TYPES = [DEFAULT_DOC_TYPE, nil].freeze
+
+      attr_reader :client, :batch_size
+
+      # :reek:ControlParameter (want to avoid the creating of the logger on method definition)
+      # @param [JayAPI::Elasticsearch::Client] client The Elasticsearch Client object.
+      # @param [Array<String>] index_names The names of the Elasticsearch indexes.
+      # @param [Integer] batch_size The size of the batch. When this many items
+      #   are pushed into the index they are flushed to the Elasticsearch
+      #   instance.
+      # @param [Logging::Logger, nil] logger The logger object to use, if
+      #   none is given a new one will be created.
+      def initialize(client:, index_names:, batch_size: 100, logger: nil)
+        @logger = logger || Logging.logger[self]
+
+        @client = client
+        @index_names = index_names
+        @batch_size = batch_size
+
+        @batch = []
+      end
+
+      # 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)
+        index_names.each do |index_name|
+          batch << { index: { _index: index_name, _type: 'nested', data: data } }
+        end
+
+        flush! if batch.size >= batch_size
+      end
+
+      # Sends a record to the Elasticsearch instance right away.
+      # @param [Hash] data The data to be sent.
+      # @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+.
+      # @return [Array<Hash>] An array with hashes containing information about
+      #   the created documents. An example of such Hashes is:
+      #
+      #  {
+      #    "_index" => "xyz01_unit_test",
+      #    "_type" => "nested",
+      #    "_id" => "SVY1mJEBQ5CNFZM8Lodt",
+      #    "_version" => 1,
+      #    "result" => "created",
+      #    "_shards" => { "total" => 2, "successful" => 1, "failed" => 0 },
+      #    "_seq_no" => 0,
+      #    "_primary_term" => 1
+      #  }
+      #
+      # 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)
+
+        index_names.map { |index_name| client.index index: index_name, type: type, body: data }
+      end
+
+      # Performs a query on the index.
+      # For more information on how to build the query please refer to the
+      # Elasticsearch DSL query:
+      # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
+      # @param [Hash] query The query to perform.
+      # @param [JayAPI::Elasticsearch::BatchCounter, nil] batch_counter Object keeping track of batches.
+      # @param [Symbol, nil] type Type of query, at the moment either nil or :search_after.
+      # @return [JayAPI::Elasticsearch::QueryResults] The query results.
+      # @raise [Elasticsearch::Transport::Transport::ServerError] If the
+      #   query fails.
+      def search(query, batch_counter: nil, type: nil)
+        begin
+          response = Response.new(client.search(index: index_names, body: query))
+        rescue ::Elasticsearch::Transport::Transport::Errors::BadRequest
+          logger.error "The 'search' query is invalid: #{JSON.pretty_generate(query)}"
+          raise
+        end
+        query_results(query, response, batch_counter, type)
+      end
+
+      # Sends whatever is currently in the send queue to the Elasticsearch
+      # instance and clears the queue.
+      def flush
+        return unless @batch.any?
+
+        flush!
+      end
+
+      # Returns the number of elements currently on the send queue.
+      # @return [Integer] The number of items in the send queue.
+      def queue_size
+        batch.size
+      end
+
+      # Delete the documents matching the given query from the Index.
+      # For more information on how to build the query please refer to the
+      # Elasticsearch DSL documentation:
+      # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
+      # https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html
+      # @param [Hash] query The delete query
+      # @param [Integer] slices Number of slices to cut the operation into for
+      #   faster processing (i.e., run the operation in parallel)
+      # @param [Boolean] wait_for_completion False if Elasticsearch should not
+      #   wait for completion and perform the request asynchronously, true if it
+      #   should wait for completion (i.e., run the operation synchronously)
+      # @return [Hash] A Hash that details the results of the operation
+      # @example Returned Hash (with `wait_for_completion: true`):
+      #     {
+      #       took: 103,
+      #       timed_out: false,
+      #       total: 76,
+      #       deleted: 76,
+      #       batches: 1,
+      #       version_conflicts: 0,
+      #       noops: 0,
+      #       retries: { bulk: 0, search: 0 },
+      #       throttled_millis: 0,
+      #       requests_per_second: 1.0,
+      #       throttled_until_millis: 0,
+      #       failures: []
+      #     }
+      # @example Returned Hash (with `wait_for_completion: false`):
+      #     {
+      #       task: "B5oDyEsHQu2Q-wpbaMSMTg:577388264"
+      #     }
+      # @raise [Elasticsearch::Transport::Transport::ServerError] If the
+      #   query fails.
+      def delete_by_query(query, slices: nil, wait_for_completion: true)
+        request_params = { index: index_names, body: query }.tap do |params|
+          params.merge!(slices: slices) if slices
+          params.merge!(wait_for_completion: false) unless wait_for_completion
+        end
+
+        client.delete_by_query(**request_params).deep_symbolize_keys
+      end
+
+      # Deletes asynchronously the documents matching the given query from the
+      # Index.
+      # For more information on how to build the query please refer to the
+      # Elasticsearch DSL documentation:
+      # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
+      # https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html
+      # @param [Hash] query The delete query
+      # @param [Integer, String] slices Number of slices to cut the operation
+      #   into for faster processing (i.e., run the operation in parallel). Use
+      #   "auto" to make Elasticsearch decide how many slices to divide into
+      # @return [Concurrent::Promise] The eventual value returned from the single
+      #   completion of the delete operation
+      def delete_by_query_async(query, slices: nil)
+        async.delete_by_query(query, slices: slices)
+      end
+
+      private
+
+      attr_reader :index_names, :logger, :batch
+
+      # Scans the Elasticsearch response in search for the first item that has
+      # an erroneous state and raises an error including the error details.
+      # @param [Hash] response The response returned by the Elasticsearch client.
+      # @raise [Errors::ElasticsearchError] Is always raised.
+      def handle_errors(response)
+        error_item = response['items'].find { |item| item['index']['error'] }
+
+        raise Errors::ElasticsearchError,
+              "An error occurred when pushing the data to Elasticsearch:\n#{error_item['index']['error'].inspect}"
+      end
+
+      # Flushes the current send queue to the Elasticsearch instance and
+      # clears the queue.
+      def flush!
+        logger.info "Pushing data to Elasticsearch (#{batch.size} records)..."
+        response = client.bulk body: batch
+
+        handle_errors(response) if response['errors']
+
+        logger.info 'Done'
+        @batch = []
+      end
+
+      # @param [Hash] query The elastic search query.
+      # @param [JayAPI::Elasticsearch::Response] response The response to the query.
+      # @param [JayAPI::Elasticsearch::BatchCounter, nil] batch_counter Object keeping track of batches.
+      # @param [Symbol, nil] type Type of query, at the moment either nil or :search_after.
+      # @return [QueryResults]
+      def query_results(query, response, batch_counter, type)
+        (type == :search_after ? SearchAfterResults : QueryResults).new(
+          index: self,
+          query: query,
+          response: response,
+          batch_counter: BatchCounter.create_or_update(batch_counter, query, response.size)
+        )
+      end
+
+      # @return [JayAPI::Elasticsearch::Async]
+      def async
+        @async ||= JayAPI::Elasticsearch::Async.new(self)
+      end
+    end
+  end
+end

data/lib/jay_api/elasticsearch/indexes.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'indexable'
+
+module JayAPI
+  module Elasticsearch
+    # Represents a group of Elasticsearch indexes. Allows the execution of
+    # searches over all of the specified indexes or push data to all of them
+    # at the same time.
+    class Indexes
+      include ::JayAPI::Elasticsearch::Indexable
+
+      # @param [JayAPI::Elasticsearch::Client] client The Elasticsearch Client object.
+      # @param [Array<String>] index_names The names of the Elasticsearch indexes.
+      # @param [Integer] batch_size The size of the batch. When this many items
+      #   are pushed into the indexes they are flushed to the Elasticsearch
+      #   instance.
+      # @param [Logging::Logger, nil] logger The logger object to use, if
+      #   none is given a new one will be created.
+      def initialize(client:, index_names:, batch_size: 100, logger: nil)
+        super
+
+        return if (batch_size % index_names.size).zero?
+
+        self.logger.warn(
+          "'batch_size' is not a multiple of the number of elements in 'index_names'. " \
+          "This can lead to a _bulk size slightly bigger than 'batch_size'"
+        )
+      end
+
+      attr_reader :index_names
+    end
+  end
+end

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

@@ -21,8 +21,8 @@ module JayAPI
       def_delegators :response, :hits, :total, :size, :count, :first, :last, :any?, :empty?, :aggregations
 
       # Creates a new instance of the class.
-      # @param [JayAPI::Elasticsearch::Index] index The Elasticsearch
-      #   index used to perform the query.
+      # @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::BatchCounter] batch_counter An object keeping track of the current batch.

data/lib/jay_api/elasticsearch.rb

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

data/lib/jay_api/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jay_api
 version: !ruby/object:Gem::Version
-  version: 28.2.0
+  version: 28.4.0
 platform: ruby
 authors:
 - Accenture-Industry X
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-30 00:00:00.000000000 Z
+date: 2025-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -135,17 +135,22 @@ files:
 - lib/jay_api/elasticsearch/errors/query_execution_timeout.rb
 - lib/jay_api/elasticsearch/errors/search_after_error.rb
 - lib/jay_api/elasticsearch/index.rb
+- lib/jay_api/elasticsearch/indexable.rb
+- lib/jay_api/elasticsearch/indexes.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/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