esse 0.4.0.rc3 → 0.4.0.rc5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dd8f8e268f5c33ed55b160ca803a3d3b4d3c4e7a806b93941b53281325291fb
-  data.tar.gz: 4b9437a67ff80a09b3951174c60e4658b987f08633dd2ca124fde50cb2cca0b4
+  metadata.gz: fb2a09b3e73966e0ae1f5e330f9f48604220ea9f8be3e764fd78637ec8e375f1
+  data.tar.gz: 7dd0dc43a3e2f0823ae4af63f64318f181fee7fd48ba477ca04feb3e48e2ba66
 SHA512:
-  metadata.gz: c35caa2948ee2c511e4f0171bfd23b92a3ccf6812bcbc4c1f7b007d8e3c42912aa483b1a9baa00b75a54f66de6ad92de1087c4b87d174eab9364931d7a22c3c9
-  data.tar.gz: 3944a4f0ab6e2b73fe9f52a6dff26b64d1d1ed927f40f7b1eaf42f7b27898b7232c79068cefd9395433838fe8697151b02ccb1166d4d8f4eef186a36729a5881
+  metadata.gz: 16022150a582f772821c47760aae2edc07b8b3f9cc050ca616b0a2a2da3ca0d0e394769b041b6f17730d00fa01c38f8ae7cf3afbb7ab8f9370d94c3ef45ab57e
+  data.tar.gz: 440417523c35fc153e6b0e48cafee2fc8d332e0e37058852b8bc0abe74728eae3b76acd29274f950b14a35137fcb47cff3a1b233cad916639f2412f8b9dfba9f

data/lib/esse/cli/event_listener.rb

@@ -102,6 +102,32 @@ module Esse
           to: colorize(event[:request].dig(:body, :dest, :index), :bold),
           runtime: formatted_runtime(event[:runtime])
       end
+
+      def elasticsearch_task(event)
+        running_time_in_nanos = event[:response].dig('task', 'running_time_in_nanos')
+        runtime = running_time_in_nanos ? "#{running_time_in_nanos / 1_000_000} ms" : 'unknown'
+
+        case event[:response]['completed']
+        when true
+          print_message '[%<runtime>s] Task %<task_id>s successfuly completed. %<total_runtime>s',
+            task_id: colorize(event[:request][:id], :bold),
+            runtime: formatted_runtime(event[:runtime]),
+            total_runtime: colorize("Elapsed time: #{runtime}", :bold)
+        when false
+          description = event[:response].dig('task', 'description')
+          print_message '[%<runtime>s] Task %<task_id>s still in progress: %<description>s. %<total_runtime>s',
+            task_id: colorize(event[:request][:id], :bold),
+            description: description,
+            runtime: formatted_runtime(event[:runtime]),
+            total_runtime: colorize("Elapsed time: #{runtime}", :bold)
+        end
+      end
+
+      def elasticsearch_cancel_task(event)
+        print_message '[%<runtime>s] Task %<task_id>s successfuly canceled',
+          task_id: colorize(event[:request][:id], :bold),
+          runtime: formatted_runtime(event[:runtime])
+      end
     end
   end
 end

data/lib/esse/cli/index/update_lazy_attributes.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'base_operation'
+
+module Esse
+  module CLI
+    class Index::UpdateLazyAttributes < Index::BaseOperation
+      attr_reader :attributes
+
+      def initialize(indices:, attributes: nil, **options)
+        super(indices: indices, **options)
+        @attributes = Array(attributes)
+      end
+
+      def run
+        validate_options!
+        indices.each do |index|
+          repos = if (repo = @options[:repo])
+            [index.repo(repo)]
+          else
+            index.repo_hash.values
+          end
+
+          repos.each do |repo|
+            attrs = repo_attributes(repo)
+            next unless attrs.any?
+
+            repo.send(:each_batch_ids, **context_options) do |ids|
+              attrs.each do |attribute|
+                repo.update_documents_attribute(attribute, ids, bulk_options)
+              end
+            end
+          end
+        end
+      end
+
+      private
+
+      def bulk_options
+        @bulk_options ||= (@options[:bulk_options] || {}).transform_values do |value|
+          value.is_a?(String) ? Hstring.new(value).coerce_type : value
+        end
+      end
+
+      def context_options
+        @context_options ||= (@options[:context] || {}).transform_values do |value|
+          value.is_a?(String) ? Hstring.new(value).coerce_type : value
+        end
+      end
+
+      def validate_options!
+        validate_indices_option!
+      end
+
+      def repo_attributes(repo)
+        return repo.lazy_document_attribute_names(true) if attributes.empty?
+
+        repo.lazy_document_attribute_names(attributes)
+      end
+    end
+  end
+end

