elasticsearch_record 1.2.4 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41575ee0aefe81ed3069dc81c1c0d9062ea841998a7bb4affaab885dad0a4291
-  data.tar.gz: 73e98d4b6aad0fda63df0fff562537245f2d4c95fb5f53d67ad891550d8e6b1b
+  metadata.gz: 0e7302cf1310d0d583125bf9a9e526203feb42d000569b6daca266d88ae7bb50
+  data.tar.gz: e67b0946f566b44232827244c323aa2e221796f4d0ac91adf4696179f4ba56e1
 SHA512:
-  metadata.gz: ed60e5fe591f92169d51f333c600338cd4fcee46ca6ca988625399ee522068e3b5c67738fe5b9f3fcc1cede6491cfb1b969c525d5b1af2f2ed03e93b7303237f
-  data.tar.gz: eb51b9dc16d0457905fb15589ff2542dfe0a8f59678459be910726305a3b0527e3ddcee6d7e5271e2db0d658dabd5f476eea71b4dca27c1f99375d987de50f0b
+  metadata.gz: 3fbf9f25937e5c77520af89de811c72bc9e2a51a49cbb1c6f7a77d0b2af8d2e533b3cc2fc11acf3f8b9a78ed5616c97c068cc88a1171e85bcc5611252960b345
+  data.tar.gz: f8d77b26a20ddd8db5495638fdd98da72bcd1bd6978f17d6a1a794ab436fc184e3dafa153c67b364f6c89e59c5bca1eb0a59e09b240c4ea8e6055c017eb4738c

data/README.md

@@ -198,6 +198,7 @@ total = scope.total
 - kind 
 - configure
 - aggregate
+- refresh
 - query
 - filter
 - must_not
@@ -274,6 +275,8 @@ Access these methods through the model's connection.
 - meta_exists?
 - max_result_window
 - cluster_info
+- cluster_settings
+- cluster_health
 
 ## Active Record Schema migration methods
 Access these methods through the model's connection or within any `Migration`.
@@ -285,26 +288,30 @@ Access these methods through the model's connection or within any `Migration`.
 - close_tables
 - truncate_table
 - truncate_tables
+- refresh_table
+- refresh_tables
 - drop_table
 - block_table
 - unblock_table
 - clone_table
 - create_table
 - change_table
+- rename_table
 
 **table actions:**
 - change_meta
-- delete_meta
+- remove_meta
 - add_mapping
 - change_mapping
 - change_mapping_meta
 - change_mapping_attributes
+- remove_mapping
 - add_setting
 - change_setting
-- delete_setting
+- remove_setting
 - add_alias
 - change_alias
-- delete_alias
+- remove_alias
 
 ```ruby
 # Example migration
@@ -322,6 +329,11 @@ class AddTests < ActiveRecord::Migration[7.0]
     # changes the auto-increment value
     change_meta "assignments", :auto_increment, 3625
     
+    # removes the mapping 'updated_at' from the 'assignments' index.
+    # the flag 'recreate' is required, since 'remove' is not supported for elasticsearch.
+    # this will recreate the whole index (data will be LOST!!!)
+    remove_mapping :assignments, :updated_at, recreate: true 
+    
     create_table "settings", force: true do |t|
       t.mapping :created_at, :date
       t.mapping :key, :integer do |m|
@@ -347,8 +359,8 @@ class AddTests < ActiveRecord::Migration[7.0]
       t.add_alias('supersettings')
     end
 
-    delete_alias('settings', :supersettings)
-    delete_setting('settings', 'index.search.idle.after')
+    remove_alias('settings', :supersettings)
+    remove_setting('settings', 'index.search.idle.after')
 
     change_table 'settings', force: true do |t|
       t.integer :amount_of_newbies
@@ -357,10 +369,14 @@ class AddTests < ActiveRecord::Migration[7.0]
     create_table "vintage", force: true do |t|
       t.primary_key :number
       t.string :name
+      t.string :comments
       t.timestamps
     end
 
-    change_mapping_attributes "vintage", :number, fields: {raw: {type: :keyword}}
+    change_table 'vintage', if_exists: true, recreate: true do |t|
+      t.change_mapping :number, fields: {raw: {type: :keyword}}
+      t.remove_mapping :number
+    end
   end
 
   def down

data/docs/CHANGELOG.md

@@ -1,5 +1,26 @@
 # ElasticsearchRecord - CHANGELOG
 
+## [1.3.0] - 2023-01-17
+* [add] 'metas: {}' param for `CreateTableDefinition` to provide individual meta information without providing them through 'mappings'
+* [add] 'change_'- & 'remove_'-methods for _mapping, setting & alias_  for `CreateTableDefinition`
+* [add] `ActiveRecord::ConnectionAdapters::Elasticsearch::TableMappingDefinition#meta` for easier access
+* [add] `UpdateTableDefinition#remove_mapping` to always raise an ArgumentError (now created @ `CreateTableDefinition` through change_table(x, recreate: true) )
+* [add] `_env_table_name`-syntax to `ActiveRecord::ConnectionAdapters::Elasticsearch::SchemaDumper#table` for prefixed & suffixed tables in connections
+* [add] `#cluster_health`, `#refresh_table`, `#refresh_tables` & `#rename_table` methods to 'connection'
+* [add] `#change_table` 'recreate: false' parameter to switch between a 'change' or 'recreate' of an index
+* [add] `#refresh` method to relations to explicit set the refresh value of the generated query
+* [ref] `CloneTableDefinition` to adapt settings (number_of_shards & number_of_replicas) from source table by default
+* [ref] `CreateTableDefinition#transform_mappings!` also support simple 'key->attributes' assignment of custom provided mappings
+* [ref] 'delete_'-methods into more common 'remove_'  for `UpdateTableDefinition`
+* [ref] `UpdateTableDefinition#change_mapping` to always raise an ArgumentError (now moved to `CreateTableDefinition` through change_table(x, recreate: true) )
+* [ref] `#change_table` missing '&block'
+* [ref] 'delete_'-methods into more common 'remove_' to 'connection'
+* [ref] ':\_\_claim\_\_'-operator to ':\_\_query\_\_' within `Arel::Collectors::ElasticsearchQuery`
+* [ref] update & delete queries to preset a 'refresh: true' as default _(can be overwritten through 'relation.refresh(false)' )_
+* [rem] `#clone_table` unusable '&block'
+* [rem] `#compute_table_name`-method - must be explicit provided with `#_env_table_name(name)`
+* [fix] `#where!` & `#build_where_clause` methods to also build a valid 'where_clause' in nested 'where' & 'or'
+
 ## [1.2.4] - 2022-12-15
 * [fix] missing `#visit_Arel_Nodes_In` method in `Arel::Visitors::ElasticsearchQuery` to build array conditions
 * [fix] resolving buckets from relation `ElasticsearchRecord::Result#buckets` not recognizing sub-buckets

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

