elasticsearch_record 1.0.2 → 1.1.0

data/lib/arel/visitors/elasticsearch_schema.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Arel # :nodoc: all
+  module Visitors
+    module ElasticsearchSchema
+      extend ActiveSupport::Concern
+
+      included do
+        delegate :type_to_sql,
+                 to: :connection, private: true
+      end
+
+      private
+
+      #################
+      # SCHEMA VISITS #
+      #################
+
+      def visit_CreateTableDefinition(o)
+        # prepare query
+        claim(:type, ::ElasticsearchRecord::Query::TYPE_INDEX_CREATE)
+
+        # set the name of the index
+        claim(:index, visit(o.name))
+
+        # sets settings
+        resolve(o, :visit_TableSettings) if o.settings.present?
+
+        # sets mappings
+        resolve(o, :visit_TableMappings) if o.mappings.present?
+
+        # sets aliases
+        resolve(o, :visit_TableAliases) if o.aliases.present?
+      end
+
+      def visit_InterlacedUpdateTableDefinition(o)
+        # set the name of the index
+        claim(:index, visit(o.name))
+
+        # prepare definition
+        visit(o.definition)
+      end
+
+      def visit_ChangeMappingDefinition(o)
+        # prepare query
+        claim(:type, ::ElasticsearchRecord::Query::TYPE_INDEX_UPDATE_MAPPING)
+
+        assign(:properties, {}) do
+          resolve(o.items, :visit_TableMappingDefinition)
+        end
+      end
+
+      alias :visit_AddMappingDefinition :visit_ChangeMappingDefinition
+
+      def visit_ChangeSettingDefinition(o)
+        # prepare query
+        claim(:type, ::ElasticsearchRecord::Query::TYPE_INDEX_UPDATE_SETTING)
+
+        # special overcomplicated blocks to assign a hash of settings directly to the body
+        assign(:__claim__, {}) do
+          assign(:body, {}) do
+            resolve(o.items, :visit_TableSettingDefinition)
+          end
+        end
+      end
+
+      alias :visit_AddSettingDefinition :visit_ChangeSettingDefinition
+      alias :visit_DeleteSettingDefinition :visit_ChangeSettingDefinition
+
+      def visit_ChangeAliasDefinition(o)
+        # prepare query
+        claim(:type, ::ElasticsearchRecord::Query::TYPE_INDEX_UPDATE_ALIAS)
+
+        claim(:argument, :name, o.item.name)
+        claim(:body, o.item.attributes)
+      end
+
+      alias :visit_AddAliasDefinition :visit_ChangeAliasDefinition
+
+      def visit_DeleteAliasDefinition(o)
+        # prepare query
+        claim(:type, ::ElasticsearchRecord::Query::TYPE_INDEX_DELETE_ALIAS)
+
+        claim(:argument, :name, o.items.map(&:name).join(','))
+      end
+
+      ##############
+      # SUB VISITS #
+      ##############
+
+      def visit_TableSettings(o)
+        assign(:settings, {}) do
+          resolve(o.settings, :visit_TableSettingDefinition)
+        end
+      end
+
+      def visit_TableMappings(o)
+        assign(:mappings, {}) do
+          assign(:properties, {}) do
+            resolve(o.mappings, :visit_TableMappingDefinition)
+          end
+        end
+      end
+
+      def visit_TableAliases(o)
+        assign(:aliases, {}) do
+          resolve(o.aliases, :visit_TableAliasDefinition)
+        end
+      end
+
+      def visit_TableSettingDefinition(o)
+        assign(o.name, o.value, :__force__)
+      end
+
+      def visit_TableMappingDefinition(o)
+        assign(o.name, o.attributes.merge({type: type_to_sql(o.type)}))
+      end
+
+      def visit_TableAliasDefinition(o)
+        assign(o.name, o.attributes)
+      end
+    end
+  end
+end