data/lib/esse/cli/index.rb

@@ -19,6 +19,10 @@ module Esse
       option :reindex, desc: 'Use _reindex API to import documents from the old index to the new index'
       option :optimize, type: :boolean, default: true, desc: 'Optimize index before import documents by disabling refresh_interval and setting number_of_replicas to 0'
       option :settings, type: :hash, default: nil, desc: 'List of settings to pass to the index class. Example: --settings=refresh_interval:1s,number_of_replicas:0'
+
+      option :preload_lazy_attributes, type: :string, default: nil, desc: 'Command separated list of lazy document attributes to preload using search API before the bulk import. Or pass `true` to preload all lazy attributes'
+      option :eager_load_lazy_attributes, type: :string, default: nil, desc: 'Comma separated list of lazy document attributes to include to the bulk index request. Or pass `true` to include all lazy attributes'
+      option :update_lazy_attributes, type: :string, default: nil, desc: 'Comma separated list of lazy document attributes to bulk update after the bulk index request Or pass `true` to include all lazy attributes'
       def reset(*index_classes)
         require_relative 'index/reset'
         opts = HashUtils.deep_transform_keys(options.to_h, &:to_sym)
@@ -27,6 +31,22 @@ module Esse
         if opts[:import] && opts[:reindex]
           raise ArgumentError, 'You cannot use --import and --reindex together'
         end
+
+        %i[preload_lazy_attributes eager_load_lazy_attributes update_lazy_attributes].each do |key|
+          val = opts.delete(key)
+          val = 'true' if val == key.to_s
+          next if val.nil? || val == 'false'
+
+          if opts[:reindex]
+            raise ArgumentError, "You cannot use --#{key}=#{val} with --reindex"
+          elsif opts[:import] == false
+            raise ArgumentError, "You cannot use --#{key}=#{val} with --import=false"
+          end
+
+          opts[:import] = {} if opts[:import] == true
+          opts[:import][key] = (val == 'true') ? true : val.split(',')
+        end
+
         Reset.new(indices: index_classes, **opts).run
       end
 
@@ -39,7 +59,7 @@ module Esse
       DESC
       option :suffix, type: :string, default: nil, aliases: '-s', desc: 'Suffix to append to index name'
       option :alias, type: :boolean, default: false, aliases: '-a', desc: 'Update alias after create index'
-      option :settings, type: :hash, default: nil, desc: 'List of settings to pass to the index class. Example: --settings=index.refresh_interval:-1,index.number_of_replicas:0'
+      option :settings, type: :hash, default: nil, desc: 'List of settings to pass to the index class. Example: --settings=index.refresh_interval:-1 index.number_of_replicas:0'
       def create(*index_classes)
         require_relative 'index/create'
         opts = HashUtils.deep_transform_keys(options.to_h, &:to_sym)
@@ -66,7 +86,7 @@ module Esse
       desc 'update_settings *INDEX_CLASS', 'Closes the index for read/write operations, updates the index settings, and open it again'
       option :suffix, type: :string, default: nil, aliases: '-s', desc: 'Suffix to append to index name'
       option :type, type: :string, default: nil, aliases: '-t', desc: 'Document Type to update mapping for'
-      option :settings, type: :hash, default: nil, desc: 'List of settings to pass to the index class. Example: --settings=index.refresh_interval:-1,index.number_of_replicas:0'
+      option :settings, type: :hash, default: nil, desc: 'List of settings to pass to the index class. Example: --settings=index.refresh_interval:-1 index.number_of_replicas:0'
       def update_settings(*index_classes)
         require_relative 'index/update_settings'
         opts = HashUtils.deep_transform_keys(options.to_h, &:to_sym)
@@ -107,11 +127,23 @@ module Esse
         opts = HashUtils.deep_transform_keys(options.to_h, &:to_sym)
         %i[preload_lazy_attributes eager_load_lazy_attributes update_lazy_attributes].each do |key|
           if (val = opts.delete(key)) && val != 'false'
