elasticsearch_record 1.8.2 → 2.0.0

data/lib/elasticsearch_record/persistence.rb

@@ -15,12 +15,12 @@ module ElasticsearchRecord
         _insert_with_auto_increment(values) do |arguments|
           # build new query
           query = ElasticsearchRecord::Query.new(
-            index:     table_name,
-            type:      ElasticsearchRecord::Query::TYPE_CREATE,
+            index: table_name,
+            type: ElasticsearchRecord::Query::TYPE_CREATE,
             # IMPORTANT: always exclude possible provided +_id+ field
-            body:      values.except('_id'),
+            body: values.except('_id'),
             arguments: arguments,
-            refresh:   true)
+            refresh: true)
 
           # execute query and return inserted id
           connection.insert(query, "#{self} Create", returning: returning)
@@ -35,11 +35,11 @@ module ElasticsearchRecord
 
         # build new query
         query = ElasticsearchRecord::Query.new(
-          index:     table_name,
-          type:      ElasticsearchRecord::Query::TYPE_UPDATE,
-          body:      { doc: values },
+          index: table_name,
+          type: ElasticsearchRecord::Query::TYPE_UPDATE,
+          body: { doc: values },
           arguments: { id: constraints[self.primary_key] },
-          refresh:   true)
+          refresh: true)
 
         # execute query and return total updates
         connection.update(query, "#{self} Update")
@@ -50,10 +50,10 @@ module ElasticsearchRecord
       def _delete_record(constraints)
         # build new query
         query = ElasticsearchRecord::Query.new(
-          index:     table_name,
-          type:      ElasticsearchRecord::Query::TYPE_DELETE,
+          index: table_name,
+          type: ElasticsearchRecord::Query::TYPE_DELETE,
           arguments: { id: constraints[self.primary_key] },
-          refresh:   true)
+          refresh: true)
 
         # execute query and return total deletes
         connection.delete(query, "#{self} Delete")
@@ -66,7 +66,7 @@ module ElasticsearchRecord
         # check, if the primary_key's value is provided.
         # so, no need to resolve a +auto_increment+ value, but provide the id directly
         if (id = values[self.primary_key]).present?
-          yield({id: id})
+          yield({ id: id })
         elsif auto_increment?
           # future increments: uuid (+uuidv6 ?), hex, radix(2-36), integer
           # allocated through: primary_key_type
@@ -75,17 +75,34 @@ module ElasticsearchRecord
             # try to resolve the current-auto-increment value from the tables meta
             connection.table_metas(self.table_name).dig('auto_increment').to_i + 1,
             # for secure reasons: also resolve the current maximum value for the primary key
-            self.unscoped.all.maximum(self.primary_key).to_i + 1
+            self.unscoped.maximum(self.primary_key).to_i + 1
           ]
 
-          id = yield({ id: ids.max })
+          # yield and resolve the new inserted *result*
+          result = yield({ id: ids.max })
 
-          if id.present?
-            connection.change_meta(self.table_name, :auto_increment, id)
+          # IMPORTANT: the block returns whatever +connection.insert+ resolved, which is NOT a plain id:
+          # ActiveRecord always provides the primary_key as +returning+ column, so an ARRAY of the
+          # returning column values is resolved (see @ ActiveRecord::Persistence#_create_record).
+          # The +_meta+ must be updated with the PLAIN id - storing the raw result breaks the
+          # +.to_i+ of the NEXT insert (which then only resolves a 0 - or fails altogether).
+          id = case result
+               when Array
+                 result.first
+               when Hash
+                 result[:id] || result['id']
+               else
+                 result
+               end
+
+          if id.present? && id.to_i > 0
+            # IMPORTANT: elasticsearch resolves a document +_id+ as String - the +_meta+ must keep the
+            # INTEGER it was created with, so the schema does not change its type behind the first insert.
+            connection.change_meta(self.table_name, :auto_increment, id.to_i)
           end
 
-          # return inserted id
-          id
+          # return the UNCHANGED insert result - it is zipped against the +returning+ columns
+          result
         else
           yield({})
         end

data/lib/elasticsearch_record/query.rb

@@ -1,36 +1,39 @@
 module ElasticsearchRecord
   class Query
     # STATUS CONSTANTS
-    STATUS_VALID  = :valid
+    STATUS_VALID = :valid
     STATUS_FAILED = :failed
 
     # -- UNDEFINED TYPE ------------------------------------------------------------------------------------------------
     TYPE_UNDEFINED = :undefined
 
     # -- QUERY TYPES ---------------------------------------------------------------------------------------------------
-    TYPE_COUNT   = :count
-    TYPE_SEARCH  = :search
+    TYPE_COUNT = :count
+    TYPE_SEARCH = :search
     TYPE_MSEARCH = :msearch
-    TYPE_SQL     = :sql
-    TYPE_ESQL    = :esql
+    TYPE_SQL = :sql
+
+    # PLEASE NOTE: ES|QL requires Elasticsearch >= 8.11
+    # (the +esql+ API namespace does not exist before that)
+    TYPE_ESQL = :esql
 
     # -- DOCUMENT TYPES ------------------------------------------------------------------------------------------------
-    TYPE_CREATE          = :create
-    TYPE_UPDATE          = :update
+    TYPE_CREATE = :create
+    TYPE_UPDATE = :update
     TYPE_UPDATE_BY_QUERY = :update_by_query
-    TYPE_DELETE          = :delete
+    TYPE_DELETE = :delete
     TYPE_DELETE_BY_QUERY = :delete_by_query
 
     # -- INDEX TYPES ---------------------------------------------------------------------------------------------------
     TYPE_INDEX_CREATE = :index_create
-    TYPE_INDEX_CLONE  = :index_clone
+    TYPE_INDEX_CLONE = :index_clone
     # 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
+    TYPE_INDEX_UPDATE_ALIAS = :index_update_alias
+    TYPE_INDEX_DELETE_ALIAS = :index_delete_alias
 
     # includes valid types only
     TYPES = [
@@ -54,22 +57,39 @@ module ElasticsearchRecord
     # acts like the SQL-query "where('1=0')"
     FAILED_BODIES = {
       TYPE_SEARCH => { size: 0, query: { bool: { filter: [{ term: { _id: '_' } }] } } },
-      TYPE_COUNT  => { query: { bool: { filter: [{ term: { _id: '_' } }] } } }
+      TYPE_COUNT => { query: { bool: { filter: [{ term: { _id: '_' } }] } } }
     }.freeze
 
     # defines special api gates to be used per type.
     # if no special type is defined, it simply uses +[:core,self.type]+
-    GATES = {
-      TYPE_SQL                  => [:sql, :query],
-      TYPE_ESQL                 => [:esql, :query],
-      TYPE_INDEX_CREATE         => [:indices, :create],
-      TYPE_INDEX_CLONE          => [:indices, :clone],
-      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],
+    # @return [Hash<Symbol=>String>]
+    GATES_MAP = {
+      TYPE_SQL => 'sql.query',
+      TYPE_ESQL => 'esql.query',
+      TYPE_INDEX_CREATE => 'indices.create',
+      TYPE_INDEX_CLONE => 'indices.clone',
+      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
 
+    # -- PROJECTION MARKERS --------------------------------------------------------------------------------------------
+
+    # defines a projection marker that forces a query to return *no* +_source+ fields at all.
+    # metadata fields ('_id', '_score', ...) are not part of the +_source+ - they are always
+    # returned on the document level and therefore stay accessible.
+    #
+    # this is the only way to clear the columns that +visit_Arel_Nodes_SelectCore+ claims for
+    # every relation - a +configure+ can only reach the query-body, never the columns.
+    #
+    # HINT: only evaluated as the *first* projection - combining it with other fields
+    # (e.g. +select(COLUMNS_NONE, :name)+) silently discards them.
+    #
+    # see @ ElasticsearchRecord::Relation::ResultMethods#meta_only!
+    # see @ Arel::Visitors::ElasticsearchQuery#visit_Selects
+    COLUMNS_NONE = '!'
+
     # defines the index the query should be executed on
     # @!attribute String
     attr_reader :index
@@ -101,14 +121,14 @@ module ElasticsearchRecord
     attr_reader :columns
 
     def initialize(index: nil, type: TYPE_UNDEFINED, status: STATUS_VALID, body: nil, refresh: nil, timeout: nil, arguments: {}, columns: [])
-      @index     = index
-      @type      = type
-      @status    = status
-      @refresh   = refresh
-      @timeout   = timeout
-      @body      = body
+      @index = index
+      @type = type
+      @status = status
+      @refresh = refresh
+      @timeout = timeout
+      @body = body
       @arguments = arguments
-      @columns   = columns
+      @columns = columns
     end
 
     # sets the failed status for this query.
@@ -136,9 +156,9 @@ module ElasticsearchRecord
     # returns the API gate to be called to execute the query.
     # each query type needs a different endpoint.
     # @see Elasticsearch::API
-    # @return [Array<Symbol, Symbol>] - API gate [<namespace>,<action>]
+    # @return [Symbol, String] - API gate "<namespace>.<action>" | <:action>
     def gate
-      GATES[self.type].presence || [:core, self.type]
+      GATES_MAP[self.type].presence || self.type
     end
 
     # returns true if this is a write query
@@ -161,13 +181,13 @@ module ElasticsearchRecord
     # Also used possible PRE-defined arguments to be merged with those mentioned attributes.
     # @return [Hash]
     def query_arguments
-      args           = @arguments.deep_dup
+      args = @arguments.deep_dup
 
       # set index, if present
-      args[:index]   = self.index if self.index.present?
+      args[:index] = self.index if self.index.present?
 
       # set body, if present
-      args[:body]    = self.body if self.body.present?
+      args[:body] = self.body if self.body.present?
 
       # set refresh, if defined (also includes false value)
       args[:refresh] = self.refresh unless self.refresh.nil?

data/lib/elasticsearch_record/querying.rb

@@ -48,7 +48,7 @@ module ElasticsearchRecord
                 when String # really find by SQL
                   ElasticsearchRecord::Query.new(
                     type: ElasticsearchRecord::Query::TYPE_SQL,
-                    body: { query: query_or_sql },
+                    body: { query: sql },
                     # IMPORTANT: Always provide all columns
                     columns: source_column_names)
                 when Hash
@@ -96,8 +96,7 @@ module ElasticsearchRecord
       # executes a +esql+ by provided *ES|SL* query
       # Does NOT instantiate records.
       # @param [String] esql
-      # @param [Boolean] async (default: false)
-      def esql(esql, async: false)
+      def esql(esql)
         # build new query
         query = ElasticsearchRecord::Query.new(
           type: ElasticsearchRecord::Query::TYPE_ESQL,
@@ -105,15 +104,14 @@ module ElasticsearchRecord
           # IMPORTANT: Always provide all columns
           columns: source_column_names)
 
-        connection.internal_exec_query(query, "#{name} ES|QL", async: async)
+        connection.exec_query(query, "#{name} ES|QL")
       end
 
 
       # executes a +msearch+ by provided *RAW* queries.
       # Does NOT instantiate records.
       # @param [Array<String>] queries
-      # @param [Boolean] async (default: false)
-      def msearch(queries, async: false)
+      def msearch(queries)
         # build new msearch query
         query = ElasticsearchRecord::Query.new(
           index: table_name,
@@ -122,7 +120,7 @@ module ElasticsearchRecord
           # IMPORTANT: Always provide all columns
           columns: source_column_names)
 
-        connection.internal_exec_query(query, "#{name} Msearch", async: async)
+        connection.exec_query(query, "#{name} Msearch")
       end
 
       # executes a search by provided +RAW+ query - supports +Elasticsearch::DSL+ gem if loaded

data/lib/elasticsearch_record/relation/calculation_methods.rb

@@ -8,6 +8,12 @@ module ElasticsearchRecord
       #
       #   Person.all.count(:age)
       #   => returns the total count of all people whose age is present in database
+      #
+      #   Person.all.limit(10).count
+      #   => returns at most 10 - the SQL 'LIMIT n OFFSET m' semantic is applied on the resolved total
+      #
+      # @param [Symbol, String, nil] column_name
+      # @return [Integer, Hash]
       def count(column_name = nil)
         # fallback to default
         return super() if block_given?
@@ -36,12 +42,12 @@ module ElasticsearchRecord
           # HINT: +:__query__+ directly interacts with the query-object and sets the 'terminate_after' argument
           # see @ ElasticsearchRecord::Query#arguments & Arel::Collectors::ElasticsearchQuery#assign
           arel = spawn.unscope!(:offset, :limit, :order, :configure, :aggs).configure!(:__query__, argument: { terminate_after: limit_value }).arel
-          klass.connection.select_count(arel, "#{klass.name} Count")
+          _resolve_limited_count(klass.connection.select_count(arel, "#{klass.name} Count"))
         else
           # since total will be limited to 10000 results, we need to resolve the real values by a custom query.
           # This query is called through +#select_count+.
           arel = spawn.unscope!(:offset, :limit, :order, :configure, :aggs)
-          klass.connection.select_count(arel, "#{klass.name} Count")
+          _resolve_limited_count(klass.connection.select_count(arel, "#{klass.name} Count"))
         end
       end
 
@@ -129,9 +135,17 @@ module ElasticsearchRecord
       #
       # @note returns *nil* on a *NullRelation*
       #
+      # PLEASE NOTE: the aggregation quantifies the relationship BETWEEN fields, so it requires at
+      # least two of them. A single column would additionally take the 'field'-branch of
+      # +#calculate_aggregation+ - but the metric only accepts a 'fields' node.
+      #
       # @param [Array<Symbol|String>] column_names
+      # @raise [ArgumentError] if less than two columns were provided
       # @return [Hash,nil]
       def matrix_stats(*column_names)
+        # ensure minimum number of names are provided
+        raise(ArgumentError, "Unable to build a 'matrix_stats' aggregation with less than two columns (#{column_names.size} provided) @ #{klass.name}!") if column_names.size < 2
+
         calculate_aggregation(:matrix_stats, *column_names)
       end
 
@@ -316,6 +330,28 @@ module ElasticsearchRecord
       end
 
       alias_method :calculate, :calculate_aggregation
+
+      private
+
+      # applies the SQL +LIMIT n OFFSET m+ semantic onto an already resolved total.
+      #
+      # IMPORTANT: Elasticsearch always answers a count with the FULL total. The +terminate_after+
+      # argument (see @ +#count+) cannot provide this semantic on its own:
+      # - it limits the *collected* documents, but a count query collects none - so it never fires
+      # - and it acts PER SHARD, which would resolve +limit * shards+ on a multi-shard index
+      #
+      # Clamping the resolved total is exact either way: a per-shard early termination can only
+      # return a value between +min(limit, total)+ and +total+, so the minimum stays the same.
+      #
+      # @param [Integer] total - the resolved (full) total
+      # @return [Integer]
+      def _resolve_limited_count(total)
+        # the offset is subtracted first - it can never result in a negative count
+        total -= offset_value if offset_value
+        return 0 if total < 0
+
+        limit_value ? [total, limit_value].min : total
+      end
     end
   end
 end

data/lib/elasticsearch_record/relation/query_methods.rb

@@ -50,6 +50,7 @@ module ElasticsearchRecord
       end
 
       # same like +#configure!+, but on the same relation (no spawn)
+      # @return [self]
       def configure!(*args)
         check_if_method_has_arguments!(__callee__, args)
 
@@ -274,6 +275,27 @@ module ElasticsearchRecord
         self
       end
 
+      # overwrite to prevent metadata fields within the projection.
+      # Metadata fields (like '_id' or '_score') are NOT part of the +_source+ node, so they cannot be
+      # resolved through the +_source+-filter this method builds - providing them would silently create
+      # a filter that never matches.
+      # HINT: This is different to the +pluck+-method which allows to resolve meta keys directly.
+      # see @ Arel::Visitors::ElasticsearchQuery#visit_Selects
+      # @param [Array] fields
+      def select(*fields)
+        # IMPORTANT: +select+ can also be called with a block (and without any fields) - in this case
+        # ActiveRecord directly forwards to +super()+, so we must not interfere here.
+        if fields.any? && (invalid = _invalid_projection_fields(fields)).present?
+          raise(ActiveRecord::UnknownAttributeReference,
+                "Unable to select metadata attributes: #{invalid.map(&:inspect).join(", ")}. " \
+                "Metadata fields are not part of the '_source' node but are always returned and accessible within the record. " \
+                "(e.g. #{klass.name}.first.#{invalid.first})."
+          )
+        end
+
+        super
+      end
+
       private
 
       def build_where_clause(opts, _rest = [])
@@ -342,6 +364,14 @@ module ElasticsearchRecord
 
         arel
       end
+
+      # returns any provided field that is a metadata field and therefore not resolvable
+      # through a projection.
+      # @param [Array] fields
+      # @return [Array<String>]
+      def _invalid_projection_fields(fields)
+        ActiveRecord::ConnectionAdapters::ElasticsearchAdapter.metadata_keys & fields.flatten.select{|fld| fld.is_a?(String) || fld.is_a?(Symbol)}.map(&:to_s)
+      end
     end
   end
 end

data/lib/elasticsearch_record/relation/result_methods.rb

@@ -66,7 +66,7 @@ module ElasticsearchRecord
       # @return [nil, String] - either returns the pit_id (no block given) or nil
       def point_in_time(keep_alive: '1m')
         # resolve a initial PIT id
-        initial_pit_id = klass.connection.api(:core, :open_point_in_time, { index: klass.table_name, keep_alive: keep_alive }, "#{klass} Open Pit").dig('id')
+        initial_pit_id = klass.connection.api(:open_point_in_time, { index: klass.table_name, keep_alive: keep_alive }, "#{klass} Open Pit").dig('id')
 
         return initial_pit_id unless block_given?
 
@@ -74,7 +74,7 @@ module ElasticsearchRecord
         yield initial_pit_id
 
         # close PIT
-        klass.connection.api(:core, :close_point_in_time, { body: { id: initial_pit_id } }, "#{klass} Close Pit")
+        klass.connection.api(:close_point_in_time, { body: { id: initial_pit_id } }, "#{klass} Close Pit")
 
         # return nil if everything was ok
         nil
@@ -90,13 +90,12 @@ module ElasticsearchRecord
       #
       # @param [String] keep_alive - how long to keep alive (for each single request) - default: '1m'
       # @param [Integer] batch_size - how many results per query (default: 1000 - this means at least 10 queries before reaching the +max_result_window+)
-      # @param [Boolean] ids_only - resolve ids only from results
       # @return [Integer, Array] either returns the results-array (no block provided) or the total amount of results
-      def pit_results(keep_alive: '1m', batch_size: 1000, ids_only: false)
-        raise(ArgumentError, "Batch size cannot be above the 'max_result_window' (#{klass.max_result_window}) !") if batch_size > klass.max_result_window
+      def pit_results(keep_alive: '1m', batch_size: 1000)
+        raise(ArgumentError, "Batch size cannot be above the 'max_result_window' (#{batch_size} > #{klass.max_result_window}) !") if batch_size > klass.max_result_window
 
         # check if limit or offset values where provided
-        results_limit  = limit_value ? limit_value : Float::INFINITY
+        results_limit = limit_value ? limit_value : Float::INFINITY
         results_offset = offset_value ? offset_value : 0
 
         # search_after requires a order - we resolve a order either from provided value or by default ...
@@ -107,9 +106,6 @@ module ElasticsearchRecord
         # see @ https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html
         relation.order!(_shard_doc: :asc) if relation.order_values.empty? && klass.connection.access_shard_doc?
 
-        # resolve ids only
-        relation.reselect!('_id') if ids_only
-
         # clear limit & offset
         relation.offset!(nil).limit!(nil)
 
@@ -117,47 +113,47 @@ module ElasticsearchRecord
         relation.configure!(:__query__, { index: nil })
 
         # we store the results in this array
-        results       = []
+        results = []
         results_total = 0
 
         # resolve a new pit and auto-close after we finished
         point_in_time(keep_alive: keep_alive) do |pit_id|
+          # set the initial pit hash, used to configure the ES query
           current_pit_hash = { pit: { id: pit_id, keep_alive: keep_alive } }
 
           # resolve new data until we got all we need
           loop do
             # change pit settings & limit (spawn is required, since a +resolve+ will make the relation immutable)
-            current_response = relation.spawn.configure!(current_pit_hash).limit!(batch_size).resolve('Pit Results').response
+            # @type [ElasticsearchRecord::Result]
+            current_result = relation.spawn.configure!(current_pit_hash).limit!(batch_size).resolve('Pit Results')
 
-            # resolve only data from hits->hits[{_source}]
-            current_results        = if ids_only
-                                       current_response['hits']['hits'].map { |result| result['_id'] }
-                                     else
-                                       current_response['hits']['hits'].map { |result| result['_source'].merge('_id' => result['_id']) }
-                                     end
+            # resolve all results, depending on the existing query (select, ...)
+            current_results = current_result.to_ary
 
+            # temporary store the absolute length - used for pagination or stop
             current_results_length = current_results.length
 
             # check if we reached the required offset
             if results_offset < current_results_length
               # check for parts
-              # (maybe a offset 6300 was provided but the batch size is 1000 - so we need to skip a part ...)
+              # (maybe an offset of 6300 was provided but the batch size is 1000 - so we need to skip a part ...)
               results_from = results_offset > 0 ? results_offset : 0
-              results_to   = (results_total + current_results_length - results_from) > results_limit ? results_limit - results_total + results_from - 1 : -1
+              results_to = (results_total + current_results_length - results_from) > results_limit ? results_limit - results_total + results_from - 1 : -1
 
-              ranged_results = current_results[results_from..results_to]
+              # reduce the *current_results* by calculated +from..to+ range
+              current_results = current_results[results_from..results_to] if results_from != 0 || results_to != -1
 
               if block_given?
-                yield ranged_results
+                yield current_results
               else
-                results += ranged_results
+                results += current_results
               end
 
               # add to total
-              results_total += ranged_results.length
+              results_total += current_results.length
             end
 
-            # -------- BREAK conditions --------
+            # -- BREAK conditions --------------------------------------------------------------------------------------
 
             # we reached our maximum value
             break if results_total >= results_limit
@@ -166,22 +162,24 @@ module ElasticsearchRecord
             break if current_results_length < batch_size
 
             # additional security - prevents infinite loops
-            raise(::ActiveRecord::StatementInvalid, "'pit_results' aborted due an infinite loop error (invalid or missing order)") if current_pit_hash[:search_after] == current_response['hits']['hits'][-1]['sort'] && current_pit_hash[:pit][:id] == current_response['pit_id']
+            if current_pit_hash[:search_after] == current_result.response['hits']['hits'][-1]['sort'] && current_pit_hash[:pit][:id] == current_result.response['pit_id']
+              raise(::ActiveRecord::StatementInvalid, "'pit_results' aborted due an infinite loop error (invalid or missing order)")
+            end
 
-            # -------- NEXT LOOP changes --------
+            # -- NEXT LOOP changes -------------------------------------------------------------------------------------
 
             # reduce the offset
             results_offset -= current_results_length
 
             # assign new pit
-            current_pit_hash = { search_after: current_response['hits']['hits'][-1]['sort'], pit: { id: current_response['pit_id'], keep_alive: keep_alive } }
+            current_pit_hash = { search_after: current_result.response['hits']['hits'][-1]['sort'], pit: { id: current_result.response['pit_id'], keep_alive: keep_alive } }
 
-            # we need to justify the +batch_size+ if the query will reach over the limit
-            batch_size       = results_limit - results_total if results_offset < batch_size && (results_total + batch_size) > results_limit
+            # we need to justify the +batch_size+ if the query reaches over the limit
+            batch_size = results_limit - results_total if results_offset < batch_size && (results_total + batch_size) > results_limit
           end
         end
 
-        # return results array or total value
+        # returns either to total number of +pit+ results or an array of all collected results
         if block_given?
           results_total
         else
@@ -193,17 +191,19 @@ module ElasticsearchRecord
 
       # executes a delete query in a +point_in_time+ scope.
       # this will provide the possibility to delete more than the +max_result_window+ (default: 10000) docs in a batched process.
-      # @param [String] keep_alive
-      # @param [Integer] batch_size
-      # @param [Boolean] refresh index after delete finished (default: true)
+      # @param [String] keep_alive - defines the keep alive time per +pit+ (not in total) - should be relative to *batch_size*
+      # @param [Integer] batch_size - the size of entries to delete per +pit+
+      # @param [Boolean] refresh - auto-refresh index after delete finished (default: true)
       # @return [Integer] total amount of deleted docs
-      def pit_delete(keep_alive: '1m', batch_size: 1000, refresh: true)
-        delete_count = select('_id').pit_results(keep_alive: keep_alive, batch_size: batch_size, ids_only: true) do |ids|
+      def pit_delete(keep_alive: '1m', batch_size: 1_000, refresh: true)
+        # spawns a new query with disabled results (so only ids will be resolved)
+        delete_count = spawn.meta_only!.pit_results(keep_alive: keep_alive, batch_size: batch_size) do |results|
           # skip empty results
-          next unless ids.any?
+          next unless results.any?
 
-          # delete all IDs, but do not refresh index, yet
-          klass.connection.api(:core, :bulk, { index: klass.table_name, body: ids.map { |id| { delete: { _id: id } } }, refresh: false }, "#{klass} Pit Delete")
+          # delete all IDs through +API+
+          # does not refresh index at this point (this is done below, if not disabled)
+          klass.connection.api(:bulk, { index: klass.table_name, body: results.map { |result| { delete: { _id: result['_id'] } } }, refresh: false }, "#{klass} Pit Delete")
         end
 
         # refresh index
@@ -249,24 +249,28 @@ module ElasticsearchRecord
       end
 
       # sets query as "hits"-only query (drops the aggs from the query)
+      # @return [self]
       def hits_only!
         configure!({ aggs: nil })
-
-        self
       end
 
       # sets query as "aggs"-only query (drops the size & sort options - so no hits will return)
+      # @return [self]
       def aggs_only!
         configure!({ size: 0, from: nil, sort: nil, _source: false })
-
-        self
       end
 
       # sets query as "total"-only query (drops the size, sort & aggs options - so no hits & aggs will be returned)
+      # @return [self]
       def total_only!
         configure!({ size: 0, from: nil, aggs: nil, sort: nil, _source: false })
+      end
 
-        self
+      # sets query as "meta"-only query (drops aggs and source).
+      # This is used to prevent resolving documents from the index and only returns "meta" information (like _id, _score, _type, ...)
+      # @return [self]
+      def meta_only!
+        select(::ElasticsearchRecord::Query::COLUMNS_NONE).configure!({ aggs: nil, _source: false })
       end
     end
   end