data/lib/elasticsearch_record/core.rb

@@ -2,35 +2,69 @@ module ElasticsearchRecord
   module Core
     extend ActiveSupport::Concern
 
-    # in default, this reads the primary key column's value (+_id+).
-    # But since elasticsearch supports also additional "id" columns, we need to check against that.
+    included do
+      class_attribute :relay_id_attribute, instance_writer: false, default: false
+    end
+
+    # overwrite to provide a Elasticsearch version of returning a 'primary_key' attribute.
+    # Elasticsearch uses the static +_id+ column as primary_key, but also supports an additional +id+ column.
+    # To provide functionality of returning the +id+ attribute, this method must also support it.
+    # @return [Object]
     def id
-      has_attribute?('id') ? _read_attribute('id') : super
+      # check, if the model has a +id+ attribute
+      return _read_attribute('id') if relay_id_attribute? && has_attribute?('id')
+
+      super
     end
 
-    # in default, this sets the primary key column's value (+_id+).
-    # But since elasticsearch supports also additional "id" columns, we need to check against that.
+    # overwrite to provide a Elasticsearch version of setting a 'primary_key' attribute.
+    # Elasticsearch uses the static +_id+ column as primary_key, but also supports an additional +id+ column.
+    # To provide functionality of setting the +id+ attribute, this method must also support it.
+    # @param [Object] value
     def id=(value)
-      has_attribute?('id') ? _write_attribute('id', value) : super
+      # check, if the model has a +id+ attribute
+      return _write_attribute('id', value) if relay_id_attribute? && has_attribute?('id')
+
+      # auxiliary update the +_id+ virtual column if we have a different primary_key
+      _write_attribute('_id', value) if @primary_key != '_id'
+
+      super
     end
 
-    # overwrite the write_attribute method to write 'id', if present?
+    # overwrite to provide a Elasticsearch version of returning a 'primary_key' was attribute.
+    # Elasticsearch uses the static +_id+ column as primary_key, but also supports an additional +id+ column.
+    # To provide functionality of returning the +id_Was+ attribute, this method must also support it.
+    def id_was
+      relay_id_attribute? && has_attribute?('id') ? attribute_was('id') : attribute_was(@primary_key)
+    end
+
+    # overwrite the write_attribute method to write 'id', if present
     # see @ ActiveRecord::AttributeMethods::Write#write_attribute
     def write_attribute(attr_name, value)
-      return _write_attribute('id', value) if attr_name.to_s == 'id' && has_attribute?('id')
+      return _write_attribute('id', value) if attr_name.to_s == 'id' && relay_id_attribute? && has_attribute?('id')
 
       super
     end
 
-    # overwrite read_attribute method to read 'id', if present?
+    # overwrite read_attribute method to read 'id', if present
     # see @ ActiveRecord::AttributeMethods::Read#read_attribute
     def read_attribute(attr_name, &block)
-      return _read_attribute('id', &block) if attr_name.to_s == 'id' && has_attribute?('id')
+      return _read_attribute('id', &block) if attr_name.to_s == 'id' && relay_id_attribute? && has_attribute?('id')
 
       super
     end
 
+    module PrependClassMethods
+      # returns the table_name.
+      # Has to be prepended to provide automated compatibility to other gems.
+      def index_name
+        table_name
+      end
+    end
+
     module ClassMethods
+      prepend ElasticsearchRecord::Core::PrependClassMethods
+
       # used to create a cacheable statement.
       # This is a 1:1 copy, except that we use our own class +ElasticsearchRecord::StatementCache+
       # see @ ActiveRecord::Core::ClassMethods#cached_find_by_statement

data/lib/elasticsearch_record/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ElasticsearchRecord
+  # Generic ElasticsearchRecord exception class.
+  class ElasticsearchRecordError < StandardError
+  end
+
+  class ResponseResultError < ElasticsearchRecordError
+    def initialize(expected, result)
+      super("expected response-result failed!\nreturned: '#{result}', but should be '#{expected}'")
+    end
+  end
+end

