esse 0.4.0.rc5 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb2a09b3e73966e0ae1f5e330f9f48604220ea9f8be3e764fd78637ec8e375f1
-  data.tar.gz: 7dd0dc43a3e2f0823ae4af63f64318f181fee7fd48ba477ca04feb3e48e2ba66
+  metadata.gz: 9fc6f63594da661b35bc22ab0c83655ded02b8ebe2e20ec5612a0927934156e9
+  data.tar.gz: c46f9a70e262d40a9c60c7ce72be3e3b816d18c536f6e3fe770bd06c06c5f57b
 SHA512:
-  metadata.gz: 16022150a582f772821c47760aae2edc07b8b3f9cc050ca616b0a2a2da3ca0d0e394769b041b6f17730d00fa01c38f8ae7cf3afbb7ab8f9370d94c3ef45ab57e
-  data.tar.gz: 440417523c35fc153e6b0e48cafee2fc8d332e0e37058852b8bc0abe74728eae3b76acd29274f950b14a35137fcb47cff3a1b233cad916639f2412f8b9dfba9f
+  metadata.gz: 8525a1ba74d9452163e87e1acf1bf621654f2bb8b9a7811e6eca94fc452c47f9255808b2c45be701112be085f8d3176243a685fcfb6647a8e9845699a727911d
+  data.tar.gz: 3d0be64e631a47c07758341b34fc86eedffd76bbd12c4734016d9303c256d9c8470929fc564bdace28bb21f072e44d0193cbee06e8e808675a695b46aac92c38

data/lib/esse/events/bus.rb

@@ -92,9 +92,14 @@ module Esse
 
       # @api private
       def process(event_id, payload)
+        # Build the event once and reuse for all listeners. Previously, a new
+        # Event was created per listener via Event#payload which does
+        # @payload.merge(data) — a full hash copy each time. With 24+
+        # esse-rails subscribers, each search was creating 24+ Event objects
+        # with 24+ hash merges of the full payload (including Response with
+        # the entire OpenSearch JSON). Now it's 1 Event + 1 merge total.
+        event = events[event_id].payload(payload)
         listeners[event_id].each do |listener|
-          event = events[event_id].payload(payload)
-
           yield(event, listener)
         end
       end

data/lib/esse/events/publisher.rb

@@ -60,6 +60,11 @@ module Esse
           if publish_event
             payload[:runtime] ||= Time.now - payload.delete(:__started_at__) if payload[:__started_at__]
             __bus__.publish(event_id, payload)
+            # Release references to large objects (Query, Response with full
+            # OpenSearch JSON) so they become GC-eligible immediately after
+            # event dispatch, rather than being held until the caller's stack
+            # frame unwinds.
+            payload.clear
           end
         end
 

data/lib/esse/events.rb

@@ -56,6 +56,7 @@ module Esse
     register_event 'elasticsearch.exist'
     register_event 'elasticsearch.count'
     register_event 'elasticsearch.get'
+    register_event 'elasticsearch.mget'
     register_event 'elasticsearch.reindex'
     register_event 'elasticsearch.update_by_query'
     register_event 'elasticsearch.delete_by_query'

data/lib/esse/index/documents.rb

@@ -29,6 +29,37 @@ module Esse
         cluster.api.get(**options)
       end
 
+      # Retrieves multiple JSON documents by ID from an index.
+      #
+      #   UsersIndex.mget(ids: [1, 2, 3])
+      #   UsersIndex.mget(ids: [Esse::HashDocument.new(id: 1), Esse::HashDocument.new(id: 2)])
+      #
+      # @param ids [Array<Esse::Document, Hash, String, Integer>] documents, hashes, or IDs to retrieve
+      # @param options [Hash] Hash of paramenters that will be passed along to elasticsearch request
+      # @option [String, nil] :suffix The index suffix. Defaults to the nil.
+      # @return [Hash] The elasticsearch response with 'docs' array
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/docs-multi-get.html
+      def mget(ids:, suffix: nil, **options)
+        options[:body] = {
+          docs: ids.map do |doc|
+            if document?(doc)
+              datum = { _id: doc.id }
+              datum[:_type] = doc.type if doc.type?
+              datum[:routing] = doc.routing if doc.routing?
+              datum
+            elsif doc.is_a?(Hash)
+              doc
+            else
+              { _id: doc }
+            end
+          end,
+        }
+        options[:index] = index_name(suffix: suffix)
+        cluster.may_update_type!(options)
+        cluster.api.mget(**options)
+      end
+
       # Check if a JSON document exists
       #
       #   UsersIndex.exist?(id: 1) # true

data/lib/esse/index/settings.rb

@@ -4,29 +4,21 @@ module Esse
   # https://github.com/elastic/elasticsearch-ruby/blob/master/elasticsearch-api/lib/elasticsearch/api/actions/indices/put_settings.rb
   class Index
     module ClassMethods
-      # Elasticsearch supports passing index.* related settings directly in the body of the request.
-      # We are moving it to the index key to make it more explicit and to be the source-of-truth when merging settings.
-      # So the settings `{ number_of_shards: 1 }` will be transformed to `{ index: { number_of_shards: 1 } }`
-      INDEX_SIMPLIFIED_SETTINGS = %i[
-        number_of_shards
-        number_of_replicas
-        refresh_interval
-        mapping
-      ].freeze
+      # Backwards-compatible alias. The canonical list now lives on
+      # +Esse::IndexSetting::INDEX_SIMPLIFIED_SETTINGS+ so that the merge
+      # logic and the simplified-key promotion stay in sync.
+      INDEX_SIMPLIFIED_SETTINGS = Esse::IndexSetting::INDEX_SIMPLIFIED_SETTINGS
 
       def settings_hash(settings: nil)
-        hash = setting.body
-        values = (hash.key?(Esse::SETTING_ROOT_KEY) ? hash[Esse::SETTING_ROOT_KEY] : hash)
-        values = HashUtils.explode_keys(values)
-        if settings.is_a?(Hash)
-          values = HashUtils.deep_merge(values, HashUtils.explode_keys(settings))
-        end
-        INDEX_SIMPLIFIED_SETTINGS.each do |key|
-          next unless values.key?(key)
-          value = values.delete(key)
-          next if value.nil?
+        # Normalize each side (global vs local) separately before merging so
+        # a flat global key (e.g. top-level :number_of_shards) cannot clobber
+        # an explicit nested local value (e.g. :index => { :number_of_shards => 8 }).
+        global = Esse::IndexSetting.normalize(setting.globals)
+        local = Esse::IndexSetting.normalize(setting.to_h)
+        values = HashUtils.deep_merge(global, local)
 
-          (values[:index] ||= {}).merge!(key => value)
+        if settings.is_a?(Hash)
+          values = HashUtils.deep_merge(values, Esse::IndexSetting.normalize(settings))
         end
 
         if values[:index].is_a?(Hash)

data/lib/esse/index_setting.rb

@@ -3,6 +3,17 @@
 module Esse
   # https://www.elastic.co/guide/en/elasticsearch/reference/1.7/indices.html
   class IndexSetting
+    # Top-level keys that Elasticsearch/OpenSearch accept either flat or nested
+    # under `index:`. We always promote them to the nested form so that values
+    # from different sources (cluster globals vs per-index template) merge
+    # predictably regardless of which form each side was authored in.
+    INDEX_SIMPLIFIED_SETTINGS = %i[
+      number_of_shards
+      number_of_replicas
+      refresh_interval
+      mapping
+    ].freeze
+
     # @param [Hash] options
     # @option options [Proc] :globals  A proc that will be called to load global settings
     # @option options [Array] :paths   A list of paths to load settings from
@@ -35,6 +46,38 @@ module Esse
       HashUtils.deep_merge(global, local)
     end
 
+    # Returns the raw (unsymbolized) global settings as supplied by the
+    # +globals+ proc. Public so that callers like
+    # +Esse::Index.settings_hash+ can normalize it independently before
+    # merging it with the local template — preventing a flat global value
+    # from clobbering a nested local value once both are merged.
+    def globals
+      @globals.call || {}
+    end
+
+    # Normalize a settings hash by:
+    #   * symbolizing keys
+    #   * stripping the `:settings` root if present
+    #   * exploding dotted keys ('index.number_of_replicas' -> { index: { number_of_replicas: ... } })
+    #   * promoting simplified flat keys (number_of_shards, etc.) into the
+    #     nested `:index` form, preserving any value already present under
+    #     `:index` (we never overwrite an explicit nested setting with a
+    #     flat value from the same source).
+    def self.normalize(hash)
+      values = HashUtils.deep_transform_keys(hash || {}, &:to_sym)
+      values = values[Esse::SETTING_ROOT_KEY] if values.key?(Esse::SETTING_ROOT_KEY)
+      values = HashUtils.explode_keys(values)
+      INDEX_SIMPLIFIED_SETTINGS.each do |key|
+        next unless values.key?(key)
+        value = values.delete(key)
+        next if value.nil?
+
+        values[:index] ||= {}
+        values[:index][key] = value unless values[:index].key?(key)
+      end
+      values
+    end
+
     protected
 
     def from_template

data/lib/esse/search/query.rb

@@ -40,7 +40,7 @@ module Esse
 
       def scroll_hits(batch_size: 1_000, scroll: '1m')
         response = execute_search_query!(size: batch_size, scroll: scroll)
-        scroll_id = nil
+        scroll_id = response.raw_response['scroll_id'] || response.raw_response['_scroll_id']
         fetched = 0
         total = response.total
 