@@ -16,6 +16,9 @@ module ActiveRecord
           @settings = HashWithIndifferentAccess.new
           @aliases  = HashWithIndifferentAccess.new
 
+          # before assigning new settings, we need to resolve some defaults
+          assign_default_clone_settings!
+
           transform_settings!(settings) if settings.present?
           transform_aliases!(aliases) if aliases.present?
         end
@@ -64,6 +67,12 @@ module ActiveRecord
 
         private
 
+        def assign_default_clone_settings!
+          settings = table_settings(name)
+          setting('index.number_of_shards', (settings.dig('index.number_of_shards') || 1))
+          setting('index.number_of_replicas', (settings.dig('index.number_of_replicas') || 0))
+        end
+
         def _before_exec
           block_table(self.name, :write)
         end

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

@@ -6,7 +6,7 @@ module ActiveRecord
   module ConnectionAdapters
     module Elasticsearch
       class CreateTableDefinition < TableDefinition
-        def initialize(conn, name, settings: nil, mappings: nil, aliases: nil, **opts)
+        def initialize(conn, name, settings: nil, mappings: nil, aliases: nil, metas: nil, **opts)
           super(conn, name, **opts)
 
           @settings = HashWithIndifferentAccess.new
@@ -17,6 +17,9 @@ module ActiveRecord
           transform_settings!(settings) if settings.present?
           transform_mappings!(mappings) if mappings.present?
           transform_aliases!(aliases) if aliases.present?
+          # PLEASE NOTE: metas are already provided through the mappings (['_meta']),
+          # but this will support individually provided key<->values...
+          transform_metas!(metas) if metas.present?
         end
 
         # returns an array with all +TableSettingDefinition+.
@@ -64,18 +67,23 @@ module ActiveRecord
           self
         end
 
+        def change_meta(name, value, **options)
+          # simply force full overwrite
+          meta(name, value, force: true, **options)
+        end
+
         def remove_meta(name)
           @metas.delete(name)
         end
 
         # adds a new mapping
-        def mapping(name, type, force: false, **options, &block)
+        def mapping(name, type, if_not_exists: false, force: false, **options, &block)
+          return if if_not_exists && @mappings.key?(name)
           raise ArgumentError, "you cannot define an already defined mapping '#{name}'!" if @mappings.key?(name) && !force?(force)
 
           mapping = new_mapping_definition(name, type, **options, &block)
           @mappings[name] = mapping
 
-
           # check if the mapping is assigned as primary_key
           if mapping.primary_key?
             meta :primary_key, mapping.name
@@ -86,16 +94,51 @@ module ActiveRecord
         end
 
         # provide backwards compatibility to columns
-        alias column mapping
+        alias :column :mapping
+        alias :add_mapping :mapping
+        alias :add_column :mapping
+
+        def change_mapping(name, type, if_exists: false, **options, &block)
+          return if if_exists && !@mappings.key?(name)
+
+          raise ArgumentError, "you cannot change an unknown mapping '#{name}'" unless @mappings.key?(name)
+
+          mapping(name, type, force: true, **options, &block)
+        end
+
+        alias :change_column :change_mapping
+        alias :change :change_mapping
+
+        def change_mapping_meta(name, **options)
+          raise ArgumentError, "you cannot change the 'meta' parameter for an unknown mapping '#{name}'" unless @mappings.key?(name)
+
+          # merge mapping options
+          opts = @mappings[name].attributes
+          opts['meta'] = @mappings[name].meta.merge(options)
+
+          mapping(name, @mappings[name].type, force: true, **opts)
+        end
+
+        def change_mapping_attributes(name, if_exists: false, **options, &block)
+          return if if_exists && !@mappings.key?(name)
+
+          raise ArgumentError, "you cannot change an unknown mapping '#{name}'" unless @mappings.key?(name)
+
+          # merge mapping attributes
+          opts = @mappings[name].attributes.merge(options)
+
+          mapping(name, @mappings[name].type, force: true, **opts, &block)
+        end
 
         def remove_mapping(name)
           @mappings.delete(name)
         end
 
         # provide backwards compatibility to columns
-        alias remove_column remove_mapping
+        alias :remove_column :remove_mapping
 
-        def setting(name, value, force: false, **options, &block)
+        def setting(name, value, if_not_exists: false, force: false, **options, &block)
+          return if if_not_exists && @settings.key?(name)
           raise ArgumentError, "you cannot define an already defined setting '#{name}'!" if @settings.key?(name) && !force?(force)
 
           @settings[name] = new_setting_definition(name, value, **options, &block)
@@ -103,13 +146,19 @@ module ActiveRecord
           self
         end
 
+        def change_setting(name, value, if_exists: false, **options, &block)
+          return if if_exists && !@settings.key?(name)
+
+          # simply force full overwrite
+          setting(name, value, force: true, **options, &block)
+        end
+
         def remove_setting(name)
           @settings.delete name
         end
 