data/lib/elasticsearch_record/gem_version.rb

@@ -8,10 +8,14 @@ module ElasticsearchRecord
 
   module VERSION
     MAJOR = 1
-    MINOR = 0
-    TINY  = 2
+    MINOR = 1
+    TINY  = 0
     PRE   = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")
+
+    def self.to_s
+      STRING
+    end
   end
 end

data/lib/elasticsearch_record/instrumentation/log_subscriber.rb

@@ -5,7 +5,7 @@ module ElasticsearchRecord
     # attach to ElasticsearchRecord related events
     class LogSubscriber < ActiveSupport::LogSubscriber
 
-      IGNORE_PAYLOAD_NAMES = ["SCHEMA", "EXPLAIN"]
+      IGNORE_PAYLOAD_NAMES = %w[SCHEMA EXPLAIN]
 
       def self.runtime=(value)
         Thread.current["elasticsearch_record_runtime"] = value
@@ -20,45 +20,63 @@ module ElasticsearchRecord
         rt
       end
 
-      # Intercept `search.elasticsearch` events, and display them in the Rails log
-      #
+      # Intercept `query.elasticsearch` events, and display them in the Rails log
       def query(event)
         self.class.runtime += event.duration
+
         return unless logger.debug?
 
         payload = event.payload
         return if IGNORE_PAYLOAD_NAMES.include?(payload[:name])
 
+        # build name from several payload data
         name = if payload[:async]
                  "ASYNC #{payload[:name]} (#{payload[:lock_wait].round(1)}ms) (execution time #{event.duration.round(1)}ms)"
                else
                  "#{payload[:name]} (#{event.duration.round(1)}ms)"
                end
-        name  = "CACHE #{name}" if payload[:cached]
+        name = "CACHE #{name}" if payload[:cached]
 
+        # nice feature: displays the REAL query-time (_qt)
         name = "#{name} (took: #{payload[:arguments][:_qt].round(1)}ms)" if payload[:arguments][:_qt]
 
-        query  = payload[:arguments].except(:index, :_qt).inspect.gsub(/:(\w+)=>/, '\1: ').presence || '-'
+        # build query
+        query = payload[:arguments].except(:_qt).inspect.gsub(/:(\w+)=>/, '\1: ').presence || '-'
 
         # final coloring
-        name = color(name, CYAN, true)
-        query  = color(query, gate_color(payload[:gate]), true) if colorize_logging
+        name  = color(name, name_color(payload[:name]), true)
+        query = color(query, gate_color(payload[:gate]), true) if colorize_logging
 
         debug "  #{name} #{query}"
       end
 
       private
 
+      def name_color(name)
+        if name.blank? || name.match(/^[\p{Lu}\ ]+$/) # uppercase letters only : API, DROP, CREATE, ...
+          MAGENTA
+        else
+          CYAN
+        end
+      end
+
       def gate_color(gate)
         case gate
-        when 'core.search', 'core.msearch'
+          # SELECTS
+        when 'core.get', 'core.mget', 'core.search', 'core.msearch', 'core.count', 'core.exists', 'sql.query'
           BLUE
+          # DELETES
         when 'core.delete', 'core.delete_by_query'
           RED
-        when 'core.create'
+          # CREATES
+        when 'core.create', 'core.reindex'
           GREEN
+          # UPDATES
         when 'core.update', 'core.update_by_query'
           YELLOW
+          # MIXINS
+        when /indices\.\w+/, 'core.bulk', 'core.index'
+          WHITE
         else
           MAGENTA
         end

data/lib/elasticsearch_record/model_schema.rb

@@ -13,6 +13,11 @@ module ElasticsearchRecord
         index_base_name || super(model_name)
       end
 
