elasticsearch_record 1.8.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbb80c1852041338e02e17314a2a70e852db077e2724383fe05d1990dc5c601e
-  data.tar.gz: 5d1f2b445e83e602b16ac571b8b3824784490f9c365a304b4be06aaa02620cb2
+  metadata.gz: 27f0d74b39e373493b56511cb08e07ed2fc447da5f33cf5a23a8a080072f3d4e
+  data.tar.gz: 52f5843b03ea19f3f236910f2268aadb1eba5b7eae48c59734d162fdd2bc6000
 SHA512:
-  metadata.gz: 80ac0419ba02c1d7cc563446067caff43f7ee5b1a92c1155b5d3c2871652b06d5a8998aae4da6ee5c44289c7579a87b1346c15ae15630c11ab8cded34412e524
-  data.tar.gz: 1559d1ab3873e002c867c88726358a4d1c3f875e087f8b37ec58d9c8ee196fc757490c246409c1bc32871e9210b617e6c48473c7fe6fe68e97ab47e66da010ec
+  metadata.gz: '07733791c4f29ed331631d6ede8ba83b23ebad2af68afffda6e998eca7d09f4aad4a57a83c87e10dbd866a98bb8f77a6d4fffc905b1dd214d13f48313d603955'
+  data.tar.gz: 4f3e9ffb52a06c4db77fb698b7e715eac3ad77aa259df5f66905890f69646b35e4f6ee809c52feae3180544de8e47943f6cff95faeff12c43bfaecc9d0e01cb4

data/Gemfile

@@ -4,3 +4,10 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in elasticsearch_record.gemspec
 gemspec
+
+# Pin the Elasticsearch client to the 8.x line for local development & specs.
+# The gemspec intentionally allows '>= 7.17', but the 9.x client sends an
+# 'Accept: application/vnd.elasticsearch+json; compatible-with=9' header that
+# 8.x servers reject with a media_type_header_exception (HTTP 400).
+# Keep this in sync with the server you develop against.
+gem 'elasticsearch', '~> 8.0'

data/README.md

@@ -16,8 +16,9 @@ _ElasticsearchRecord is a ActiveRecord adapter and provides similar functionalit
 
 - This is the `main`-branch, which currently supports rails **7.1** _(see section 'Rails_Versions' for supported versions)_
 - supports ActiveRecord ~> 7.1 + Elasticsearch >= 7.17
-- added features up to Elasticsearch `8.16.1`
-- tested with Elasticsearch `8.15.2`
+- added features up to Elasticsearch `8.17.1`
+- _ES|QL_ queries _(`TYPE_ESQL` / the `esql.query` gate)_ require **Elasticsearch >= 8.11**, where the feature became
+  generally available. All other features remain available from Elasticsearch `7.17`.
 
 -----
 
@@ -50,7 +51,7 @@ gem 'elasticsearch_record', '~> 1.8'
 
 # alternative
 gem 'elasticsearch_record', git: 'https://github.com/ruby-smart/elasticsearch_record', branch: 'rails-7-1-stable'
-gem 'elasticsearch_record', git: 'https://github.com/ruby-smart/elasticsearch_record', branch: 'rails-70-stable'
+gem 'elasticsearch_record', git: 'https://github.com/ruby-smart/elasticsearch_record', branch: 'rails-7-0-stable'
 
 ```
 
@@ -616,17 +617,29 @@ 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 ...
+Table (index) names are resolved within the current environment, even if the environments share 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.
+**Every table statement applies them by default**, so a migration only ever names 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:
+```yml
+production:
+  elasticsearch:
+    # ...
+    table_name_suffix: '-pro'
+
+development:
+  elasticsearch:
+    # ...
+    table_name_suffix: '-dev'
+```
 
+For the **settings** table / index this results in the following names:
 * settings-pro
 * settings-dev
 
@@ -636,7 +649,8 @@ A single migration can be created to be used within each environment:
 # Example migration
 class AddSettings < ActiveRecord::Migration[7.0]
   def up
-    create_table _env_table_name("settings"), force: true do |t|
+    # creates 'settings-pro' on production & 'settings-dev' on development
+    create_table "settings", force: true do |t|
       t.mapping :created_at, :date
       t.mapping :key, :integer do |m|
         m.primary_key = true
@@ -653,11 +667,63 @@ class AddSettings < ActiveRecord::Migration[7.0]
   end 
   
   def down
-    drop_table _env_table_name("settings")
+    drop_table "settings"
   end
 end 
 ```
 