-        # we can use +alias+ here, since the instance method is not a reserved keyword!
-
-        def alias(name, force: false, **options, &block)
+        def add_alias(name, if_not_exists: false, force: false, **options, &block)
+          return if if_not_exists && @aliases.key?(name)
           raise ArgumentError, "you cannot define an already defined alias '#{name}'." if @aliases.key?(name) && !force?(force)
 
           @aliases[name] = new_alias_definition(name, **options, &block)
@@ -117,6 +166,13 @@ module ActiveRecord
           self
         end
 
+        def change_alias(name, if_exists: false, **options, &block)
+          return if if_exists && !@aliases.key?(name)
+
+          # simply force full overwrite
+          add_alias(name, force: true, **options, &block)
+        end
+
         def remove_alias(name)
           @aliases.delete name
         end
@@ -154,6 +210,51 @@ module ActiveRecord
         def state
           nil
         end
+
+        def transform_mappings!(mappings)
+          # transform +_meta+ mappings
+          if mappings['_meta'].present?
+            mappings['_meta'].each do |name, value|
+              self.meta(name, value, force: true)
+            end
+          end
+
+          # transform properties (=columns)
+          if mappings['properties'].present?
+            mappings['properties'].each do |name, attributes|
+              self.mapping(name, attributes.delete('type'), force: true, **attributes)
+            end
+          elsif mappings.present? && mappings.values[0].is_a?(Hash)
+            # raw settings where provided with just (key => attributes)
+            mappings.each do |name, attributes|
+              self.mapping(name, attributes.delete('type'), force: true, **attributes)
+            end
+          end
+        end
+
+        def transform_settings!(settings)
+          # exclude settings, that are provided through the API but are not part of the index-settings
+          settings
+            .with_indifferent_access
+            .each { |name, value|
+              # don't transform ignored names
+              next if ActiveRecord::ConnectionAdapters::Elasticsearch::TableSettingDefinition.match_ignore_names?(name)
+
+              self.setting(name, value, force: true)
+            }
+        end
+
+        def transform_aliases!(aliases)
+          aliases.each do |name, attributes|
+            self.alias(name, force: true, **attributes)
+          end
+        end
+
+        def transform_metas!(metas)
+          metas.each do |name, value|
+            self.meta(name, value, force: true)
+          end
+        end
       end
     end
   end

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

@@ -147,40 +147,6 @@ module ActiveRecord
         def strict?(strict = nil)
           opts.fetch(:strict, false) || strict
         end
-
-        def transform_mappings!(mappings)
-          # transform +_meta+ mappings
-          if mappings['_meta'].present?
-            mappings['_meta'].each do |name, value|
-              self.meta(name, value)
-            end
-          end
-
-          # transform properties (=columns)
-          if mappings['properties'].present?
-            mappings['properties'].each do |name, attributes|
-              self.mapping(name, attributes.delete('type'), **attributes)
-            end
-          end
-        end
-
-        def transform_settings!(settings)
-          # exclude settings, that are provided through the API but are not part of the index-settings
-          settings
-            .with_indifferent_access
-            .each { |name, value|
-              # don't transform ignored names
-              next if ActiveRecord::ConnectionAdapters::Elasticsearch::TableSettingDefinition.match_ignore_names?(name)
-
-              self.setting(name, value)
-            }
-        end
-
-        def transform_aliases!(aliases)
-          aliases.each do |name, attributes|
-            self.alias(name, **attributes)
-          end
-        end
       end
     end
   end

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

@@ -99,6 +99,12 @@ module ActiveRecord
           _lazy_attributes[:auto_increment] = value
         end
 
+        # returns the meta hash
+        # @param [Hash]
+        def meta
+          __get_attribute(:meta) || {}
+        end
+
         def meta=(value)
           if value.nil?
             __remove_attribute(:meta)

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

@@ -8,15 +8,13 @@ module ActiveRecord
     module Elasticsearch
       class UpdateTableDefinition < TableDefinition
 
-        attr_reader :definitions
-
         # defines which definitions can be executed composite
         COMPOSITE_DEFINITIONS = [
           AddMappingDefinition,
           ChangeMappingDefinition,
           ChangeMetaDefinition,
           AddSettingDefinition,
-          DeleteAliasDefinition
+          RemoveAliasDefinition
         ].freeze
 
         def add_mapping(name, type, if_not_exists: false, **options, &block)
@@ -35,23 +33,14 @@ module ActiveRecord
           define! ChangeMetaDefinition, new_meta_definition(name, value, **options)
         end
 
-        def delete_meta(name, **options)
+        def remove_meta(name, **options)
           load_meta_definition!
 
           define! ChangeMetaDefinition, new_meta_definition(name, nil, **options)
         end
 
-        def change_mapping(name, type, if_exists: false, **options, &block)
-          return if if_exists && !mapping_exists?(self.name, name, type)
-
-          mapping = new_mapping_definition(name, type, **options, &block)
-          define! ChangeMappingDefinition, mapping
-
-          # check if the mapping is assigned as primary_key
-          if mapping.primary_key?
-            change_meta :primary_key, mapping.name
-            change_meta(:auto_increment, mapping.auto_increment) if mapping.auto_increment?
-          end
+        def change_mapping(name, type, **options, &block)
+          raise ArgumentError, "you cannot change the mapping '#{name}' without the 'recreate: true' flag in the '#change_table' call"
         end
 
         alias :change_column :change_mapping
@@ -67,16 +56,28 @@ module ActiveRecord
           define! ChangeMappingDefinition, new_mapping_definition(name, mapping['type'], meta: meta)
         end
 
-        def change_mapping_attributes(name, **options, &block)
-          mapping = table_mappings(self.name).dig('properties', name.to_s)
-          raise ArgumentError, "you cannot change parameters for an unknown mapping '#{name}'" if mapping.blank?
+        def change_mapping_attributes(name, if_exists: false, **options, &block)
+          return if if_exists && !mapping_exists?(self.name, name)
+
+          # receive current mapping
+          current_mapping = table_mappings(self.name).dig('properties', name.to_s)
+          raise ArgumentError, "you cannot change an unknown mapping '#{name}'" if current_mapping.blank?
 