+      # returns the configured +max_result_window+ (default: 10000)
+      def max_result_window
+        @max_result_window ||= connection.max_result_window(table_name)
+      end
+
       # returns an array with columns names, that are not virtual (and not a base structure).
       # so this is a array of real document (+_source+) attributes of the index.
       # @return [Array<String>]

data/lib/elasticsearch_record/persistence.rb

@@ -6,17 +6,31 @@ module ElasticsearchRecord
 
       # insert a new record into the Elasticsearch index
       # NOTICE: We don't want to mess up with the Arel-builder - so we send new data directly to the API
+      # @param [ActiveModel::Attribute] values
+      # @return [Object] id
       def _insert_record(values)
-        # values is not a "key=>values"-Hash, but a +ActiveModel::Attribute+ - so we need to resolve the casted values here
+        # values is not a "key=>values"-Hash, but a +ActiveModel::Attribute+ - so the casted values gets resolved here
         values = values.transform_values(&:value)
 
-        # if a primary_key (+_id+) was provided, we need to extract this and allocate this to the arguments
-        arguments = if (id = values.delete(self.primary_key)).present?
-                      { id: id }
+        update_auto_increment = false
+
+        # resolve possible provided primary_key value from values
+        arguments = if (id = values[self.primary_key]).present?
+                      {id: id}
+                    elsif self.columns_hash[self.primary_key]&.meta['auto_increment'] # BETA: should not be used on mass imports to the Elasticsearch-index
+                      update_auto_increment = true
+                      ids = [
+                        connection.table_mappings(self.table_name).dig('properties', self.primary_key, 'meta', 'auto_increment').to_i + 1,
+                        self.unscoped.all.maximum(self.primary_key).to_i + 1
+                      ]
+                      {id: ids.max}
                     else
                       {}
                     end
 
+        # IMPORTANT: Always drop possible provided 'primary_key' column +_id+.
+        values.delete(self.primary_key)
+
         # build new query
         query = ElasticsearchRecord::Query.new(
           index:     table_name,
@@ -25,17 +39,18 @@ module ElasticsearchRecord
           arguments: arguments,
           refresh:   true)
 
-        # execute query and build a RAW response
-        response = connection.exec_query(query, "#{self} Create").response
+        # execute query and return inserted id
+        id = connection.insert(query, "#{self} Create")
 
-        raise RecordNotSaved unless response['result'] == 'created'
+        if id.present? && update_auto_increment
+          connection.change_mapping_meta(table_name, self.primary_key, auto_increment: id)
+        end
 
-        # return the new id
-        response['_id']
+        id
       end
 
       # updates a persistent entry in the Elasticsearch index
-      # NOTICE: We don't want to mess up with the Arel-builder - so we send new data directly to the API
+      # NOTICE: We don't want to mess up with the Arel-builder - so data is directly send to the API
       def _update_record(values, constraints)
         # values is not a "key=>values"-Hash, but a +ActiveModel::Attribute+ - so we need to resolve the casted values here
         values = values.transform_values(&:value)
@@ -45,20 +60,15 @@ module ElasticsearchRecord
           index:     table_name,
           type:      ElasticsearchRecord::Query::TYPE_UPDATE,
           body:      { doc: values },
-          arguments: { id: constraints['_id'] },
+          arguments: { id: constraints[self.primary_key] },
           refresh:   true)
 
-        # execute query and build a RAW response
-        response = connection.exec_query(query, "#{self} Update").response
-
-        raise RecordNotSaved unless response['result'] == 'updated'
-
-        # return affected rows
-        response['_shards']['total']
+        # execute query and return total updates
+        connection.update(query, "#{self} Update")
       end
 
       # removes a persistent entry from the Elasticsearch index
-      # NOTICE: We don't want to mess up with the Arel-builder - so we send new data directly to the API
+      # NOTICE: We don't want to mess up with the Arel-builder - so data is directly send to the API
       def _delete_record(constraints)
         # build new query
         query = ElasticsearchRecord::Query.new(
@@ -67,13 +77,8 @@ module ElasticsearchRecord
           arguments: { id: constraints[self.primary_key] },
           refresh:   true)
 