+### opting out with `decorate: false`
+
+Provide `decorate: false` to address an index by its **literal** name:
+
+```ruby
+# addresses 'settings-pro' - even from a '-dev' suffixed connection
+drop_table "settings-pro", decorate: false
+```
+
+This is required in two cases:
+
+* the name is **already resolved** _(e.g. `Model.table_name`, or a name read back from `#tables`)_
+* the base name itself **starts with the prefix** or **ends with the suffix** - `_env_table_name`
+  keeps itself idempotent through a `start_with?` / `end_with?` check and cannot tell such a name
+  apart from an already resolved one
+
+The flag only ever applies to table (index) names - `alias`, `mapping`, `setting` & `meta` names are
+never touched. Statements taking **two** names _(`clone_table`, `rename_table`, `reindex_table`,
+`restore_table`, `backup_table`, `create_table copy_from:`)_ resolve both.
+
+The **schema statements** _(`table_exists?`, `table_schema`, `table_mappings`, `table_settings`,
+`columns`, ...)_ are deliberately **not** decorated - ActiveRecord and the schema dumper call them
+with an already resolved index name.
+
+The `_env_table_name`-method itself is still public, so existing migrations keep working - it is now
+redundant, since it resolves the very same name the statement would resolve on its own.
+
+### global kill-switch
+
+The default of a **not explicitly provided** `decorate:` argument is resolved from a global flag:
+
+```ruby
+# e.g. in an initializer
+ElasticsearchRecord.decorate_table_names = false
+```
+
+Setting it to `false` restores the former, opt-in behaviour, where the decoration had to be applied
+by hand through `_env_table_name`. A single statement can still opt in or out on its own, so
+`decorate: true` keeps working while the flag is off:
+
+```ruby
+ElasticsearchRecord.decorate_table_names = false
+
+drop_table "settings"                  # => drops 'settings'
+drop_table "settings", decorate: true  # => drops 'settings-dev'
+drop_table _env_table_name("settings") # => drops 'settings-dev' (the former syntax)
+```
+
+The schema dumper follows the flag: while the decoration is globally disabled it dumps the **full**
+index name with an explicit `decorate: false`, so a dumped schema stays correct even if the flag is
+flipped back on before it is loaded.
+
 ## Docs
 
 [CHANGELOG](docs/CHANGELOG.md)

data/docs/CHANGELOG.md

@@ -1,5 +1,43 @@
 # ElasticsearchRecord - CHANGELOG
 