+            val = 'true' if val == key.to_s
             opts[key] = (val == 'true') ? true : val.split(',')
           end
         end
         Import.new(indices: index_classes, **opts).run
       end
+
+      desc "update_lazy_attributes INDEX_CLASS", "Async update lazy attributes for the given index"
+      option :repo, type: :string, default: nil, alias: "-r", desc: "Repository to use for import"
+      option :suffix, type: :string, default: nil, aliases: "-s", desc: "Suffix to append to index name"
+      option :context, type: :hash, default: {}, required: true, desc: "List of options to pass to the index class"
+      option :bulk_options, type: :hash, default: nil, desc: 'List of options to pass to the bulk update request. Example: --bulk-options=timeout:30s refresh:true retry_on_conflict:3'
+      def update_lazy_attributes(index_class, *attributes)
+        require_relative "index/update_lazy_attributes"
+        opts = HashUtils.deep_transform_keys(options.to_h, &:to_sym)
+        UpdateLazyAttributes.new(indices: [index_class], attributes: attributes, **opts).run
+      end
     end
   end
 end

data/lib/esse/cli/parser/bool_or_hash.rb

@@ -35,16 +35,20 @@ module Esse
         private
 
         def may_array(value)
-          return may_bool(value) unless ARRAY_SEPARATOR.match?(value)
+          return cast(value) unless ARRAY_SEPARATOR.match?(value)
 
-          value.split(ARRAY_SEPARATOR).map { |v| may_bool(v) }
+          value.split(ARRAY_SEPARATOR).map { |v| cast(v) }
         end
 
-        def may_bool(value)
-          return true if TRUTHY.include?(value)
-          return false if FALSEY.include?(value)
-
-          value
+        def cast(value)
+          case value
+          when *TRUTHY then true
+          when *FALSEY then false
+          when /\A\d+\z/ then value.to_i
+          when /\A\d+\.\d+\z/ then value.to_f
+          else
+            value
+          end
         end
       end
     end

data/lib/esse/collection.rb

@@ -14,5 +14,11 @@ module Esse
     def each
       raise NotImplementedError, 'Override this method to iterate over the collection'
     end
+
+    # @yield [<Array>] A batch of document IDs to be processed.
+    # @abstract Override this method to yield each chunk of document IDs
+    def each_batch_ids
+      raise NotImplementedError, 'Override this method to iterate over the collection in batches of IDs'
+    end
   end
 end

data/lib/esse/document.rb

@@ -1,7 +1,23 @@
 # frozen_string_literal: true
 
+# Esse::Document is the base class for all documents in Esse.
+# It provides methods to access the document ID, type, routing, meta, and source.
+# It also provides methods to convert the document to a hash or bulk format.
+#
+# @example
+#   class UserDocument < Esse::Document
+#     def id
+#       object.id
+#     end
+#
+#     def source
+#       { name: object.name, email: object.email }
+#     end
+#   end
+
 module Esse
   class Document
+
     MUTATIONS_FALLBACK = {}.freeze
 
     attr_reader :object, :options
@@ -39,11 +55,6 @@ module Esse
       !routing.nil?
     end
 
-    # @TODO allow import, index, bulk to accept a suffix to tell which index to use
-    # def index_suffix
-    #   nil
-    # end
-
     # @return [Hash] the document meta
     # @abstract Override this method to return the document meta
     def meta
@@ -108,7 +119,7 @@ module Esse
       DocumentForPartialUpdate.new(self, source: source)
     end
 
-    def inspect
+    def to_s
       attributes = {id: :id, routing: :routing, source: :memoized_source}.map do |attr_name, attr_src|
         value = send(attr_src)
         next unless value

data/lib/esse/events.rb

@@ -59,5 +59,8 @@ module Esse
     register_event 'elasticsearch.reindex'
     register_event 'elasticsearch.update_by_query'
     register_event 'elasticsearch.delete_by_query'
+    register_event 'elasticsearch.tasks'
+    register_event 'elasticsearch.task'
+    register_event 'elasticsearch.cancel_task'
   end
 end

data/lib/esse/import/bulk.rb

@@ -1,30 +1,6 @@
 module Esse
   module Import
     class Bulk