-        # execute query and build a RAW response
-        response = connection.exec_query(query, "#{self} Destroy").response
-
-        raise RecordNotDestroyed unless response['result'] == 'deleted'
-
-        # return affected rows
-        response['_shards']['total']
+        # execute query and return total deletes
+        connection.delete(query, "#{self} Delete")
       end
     end
   end

data/lib/elasticsearch_record/query.rb

@@ -4,33 +4,66 @@ module ElasticsearchRecord
     STATUS_VALID  = :valid
     STATUS_FAILED = :failed
 
-    # TYPE CONSTANTS
-    TYPE_UNDEFINED       = :undefined
-    TYPE_COUNT           = :count
-    TYPE_SEARCH          = :search
-    TYPE_MSEARCH         = :msearch
-    TYPE_SQL             = :sql
+    # -- UNDEFINED TYPE ------------------------------------------------------------------------------------------------
+    TYPE_UNDEFINED = :undefined
+
+    # -- QUERY TYPES ---------------------------------------------------------------------------------------------------
+    TYPE_COUNT   = :count
+    TYPE_SEARCH  = :search
+    TYPE_MSEARCH = :msearch
+    TYPE_SQL     = :sql
+
+    # -- DOCUMENT TYPES ------------------------------------------------------------------------------------------------
     TYPE_CREATE          = :create
     TYPE_UPDATE          = :update
     TYPE_UPDATE_BY_QUERY = :update_by_query
     TYPE_DELETE          = :delete
     TYPE_DELETE_BY_QUERY = :delete_by_query
 
+    # -- INDEX TYPES ---------------------------------------------------------------------------------------------------
+    TYPE_INDEX_CREATE = :index_create
+    # INDEX update is not implemented by Elasticsearch
+    # - this is handled through individual updates of +mappings+, +settings+ & +aliases+.
+    # INDEX delete is handled directly as API-call
+    TYPE_INDEX_UPDATE_MAPPING = :index_update_mapping
+    TYPE_INDEX_UPDATE_SETTING = :index_update_setting
+    TYPE_INDEX_UPDATE_ALIAS   = :index_update_alias
+    TYPE_INDEX_DELETE_ALIAS   = :index_delete_alias
+
     # includes valid types only
-    TYPES = [TYPE_COUNT, TYPE_SEARCH, TYPE_MSEARCH, TYPE_SQL, TYPE_CREATE, TYPE_UPDATE, TYPE_UPDATE_BY_QUERY, TYPE_DELETE, TYPE_DELETE_BY_QUERY].freeze
+    TYPES = [
+      # -- QUERY TYPES
+      TYPE_COUNT, TYPE_SEARCH, TYPE_MSEARCH, TYPE_SQL,
+      # -- DOCUMENT TYPES
+      TYPE_CREATE, TYPE_UPDATE, TYPE_UPDATE_BY_QUERY, TYPE_DELETE, TYPE_DELETE_BY_QUERY,
+
+      # -- INDEX TYPES
+      TYPE_INDEX_CREATE, TYPE_INDEX_UPDATE_MAPPING, TYPE_INDEX_UPDATE_SETTING, TYPE_INDEX_UPDATE_ALIAS,
+      TYPE_INDEX_DELETE_ALIAS
+    ].freeze
 
     # includes reading types only
-    READ_TYPES = [TYPE_COUNT, TYPE_SEARCH, TYPE_MSEARCH, TYPE_SQL].freeze
+    READ_TYPES = [
+      TYPE_COUNT, TYPE_SEARCH, TYPE_MSEARCH, TYPE_SQL
+    ].freeze
 
-    # defines a query to be executed if the query fails - +(none)+ queries
+    # defines a body to be executed if the query fails - +(none)+
     # acts like the SQL-query "where('1=0')"
-    FAILED_SEARCH_BODY = { size: 0, query: { bool: { filter: [{ term: { _id: '_' } }] } } }.freeze
+    FAILED_BODIES = {
+      TYPE_SEARCH => { size: 0, query: { bool: { filter: [{ term: { _id: '_' } }] } } },
+      TYPE_COUNT  => { query: { bool: { filter: [{ term: { _id: '_' } }] } } }
+    }.freeze
 
     # defines special api gates to be used per type.
-    # if not defined it simply uses +[:core,self.type]+
+    # if no special type is defined, it simply uses +[:core,self.type]+
     GATES = {
-      TYPE_SQL => [:sql, :query]
-    }
+      TYPE_SQL                  => [:sql, :query],
+      TYPE_INDEX_CREATE         => [:indices, :create],
+      TYPE_INDEX_UPDATE_MAPPING => [:indices, :put_mapping],
+      TYPE_INDEX_UPDATE_SETTING => [:indices, :put_settings],
+      TYPE_INDEX_UPDATE_ALIAS   => [:indices, :put_alias],
+      TYPE_INDEX_DELETE_ALIAS   => [:indices, :delete_alias],
+    }.freeze
 
     # defines the index the query should be executed on
     # @!attribute String
@@ -52,7 +85,7 @@ module ElasticsearchRecord
 
     # defines the query body - in most cases this is a hash
     # @!attribute Hash
-    attr_reader :body
+    # attr_reader :body
 
     # defines the query arguments to be passed to the API
     # @!attribute Hash
@@ -102,14 +135,20 @@ module ElasticsearchRecord
       !READ_TYPES.include?(self.type)
     end
 
+    # returns the query body - depends on the +status+!
+    # failed queried will return the related +FAILED_BODIES+ or +{}+ as fallback
+    # @return [Hash, nil]
+    def body
+      return (FAILED_BODIES[self.type].presence || {}) if self.status == STATUS_FAILED
+
+      @body
+    end
+
     # builds the final query arguments.
     # Depends on the query status, index, body & refresh attributes.
     # Also used possible PRE-defined arguments to be merged with those mentioned attributes.
     # @return [Hash]
     def query_arguments
-      # check for failed status
-      return { index: self.index, body: FAILED_SEARCH_BODY } if self.status == STATUS_FAILED
-
       args           = @arguments.deep_dup
 
       # set index, if present

data/lib/elasticsearch_record/querying.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ElasticsearchRecord
   module Querying
     extend ActiveSupport::Concern
@@ -88,6 +90,21 @@ module ElasticsearchRecord
         connection.exec_query(query, "#{name} Msearch", async: async)
       end
 
+      # executes a search by provided +RAW+ query - supports +Elasticsearch::DSL+ gem if loaded
+      def search(*args, &block)
+        begin
+          # require the Elasticsearch::DSL gem, if loaded
+          require 'elasticsearch/dsl'
+          query = ::Elasticsearch::DSL::Search::Search.new(*args, &block).to_hash
+        rescue LoadError
+          query = args.extract_options!
+        rescue
+          query = args.extract_options!
+        end
+
+        find_by_query(query)
+      end
+
       # execute query by msearch
       def _query_by_msearch(queries, async: false)
         connection.select_multiple(queries, "#{name} Msearch", async: async)

data/lib/elasticsearch_record/relation/calculation_methods.rb

@@ -12,6 +12,9 @@ module ElasticsearchRecord
         # fallback to default
         return super() if block_given?
 
+        # check for already failed query
+        return 0 if null_relation?
+
         # reset column_name, if +:all+ was provided ...
         column_name = nil if column_name == :all
 

data/lib/elasticsearch_record/relation/core_methods.rb

@@ -29,28 +29,68 @@ module ElasticsearchRecord
         to_sql.query_arguments
       end
 