-          options = mapping.with_indifferent_access.except(:type).merge(options) if options.present?
+          # build new mapping
+          mapping = new_mapping_definition(name, current_mapping[:type], **options, &block)
+          define! ChangeMappingDefinition, mapping
 
-          define! ChangeMappingDefinition, new_mapping_definition(name, mapping['type'], **options, &block)
+          # check if the mapping is assigned as new primary_key
+          if mapping.primary_key?
+            change_meta :primary_key, mapping.name
+            change_meta(:auto_increment, mapping.auto_increment) if mapping.auto_increment?
+          end
         end
 
-        alias :change_mapping_attribute :change_mapping_attributes
+        def remove_mapping(name)
+          raise ArgumentError, "you cannot remove the mapping '#{name}' without the 'recreate: true' flag in the '#change_table' call"
+        end
+        alias :remove_column :remove_mapping
 
         def add_setting(name, value, if_not_exists: false, **options, &block)
           return if if_not_exists && setting_exists?(self.name, name)
@@ -90,10 +91,10 @@ module ActiveRecord
           define! ChangeSettingDefinition, new_setting_definition(name, value, **options, &block)
         end
 
-        def delete_setting(name, if_exists: false, **options, &block)
+        def remove_setting(name, if_exists: false, **options, &block)
           return if if_exists && !setting_exists?(self.name, name)
 
-          define! DeleteSettingDefinition, new_setting_definition(name, nil, **options, &block)
+          define! RemoveSettingDefinition, new_setting_definition(name, nil, **options, &block)
         end
 
         def add_alias(name, if_not_exists: false, **options, &block)
@@ -108,10 +109,10 @@ module ActiveRecord
           define! ChangeAliasDefinition, new_alias_definition(name, **options, &block)
         end
 
-        def delete_alias(name, if_exists: false, **, &block)
+        def remove_alias(name, if_exists: false, **, &block)
           return if if_exists && !alias_exists?(self.name, name)
 
-          define! DeleteAliasDefinition, new_alias_definition(name, &block)
+          define! RemoveAliasDefinition, new_alias_definition(name, &block)
         end
 
         # Appends <tt>:datetime</tt> columns <tt>:created_at</tt> and
@@ -123,6 +124,11 @@ module ActiveRecord
           add_mapping(:updated_at, :datetime, if_not_exists: true, **options)
         end
 
+        # returns the definitions hash
+        def definitions
+          @definitions ||= {}
+        end
+
         private
 
         # loads existing meta definitions from table_mappings
@@ -130,16 +136,14 @@ module ActiveRecord
           return if @load_meta_definition
           @load_meta_definition = true
 
-
           table_metas(self.name).each do |name, value|
             define! ChangeMetaDefinition, new_meta_definition(name, value)
           end
         end
 
         def define!(klass, item)
-          @definitions        ||= {}
-          @definitions[klass] ||= []
-          @definitions[klass] << item
+          self.definitions[klass] ||= []
+          self.definitions[klass] << item
         end
 
         def _before_assign
@@ -157,6 +161,7 @@ module ActiveRecord
           # reset table state
           clear_state!
         end
+
         alias :_rescue_assign :_after_exec
         alias :_rescue_exec :_after_exec
 

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

@@ -14,12 +14,12 @@ module ActiveRecord
       # setting definitions
       AddSettingDefinition    = Struct.new(:items) # composite
       ChangeSettingDefinition = Struct.new(:items) # composite
-      DeleteSettingDefinition = Struct.new(:items) # composite
+      RemoveSettingDefinition = Struct.new(:items) # composite
 
       # alias definitions
       AddAliasDefinition    = Struct.new(:item) # single
       ChangeAliasDefinition = Struct.new(:item) # single
-      DeleteAliasDefinition = Struct.new(:items) # composite
+      RemoveAliasDefinition = Struct.new(:items) # composite
     end
   end
 end

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

@@ -20,6 +20,11 @@ module ActiveRecord
           @options[:table_name_suffix] = @connection.table_name_suffix if @options[:table_name_suffix].blank?
         end
 
+        # returns true if the connection has table-names, that are environment related
+        def _has_env_table_names?
+          @options[:table_name_prefix].present? || @options[:table_name_suffix].present?
+        end
+
         # overwrite the method to 'fix' a possible ActiveRecord bug:
         # If a +table_name_prefix+ or +table_name_suffix+ was provided we also only want to dump those tables,
         # which matches the prefix/suffix. So possible, environment-related tables will be ignored
@@ -35,7 +40,7 @@ module ActiveRecord
           return true if @options[:table_name_prefix].present? && !table_name.start_with?(@options[:table_name_prefix].to_s)
 
           # if the table ends NOT with +suffix+ it must be ignored
-          return true if  @options[:table_name_suffix].present? && !table_name.end_with?(@options[:table_name_suffix].to_s)
+          return true if @options[:table_name_suffix].present? && !table_name.end_with?(@options[:table_name_suffix].to_s)
 
           false
         end
@@ -50,7 +55,14 @@ module ActiveRecord
             # resolve string printer
             tbl = StringIO.new
 
-            tbl.print "  create_table #{remove_prefix_and_suffix(table).inspect}"
+            tbl.print "  create_table"
+
+            if _has_env_table_names?
+              tbl.print " _env_table_name(#{remove_prefix_and_suffix(table).inspect})"
+            else
+              tbl.print " #{remove_prefix_and_suffix(table).inspect}"
+            end
+
             tbl.print ", force: true do |t|"
 
             # META

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

@@ -399,6 +399,12 @@ module ActiveRecord
             settings['persistent'].merge(settings['transient'])
           end
 