-      def self.build_from_documents(type: nil, index: nil, delete: nil, create: nil, update: nil)
-        index = Array(index).select(&Esse.method(:document?)).reject(&:ignore_on_index?).map do |doc|
-          value = doc.to_bulk
-          value[:_type] ||= type if type
-          value
-        end
-        create = Array(create).select(&Esse.method(:document?)).reject(&:ignore_on_index?).map do |doc|
-          value = doc.to_bulk
-          value[:_type] ||= type if type
-          value
-        end
-        update = Array(update).select(&Esse.method(:document?)).reject(&:ignore_on_index?).map do |doc|
-          value = doc.to_bulk(operation: :update)
-          value[:_type] ||= type if type
-          value
-        end
-        delete = Array(delete).select(&Esse.method(:document?)).reject(&:ignore_on_delete?).map do |doc|
-          value = doc.to_bulk(data: false)
-          value[:_type] ||= type if type
-          value
-        end
-        new(index: index, delete: delete, create: create, update: update)
-      end
-
       def initialize(index: nil, delete: nil, create: nil, update: nil)
         @index = Esse::ArrayUtils.wrap(index).map { |payload| { index: payload } }
         @create = Esse::ArrayUtils.wrap(create).map { |payload| { create: payload } }

data/lib/esse/index/documents.rb

@@ -88,6 +88,7 @@ module Esse
       # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/docs-delete.html
       def delete(doc = nil, suffix: nil, **options)
         if document?(doc)
+          options = request_params_for(:delete, doc).merge(options) if request_params_for?(:delete)
           options[:id] = doc.id
           options[:type] = doc.type if doc.type?
           options[:routing] = doc.routing if doc.routing?
@@ -113,6 +114,7 @@ module Esse
       # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/docs-update.html
       def update(doc = nil, suffix: nil, **options)
         if document?(doc)
+          options = request_params_for(:update, doc).merge(options) if request_params_for?(:update)
           options[:id] = doc.id
           options[:body] = { doc: doc.mutated_source }
           options[:type] = doc.type if doc.type?
@@ -139,6 +141,7 @@ module Esse
       # @see https://www.elastic.co/guide/en/elasticsearch/reference/7.5/docs-index_.html
       def index(doc = nil, suffix: nil, **options)
         if document?(doc)
+          options = request_params_for(:index, doc).merge(options) if request_params_for?(:index)
           options[:id] = doc.id
           options[:body] = doc.mutated_source
           options[:type] = doc.type if doc.type?
@@ -181,6 +184,7 @@ module Esse
           elsif Esse.document?(doc) && !doc.ignore_on_index?
             hash = doc.to_bulk
             hash[:_type] ||= type if type
+            hash = request_params_for(:index, doc, bulk: true).merge(hash) if request_params_for?(:index)
             to_index << hash
           end
         end
@@ -190,6 +194,7 @@ module Esse
           elsif Esse.document?(doc) && !doc.ignore_on_index?
             hash = doc.to_bulk
             hash[:_type] ||= type if type
+            hash = request_params_for(:create, doc, bulk: true).merge(hash) if request_params_for?(:create)
             to_create << hash
           end
         end
@@ -199,6 +204,7 @@ module Esse
           elsif Esse.document?(doc) && !doc.ignore_on_index?
             hash = doc.to_bulk(operation: :update)
             hash[:_type] ||= type if type
+            hash = request_params_for(:update, doc, bulk: true).merge(hash) if request_params_for?(:update)
             to_update << hash
           end
         end
@@ -208,6 +214,7 @@ module Esse
           elsif Esse.document?(doc) && !doc.ignore_on_delete?
             hash = doc.to_bulk(data: false)
             hash[:_type] ||= type if type
+            hash = request_params_for(:delete, doc, bulk: true).merge(hash) if request_params_for?(:delete)
             to_delete << hash
           end
         end

data/lib/esse/index/indices.rb

@@ -30,12 +30,23 @@ module Esse
         options = CREATE_INDEX_RESERVED_KEYWORDS.merge(options)
         name = build_real_index_name(suffix)
         definition = body || [settings_hash(settings: settings), mappings_hash].reduce(&:merge)
+        index_alias = options.delete(:alias)
 
-        if options.delete(:alias) && name != index_name
+        if index_alias && name != index_name
           definition[:aliases] = { index_name => {} }
         end
 