-      # executes the elasticsearch msearch on the related klass
+      # Allows to execute several search operations in one request.
+      # executes the elasticsearch +msearch+ on the related class-index.
+      #
+      # A optionally array of items will be each yielded with a spawn(of the current relation) and item.
+      # Each yield-return will resolve its +arel+ which will then transform to multiple queries and send in a single request.
+      #
+      # Responses can be refined by providing a +resolve+ option, to resolve specific results from each +ElasticsearchRecord::Result+
+      # (e.g. used to resolve 'aggregations, buckets, ...')
+      #
+      # As a default the method returns an array of (resolved) responses in the order of the provided +values+-array.
+      # This can be transformed into a hash of keys (provided items) and values (responses) by providing the +transpose+ flag.
+      #
+      # WARNING: if the current relation is a +NullRelation+ (**#none** was assigned), the method directly returns nil!
       #
       # @example
-      #   msearch([2020, 2019, 2018]).each{ |q, year| q.where!(year: year) }
+      #   # msearch on the current relation
+      #   msearch
+      #   # > [ElasticsearchRecord::Result]
       #
-      # @param [Array] values - values to be yielded
-      # @param [nil, Symbol] response_type - optional type of search response (:took, :total , :hits , :aggregations , :length , :results, :each)
-      def msearch(values = nil, response_type = nil)
-        if values.nil?
-          arels = [arel]
-        else
-          arels = values.map { |value|
-            # spawn a new relation and return the arel-object
-            yield(spawn, value).arel
-          }
-        end
+      # @example
+      #   # msearch with provided items
+      #   msearch([2020, 2019, 2018]).each{ |query, year| query.where!(year: year) }
+      #   # > [ElasticsearchRecord::Result, ElasticsearchRecord::Result, ElasticsearchRecord::Result]
+      #
+      # @example
+      #   # msearch with refining options
+      #   msearch([2020, 2019, 2018], resolve: :aggregations, transpose: true).each{ |query, year| query.where!(year: year).aggregate!(:total, { sum: { field: :count }}) }
+      #   # > {2020 => {...aggs...}, 2019 => {...aggs...}, 2018 => {...aggs...}}
+      #
+      # @example
+      #   # msearch with none (NullRelation)
+      #   scope = spawn.none
+      #   scope.msearch([2020, 2019, 2018]).each{ |query, year| ... }
+      #   # > nil
+      #
+      # @param [nil, Array] items - items to be yielded and used to provide individual queries (yields: |spawn, value| )
+      # @param [Hash] opts - additional options to refine the results
+      # @option opts[Symbol] :resolve - optionally resolve specific results from each result (:took, :total , :hits , :aggregations , :length , :results, :each)
+      # @option opts[Boolean] :transpose - transposes the provided values & results as Hash (default: false)
+      # @option opts[Boolean] :keep_null_relation - by provided true-value, a NullRelation will not be ignored - so items will be yielded & query will be executed (default: false)
+      # @return [Array, Hash, nil]
+      def msearch(items = nil, opts = {})
+        # prevent query on +NullRelation+!
+        return nil if null_relation? && !opts[:keep_null_relation]
+
+        # check if values are provided, if not we use the arel from the current relation-scope
+        arels = if items.nil?
+                  [arel]
+                else
+                  # spawn a new relation to the block and maps each arel-object
+                  items.map { |value| yield(spawn, value).arel }
+                end
 
-        # returns a response object with multiple single responses
-        responses = klass._query_by_msearch(arels)
+        # check provided resolve method
+        responses = if opts[:resolve]
+                      klass._query_by_msearch(arels).map(&opts[:resolve].to_sym)
+                    else
+                      klass._query_by_msearch(arels)
+                    end
 
-        if response_type
-          responses.map(&response_type.to_sym)
+        if opts[:transpose]
+          [items, responses].transpose.to_h
         else
           responses
         end