+          # returns the cluster health
+          # @return [Hash]
+          def cluster_health(**options)
+            api(:cluster, :health, options, 'CLUSTER HEALTH').to_h
+          end
+
           # transforms provided schema-type to a sql-type
           # overwrite original methods to provide a elasticsearch version
           # @param [String, Symbol] type
@@ -467,7 +473,7 @@ module ActiveRecord
 
           # overwrite original methods to provide a elasticsearch version
           def extract_table_options!(options)
-            options.extract!(:settings, :mappings, :aliases, :force, :strict)
+            options.extract!(:settings, :mappings, :aliases, :metas, :force, :strict)
           end
         end
       end

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

@@ -11,6 +11,7 @@ module ActiveRecord
           # ORIGINAL methods untouched:
           #
           # SUPPORTED but not used:
+          # -
           #
           # UNSUPPORTED methods that will be ignored:
           # - native_database_types
@@ -25,11 +26,6 @@ module ActiveRecord
           # - change_column_default
           # - change_column_null
           # - rename_column
-          #
-          # UPCOMING future methods:
-          # - clone (option -> close, or read-only (#lock / unlock) )
-          # - refresh
-          # - rename_table
 
           define_unsupported_method :create_join_table, :drop_join_table, :create_alter_table,
                                     :change_column_default, :change_column_null, :rename_column, :rename_table
@@ -70,6 +66,26 @@ module ActiveRecord
             table_names.map { |table_name| close_table(table_name) }
           end
 
+          # refresh an index.
+          # A refresh makes recent operations performed on one or more indices available for search.
+          # raises an exception if the index could not be found.
+          #
+          # @param [String] table_name
+          # @return [Boolean] result state (returns false if refreshing failed)
+          def refresh_table(table_name)
+            api(:indices, :refresh, { index: table_name }, 'REFRESH TABLE').dig('_shards','failed') == 0
+          end
+
+          # refresh indices by provided names.
+          # @param [Array] table_names
+          # @return [Array] result state (returns false if refreshing failed)
+          def refresh_tables(*table_names)
+            table_names -= [schema_migration.table_name, InternalMetadata.table_name]
+            return if table_names.empty?
+
+            table_names.map { |table_name| refresh_table(table_name) }
+          end
+
           # truncates index by provided name.
           # HINT: Elasticsearch does not have a +truncate+ concept:
           # - so we have to store the current index' schema
@@ -132,15 +148,14 @@ module ActiveRecord
             end
           end
 
-          # clones an entire table to the provided +target_name+.
+          # clones an entire table (index) to the provided +target_name+.
           # During cloning, the table will be automatically 'write'-blocked.
           # @param [String] table_name
           # @param [String] target_name
           # @param [Hash] options
-          # @param [Proc] block
-          def clone_table(table_name, target_name, **options, &block)
+          def clone_table(table_name, target_name, **options)
             # create new definition
-            definition = clone_table_definition(table_name, target_name, **extract_table_options!(options), &block)
+            definition = clone_table_definition(table_name, target_name, **extract_table_options!(options))
 
             # yield optional block
             if block_given?
@@ -153,6 +168,24 @@ module ActiveRecord
             definition.exec!
           end
 
+          # renames a table (index) by executing multiple steps:
+          # - clone table
+          # - wait for 'green' state
+          # - drop old table
+          # The +timeout+ option will define how long to wait for the 'green' state.
+          #
+          # @param [String] table_name
+          # @param [String] target_name
+          # @param [String (frozen)] timeout (default: '30s')
+          # @param [Hash] options - additional 'clone' options (like settings, alias, ...)
+          def rename_table(table_name, target_name, timeout: '30s', **options)
+            schema_cache.clear_data_source_cache!(table_name)
+
+            clone_table(table_name, target_name, **options)
+            cluster_health(index: target_name, wait_for_status: 'green', timeout: timeout)
+            drop_table(table_name)
+          end
+
           # creates a new table (index).
           # [<tt>:force</tt>]
           #   Set to +true+ to drop an existing table
@@ -168,9 +201,6 @@ module ActiveRecord
           # @param [Hash] options
           # @return [Boolean] acknowledged status
           def create_table(table_name, force: false, copy_from: nil, if_not_exists: false, **options)
-            # IMPORTANT: compute will add possible configured prefix & suffix
-            table_name = compute_table_name(table_name)
-
             return if if_not_exists && table_exists?(table_name)
 
             # copy schema from existing table
@@ -204,12 +234,14 @@ module ActiveRecord
           #     t.mapping :name, :string
           #     # Other column alterations here
           #   end
-          def change_table(table_name, if_exists: false, **options)
-            # IMPORTANT: compute will add possible configured prefix & suffix
-            table_name = compute_table_name(table_name)
-
+          def change_table(table_name, if_exists: false, recreate: false, **options, &block)
             return if if_exists && !table_exists?(table_name)
 
+            # check 'recreate' flag.
+            # If true, a 'create_table' with copy of the current will be executed
+            return create_table(table_name, force: true, copy_from: table_name, **options, &block) if recreate
+
+            # build new update definition
             definition = update_table_definition(table_name, self, **options)
 
             # yield optional block
@@ -231,12 +263,19 @@ module ActiveRecord
 
           alias :add_column :add_mapping
 
+          # will fail unless +recreate:true+ option was provided
           def change_mapping(table_name, name, type, **options, &block)
             _exec_change_table_with(:change_mapping, table_name, name, type, **options, &block)
           end
 
           alias :change_column :change_mapping
 
+          def remove_mapping(table_name, name, **options)
+            _exec_change_table_with(:remove_mapping, table_name, name, **options)
+          end
+
+          alias :remove_column :remove_mapping
+
           def change_mapping_meta(table_name, name, **options)
             _exec_change_table_with(:change_mapping_meta, table_name, name, **options)
           end