-        cluster.api.create_index(index: name, body: definition, **options)
+        retried = false
+        begin
+          cluster.api.create_index(index: name, body: definition, **options)
+        rescue Esse::Transport::BadRequestError => e
+          if retried == false && e.message.include?('exists with the same name') && index_alias == :force
+            cluster.api.delete_index(index: index_name)
+            retried = true
+            retry
+          end
+          raise
+        end
       end
 
       # Deletes, creates and imports data to the index. Performs zero-downtime index resetting.
@@ -59,8 +70,8 @@ module Esse
         optimized_creation = optimize && syncronous_import && (import || reindex)
         if optimized_creation
           definition = [settings_hash(settings: settings), mappings_hash].reduce(&:merge)
-          number_of_replicas = definition.dig(Esse::SETTING_ROOT_KEY, :index, :number_of_replicas)
-          refresh_interval = definition.dig(Esse::SETTING_ROOT_KEY, :index, :refresh_interval)
+          number_of_replicas = definition.dig(Esse::SETTING_ROOT_KEY, :index, :number_of_replicas) || 1
+          refresh_interval = definition.dig(Esse::SETTING_ROOT_KEY, :index, :refresh_interval) || '1s'
           new_number_of_replicas = ((definition[Esse::SETTING_ROOT_KEY] ||= {})[:index] ||= {})[:number_of_replicas] = 0
           new_refresh_interval = ((definition[Esse::SETTING_ROOT_KEY] ||= {})[:index] ||= {})[:refresh_interval] = '-1'
           create_index(**options, suffix: suffix, alias: false, body: definition)
@@ -88,6 +99,10 @@ module Esse
         end
 
         if optimized_creation && number_of_replicas != new_number_of_replicas || refresh_interval != new_refresh_interval
+          settings ||= {}
+          settings[:index] ||= {}
+          settings[:index][:number_of_replicas] = number_of_replicas
+          settings[:index][:refresh_interval] = refresh_interval
           update_settings(suffix: suffix, settings: settings)
           refresh(suffix: suffix)
         end
@@ -109,8 +124,13 @@ module Esse
 
         task_id = resp['task']
         task = nil
-        while (task = cluster.api.task(id: task_id))['completed'] == false
-          sleep poll_interval
+        begin
+          while (task = cluster.api.task(id: task_id))['completed'] == false
+            sleep poll_interval.to_i
+          end
+        rescue Interrupt => e
+          cluster.api.cancel_task(id: task_id)
+          raise e
         end
         task
       end

data/lib/esse/index/inheritance.rb

@@ -39,6 +39,7 @@ module Esse
           :@mapping => nil,
           :@cluster_id => :dup,
           :@plugins => :dup,
+          :@request_params => :dup,
         }
       end
     end

data/lib/esse/index/request_configurable.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Esse
+  class Index
+    module RequestConfigurable
+      OPERATIONS = %i[index create update delete].freeze
+      BULK_OPERATIONS_AND_PARAMS = {
+        index: %i[_index _type routing if_primary_term if_seq_no version version_type dynamic_templates pipeline require_alias],
+        create: %i[_index _type routing if_primary_term if_seq_no version version_type dynamic_templates pipeline require_alias],
+        update: %i[_index _type routing if_primary_term if_seq_no version version_type require_alias retry_on_conflict],
+        delete: %i[_index _type routing if_primary_term if_seq_no version version_type],
+      }.freeze
+
+      def self.extended(base)
+        base.extend DSL
+      end
+
+      class RequestParams
+        attr_reader :operation, :hash, :block
+
+        def initialize(operation, hash = {}, &block)
+          @operation = operation
+          @hash = hash.transform_keys(&:to_sym)
+          @block = block
+        end
+
+        # @param doc [Esse::Document] the document to apply the request parameters to
+        # @return [Hash] the request parameters for the operation
+        # @raise [ArgumentError] if the result of the block is not a Hash
+        def call(doc)
+          return hash unless block
+
+          result = block.call(doc) || {}
+          raise ArgumentError, "Expected a Hash, got #{result.class}" unless result.is_a?(Hash)
+
+          hash.merge(result.transform_keys(&:to_sym))
+        end
+      end
+
+      class Container
+        def initialize
+          @mutex = Mutex.new
+          @entries = {}.freeze
+        end
+
+        def add(operation, entry)
+          @mutex.synchronize do
+            hash = @entries.dup
+            arr = (hash[operation] || []).dup
+            arr << entry
+            hash[operation] = arr.freeze
+            @entries = hash.freeze
+          end
+        end
+
+        def key?(operation)
+          @entries.key?(operation)
+        end
+
+        def retrieve(operation, doc)
+          return {} unless @entries[operation]
+
+          @entries[operation].each_with_object({}) do |entry, hash|
+            hash.merge!(entry.call(doc))
+          end
+        end
+      end
+
+      module DSL
+        def request_params(*operations, **params, &block)
+          operations.each do |operation|
+            raise ArgumentError, "Invalid operation: #{operation}" unless OPERATIONS.include?(operation)
+
+            @request_params ||= Container.new
+            @request_params.add(operation, RequestParams.new(operation, params, &block))
+          end
+
+          self
+        end
+
+        def request_params_for(operation, doc, bulk: false)
+          return {} unless request_params_for?(operation)
+
+          params = @request_params.retrieve(operation, doc)
+
+          if bulk && BULK_OPERATIONS_AND_PARAMS.key?(operation)
+            params.slice(*BULK_OPERATIONS_AND_PARAMS[operation])
+          else
+            params
+          end
+        end
+
+        def request_params_for?(operation)
+          return false unless @request_params
+
+          @request_params.key?(operation)
+        end
+      end
+    end
+
+    extend RequestConfigurable
+  end
+end