+## [2.0.0] - 2026-08-10
+* [add] `ElasticsearchRecord.decorate_table_names` _(default: `true`)_ as global kill-switch for the table name decoration - only provides the default for an omitted `decorate:`-argument, `#_env_table_name` stays unaffected
+* [add] `TableStatements#truncate_table` raises an `ArgumentError` for AR-internal indices - the statement runs a `drop` & `create` and would wipe the migration state. `#drop_table` stays unguarded by design _(AR resets both tables through it)_
+* [add] `QueryMethods#select` raises on metadata fields _(`_id`, `_score`, ...)_ - they are always returned anyway
+* [add] `ElasticsearchRecord::Result` now resolves **tabular** responses _(`sql`: columns + rows, `esql`: columns + values)_, so `find_by_sql` _(String)_ & `find_by_esql` instantiate records - rows are zipped against the **response** columns
+* [add] `CalculationMethods#matrix_stats` raises an `ArgumentError` for less than two columns - the metric quantifies the relationship **between** fields
+* [add] `ResultMethods#meta_only!` to resolve the metadata nodes _(`_id`, `_score`, ...)_ of each hit without transferring the `_source`
+* [add] `Query::COLUMNS_NONE` constant for the `'!'` projection marker - replaces the bare literal in `visit_Selects` & `meta_only!`
+* [add] specs for `ElasticsearchRecord::Persistence`, `ModelApi`, `SchemaMigration`, `Querying::ClassMethods`, the `Relation` methods _(Core, Query, Calculation & Result)_, the `Elasticsearch::SchemaStatements`, `TableStatements` & `SchemaDumper`, every class of the `Elasticsearch::Type` namespace _(incl. its `TYPE_MAP` registration)_, `Arel::Collectors::ElasticsearchQuery` and all three `Arel::Visitors::Elasticsearch*` visitors - incl. the 1.8.1 "only ten migrations" and 1.8.2 nested-reset regressions and a `TestIndexWithAutoIncrement` support that builds a model against a real `auto_increment` schema _(destructive calls still run through `TestIndex` and its name guard)_. Behaviours pinned as-is:
+  * `#or` compiles into a **failed** query _(the visitor fails every `Arel::Nodes::Grouping`)_, and AR's blank-arg stripping silently drops `configure(key, nil)` _(only the Hash form removes a key)_
+  * an index **alias** is dumped as a mapping of the elasticsearch 'alias' field type, which makes the `t.alias` branch of the dumper unreachable
+  * opposed nil-handling of metas _(deleted)_ and settings _(kept through `:__force__`)_
+  * a failed `create` has no `FAILED_BODIES` entry and falls back to an empty body; a multi-column `order` keeps only the last sort
+  * `SchemaMigration#count` and `#delete_version` / `#delete_all_versions` cannot be served by elasticsearch
+  * `_update_record` / `_delete_record` always return `0` _(a document-API response carries no `total`)_, and an auto-incremented id is only written as document `_id`, never into the mapped primary-key field
+  * `meta_only!` **spawns** instead of mutating the receiver _(unlike the other bang methods)_ and pins the `COLUMNS_NONE` projection; `pit_results` pins its infinite-loop guard
+* [ref] **BREAKING**: every table statement resolves its table (index) name through `#_env_table_name` **by default** - the `table_name_prefix` / `table_name_suffix` no longer have to be applied by hand, which silently wrote into another environment's index. A new `decorate:`-argument _(default: `true`)_ switches it off per call for already resolved names. Only TABLE names are decorated; schema statements stay undecorated
+* [ref] `SchemaDumper#table` dumps the **base** name instead of a `_env_table_name(...)` call - if that name would not resolve back, the full name is dumped with an explicit `decorate: false`
+* [ref] **BREAKING**: `#open_tables`, `#close_tables`, `#refresh_tables` & `#truncate_tables` no longer subtract the AR-internal indices _(an explicitly named index was silently dropped)_ - plain loops now, forwarding `decorate:` to their singular statement and returning an `Array` for every provided name
+* [ref] `TableStatements` drops the stale `:rename_table` entry from `define_unsupported_method` - the real implementation overwrote it anyway
+* [ref] `#restore_table` replaces its `open`-argument with `unblock:` _(default: true)_ - a restore clones and inherits the 'write'-block, so the table was open but **read-only**. `ModelApi#restore!` follows along
+* [ref] `ResultMethods#pit_results` resolves through `ElasticsearchRecord::Result` and respects the current projection _(`ids_only` removed in favour of `meta_only!`)_
+* [ref] `TestIndex` spec support to optionally create/drop a second index _(still guarded by the `ALLOWED` name check)_
+* [fix] `#rename_table` to resolve both names **itself** - the `clear_data_source_cache!` and `cluster_health` calls in between were left with the undecorated name
+* [fix] `#backup_table` to build the auto-generated target from the **already resolved** name _(the suffix landed behind the `-snapshot-` part)_
+* [fix] `#_env_table_name` to cast prefix & suffix - an empty `table_name_prefix:` yml entry resolves to `nil` and raised a `TypeError`
+* [fix] `Result#cast_values` to resolve values from the `_source` node, metadata fields from the document level
+* [fix] `visit_Selects` to no longer provide metadata fields to the `_source`-filter _(never matched)_ - projects `_source: false` if only metadata is selected
+* [fix] `Querying::ClassMethods#esql` & `#msearch` to dispatch through the public `exec_query` _(rails 7.1 made `internal_exec_query` private)_ - the `async:`-argument was dropped along with it
+* [fix] `Querying::ClassMethods#find_by_sql` to reference the provided `sql` for `String` queries _(undefined `query_or_sql` raised a `NameError`)_
+* [fix] `SchemaStatements#max_result_window` to resolve the **flat** setting key and cast it to an `Integer` _(always fell back to 10000 and broke the batch_size guards)_
+* [fix] `SchemaStatements#primary_keys` to always return an `Array` _(the `_meta` branch returned a raw String)_
+* [fix] `CalculationMethods#count` to apply the SQL `LIMIT n OFFSET m` semantic on the resolved total - `terminate_after` alone acts **per shard** and never fires on a count query. `#size` on an unloaded relation was affected as well
+* [fix] `UpdateTableDefinition#change_mapping_attributes` to resolve the current mapping type with a **String** key _(fell back to `:object` / `:nested`, so elasticsearch rejected every mapping parameter)_
+* [fix] `#restore_table` to no longer touch the backup after a `drop_backup: true` _(it no longer exists at that point)_
+* [fix] `_insert_with_auto_increment` to write the **plain, integer** id into `_meta.auto_increment` - the block returns an Array of the `returning` values, which was stored as-is and raised on the NEXT insert. Now unwraps Array / Hash / plain and casts to `Integer`
+* [fix] `ResultMethods#pit_delete` to no longer `select('_id')` _(rejected by the new metadata guard)_ - resolves the ids through `meta_only!`
+
 ## [1.8.2] - 2024-11-26
 * [fix] `ElasticsearchRecord::Relation::QueryMethods#build_query_clause` to raise an exception on `nil` assignments
 * [fix] `Arel::Visitors::ElasticsearchBase#compile` to always reset temporary assignments _(causes missing assignments after a query-build-exception)_