@@ -245,14 +284,12 @@ module ActiveRecord
             _exec_change_table_with(:change_mapping_attributes, table_name, name, **options, &block)
           end
 
-          alias :change_mapping_attribute :change_mapping_attributes
-
           def change_meta(table_name, name, value, **options)
             _exec_change_table_with(:change_meta, table_name, name, value, **options)
           end
 
-          def delete_meta(table_name, name, **options)
-            _exec_change_table_with(:delete_meta, table_name, name, **options)
+          def remove_meta(table_name, name, **options)
+            _exec_change_table_with(:remove_meta, table_name, name, **options)
           end
 
           # -- setting -------------------------------------------------------------------------------------------------
@@ -265,8 +302,8 @@ module ActiveRecord
             _exec_change_table_with(:change_setting, table_name, name, value, **options, &block)
           end
 
-          def delete_setting(table_name, name, **options, &block)
-            _exec_change_table_with(:delete_setting, table_name, name, **options, &block)
+          def remove_setting(table_name, name, **options, &block)
+            _exec_change_table_with(:remove_setting, table_name, name, **options, &block)
           end
 
           # -- alias ---------------------------------------------------------------------------------------------------
@@ -279,28 +316,31 @@ module ActiveRecord
             _exec_change_table_with(:change_alias, table_name, name, **options, &block)
           end
 
-          def delete_alias(table_name, name, **options, &block)
-            _exec_change_table_with(:delete_alias, table_name, name, **options, &block)
+          def remove_alias(table_name, name, **options, &block)
+            _exec_change_table_with(:remove_alias, table_name, name, **options, &block)
           end
 
-          # computes a provided +table_name+ with optionally configured +table_name_prefix+ & +table_name_suffix+.
+          # recaps a provided +table_name+ with optionally configured +table_name_prefix+ & +table_name_suffix+.
+          # This depends on the connection config of the current environment.
+          #
           # @param [String] table_name
           # @return [String]
-          def compute_table_name(table_name)
+          def _env_table_name(table_name)
             table_name = table_name.to_s
-            
+
             # HINT: +"" creates a new +unfrozen+ string!
-            str = +""
-            str << table_name_prefix unless table_name.start_with?(table_name_prefix)
-            str << table_name
-            str << table_name_suffix unless table_name.end_with?(table_name_suffix)
-            str
+            name = +""
+            name << table_name_prefix unless table_name.start_with?(table_name_prefix)
+            name << table_name
+            name << table_name_suffix unless table_name.end_with?(table_name_suffix)
+
+            name
           end
 
           private
 
-          def _exec_change_table_with(method, table_name, *args, **kwargs, &block)
-            change_table(table_name) do |t|
+          def _exec_change_table_with(method, table_name, *args, recreate: false, **kwargs, &block)
+            change_table(table_name, recreate: recreate) do |t|
               t.send(method, *args, **kwargs, &block)
             end
           end

data/lib/arel/collectors/elasticsearch_query.rb

@@ -9,6 +9,9 @@ module Arel # :nodoc: all
       # required for ActiveRecord
       attr_accessor :preparable
 
+      # returns the current bind index (default: 1)
+      attr_reader :bind_index
+
       def initialize
         # force initialize a body as hash
         super(body: {})
@@ -44,7 +47,8 @@ module Arel # :nodoc: all
           # adds / sets any argument
           if args.length == 2
             @arguments[args[0]] = args[1]
-          else # should be a hash
+          else
+            # should be a hash
             @arguments.merge!(args[0])
           end
         when :body
@@ -90,10 +94,13 @@ module Arel # :nodoc: all
 
       private
 
-      # calls a assign on the body
+      # calls a assign on the body.
+      # forwards value to the +#claim+ method if key is +:__query__+.
+      # @param [Symbol] key
+      # @param [Object] value
       def assign(key, value)
         # check for special provided key, to claim through an assign
-        if key == :__claim__
+        if key == :__query__
           if value.is_a?(Array)
             value.each do |arg|
               vkey = arg.keys.first

data/lib/arel/visitors/elasticsearch_query.rb

@@ -13,7 +13,7 @@ module Arel # :nodoc: all
 
       # SELECT // SEARCH
       def visit_Arel_Nodes_SelectStatement(o)
-        # prepare query
+        # prepare query type
         claim(:type, ::ElasticsearchRecord::Query::TYPE_SEARCH)
 
         resolve(o.cores) # visit_Arel_Nodes_SelectCore
@@ -26,20 +26,23 @@ module Arel # :nodoc: all
         resolve(o.configure)
       end
 
-      # UPDATE
+      # UPDATE (by query - not a single record...)
       def visit_Arel_Nodes_UpdateStatement(o)
         # switch between updating a single Record or multiple by query
         if o.relation.is_a?(::Arel::Table)
           raise NotImplementedError, "if you've made it this far, something went wrong ..."
         end
 
-        # prepare query
+        # prepare query type
         claim(:type, ::ElasticsearchRecord::Query::TYPE_UPDATE_BY_QUERY)
 
+        # force refresh after update - but it can be unset again through the 'configure' ...
+        claim(:refresh, true)
+
         # sets the index
         resolve(o.relation)
 
-        # updating multiple entries need a script
+        # updating multiple entries needs a script
         assign(:script, {}) do
           assign(:inline, "") do
             updates = collect(o.values)
@@ -59,16 +62,19 @@ module Arel # :nodoc: all
         resolve(o.configure)
       end
 
-      # DELETE
+      # DELETE (by query - not a single record...)
       def visit_Arel_Nodes_DeleteStatement(o)
         # switch between updating a single Record or multiple by query
         if o.relation.is_a?(::Arel::Table)
           raise NotImplementedError, "if you've made it this far, something went wrong ..."
         end
 
-        # prepare query
+        # prepare query type
         claim(:type, ::ElasticsearchRecord::Query::TYPE_DELETE_BY_QUERY)
 