data/lib/esse/index/settings.rb

@@ -11,6 +11,7 @@ module Esse
         number_of_shards
         number_of_replicas
         refresh_interval
+        mapping
       ].freeze
 
       def settings_hash(settings: nil)
@@ -22,9 +23,17 @@ module Esse
         end
         INDEX_SIMPLIFIED_SETTINGS.each do |key|
           next unless values.key?(key)
+          value = values.delete(key)
+          next if value.nil?
 
-          (values[:index] ||= {}).merge!(key => values.delete(key))
+          (values[:index] ||= {}).merge!(key => value)
         end
+
+        if values[:index].is_a?(Hash)
+          INDEX_SIMPLIFIED_SETTINGS.each { |key| values[:index].delete(key) if values[:index][key].nil? }
+          values.delete(:index) if values[:index].empty?
+        end
+
         { Esse::SETTING_ROOT_KEY => values }
       end
 

data/lib/esse/index.rb

@@ -23,5 +23,6 @@ module Esse
     require_relative 'index/indices'
     require_relative 'index/search'
     require_relative 'index/documents'
+    require_relative 'index/request_configurable'
   end
 end

data/lib/esse/primitives/hstring.rb

@@ -82,5 +82,19 @@ module Esse
       @value
     end
     def_conventional :presence!
+
+    def coerce_type
+      if @value =~ /\A-?\d+\z/
+        return @value.to_i
+      elsif @value =~ /\A-?\d+\.\d+\z/
+        return @value.to_f
+      elsif @value == 'true'
+        return true
+      elsif @value == 'false'
+        return false
+      end
+
+      @value
+    end
   end
 end

data/lib/esse/repository/documents.rb

@@ -10,6 +10,7 @@ module Esse
       def update_documents_attribute(name, ids_or_doc_headers = [], kwargs = {})
         batch = documents_for_lazy_attribute(name, ids_or_doc_headers)
         return if batch.empty?
+
         kwargs = kwargs.transform_keys(&:to_sym)
 
         if kwargs.delete(:index_on_missing) { true }

data/lib/esse/repository/object_document_mapper.rb

@@ -157,6 +157,66 @@ module Esse
         @document_proc.call(model, **kwargs)
       end
 