@@ -18,6 +56,14 @@
 * [add] new repository branch `rails-7-1-stable` to support different rails version
 * [ref] gemspec to lock on rails 7.1
 
+## [1.7.5] - 2024-11-26 _(no gem release)_
+* [ref] `ElasticsearchRecord::Relation::QueryMethods#build_query_clause` to raise an exception instead of building an empty `QueryClause`
+
+## [1.7.4] - 2024-11-25 _(no gem release)_
+* [fix] `Arel::Visitors::ElasticsearchBase#compile` to always reset temporary assignments _(causes missing assignments after a query-build-exception)_
+* [fix] `Arel::Nodes::SelectAgg` to not merge nil-values
+* [fix] `ElasticsearchRecord::Relation::QueryMethods#build_query_clause` to prevent nil-Array assignment _(e.g. `[nil]` causes q query exception)_
+
 ## [1.7.3] - 2024-05-07 _(no gem release)_
 * [add] new elasticsearch mapping types _(percolator, geo, vector, texts, ...)_
 * [ref] `ElasticsearchRecord::Relation#limit` to detect `Float::INFINITY` to also set the **max_result_window**

data/elasticsearch_record.gemspec

@@ -35,7 +35,7 @@ DESC
   spec.add_dependency 'activerecord', '~> 7.1.0'
   spec.add_dependency 'elasticsearch', '>= 7.17'
 
-  #spec.add_development_dependency 'coveralls_reborn', '~> 0.25'
+  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'

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

@@ -131,14 +131,29 @@ module ActiveRecord
 
           private
 
+          # gets called for all queries - a +ElasticsearchRecord::Query+ must be provided.
+          # @param [ElasticsearchRecord::Query] query
+          # @param [String (frozen),nil] name
+          # @param [Array] binds - not supported on the top-level and therefore ignored!
+          # @param [Boolean] prepare - used by the default AbstractAdapter - but not supported and therefore never ignored!
+          # @param [Boolean] async
+          # @return [ElasticsearchRecord::Result]
+          def internal_exec_query(query, name = "QUERY", binds = [], prepare: false, async: false)
+            build_result(
+              internal_execute(query, name, async: async),
+              columns: query.columns
+            )
+          end
+
           # Executes the query object in the context of this connection and returns the raw result
           # from the connection adapter.
           # @param [ElasticsearchRecord::Query] query
           # @param [String (frozen),nil] name
-          # @param [Boolean] async (default: false)
+          # @param [Boolean] async (default: false) - NOT supported!
           # @param [Boolean] allow_retry (default: false)
+          # @param [Boolean] materialize_transactions (default: false) - NOT supported!
           # @return [ElasticsearchRecord::Result]
-          def internal_execute(query, name = nil, async: false, allow_retry: false, materialize_transactions: nil)
+          def internal_execute(query, name = nil, async: false, allow_retry: false, materialize_transactions: false)
             # validate the query
             raise ActiveRecord::StatementInvalid, 'Unable to execute! Provided query is not a "ElasticsearchRecord::Query".' unless query.is_a?(ElasticsearchRecord::Query)
             raise ActiveRecord::StatementInvalid, 'Unable to execute! Provided query is invalid.' unless query.valid?