+        # force refresh after delete - but it can be unset again through the 'configure' ...
+        claim(:refresh, true)
+
         # sets the index
         resolve(o.relation)
 
@@ -84,13 +90,15 @@ module Arel # :nodoc: all
         resolve(o.configure)
       end
 
-      # INSERT
+      # INSERT (by query - not a single record...)
+      # this is also used by 'meta' or 'schema_migrations' tables ...
       def visit_Arel_Nodes_InsertStatement(o)
-
         # switch between updating a single Record or multiple by query
         if o.relation.is_a?(::Arel::Table)
-          # prepare query
+          # prepare query type
           claim(:type, ::ElasticsearchRecord::Query::TYPE_CREATE)
+
+          # force refresh after insert
           claim(:refresh, true)
 
           # sets the index

data/lib/arel/visitors/elasticsearch_schema.rb

@@ -89,8 +89,9 @@ module Arel # :nodoc: all
         # 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
+        # special overcomplicated blocks to assign a hash of settings directly to the body...
+        # todo: refactor this in future versions
+        assign(:__query__, {}) do
           assign(:body, {}) do
             resolve(o.items, :visit_TableSettingDefinition)
           end
@@ -98,7 +99,7 @@ module Arel # :nodoc: all
       end
 
       alias :visit_AddSettingDefinition :visit_ChangeSettingDefinition
-      alias :visit_DeleteSettingDefinition :visit_ChangeSettingDefinition
+      alias :visit_RemoveSettingDefinition :visit_ChangeSettingDefinition
 
       def visit_ChangeAliasDefinition(o)
         # prepare query
@@ -110,7 +111,7 @@ module Arel # :nodoc: all
 
       alias :visit_AddAliasDefinition :visit_ChangeAliasDefinition
 
-      def visit_DeleteAliasDefinition(o)
+      def visit_RemoveAliasDefinition(o)
         # prepare query
         claim(:type, ::ElasticsearchRecord::Query::TYPE_INDEX_DELETE_ALIAS)
 

data/lib/elasticsearch_record/gem_version.rb

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

data/lib/elasticsearch_record/relation/calculation_methods.rb

@@ -33,9 +33,9 @@ module ElasticsearchRecord
           # 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+.
           #
-          # HINT: :__claim__ directly interacts with the query-object and sets a 'terminate_after' argument
-          # (see @ Arel::Collectors::ElasticsearchQuery#assign)
-          arel = spawn.unscope!(:offset, :limit, :order, :configure, :aggs).configure!(:__claim__, argument: { terminate_after: limit_value }).arel
+          # 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")
         else
           # since total will be limited to 10000 results, we need to resolve the real values by a custom query.

data/lib/elasticsearch_record/relation/query_methods.rb

@@ -27,9 +27,12 @@ module ElasticsearchRecord
         self
       end
 
-      # sets or overwrites additional arguments for the query (not the :query-node, the whole query).
-      # You can also force a overwrite of previously defined arguments, like +size+ or +from+.
-      # This is useful to force remove of keys.
+      # sets or overwrites additional arguments for the whole query (not the current 'query-node' - the whole query).
+      # Previously defined arguments (like +size+ or +from+) can also be overwritten.
+      # Providing a +nil+ value will remove the key  - this is useful to force remove of keys.
+      #
+      # Providing the special key +:__query__+ will directly access the query object, to alter query-related values
+      # (like 'refresh, arguments, columns, ...' - see @ Arel::Collectors::ElasticsearchQuery
       #
       # @example
       #   # adds {refresh true} to the query
@@ -37,6 +40,10 @@ module ElasticsearchRecord
       #
       #   # overwrites or sets {from: 50} but removes the :sort key
       #   configure({from: 50, sort: nil})
+      #
+      #   # sets the query's 'refresh' to true
+      #   configure(:__query__, refresh: true)
+      #
       # @param [Array] args
       def configure(*args)
         spawn.configure!(*args)
@@ -48,10 +55,10 @@ module ElasticsearchRecord
 
         if args.length == 1 && args.first.is_a?(Hash)
           self.configure_value = self.configure_value.merge(args[0])
-        elsif args.length == 2 && args[0] == :__claim__
-          tmp = self.configure_value[:__claim__] || []
+        elsif args.length == 2 && args[0] == :__query__
+          tmp = self.configure_value[:__query__] || []
           tmp << args[1]
-          self.configure_value = self.configure_value.merge(:__claim__ => tmp)
+          self.configure_value = self.configure_value.merge(:__query__ => tmp)
         elsif args.length == 2
           self.configure_value = self.configure_value.merge(args[0] => args[1])
         end
@@ -69,7 +76,8 @@ module ElasticsearchRecord
 
       alias_method :aggs, :aggregate
 
-      def aggregate!(opts, *rest) # :nodoc:
+      def aggregate!(opts, *rest)
+        # :nodoc:
         case opts
         when Symbol, String
           self.aggs_clause += build_query_clause(opts, rest)
@@ -84,6 +92,16 @@ module ElasticsearchRecord
         self
       end
 
+      # sets the query's +refresh+ value.
+      # @param [Boolean] value (default: true)
+      def refresh(value = true)
+        spawn.refresh!(value)
+      end
+
+      def refresh!(value = true)
+        configure!(:__query__, refresh: value)
+      end
+
       # add a whole query 'node' to the query.
       # @example
       #   query(:bool, {filter: ...})
@@ -92,7 +110,8 @@ module ElasticsearchRecord
         spawn.query!(*args)
       end
 
-      def query!(kind, opts, *rest) # :nodoc:
+      def query!(kind, opts, *rest)
+        # :nodoc:
         kind!(kind)
         self.query_clause += build_query_clause(opts.keys[0], opts.values[0], rest)
         self
@@ -106,7 +125,8 @@ module ElasticsearchRecord
         spawn.filter!(*args)
       end
 