+      # Used to fetch batches of ids from the collection that implement the `each_batch_ids` method.
+      #
+      # @param [Hash] kwargs The context
+      # @yield [Array] A batch of document IDs to be processed.
+      # @raise [NotImplementedError] if the collection does not implement the `each_batch_ids` method.
+      # @raise [NotImplementedError] if the collection is not defined.
+      # @return [Enumerator] The enumerator
+      # @example
+      #   each_batch_ids(active: true) do |ids|
+      #     puts ids.size
+      #   end
+      def each_batch_ids(*args, **kwargs)
+        if @collection_proc.nil?
+          raise NotImplementedError, format('there is no %<t>p collection defined for the %<k>p index', t: repo_name, k: index.to_s)
+        end
+
+        if @collection_proc.is_a?(Class) && @collection_proc.method_defined?(:each_batch_ids)
+          colection_instance = @collection_proc.new(*args, **kwargs)
+          if block_given?
+            colection_instance.each_batch_ids { |ids| yield ids }
+          else
+            Enumerator.new do |yielder|
+              colection_instance.each_batch_ids { |ids| yielder.yield ids }
+            end
+          end
+        else
+          Kernel.warn(<<~MSG)
+            The public `#each_batch_ids' method is not available for the collection defined in the #{repo_name} index.
+
+            The `#each' method will be used instead, which may lead to performance degradation because it serializes the entire document
+            to only obtain the IDs. Consider implementing a public `#each_batch_ids' method in your collection class for better performance.
+
+            Example implementation taking into account you are dealing with an ActiveRecord model:
+              class UserCollection < Esse::Collection
+                # ....
+
+                def each_batch_ids
+                  user_query.except(:includes, :preload, :eager_load).in_batches do |batch|
+                    yield batch.pluck(:id)
+                  end
+                end
+              end
+          MSG
+
+          enumerator = Enumerator.new do |yielder|
+            each_batch(*args, **kwargs) do |*batch_args|
+              batch, collection_context = batch_args
+              collection_context ||= {}
+              ids = [*batch].map { |entry| serialize(entry, **collection_context)&.id }.compact
+              yielder.yield(ids) if ids.any?
+            end
+          end
+          return enumerator unless block_given?
+
+          enumerator.each { |ids| yield ids }
+        end
+      rescue LocalJumpError
+        raise(SyntaxError, 'block must be explicitly declared in the collection definition')
+      end
+
       protected
 
       def coerce_to_document(value)

data/lib/esse/transport/cluster.rb

@@ -40,16 +40,24 @@ module Esse
       #
       # @see https://www.elastic.co/guide/en/elasticsearch/reference/current/tasks.html
       def tasks(**options)
-        # coerce_exception { client.perform_request('GET', '/_tasks', options).body }
-        coerce_exception { client.tasks.list(**options) }
+        Esse::Events.instrument('elasticsearch.tasks') do |payload|
+          payload[:request] = options
+          payload[:response] = coerce_exception { client.tasks.list(**options) }
+        end
       end
 
       def task(id:, **options)
-        coerce_exception { client.tasks.get(task_id: id, **options) }
+        Esse::Events.instrument('elasticsearch.task') do |payload|
+          payload[:request] = { id: id }.merge(options)
+          payload[:response] = coerce_exception { client.tasks.get(task_id: id, **options) }
+        end
       end
 
       def cancel_task(id:, **options)
-        coerce_exception { client.tasks.cancel(task_id: id, **options) }
+        Esse::Events.instrument('elasticsearch.cancel_task') do |payload|
+          payload[:request] = { id: id }.merge(options)
+          payload[:response] = coerce_exception { client.tasks.cancel(task_id: id, **options) }
+        end
       end
     end
 

data/lib/esse/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: esse
 version: !ruby/object:Gem::Version
-  version: 0.4.0.rc3
+  version: 0.4.0.rc5
 platform: ruby
 authors:
 - Marcos G. Zimmermann
 autorequire:
 bindir: exec
 cert_chain: []
-date: 2024-10-04 00:00:00.000000000 Z
+date: 2025-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -226,6 +226,7 @@ files:
 - lib/esse/cli/index/open.rb
 - lib/esse/cli/index/reset.rb
 - lib/esse/cli/index/update_aliases.rb
+- lib/esse/cli/index/update_lazy_attributes.rb
 - lib/esse/cli/index/update_mapping.rb
 - lib/esse/cli/index/update_settings.rb
 - lib/esse/cli/parser/bool_or_hash.rb
@@ -272,6 +273,7 @@ files:
 - lib/esse/index/mappings.rb
 - lib/esse/index/object_document_mapper.rb
 - lib/esse/index/plugins.rb
+- lib/esse/index/request_configurable.rb
 - lib/esse/index/search.rb
 - lib/esse/index/settings.rb
 - lib/esse/index/type.rb
@@ -324,7 +326,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubygems_version: 3.0.3.1
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Pure Ruby and framework-agnostic ElasticSearch/OpenSearch toolkit for building