elasticsearch_record 1.4.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a386dd571b2e88a62e26f815c16783d3fda97ed911b4edffa4db884230dfc18
-  data.tar.gz: a50697c2043a3160c31716d07d9afbe05bab691267773b92f424bead64193ecb
+  metadata.gz: b6e4ca9acc6ee9abda4a3dacec4a75f9f1af77c361dbff3b53aa30648dfa5a5f
+  data.tar.gz: f6cf2edda611efb7daa6585764c09c2320040c8970555d64dab96ced763d2f19
 SHA512:
-  metadata.gz: 4c3172895b50805a17964e0db2406b90fd5797c40d91d17ee9c0cea2a26d0b52d328663f5b44ff882d32bf490662146ef5064040361ae5a677d97868078332b5
-  data.tar.gz: 3d86fb89924f99c2ad64e44c225f78c434cabcbadc4660dfa8032c5038394b05b5ab949abd93d9895b3a7148c07f12ac99374c8cee1c2ce805f2188eab6be143
+  metadata.gz: 1d9327c0b6500d47ec5459ebd5e6053d8178d59b33cd690d5f9a2752ec22cc52d2728b295dd4644c5f7fa6b794c6a8d69305b372c6c138e2ae8c717500669453
+  data.tar.gz: 050e345874250113d23c69d4de6d3c8f35c7c6b4538fe8d1ee3dbeaf86a64dc7c745175a8301c5d78121481927bff34033a321e390fbaddf3356110951afb3c4

data/README.md

@@ -14,10 +14,8 @@ _ElasticsearchRecord is a ActiveRecord adapter and provides similar functionalit
 
 **PLEASE NOTE:**
 
-- This is still in **development**!
-- Specs & documentation will follow. 
-- You might experience BUGs and Exceptions...
-- Currently supports only ActiveRecord 7.0 + Elasticsearch 8.4 _(downgrade for rails 6.x is planned in future versions)_
+- Specs & documentation are still missing, but will follow.
+- Currently supports ActiveRecord ~> 7.0 + Elasticsearch >= 7.17
 
 -----
 
@@ -58,12 +56,13 @@ Or install it yourself as:
 ## Setup
 
 ### a) Update your **database.yml** and add a elasticsearch connection:
+
 ```yml
  # config/database.yml
  
  development:
    primary:
-    # <...>
+     # <...>
 
    # elasticsearch
    elasticsearch:
@@ -71,10 +70,24 @@ Or install it yourself as:
      host: localhost:9200
      user: elastic
      password: '****'
-     log: true
+     
+     # enable ES verbose logging
+     # log: true
+     
+     # add table (index) prefix & suffix to all 'tables'
+     # table_name_prefix: 'app-'
+     # table_name_suffix: '-development'
  
  production:
-   ...
+   # <...>
+
+   # elasticsearch
+   elasticsearch:
+     # <...>
+   
+     # add table (index) prefix & suffix to all 'tables'
+     # table_name_prefix: 'app-'
+     # table_name_suffix: '-production'
  
  test:
    ...
@@ -82,15 +95,19 @@ Or install it yourself as:
  
 ```
 
-### b) Require ```elasticsearch_record/instrumentation``` in your application.rb (if you want to...):
+### b) Require `elasticsearch_record/instrumentation` in your application.rb (if you want to...):
+
 ```ruby
 # config/application.rb
+
 require_relative "boot"
 
 require "rails"
 # Pick the frameworks you want:
 
-# ...
+# <...>
+
+# add instrumentation
 require 'elasticsearch_record/instrumentation'
 
 module Application
@@ -98,17 +115,29 @@ module Application
 end
 ```
 
-### c) Create a model that inherits from ```ElasticsearchRecord::Base``` model.
+### c) Create a model that inherits from `ElasticsearchRecord::Base` model.
+
 ```ruby
 # app/models/application_elasticsearch_record.rb
-   
-class Search < ElasticsearchRecord::Base
-   
+
+class ApplicationElasticsearchRecord < ElasticsearchRecord::Base
+  # needs to be abstract
+  self.abstract_class = true
 end
+```
+
+Example class, that inherits from **ApplicationElasticsearchRecord**
 
+```ruby
+# app/models/search.rb
+   
+class Search < ApplicationElasticsearchRecord
+  
+end
 ```
 
 ### d) have FUN with your model:
+
 ```ruby
 scope = Search
         .where(name: 'Custom Object Name')
@@ -129,12 +158,13 @@ scope.where(kind: :undefined).offset(10).update_all(name: "New Name")
 
 ## Active Record Query Interface
 
-### Refactored ```where``` method:
+### Refactored `where` method:
 Different to the default where-method you can now use it in different ways.
 
 Using it by default with a Hash, the method decides itself to either add a filter, or must_not clause.
 
-_Hint: If not provided through ```#kind```-method a default kind **:bool** will be used._
+_Hint: If not provided through `#kind`-method a default kind **:bool** will be used._
+
 ```ruby
 # use it by default
 Search.where(name: 'A nice object')
@@ -187,7 +217,6 @@ results_count = scope.count
 # > 5
 total = scope.total
 # > 3335
-
 ```
 
 ### Available query/relation chain methods
@@ -239,11 +268,79 @@ _see simple documentation about these methods @ [rubydoc](https://rubydoc.info/g
 
 -----
 
-### Useful model class attributes
-- index_base_name
-- relay_id_attribute
+## Useful model class attributes
+
+### index_base_name
+Rails resolves a pluralized underscore table_name from the class name by default - which will not work for some models.
+
+To support a generic +table_name_prefix+ & +table_name_suffix+ from the _database.yml_, 
+the 'index_base_name' provides a possibility to chain prefix, **base** and suffix.
+
+```ruby
+class UnusalStat < ApplicationElasticsearchRecord
+  self.index_base_name = 'unusal-stats'
+end
+
+UnusalStat.where(year: 2023).to_query
+# => {:index=>"app-unusal-stats-development", :body ...
+```
+
+### delegate_id_attribute
+Rails resolves the primary_key's value by accessing the **#id** method.
+
+Since Elasticsearch also supports an additional, independent **id** attribute,
+it would only be able to access this through `_read_attribute(:id)`.
+
+To also have the ability of accessing this attribute through the default, this flag can be enabled.
+
+```ruby
+class SearchUser < ApplicationElasticsearchRecord
+  # attributes: id, name
+end
+
+# create new user within the index
+user = SearchUser.create(id: 8, name: 'Parker')
+
+# accessing the id, does NOT return the stored id by default - this will be delegated to the primary_key '_id'.
+user.id
+# => 'b2e34xa2'
+
+# -- ENABLE delegation -------------------------------------------------------------------
+SearchUser.delegate_id_attribute = true
+
+# create new user within the index
+user = SearchUser.create(id: 9, name: 'Pam')
+
+# accessing the id accesses the stored attribute now
+user.id
+# => 9
+
+# accessing the ES index id
+user._id
+# => 'xtf31bh8x'
+```
+
+## delegate_query_nil_limit
+Elasticsearch's default value for queries without a **size** is forced to **10**.
+To provide a similar behaviour as the (my)SQL interface,
+this can be automatically set to the `max_result_window` value by calling `.limit(nil)` on the models' relation.
+
+```ruby
+SearchUser.where(name: 'Peter').limit(nil)
+# returns a maximum of 10 items ...
+# => [...]
+
+# -- ENABLE delegation -------------------------------------------------------------------
+SearchUser.delegate_query_nil_limit = true
 
-### Useful model class methods
+SearchUser.where(name: 'Peter').limit(nil)
+# returns up to 10_000 items ...
+# => [...]
+
+# hint: if you want more than 10_000 use the +#pit_results+ method!
+```
+
+## Useful model class methods
 - auto_increment?
 - max_result_window
 - source_column_names
@@ -251,26 +348,29 @@ _see simple documentation about these methods @ [rubydoc](https://rubydoc.info/g
 - find_by_query
 - msearch
 
-### Useful model API methods
-Fast access to model-related methods for easier access without creating a overcomplicated method call.
+## Useful model API methods
+Quick access to model-related methods for easier access without creating a overcomplicated method call on the models connection...
 
 Access these methods through the model class method `.api`.
+
 ```ruby
-  # returns mapping of model class
-  klass.api.mappings
+# returns mapping of model class
+klass.api.mappings
 
-  # e.g. for ElasticUser model
-  ElasticUser.api.mappings
+# e.g. for ElasticUser model
+SearchUser.api.mappings
 
-  # insert new raw data
-  ElasticUser.api.insert([{name: 'Hans', age: 34}, {name: 'Peter', age: 22}])
+# insert new raw data
+SearchUser.api.insert([{name: 'Hans', age: 34}, {name: 'Peter', age: 22}])
 ```
 
-* open
-* close
-* refresh
-* block
-* unblock
+* open!
+* close!
+* refresh!
+* block!
+* unblock!
+* drop!(confirm: true)
+* truncate!(confirm: true)
 * mappings
 * metas
 * settings
@@ -290,12 +390,14 @@ Fast insert, update, delete raw data
 * delete
 * bulk
 
+-----
+
 ## ActiveRecord ConnectionAdapters table-methods
 Access these methods through the model class method `.connection`.
 
 ```ruby
-  # returns mapping of provided table (index)
-  klass.connection.table_mappings('table-name')
+# returns mapping of provided table (index)
+klass.connection.table_mappings('table-name')
 ```
 
 - table_mappings
@@ -316,7 +418,7 @@ Access these methods through the model class method `.connection`.
 ## Active Record Schema migration methods
 Access these methods through the model's connection or within any `Migration`.
 
-**cluster actions:**
+### cluster actions:
 - open_table
 - open_tables
 - close_table
@@ -333,7 +435,7 @@ Access these methods through the model's connection or within any `Migration`.
 - change_table
 - rename_table
 
-**table actions:**
+### table actions:
 - change_meta
 - remove_meta
 - add_mapping
@@ -348,8 +450,10 @@ Access these methods through the model's connection or within any `Migration`.
 - change_alias
 - remove_alias
 
+
+**Example migration:**
+
 ```ruby
-# Example migration
 class AddTests < ActiveRecord::Migration[7.0]
   def up
     create_table "assignments", if_not_exists: true do |t|
@@ -422,6 +526,49 @@ class AddTests < ActiveRecord::Migration[7.0]
 end
 ```
 
+## environment-related-table-name:
+Using the `_env_table_name`-method will resolve the table (index) name within the current environment,
+even if the environments shares the same cluster ...
+
+This can be provided through the `database.yml` by using the `table_name_prefix/suffix` configuration keys.
+Within the migration the `_env_table_name`-method must be used in combination with the table (index) base name.
+
+**Example:**
+Production uses a index suffix with '-pro', development uses '-dev' - they share the same cluster, but different indexes.
+
+For the **settings** table:
+
+* settings-pro
+* settings-dev
+
+A single migration can be created to be used within each environment:
+
+```ruby
+# Example migration
+class AddSettings < ActiveRecord::Migration[7.0]
+  def up
+    create_table _env_table_name("settings"), force: true do |t|
+      t.mapping :created_at, :date
+      t.mapping :key, :integer do |m|
+        m.primary_key = true
+        m.auto_increment = 10
+      end
+      t.mapping :status, :keyword
+      t.mapping :updated_at, :date
+      t.mapping :value, :text
+
+      t.setting "index.number_of_replicas", "0"
+      t.setting "index.number_of_shards", "1"
+      t.setting "index.routing.allocation.include._tier_preference", "data_content"
+    end
+  end 
+  
+  def down
+    drop_table _env_table_name("settings")
+  end
+end 
+```
+
 ## Docs
 
 [CHANGELOG](docs/CHANGELOG.md)

data/docs/CHANGELOG.md

@@ -1,5 +1,21 @@
 # ElasticsearchRecord - CHANGELOG
 
+## [1.5.1] - 2023-07-11
+* [fix] `ElasticsearchRecord::ModelApi` 'drop!' & 'truncate!' methods to support correct parameter 'confirm'
+* [ref] improved yard documentation
+
+## [1.5.0] - 2023-07-10
+* [add] additional `ElasticsearchRecord::ModelApi` methods **drop!** & **truncate!**, which have to be called with a `confirm:true` parameter
+* [add] `.ElasticsearchRecord::Base.delegate_query_nil_limit` to automatically delegate a relations `limit(nil)`-call to the **max_result_window** _(set to 10.000 as default)_
+* [add] `ActiveRecord::ConnectionAdapters::Elasticsearch::SchemaStatements#access_shard_doc?` which checks, if the **PIT**-shard_doc order is available
+* [add] support for **_shard_doc** as a default order for `ElasticsearchRecord::Relation#pit_results`
+* [ref] `.ElasticsearchRecord::Base.relay_id_attribute` to a more coherent name: `delegate_id_attribute` 
+* [ref] `ElasticsearchRecord::Relation#ordered_relation` to optimize already ordered relations
+* [ref] gemspecs to support different versions of Elasticsearch
+* [ref] improved README
+* [fix] `ElasticsearchRecord::Relation#pit_results` infinite loop _(caused by missing order)_
+* [fix] `ElasticsearchRecord::Relation#pit_results` results generation without 'uniq' check of the array
+
 ## [1.4.0] - 2023-01-27
 * [add] `ElasticsearchRecord::ModelApi` for fast & easy access the elasticsearch index - callable through `.api` (e.g. ElasticUser.api.mappings)
 * [ref] `ElasticsearchRecord::Instrumentation::LogSubscriber` to truncate the query-string (default: 1000)

data/elasticsearch_record.gemspec

@@ -32,12 +32,13 @@ DESC
 
   spec.require_paths = ["lib"]
 
-  spec.add_dependency 'activerecord', '~> 7.0.0'
-  spec.add_dependency 'elasticsearch', '~> 8.4'
+  spec.add_dependency 'activerecord', '~> 7.0'
+  spec.add_dependency 'elasticsearch', '>= 7.17'
 
   #spec.add_development_dependency 'coveralls_reborn', '~> 0.25'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rake', "~> 13.0"
   spec.add_development_dependency 'yard', '~> 0.9'
   spec.add_development_dependency 'yard-activesupport-concern', '~> 0.0.1'
+  spec.add_development_dependency 'yard-relative_markdown_links', '>= 0.4'
 end

data/lib/active_record/connection_adapters/elasticsearch/schema_definitions/table_mapping_definition.rb

@@ -100,7 +100,7 @@ module ActiveRecord
         end
 
         # returns the meta hash
-        # @param [Hash]
+        # @return [Hash]
         def meta
           __get_attribute(:meta) || {}
         end

data/lib/active_record/connection_adapters/elasticsearch/schema_statements.rb

@@ -376,6 +376,14 @@ module ActiveRecord
             @access_id_fielddata
           end
 
+          # returns true if +_shard_doc+ field can be accessed through PIT-search.
+          # @return [Boolean]
+          def access_shard_doc?
+            @access_shard_doc = cluster_info[:version] >= "7.12" if @access_shard_doc.nil?
+
+            @access_shard_doc
+          end
+
           # Returns basic information about the cluster.
           # @return [Hash{Symbol->Unknown}]
           def cluster_info

data/lib/elasticsearch_record/core.rb

@@ -5,20 +5,25 @@ module ElasticsearchRecord
     included do
       # Rails resolves the primary_key's value by accessing the +#id+ method.
       # Since Elasticsearch also supports an additional, independent +id+ attribute, it would only be able to access
-      # this through +read_attribute(:id)+.
+      # this through +_read_attribute(:id)+.
       # To also have the ability of accessing this attribute through the default, this flag can be enabled.
       # @attribute! Boolean
-      class_attribute :relay_id_attribute, instance_writer: false, default: false
+      class_attribute :delegate_id_attribute, instance_writer: false, default: false
+
+      # Elasticsearch's default value for queries without a +size+ is forced to +10+.
+      # To provide a similar behaviour as SQL, this can be automatically set to the +max_result_window+ value.
+      # @attribute! Boolean
+      class_attribute :delegate_query_nil_limit, 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
-    # with enabled +relay_id_attribute+.
+    # with enabled +delegate_id_attribute+.
     # @return [Object]
     def id
       # check, if the model has a +id+ attribute
-      return _read_attribute('id') if relay_id_attribute? && has_attribute?('id')
+      return _read_attribute('id') if delegate_id_attribute? && has_attribute?('id')
 
       super
     end
@@ -26,11 +31,11 @@ module ElasticsearchRecord
     # 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
-    # with enabled +relay_id_attribute+.
+    # with enabled +delegate_id_attribute+.
     # @param [Object] value
     def id=(value)
       # check, if the model has a +id+ attribute
-      return _write_attribute('id', value) if relay_id_attribute? && has_attribute?('id')
+      return _write_attribute('id', value) if delegate_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'
@@ -41,13 +46,13 @@ module ElasticsearchRecord
     # 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
-    # with enabled +relay_id_attribute+.
+    # with enabled +delegate_id_attribute+.
     def id_was
-      relay_id_attribute? && has_attribute?('id') ? attribute_was('id') : super
+      delegate_id_attribute? && has_attribute?('id') ? attribute_was('id') : super
     end
 
     # overwrite the write_attribute method to always write to the 'id'-attribute, if present.
-    # This methods does not check for +relay_id_attribute+ flag!
+    # This methods does not check for +delegate_id_attribute+ flag!
     # 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')
@@ -56,7 +61,7 @@ module ElasticsearchRecord
     end
 
     # overwrite read_attribute method to read from the 'id'-attribute, if present.
-    # This methods does not check for +relay_id_attribute+ flag!
+    # This methods does not check for +delegate_id_attribute+ flag!
     # 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')

data/lib/elasticsearch_record/gem_version.rb

@@ -8,8 +8,8 @@ module ElasticsearchRecord
 
   module VERSION
     MAJOR = 1
-    MINOR = 4
-    TINY  = 0
+    MINOR = 5
+    TINY  = 1
     PRE   = nil
 
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

data/lib/elasticsearch_record/model_api.rb

@@ -8,18 +8,47 @@ module ElasticsearchRecord
       @klass = klass
     end
 
-    # undelegated schema methods: clone rename create drop
+    # undelegated schema methods: clone rename create
     # those should not be quick-accessible, since they might end in heavily broken index
 
     # delegated dangerous methods (created with exclamation mark)
-    # not able to provide individual arguments - always the defaults will be used
+    # not able to provide individual arguments - always the defaults will be used!
+    #
+    # @example
+    #   open!
+    #   close!
+    #   refresh!
+    #   block!
+    #   unblock!
     %w(open close refresh block unblock).each do |method|
       define_method("#{method}!") do
         _connection.send("#{method}_table", _index_name)
       end
     end
 
+    # delegated dangerous methods with confirm parameter (created with exclamation mark)
+    # a exception will be raised, if +confirm:true+ is missing.
+    #
+    # @example
+    #   drop!(confirm: true)
+    #   truncate!(confirm: true)
+    %w(drop truncate).each do |method|
+      define_method("#{method}!") do |confirm: false|
+        raise "#{method} of table '#{_index_name}' aborted!\nexecution not confirmed!\ncall with: #{klass}.api.#{method}!(confirm: true)" unless confirm
+        _connection.send("#{method}_table", _index_name)
+      end
+    end
+
     # delegated table methods
+    #
+    # @example
+    #   mappings
+    #   metas
+    #   settings
+    #   aliases
+    #   state
+    #   schema
+    #   exists?
     %w(mappings metas settings aliases state schema exists?).each do |method|
       define_method(method) do |*args|
         _connection.send("table_#{method}", _index_name, *args)
@@ -27,12 +56,96 @@ module ElasticsearchRecord
     end
 
     # delegated plain methods
+    #
+    # @example
+    #   alias_exists?
+    #   setting_exists?
+    #   mapping_exists?
+    #   meta_exists?
     %w(alias_exists? setting_exists? mapping_exists? meta_exists?).each do |method|
       define_method(method) do |*args|
         _connection.send(method, _index_name, *args)
       end
     end
 
+    # -- DYNAMIC METHOD DOCUMENTATION FOR YARD -------------------------------------------------------------------------
+
+    # @!method open!
+    # Shortcut to open the closed index.
+    # @return [Boolean] acknowledged status
+
+    # @!method close!
+    # Shortcut to close the opened index.
+    # @return [Boolean] acknowledged status
+
+    # @!method refresh!
+    # Shortcut to refresh the index.
+    # @return [Boolean] result state (returns false if refreshing failed)
+
+    # @!method block!
+    # Shortcut to block write access on the index
+    # @return [Boolean] acknowledged status
+
+    # @!method unblock!
+    # Shortcut to unblock all blocked accesses on the index
+    # @return [Boolean] acknowledged status
+
+    # @!method drop!(confirm: false)
+    # Shortcut to drop the index
+    # @param confirm
+    # @return [Boolean] acknowledged status
+
+    # @!method truncate!(confirm: false)
+    # Shortcut to truncate the index
+    # @param confirm
+    # @return [Boolean] acknowledged status
+
+    # @!method mappings
+    # Shortcut for mappings
+    # @return [Hash]
+
+    # @!method metas
+    # Shortcut for metas
+    # @return [Hash]
+
+    # @!method settings(flat_settings=true)
+    # Shortcut for settings
+    # @param [Boolean] flat_settings (default: true)
+    # @return [Hash]
+
+    # @!method aliases
+    # Shortcut for aliases
+    # @return [Hash]
+
+    # @!method state
+    # Shortcut for state
+    # @return [Hash]
+
+    # @!method schema(features=[])
+    # Shortcut for schema
+    # @param [Array, Symbol] features
+    # @return [Hash]
+
+    # @!method exists?
+    # Shortcut for exists
+    # @return [Boolean]
+
+    # @!method alias_exists?
+    # Shortcut for alias_exists
+    # @return [Boolean]
+
+    # @!method setting_exists?
+    # Shortcut for setting_exists
+    # @return [Boolean]
+
+    # @!method mapping_exists?
+    # Shortcut for mapping_exists
+    # @return [Boolean]
+
+    # @!method meta_exists?
+    # Shortcut for meta_exists
+    # @return [Boolean]
+
     # fast insert/update data.
     #
     # @example
@@ -89,7 +202,7 @@ module ElasticsearchRecord
       if data[0].is_a?(Hash)
         bulk(data, :delete, **options)
       else
-        bulk(data.map{|id| {id: id}}, :delete, **options)
+        bulk(data.map { |id| { id: id } }, :delete, **options)
       end
     end
 
@@ -102,7 +215,7 @@ module ElasticsearchRecord
 
       _connection.api(:core, :bulk, {
         index:   _index_name,
-        body:    data.map{|item| {operation => {_id: item[:id], data: item.except(:id)}}},
+        body:    data.map { |item| { operation => { _id: item[:id], data: item.except(:id) } } },
         refresh: refresh
       }, "BULK #{operation.to_s.upcase}", **options)
     end

data/lib/elasticsearch_record/relation/core_methods.rb

@@ -99,21 +99,29 @@ module ElasticsearchRecord
       # overwrite original methods to provide a elasticsearch version:
       # checks against the +#access_id_fielddata?+ to ensure the Elasticsearch Cluster allows access on the +_id+ field.
       def ordered_relation
-        # resolve valid primary_key (either not the '_id' or +access_id_fielddata?+ is enabled)
+        # order values already exist
+        return self unless order_values.empty?
+
+        # resolve valid primary_key
+        # - either it is NOT the '_id' column
+        # OR
+        # - it is the '_id'-column, but +access_id_fielddata?+ is also enabled!
         valid_primary_key = if primary_key != '_id' || klass.connection.access_id_fielddata?
-               primary_key
-             else
-               nil
-             end
+                              primary_key
+                            else
+                              nil
+                            end
 
         # slightly changed original methods content
-        if order_values.empty? && (implicit_order_column || valid_primary_key)
+        if implicit_order_column || valid_primary_key
+          # order by +implicit_order_column+ AND +primary_key+
           if implicit_order_column && valid_primary_key && implicit_order_column != valid_primary_key
             order(table[implicit_order_column].asc, table[valid_primary_key].asc)
           else
             order(table[implicit_order_column || valid_primary_key].asc)
           end
         else
+          # order is not possible due restricted settings
           self
         end
       end

data/lib/elasticsearch_record/relation/result_methods.rb

@@ -91,15 +91,20 @@ 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+)
       def pit_results(keep_alive: '1m', batch_size: 1000)
-        raise ArgumentError, "Batch size cannot be above the 'max_result_window' (#{klass.max_result_window}) !" if batch_size > klass.max_result_window
+        raise(ArgumentError, "Batch size cannot be above the 'max_result_window' (#{klass.max_result_window}) !") if batch_size > klass.max_result_window
 
-        # check if a limit or offset values was provided
+        # check if limit or offset values where provided
         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 ...
         relation = ordered_relation
 
+        # FALLBACK (without any order) for restricted access to the '_id' field.
+        # with PIT a order by '_shard_doc' can also be used
+        # 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?
+
         # clear limit & offset
         relation.offset!(nil).limit!(nil)
 
@@ -135,7 +140,7 @@ module ElasticsearchRecord
               if block_given?
                 yield ranged_results
               else
-                results |= ranged_results
+                results += ranged_results
               end
 
               # add to total
@@ -150,8 +155,8 @@ module ElasticsearchRecord
             # we ran out of data
             break if current_results_length < batch_size
 
-            # additional security - required?
-            # break if current_pit_hash[:search_after] == current_response['hits']['hits'][-1]['sort']
+            # 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']
 
             # -------- NEXT LOOP changes --------
 

data/lib/elasticsearch_record/relation/value_methods.rb

@@ -43,6 +43,15 @@ module ElasticsearchRecord
         @values[:aggs] = value
       end
 
+      # overwrite the limit_value setter, to provide a special behaviour of auto-setting the +max_result_window+.
+      def limit=(limit)
+        if limit == '__max__' || (limit.nil? && delegate_query_nil_limit?)
+          super(max_result_window)
+        else
+          super
+        end
+      end
+
       private
 
       # alternative method to avoid redefining the const +VALID_UNSCOPING_VALUES+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elasticsearch_record
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Tobias Gonsior
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-27 00:00:00.000000000 Z
+date: 2023-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: elasticsearch
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '8.4'
+        version: '7.17'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '8.4'
+        version: '7.17'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -94,10 +94,24 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.0.1
+- !ruby/object:Gem::Dependency
+  name: yard-relative_markdown_links
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
 description: 'ElasticsearchRecord is a ActiveRecord adapter and provides similar functionality
   for Elasticsearch.
 
-'
+  '
 email:
 - info@ruby-smart.org
 executables: []
@@ -191,7 +205,7 @@ metadata:
   source_code_uri: https://github.com/ruby-smart/elasticsearch_record
   documentation_uri: https://rubydoc.info/gems/elasticsearch_record
   changelog_uri: https://github.com/ruby-smart/elasticsearch_record/blob/main/docs/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -206,8 +220,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.3.26
+signing_key:
 specification_version: 4
 summary: ActiveRecord adapter for Elasticsearch
 test_files: []