@@ -48,9 +48,9 @@ module Esse
           fetched += response.hits.size
           yield(response.hits) if response.hits.any?
           break if fetched >= total
-          scroll_id = response.raw_response['scroll_id'] || response.raw_response['_scroll_id']
           break unless scroll_id
           response = execute_scroll_query(scroll: scroll, scroll_id: scroll_id)
+          scroll_id = response.raw_response['scroll_id'] || response.raw_response['_scroll_id']
         end
       ensure
         begin
@@ -59,12 +59,40 @@ module Esse
         end
       end
 
+      def search_after_hits(batch_size: 1_000)
+        body = HashUtils.deep_dup(definition.fetch(:body, {}))
+        body[:size] = batch_size
+        body.delete(:from)
+        body.delete('from')
+
+        unless body.key?(:sort) || body.key?('sort')
+          raise ArgumentError, 'The query body must include a :sort to use search_after'
+        end
+
+        loop do
+          response = execute_search_query!(body: body)
+          break if response.hits.empty?
+
+          yield(response.hits)
+
+          last_sort = response.hits.last['sort']
+          break unless last_sort
+          break if response.hits.size < batch_size
+
+          body[:search_after] = last_sort
+        end
+      end
+
+      def reset!
+        @response = nil
+      end
+
       private
 
       def execute_search_query!(**execution_options)
         resp, err = nil
         Esse::Events.instrument('elasticsearch.execute_search_query') do |payload|
-          payload[:query] = self
+          payload[:query_definition] = definition
           begin
             resp = Response.new(self, transport.search(**definition, **execution_options))
           rescue => e
@@ -81,7 +109,7 @@ module Esse
       def execute_scroll_query(scroll:, scroll_id:)
         resp, err = nil
         Esse::Events.instrument('elasticsearch.execute_search_query') do |payload|
-          payload[:query] = self
+          payload[:query_definition] = definition
           begin
             resp = Response.new(self, transport.scroll(scroll: scroll, body: { scroll_id: scroll_id }))
           rescue => e
@@ -94,10 +122,6 @@ module Esse
 
         resp
       end
-
-      def reset!
-        @response = nil
-      end
     end
   end
 end

data/lib/esse/search/response.rb

@@ -7,13 +7,13 @@ module Esse
       extend Forwardable
 
       def_delegators :hits, :each, :size, :empty?
-      attr_reader :query, :raw_response, :options
+      attr_reader :query_definition, :raw_response, :options
 
-      # @param [Esse::Search::Query] query The search query
+      # @param [Esse::Search::Query, Hash] query The search query or its definition hash
       # @param [Hash] raw_response The raw response from Elasticsearch
       # @param [Hash] options The options passed to the search
       def initialize(query, raw_response, **options)
-        @query = query
+        @query_definition = query.is_a?(Hash) ? query : query.definition
         @raw_response = raw_response
         @options = options
       end

data/lib/esse/transport/documents.rb

@@ -29,6 +29,30 @@ module Esse
         end
       end
 
+      # Allows to get multiple documents in a single request.
+      #
+      # @option [String] :index The name of the index
+      # @option [Hash] :body Document identifiers; can be either `docs` (specifying full document information)
+      #   or `ids` (when index is provided). (*Required*)
+      # @option [String] :preference Specify the node or shard the operation should be performed on (default: random)
+      # @option [Boolean] :realtime Specify whether to perform the operation in realtime or search mode
+      # @option [Boolean] :refresh Refresh the shard containing the document before performing the operation
+      # @option [String] :routing Specific routing value
+      # @option [List] :stored_fields A comma-separated list of stored fields to return in the response
+      # @option [List] :_source True or false to return the _source field or not, or a list of fields to return
+      # @option [List] :_source_excludes A list of fields to exclude from the returned _source field
+      # @option [List] :_source_includes A list of fields to extract and return from the _source field
+      # @option [Hash] :headers Custom HTTP headers
+      #
+      # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-get.html
+      #
+      def mget(index:, body:, **options)
+        Esse::Events.instrument('elasticsearch.mget') do |payload|
+          payload[:request] = opts = options.merge(index: index, body: body)
+          payload[:response] = coerce_exception { client.mget(**opts) }
+        end
+      end
+
       # Returns information about whether a document exists in an index.
       #
       # @option [String] :id The document ID

data/lib/esse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Esse
-  VERSION = '0.4.0.rc5'
+  VERSION = '0.4.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: esse
 version: !ruby/object:Gem::Version
-  version: 0.4.0.rc5
+  version: 0.4.1
 platform: ruby
 authors:
 - Marcos G. Zimmermann
 autorequire:
 bindir: exec
 cert_chain: []
-date: 2025-08-04 00:00:00.000000000 Z
+date: 2026-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -319,14 +319,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Pure Ruby and framework-agnostic ElasticSearch/OpenSearch toolkit for building