jay_api 28.3.0 → 28.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07ffb602dd7c52159b2142a00f06401d0326ae8e82e05ba24c61f96d35347d8c
-  data.tar.gz: 7f0f39ca31de378467d2914e3322fd83f6fad7a0b2185a30c94582d213d04439
+  metadata.gz: c1af59670e04b1508c6773538b8d9d0478f1971e80755ea526012eaa44f4717c
+  data.tar.gz: d23445b944fd8ef0cea8fd628536132fe2cd024ec315b286223b08ecb2c57452
 SHA512:
-  metadata.gz: 8bc9fc4c9631aac5a504600ccabd68ff875e7027682f83b47830608a6578cc7a73702333be180b4dd9c7b5d9d637c32b1ef6d86a6519ba5ef8a40706b0a5d397
-  data.tar.gz: 290b96e8925ee9bbff77e469bdd8299291317639dfd37ea345e1fb88e608c45b1d799015dd6d94592a300e24a97d1aab34df7de4a3ebb8c7ef014b4a09b2e2ed
+  metadata.gz: f6805dc6330cdb960f50af2321112572f9959da7789e02c2810231df24b7a5176686754bb488234e4f64659dbdbdc078985564e5987780cd66e93aaca0e5d0e4
+  data.tar.gz: ad80fac10a256c1ff8061cc6822fe9d89763e86f9e710cf0b9e7a8f103f864d4dfd24051c90727fb7fc664a0251503a97515beb1d2cd890b3a4cd43a50066490

data/CHANGELOG.md

@@ -8,6 +8,12 @@ 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

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_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.3.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.3.0
+  version: 28.4.0
 platform: ruby
 authors:
 - Accenture-Industry X
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-05 00:00:00.000000000 Z
+date: 2025-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -135,6 +135,8 @@ 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