@@ -146,21 +161,7 @@ module ActiveRecord
             # checks for write query - raises an exception if connection is locked to readonly ...
             check_if_write_query(query)
 
-            api(*query.gate, query.query_arguments, name, async: async)
-          end
-
-          # gets called for all queries - a +ElasticsearchRecord::Query+ must be provided.
-          # @param [ElasticsearchRecord::Query] query
-          # @param [String (frozen),nil] name
-          # @param [Array] binds - not supported on the top-level and therefore ignored!
-          # @param [Boolean] prepare - used by the default AbstractAdapter - but not supported and therefore never ignored!
-          # @param [Boolean] async
-          # @return [ElasticsearchRecord::Result]
-          def internal_exec_query(query, name = "QUERY", binds = [], prepare: false, async: false)
-            build_result(
-              internal_execute(query, name, async: async),
-              columns: query.columns
-            )
+            api(query.gate, query.query_arguments, name, async: async, allow_retry: allow_retry, materialize_transactions: materialize_transactions)
           end
         end
       end

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

@@ -14,6 +14,12 @@ module ActiveRecord
           @aliases  = HashWithIndifferentAccess.new
           @metas    = HashWithIndifferentAccess.new
 
+          # HINT: Currently there is only one attribute, that cannot be assigned to any of the top hash kind, and also not opts:
+          # * dynamic
+          # This attribute must be assigned below the *mappings* node but as sibling to *properties*.
+          # This can only be done to create a special kind of options (@flags ???) and assign & fetch them within the required arel.
+          # Since this only setting can also be assigned to each individual mapping, there is currently no need to build this ...
+
           transform_settings!(settings) if settings.present?
           transform_mappings!(mappings) if mappings.present?
           transform_aliases!(aliases) if aliases.present?

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

@@ -10,7 +10,7 @@ module ActiveRecord
         include ActiveModel::Validations
 
         # exclude settings, that are provided through the API but are not part of the index-settings API
-        IGNORE_NAMES = ['provided_name', 'creation_date', 'uuid', 'version','routing.allocation.initial_recovery','resize'].freeze
+        IGNORE_NAMES = ['provided_name', 'creation_date', 'uuid', 'version', 'routing.allocation.initial_recovery', 'resize'].freeze
 
         # available setting names
         # - see @ https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#index-modules-settings
@@ -19,13 +19,12 @@ module ActiveRecord
         FINAL_NAMES = ['number_of_shards', 'routing_partition_size', 'soft_deletes.enabled'].freeze
 
         # static names can only be set during index creation or closed
-        STATIC_NAMES = ['number_of_routing_shards', 'codec',
+        STATIC_NAMES = ['number_of_routing_shards', 'codec', 'mode',
                         'soft_deletes.retention_lease.period',
                         'load_fixed_bitset_filters_eagerly', 'shard.check_on_startup',
 
                         # modules
-                        'analysis', 'routing', 'unassigned', 'merge', 'similarity', 'search', 'store', 'translog',
-                        'indexing_pressure'].freeze
+                        'analysis', 'routing', 'unassigned', 'merge', 'similarity', 'search', 'store', 'indexing_pressure'].freeze
 
         # dynamic names can always be changed
         DYNAMIC_NAMES = ['number_of_replicas', 'auto_expand_replicas', "search.idle.after", 'refresh_interval',
@@ -34,7 +33,10 @@ module ActiveRecord
                          'max_refresh_listeners', 'analyze.max_token_count', 'highlight.max_analyzed_offset',
                          'max_terms_count', 'max_regex_length', 'query.default_field', 'routing.allocation.enable',
                          'routing.rebalance.enable', 'gc_deletes', 'default_pipeline', 'final_pipeline',
-                         'hidden', 'blocks'].freeze
+                         'hidden', 'blocks',
+
+                         # modules
+                         'translog'].freeze
 
         VALID_NAMES = (FINAL_NAMES + STATIC_NAMES + DYNAMIC_NAMES).freeze
 

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

@@ -66,7 +66,9 @@ module ActiveRecord
           raise ArgumentError, "you cannot change an unknown mapping '#{name}'" if current_mapping.blank?
 
           # build new mapping
-          mapping = new_mapping_definition(name, current_mapping[:type], **options, &block)
+          # IMPORTANT: the received mapping is a String-keyed Hash - a symbol access would resolve
+          # nil here, which +TableMappingDefinition+ then falls back to :object / :nested
+          mapping = new_mapping_definition(name, current_mapping['type'], **options, &block)
           define! ChangeMappingDefinition, mapping
 
           # check if the mapping is assigned as new primary_key

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

@@ -45,6 +45,25 @@ module ActiveRecord
           false
         end
 
+        # returns true if the BASE name may be dumped, which keeps the dump loadable in another
+        # environment (with its own prefix / suffix): every table statement decorates its name on
+        # its own, so the base name may only be dumped if that decoration lands on exactly this
+        # index again. Otherwise the FULL name is dumped with a +decorate: false+.
+        #
+        # see @ ActiveRecord::ConnectionAdapters::Elasticsearch::TableStatements#_env_table_name
+        def _dumps_base_name?(table, base_name)
+          # without a prefix & suffix nothing is ever decorated - the plain name IS the index
+          return true unless _has_env_table_names?
+
+          # a globally disabled decoration would leave the base name untouched while loading
+          return false unless ElasticsearchRecord.decorate_table_names
+
+          # the base name must resolve BACK to the real index. It does not if the base name itself
+          # starts with the prefix (or ends with the suffix), and not if the dumper was built with a
+          # prefix / suffix that differs from the one of the connection.
+          @connection._env_table_name(base_name) == table
+        end
+
         def table(table, stream, nested_blocks: false, **)
           begin
             self.table_name = table
@@ -57,10 +76,12 @@ module ActiveRecord
 
             tbl.print "  create_table"
 
-            if _has_env_table_names?
-              tbl.print " _env_table_name(#{remove_prefix_and_suffix(table).inspect})"
+            base_name = remove_prefix_and_suffix(table)
+
+            if _dumps_base_name?(table, base_name)
+              tbl.print " #{base_name.inspect}"
             else
-              tbl.print " #{remove_prefix_and_suffix(table).inspect}"
+              tbl.print " #{table.inspect}, decorate: false"
             end
 
             tbl.print ", force: true do |t|"

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

@@ -92,13 +92,13 @@ module ActiveRecord
                                     :dump_schema_information
 
           def assume_migrated_upto_version(version)
-            version  = version.to_i
+            version = version.to_i
             migrated = migration_context.get_all_versions
             versions = migration_context.migrations.map(&:version)
 
             unless migrated.include?(version)
-              # use a ActiveRecord syntax to create a new version
-              schema_migration.create(version: version)
+              # use Arel syntax to create a new version
+              schema_migration.create_version(version)
             end
 
             inserting = (versions - migrated).select { |v| v < version }
@@ -107,8 +107,8 @@ module ActiveRecord
                 raise "Duplicate migration #{duplicate}. Please renumber your migrations to resolve the conflict."
               end
 
-              # use a ActiveRecord syntax to create new versions
-              inserting.each { |iversion| schema_migration.create(version: iversion) }
+              # use Arel syntax to create new versions
+              inserting.each { |iversion| schema_migration.create_version(iversion) }
             end
 
             true
@@ -119,7 +119,7 @@ module ActiveRecord
           # @see ActiveRecord::ConnectionAdapters::SchemaStatements#data_sources
           # @return [Array<String>]
           def data_sources
-            api(:indices, :get, { index: :_all, expand_wildcards: [:open, :closed] }, 'SCHEMA').keys
+            api('indices.get', { index: :_all, expand_wildcards: [:open, :closed] }, 'SCHEMA').keys
           end
 
           # Returns an array of table names defined in the database.
@@ -134,7 +134,7 @@ module ActiveRecord
           # @param [String] table_name
           # @return [Hash]
           def table_mappings(table_name)
-            api(:indices, :get_mapping, { index: table_name, expand_wildcards: [:open, :closed] }, 'SCHEMA').dig(table_name, 'mappings')
+            api('indices.get_mapping', { index: table_name, expand_wildcards: [:open, :closed] }, 'SCHEMA').dig(table_name, 'mappings')
           end
 
           # returns a hash of all meta data by provided table_name (index).
@@ -150,21 +150,21 @@ module ActiveRecord
           # @param [Boolean] flat_settings (default: true)
           # @return [Hash]
           def table_settings(table_name, flat_settings = true)
-            api(:indices, :get_settings, { index: table_name, expand_wildcards: [:open, :closed], flat_settings: flat_settings }, 'SCHEMA').dig(table_name, 'settings')
+            api('indices.get_settings', { index: table_name, expand_wildcards: [:open, :closed], flat_settings: flat_settings }, 'SCHEMA').dig(table_name, 'settings')
           end
 
           # returns a hash of all aliases by provided table_name (index).
           # @param [String] table_name
           # @return [Hash]
           def table_aliases(table_name)
-            api(:indices, :get_alias, { index: table_name, expand_wildcards: [:open, :closed] }, 'SCHEMA').dig(table_name, 'aliases')
+            api('indices.get_alias', { index: table_name, expand_wildcards: [:open, :closed] }, 'SCHEMA').dig(table_name, 'aliases')
           end
 
           # returns information about number of primaries and replicas, document counts, disk size, ... by provided table_name (index).
           # @param [String] table_name
           # @return [Hash]
           def table_state(table_name)
-            response = api(:cat, :indices, { index: table_name, expand_wildcards: [:open, :closed] }, 'SCHEMA')
+            response = api('cat.indices', { index: table_name, expand_wildcards: [:open, :closed] }, 'SCHEMA')
 
             [:health, :status, :name, :uuid, :pri, :rep, :docs_count, :docs_deleted, :store_size, :pri_store_size].zip(
               response.body.split(' ')
@@ -178,15 +178,15 @@ module ActiveRecord
           # @return [Hash]
           def table_schema(table_name, features = [:aliases, :mappings, :settings])
             if cluster_info[:version] >= '8.5.0'
-              response = api(:indices, :get, { index: table_name, expand_wildcards: [:open, :closed], features: features, flat_settings: true }, 'SCHEMA')
+              response = api('indices.get', { index: table_name, expand_wildcards: [:open, :closed], features: features, flat_settings: true }, 'SCHEMA')
             else
-              response = api(:indices, :get, { index: table_name, expand_wildcards: [:open, :closed], flat_settings: true }, 'SCHEMA')
+              response = api('indices.get', { index: table_name, expand_wildcards: [:open, :closed], flat_settings: true }, 'SCHEMA')
             end
 
             {
               settings: response.dig(table_name, 'settings'),
               mappings: response.dig(table_name, 'mappings'),
-              aliases:  response.dig(table_name, 'aliases')
+              aliases: response.dig(table_name, 'aliases')
             }
           end
 
@@ -204,8 +204,8 @@ module ActiveRecord
             # raise(ActiveRecord::StatementInvalid, "Could not find valid mappings for '#{table_name}'") if mappings.blank? || mappings['properties'].blank?
 
             # since the received mappings do not have the "primary" +_id+-column we manually need to add this here
-            # The BASE_STRUCTURE will also include some meta keys like '_score', '_type', ...
-            ActiveRecord::ConnectionAdapters::ElasticsearchAdapter::BASE_STRUCTURE + mappings['properties'].map { |key, prop|
+            # The METADATA_FIELDS will also include some meta keys like '_score', '_type', ...
+            ActiveRecord::ConnectionAdapters::ElasticsearchAdapter::METADATA_FIELDS + mappings['properties'].map { |key, prop|
               # resolve (nested) fields and properties
               fields, properties = resolve_fields_and_properties(key, prop, true)
 
@@ -228,11 +228,11 @@ module ActiveRecord
               field["name"],
               field["null_value"],
               fetch_type_metadata(field["type"]),
-              meta:       field['meta'],
-              virtual:    field['virtual'],
-              fields:     field['fields'],
+              meta: field['meta'],
+              virtual: field['virtual'],
+              fields: field['fields'],
               properties: field['properties'],
-              enabled:    field['enabled']
+              enabled: field['enabled']
             )
           end
 
@@ -250,13 +250,16 @@ module ActiveRecord
           # The only thing that uniquely identifies a document is the index together with the +_id+.
           # To support this concept we simulate this through the +_meta+ field (from the index).
           #
-          # As a alternative, the primary_key can also be provided through the mappings +meta+ field.
-          #
-          # see @ https://www.elastic.co/guide/en/elasticsearch/reference/8.5/mapping-meta-field.html
+          # As an alternative, the primary_key can also be provided through the mappings +meta+ field.
+          # - see @ https://www.elastic.co/guide/en/elasticsearch/reference/8.5/mapping-meta-field.html
+
           # @see ActiveRecord::ConnectionAdapters::AbstractMysqlAdapter#primary_keys
           # @param [String] table_name
+          # @return [Array<String>]
           def primary_keys(table_name)
-            table_metas(table_name).dig('primary_key').presence || column_definitions(table_name).
+            # IMPORTANT: the +_meta+ node stores the primary_key as a plain String - it must be
+            # wrapped, so every branch of this method returns an Array (as the API demands).
+            Array.wrap(table_metas(table_name).dig('primary_key')).presence || column_definitions(table_name).
               select { |f| f['meta'] && f['meta']['primary_key'] == 'true' }.
               # only take the last found primary key (if no custom primary_key was provided this will return +_id+ )
               map { |f| f["name"] }[-1..-1]
@@ -270,7 +273,7 @@ module ActiveRecord
           # @return [Boolean]
           def data_source_exists?(name)
             # response returns boolean
-            api(:indices, :exists?, { index: name, expand_wildcards: [:open, :closed] }, 'SCHEMA')
+            api('indices.exists?', { index: name, expand_wildcards: [:open, :closed] }, 'SCHEMA')
           end
 
           # Checks to see if the table +table_name+ exists on the database.
@@ -358,7 +361,9 @@ module ActiveRecord
           # The query will raise an ActiveRecord::StatementInvalid if the requested limit is above this value.
           # @return [Integer]
           def max_result_window(table_name)
-            table_settings(table_name).dig('index', 'max_result_window').presence || 10000
+            # IMPORTANT: the settings API returns every value as a String - without the cast the
+            # callers would compare a String against their (Integer) batch sizes.
+            table_settings(table_name).dig('index.max_result_window').presence&.to_i || 10_000
           end
 
           # returns true if the cluster option 'id_field_data' is enabled or not configured.
@@ -388,13 +393,13 @@ module ActiveRecord
           # @return [Hash{Symbol->Unknown}]
           def cluster_info
             @cluster_info ||= begin
-                                response = api(:core, :info, {}, 'CLUSTER INFO')
+                                response = api(:info, {}, 'CLUSTER INFO')
 
                                 {
-                                  name:           response.dig('name'),
-                                  cluster_name:   response.dig('cluster_name'),
-                                  cluster_uuid:   response.dig('cluster_uuid'),
-                                  version:        Gem::Version.new(response.dig('version', 'number')),
+                                  name: response.dig('name'),
+                                  cluster_name: response.dig('cluster_name'),
+                                  cluster_uuid: response.dig('cluster_uuid'),
+                                  version: Gem::Version.new(response.dig('version', 'number')),
                                   lucene_version: response.dig('version', 'lucene_version')
                                 }
                               end
@@ -403,14 +408,14 @@ module ActiveRecord
           # returns a hash of current set, none-default settings in flat
           # @return [Hash]
           def cluster_settings
-            settings = api(:cluster, :get_settings, { flat_settings: true }, 'CLUSTER SETTINGS')
+            settings = api('cluster.get_settings', { flat_settings: true }, 'CLUSTER SETTINGS')
             settings['persistent'].merge(settings['transient'])
           end
 
           # returns the cluster health
           # @return [Hash]
           def cluster_health(**options)
-            api(:cluster, :health, options, 'CLUSTER HEALTH').to_h
+            api('cluster.health', options, 'CLUSTER HEALTH').to_h
           end
 
           # transforms provided schema-type to a sql-type
@@ -469,8 +474,8 @@ module ActiveRecord
             if prop['properties'].present?
               prop['properties'].each do |nested_key, nested_prop|
                 nested_fields, nested_properties = resolve_fields_and_properties("#{key}.#{nested_key}", nested_prop)
-                fields                           |= nested_fields
-                properties                       |= nested_properties
+                fields |= nested_fields
+                properties |= nested_properties
               end
             elsif !root # don't add the root property as sub-property
               properties << { 'name' => key, 'type' => prop['type'] }