-      def filter!(opts, *rest) # :nodoc:
+      def filter!(opts, *rest)
+        # :nodoc:
         set_default_kind!
         self.query_clause += build_query_clause(:filter, opts, rest)
         self
@@ -120,7 +140,8 @@ module ElasticsearchRecord
         spawn.must_not!(*args)
       end
 
-      def must_not!(opts, *rest) # :nodoc:
+      def must_not!(opts, *rest)
+        # :nodoc:
         set_default_kind!
         self.query_clause += build_query_clause(:must_not, opts, rest)
         self
@@ -134,7 +155,8 @@ module ElasticsearchRecord
         spawn.must!(*args)
       end
 
-      def must!(opts, *rest) # :nodoc:
+      def must!(opts, *rest)
+        # :nodoc:
         set_default_kind!
         self.query_clause += build_query_clause(:must, opts, rest)
         self
@@ -148,7 +170,8 @@ module ElasticsearchRecord
         spawn.should!(*args)
       end
 
-      def should!(opts, *rest) # :nodoc:
+      def should!(opts, *rest)
+        # :nodoc:
         set_default_kind!
         self.query_clause += build_query_clause(:should, opts, rest)
         self
@@ -176,7 +199,8 @@ module ElasticsearchRecord
         super
       end
 
-      def where!(opts, *rest) # :nodoc:
+      def where!(opts, *rest)
+        # :nodoc:
         case opts
           # check the first provided parameter +opts+ and validate, if this is an alias for "must, must_not, should or filter"
           # if true, we expect the rest[0] to be a hash.
@@ -186,7 +210,7 @@ module ElasticsearchRecord
           when :filter, :must, :must_not, :should
             send("#{opts}!", *rest)
           else
-            raise ArgumentError, "Unsupported argument type for where: #{opts}"
+            raise ArgumentError, "Unsupported prefix type '#{opts}'. Allowed types are: :filter, :must, :must_not, :should"
           end
         when Array
           # check if this is a nested array of multiple [<kind>,<data>]
@@ -197,42 +221,8 @@ module ElasticsearchRecord
           else
             where!(*opts, *rest)
           end
-        when String
-          # fallback to ActiveRecords +#where_clause+
-          # currently NOT supported
-          super(opts, rest)
         else
-          # hash -> {name: 'hans'}
-          # protects against forwarding params directly to where ...
-          # User.where(params) <- will never work
-          # User.where(params.permit(:user)) <- ok
-          opts = sanitize_forbidden_attributes(opts)
-
-          # resolve possible aliases
-          opts = opts.transform_keys do |key|
-            key = key.to_s
-            klass.attribute_aliases[key] || key
-          end
-
-          # check if we have keys without Elasticsearch fields
-          if (invalid = (opts.keys - klass.searchable_column_names)).present?
-            raise(ActiveRecord::UnknownAttributeReference,
-                  "Unable to build query with unknown searchable attributes: #{invalid.map(&:inspect).join(", ")}. " \
-                "If you want to build a custom query you should use one of those methods: 'filter, must, must_not, should'. " \
-                "#{klass.name}.filter('#{invalid[0]}' => '...')"
-            )
-          end
-
-          # force set default kind, if not previously set
-          set_default_kind!
-
-          # builds predicates from opts (transforms this in a more unreadable way but is required for nested assignment & binds ...)
-          parts = opts.map do |key,value|
-            # builds and returns a new Arel Node from provided key/value pair
-            predicate_builder[key,value]
-          end
-
-          self.where_clause += ::ActiveRecord::Relation::WhereClause.new(parts)
+          self.where_clause += build_where_clause(opts, rest)
         end
 
         self
@@ -271,6 +261,45 @@ module ElasticsearchRecord
 
       private
 
+      def build_where_clause(opts, _rest = [])
+        case opts
+        when Symbol, Array, String
+          raise ArgumentError, "Unsupported or unresolved argument class '#{opts.class}' for build_where_clause: #{opts}"
+        else
+          # hash -> {name: 'hans'}
+          # protects against forwarding params directly to where ...
+          # User.where(params) <- will never work
+          # User.where(params.permit(:user)) <- ok
+          opts = sanitize_forbidden_attributes(opts)
+
+          # resolve possible aliases
+          opts = opts.transform_keys do |key|
+            key = key.to_s
+            klass.attribute_aliases[key] || key
+          end
+
+          # check if we have keys without Elasticsearch fields
+          if (invalid = (opts.keys - klass.searchable_column_names)).present?
+            raise(ActiveRecord::UnknownAttributeReference,
+                  "Unable to build query with unknown searchable attributes: #{invalid.map(&:inspect).join(", ")}. " \
+                "If you want to build a custom query you should use one of those methods: 'filter, must, must_not, should'. " \
+                "#{klass.name}.filter('#{invalid[0]}' => '...')"
+            )
+          end
+
+          # force set default kind, if not previously set
+          set_default_kind!
+
+          # builds predicates from opts (transforms this in a more unreadable way but is required for nested assignment & binds ...)
+          parts = opts.map do |key, value|
+            # builds and returns a new Arel Node from provided key/value pair
+            predicate_builder[key, value]
+          end
+
+          ::ActiveRecord::Relation::WhereClause.new(parts)
+        end
+      end
+
       def build_query_clause(kind, data, rest = [])
         ElasticsearchRecord::Relation::QueryClause.new(kind, Array.wrap(data), rest.extract_options!)
       end

data/lib/elasticsearch_record/relation/result_methods.rb

@@ -104,7 +104,7 @@ module ElasticsearchRecord
         relation.offset!(nil).limit!(nil)
 
         # remove the 'index' from the query arguments (pit doesn't like that)
-        relation.configure!(:__claim__, { index: nil })
+        relation.configure!(:__query__, { index: nil })
 
         # we store the results in this array
         results       = []

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elasticsearch_record
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.3.0
 platform: ruby
 authors:
 - Tobias Gonsior
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-15 00:00:00.000000000 Z
+date: 2023-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord