rails-paradedb 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61970bcefe75f0514836a81ab38dd8e39fe1c6f311d55f35366120d2285325b9
-  data.tar.gz: 6179c3b6d0814dcaae1179977548c4b47e6f6447110596293f242d668727d79a
+  metadata.gz: 6cec3ad6c144476e82c57a3f9cba2b9ff497a838c34c032919b1eb785d4da435
+  data.tar.gz: 2af9e08e2bf7b9a12f9c005e99bc73f4a804f8a0c23f50c1fbc57637d6b87109
 SHA512:
-  metadata.gz: 38471cccf3d392cd481dbb22cde9f35c37f09a555c4e6081c5484d9c5ad1920082172276447a2401a22c0dd46bcd1a0846f2dee26678f556f913373996a91da0
-  data.tar.gz: 6176c6252901db66d8f8dd72972f8053fc6a187d0d10391705dde18fabe16a4992d60655a351b3af8643e9ca4a57c2baff58a11a2dd93cb63a708750785034c6
+  metadata.gz: 1af9bfba690e6ba816fc5972f576885b72408594e68504e6d3bbf063944f6392debcf3cf7a028b5d08ba626d6acfaaeb7dbcb526db4adafa96cec987902fb6fa
+  data.tar.gz: 384b58ba9857bc2edb9a984ab71bd60d455daf5add4b3fc83b0c53458892496d21959b84e71680daddf7acc48f7c2832dbf930185661fb3ff587a22399a4bd84

data/CHANGELOG.md

@@ -2,13 +2,22 @@
 
 All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.12.0] - 2026-08-13
+
+### Changed
+
+- **BREAKING**: Search modifiers are now composable functions: `ParadeDB.boost`, `ParadeDB.constant`, `ParadeDB.fuzzy`, `ParadeDB.slop`, and `ParadeDB.tokenize`. Pass the wrapped value to search methods instead of using modifier keyword arguments.
+- **BREAKING**: Removed the public `ParadeDB::Arel` builder, Arel attribute predications, and `Model.paradedb_arel`. ParadeDB queries now use a private builder composed from standard Active Record nodes.
+
 ## [0.11.0] - 2026-08-04
 
 ### Added
 
 - Vector index build options `centroid_ratio`, `training_samples_per_centroid`, and `cluster_replication` in `ParadeDB::Index` `index_options` and `add_paradedb_index` (pg_search 0.25.0+). They are emitted in the `WITH (...)` clause and round-tripped through the schema dumper.
 
-[0.10.0] - 2026-08-04
+## [0.10.0] - 2026-08-04
 
 ### Added
 
@@ -24,7 +33,7 @@ All notable changes to this project will be documented in this file. The format
 - **BREAKING**: Index creation always emits `USING paradedb`, which requires pg_search 0.25.0+. There is no option to select the legacy `bm25` access method.
 - **BREAKING**: The default index name is now `<table>_search_idx` (previously `<table>_bm25_idx`), and the index generator emits `Create<Model>SearchIndex` migrations named `create_<table>_search_index.rb`.
 
-[0.9.0] - 2026-07-14
+## [0.9.0] - 2026-07-14
 
 ### Added
 
@@ -174,6 +183,7 @@ All notable changes to this project will be documented in this file. The format
 - Schema dump/load round-trip for tokenizer configuration and index options
   (including `target_segment_count`)
 
+[0.12.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.12.0
 [0.11.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.11.0
 [0.10.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.10.0
 [0.9.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.9.0

data/README.md

@@ -36,47 +36,45 @@
 
 ## ParadeDB for Rails
 
-The official ActiveRecord integration for [ParadeDB](https://paradedb.com) (powered by the [`pg_search`](https://github.com/paradedb/paradedb) Postgres extension), including first-class support for managing ParadeDB indexes and running queries using the full ParadeDB API. Follow the [getting started guide](https://docs.paradedb.com/documentation/getting-started/environment#rails) to begin.
+The official [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html) integration for [ParadeDB](https://paradedb.com) (powered by the [`pg_search`](https://github.com/paradedb/paradedb) Postgres extension), including first-class support for managing ParadeDB indexes and running queries using the full ParadeDB API. The integration covers both [full-text search](https://docs.paradedb.com/documentation/full-text/overview) and [vector search](https://docs.paradedb.com/documentation/vector/overview) over pgvector `vector` types. Follow the [getting started guide](https://docs.paradedb.com/documentation/getting-started/environment#rails) to begin.
 
 ## Requirements & Compatibility
 
-| Component  | Supported                                                         |
-| ---------- | ----------------------------------------------------------------- |
-| Ruby       | 3.2+                                                              |
-| Rails      | 7.2+                                                              |
-| ParadeDB   | 0.25.0+                                                           |
-| PostgreSQL | 15+ (PostgreSQL adapter with ParadeDB extension)                  |
-| pgvector   | Required for vector search; included in the ParadeDB Docker image |
-
-## Vector Search
-
-rails-paradedb supports full-text search and vector search over pgvector `vector(n)` columns. See the [vector search documentation](https://docs.paradedb.com/documentation/vector/overview) for details.
+| Component  | Supported                                                          |
+| ---------- | ------------------------------------------------------------------ |
+| Ruby       | 3.2+                                                               |
+| Rails      | 7.2+                                                               |
+| ParadeDB   | 0.25.0+                                                            |
+| PostgreSQL | 15+ (with the ParadeDB pg_search extension)                        |
+| pgvector   | Required for vector search (included in the ParadeDB Docker image) |
 
 ## Examples
 
 - [Quickstart](examples/quickstart/quickstart.rb)
 - [Vector Search](examples/vector_search/vector_search.rb)
 - [Faceted Search](examples/faceted_search/faceted_search.rb)
+- [Hybrid Search (RRF)](examples/hybrid_rrf/hybrid_rrf.rb)
+- [Retrieval-Augmented Generation (RAG)](examples/rag/rag.rb)
 - [Autocomplete](examples/autocomplete/autocomplete.rb)
 - [More Like This](examples/more_like_this/more_like_this.rb)
-- [Hybrid Search (RRF)](examples/hybrid_rrf/hybrid_rrf.rb)
-- [RAG](examples/rag/rag.rb)
+
+See [examples/README.md](examples/README.md) for setup instructions and a description of each example.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, test commands, linting, and PR workflow.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, running tests, linting, and the PR workflow.
 
 ## Support
 
-If you're missing a feature or have found a bug, open a
+If you're missing a feature or have found a bug, please open a
 [GitHub Issue](https://github.com/paradedb/rails-paradedb/issues/new/choose).
 
-For community support:
+To get community support, you can:
 
-- Join the [ParadeDB Slack Community](https://paradedb.com/slack)
-- Ask in [ParadeDB Discussions](https://github.com/paradedb/paradedb/discussions)
+- Post a question in the [ParadeDB Slack Community](https://paradedb.com/slack)
+- Ask for help on our [GitHub Discussions](https://github.com/paradedb/paradedb/discussions)
 
-For commercial support, contact [sales@paradedb.com](mailto:sales@paradedb.com).
+If you need commercial support, please [contact the ParadeDB team](mailto:sales@paradedb.com).
 
 ## Acknowledgments
 

data/lib/parade_db/aggregations.rb

@@ -7,14 +7,7 @@ module ParadeDB
       # Backward-compatible reader for code that accessed `filtered_spec.filter`.
       alias filter agg_filter
     end
-    FieldTermFilter = Struct.new(
-      :field,
-      :term,
-      :distance,
-      :prefix,
-      :transposition_cost_one,
-      keyword_init: true
-    )
+    FieldTermFilter = Struct.new(:field, :term, keyword_init: true)
 
     TERMS_ORDER = {
       count_desc: { "_count" => "desc" },
@@ -154,16 +147,9 @@ module ParadeDB
       { "top_hits" => payload }
     end
 
-    def filtered(spec, filter: nil, field: nil, term: nil, distance: nil, prefix: nil, transposition_cost_one: nil)
+    def filtered(spec, filter: nil, field: nil, term: nil)
       normalized_spec = normalize_spec(spec)
-      normalized_filter = normalize_filter(
-        filter: filter,
-        field: field,
-        term: term,
-        distance: distance,
-        prefix: prefix,
-        transposition_cost_one: transposition_cost_one
-      )
+      normalized_filter = normalize_filter(filter: filter, field: field, term: term)
       FilteredSpec.new(spec: normalized_spec, agg_filter: normalized_filter)
     end
 
@@ -211,7 +197,7 @@ module ParadeDB
     end
     private_class_method :normalize_spec
 
-    def normalize_filter(filter:, field:, term:, distance:, prefix:, transposition_cost_one:)
+    def normalize_filter(filter:, field:, term:)
       if filter
         if !field.nil? || !term.nil?
           raise ArgumentError, "filtered aggregation accepts either filter: or field/term arguments, not both"
@@ -223,17 +209,7 @@ module ParadeDB
         raise ArgumentError, "filtered aggregation requires filter: or both field: and term:"
       end
 
-      normalized_distance = distance.nil? ? nil : normalize_non_negative_integer(distance, "distance")
-      normalized_prefix = normalize_boolean_option(prefix, "prefix")
-      normalized_transposition = normalize_boolean_option(transposition_cost_one, "transposition_cost_one")
-
-      FieldTermFilter.new(
-        field: normalize_field(field),
-        term: term,
-        distance: normalized_distance,
-        prefix: normalized_prefix,
-        transposition_cost_one: normalized_transposition
-      )
+      FieldTermFilter.new(field: normalize_field(field), term: term)
     end
     private_class_method :normalize_filter
 
@@ -318,14 +294,6 @@ module ParadeDB
     end
     private_class_method :normalize_sort_direction
 
-    def normalize_boolean_option(value, name)
-      return nil if value.nil?
-      return value if value == true || value == false
-
-      raise ArgumentError, "#{name} must be true, false, or nil"
-    end
-    private_class_method :normalize_boolean_option
-
     def deep_stringify(value)
       case value
       when Hash

data/lib/parade_db/model.rb

@@ -11,12 +11,14 @@ module ParadeDB
       :paradedb_search,
       :more_like_this,
       :nearest,
+      :l2_distance,
+      :cosine_distance,
+      :inner_product,
       :with_facets,
       :facets,
       :with_agg,
       :facets_agg,
       :aggregate_by,
-      :paradedb_arel,
       :paradedb_index,
       :paradedb_index_class,
       :paradedb_index_classes,
@@ -74,6 +76,21 @@ module ParadeDB
         all.extending(SearchMethods).nearest(column, vector, metric: metric)
       end
 
+      def l2_distance(column, vector)
+        ensure_postgres!
+        QueryBuilder.new(table_name).vector_distance(column, vector, metric: :l2)
+      end
+
+      def cosine_distance(column, vector)
+        ensure_postgres!
+        QueryBuilder.new(table_name).vector_distance(column, vector, metric: :cosine)
+      end
+
+      def inner_product(column, vector)
+        ensure_postgres!
+        QueryBuilder.new(table_name).vector_distance(column, vector, metric: :ip)
+      end
+
       def with_facets(*fields, **opts)
         ensure_postgres!
         paradedb_validate_index!
@@ -108,11 +125,6 @@ module ParadeDB
         )
       end
 
-      def paradedb_arel
-        ensure_postgres!
-        @paradedb_arel ||= ParadeDB::Arel::Builder.new(table_name)
-      end
-
       def paradedb_index(index_class)
         @paradedb_explicit_index_classes ||= []
         @paradedb_explicit_index_classes << index_class unless @paradedb_explicit_index_classes.include?(index_class)

data/lib/parade_db/query_builder.rb

@@ -0,0 +1,415 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "vector"
+
+module ParadeDB
+  class QueryBuilder
+    RANGE_TYPES = %w[int4range int8range numrange daterange tsrange tstzrange].freeze
+    RANGE_RELATIONS = %w[Intersects Contains Within].freeze
+    Modifier = Data.define(:type, :value, :options)
+    attr_reader :table
+
+    def initialize(table = nil)
+      @table = table
+    end
+
+    def [](column)
+      column_node(column)
+    end
+
+    def boost(value, factor)
+      validate_numeric!(factor, :factor)
+      Modifier.new(type: :boost, value: value, options: { factor: factor })
+    end
+
+    def constant(value, score)
+      validate_numeric!(score, :score)
+      Modifier.new(type: :constant, value: value, options: { score: score })
+    end
+
+    def fuzzy(value, distance, prefix: nil, transposition_cost_one: nil)
+      validate_fuzzy_distance!(distance)
+      Modifier.new(
+        type: :fuzzy,
+        value: value,
+        options: { distance: distance, prefix: prefix, transposition_cost_one: transposition_cost_one }
+      )
+    end
+
+    def slop(value, distance)
+      validate_numeric!(distance, :distance)
+      Modifier.new(type: :slop, value: value, options: { distance: distance })
+    end
+
+    def tokenize(value, tokenizer)
+      raise ArgumentError, "tokenizer must be a Tokenizer" unless tokenizer.is_a?(ParadeDB::Tokenizer)
+
+      Modifier.new(type: :tokenizer, value: value, options: { tokenizer: tokenizer })
+    end
+
+    def match(column, term = nil)
+      infix("&&&", column_node(column), term_query_node(term))
+    end
+
+    def match_any(column, term = nil)
+      infix("|||", column_node(column), term_query_node(term))
+    end
+
+    def phrase(column, text)
+      rhs = text.is_a?(Array) ? array_node(normalize_phrase_terms(text).map { |term| quoted_value(term) }) : search_value_node(text)
+      infix("###", column_node(column), rhs)
+    end
+
+    def term(column, term)
+      infix("===", column_node(column), search_value_node(term))
+    end
+
+    def term_set(column, *terms)
+      array = array_node(normalize_term_set_terms(terms).map { |term| quoted_value(term) })
+      infix("@@@", column_node(column), ::Arel::Nodes::NamedFunction.new("pdb.term_set", [array]))
+    end
+
+    def regex(column, pattern)
+      infix("@@@", column_node(column), ::Arel::Nodes::NamedFunction.new("pdb.regex", [search_value_node(pattern)]))
+    end
+
+    def regex_phrase(column, *patterns, slop: nil, max_expansions: nil)
+      args = [array_node(normalize_regex_patterns(patterns).map { |pattern| quoted_value(pattern) })]
+      unless slop.nil?
+        validate_numeric!(slop, :slop)
+        args << keyword_arg_node("slop", slop)
+      end
+      unless max_expansions.nil?
+        validate_integer!(max_expansions, :max_expansions)
+        args << keyword_arg_node("max_expansions", max_expansions)
+      end
+      infix("@@@", column_node(column), ::Arel::Nodes::NamedFunction.new("pdb.regex_phrase", args))
+    end
+
+    def near(column, proximity)
+      rhs = proximity.is_a?(Modifier) || arel_expression?(proximity) ? search_value_node(proximity) : proximity_query_node(proximity)
+      infix("@@@", column_node(column), rhs)
+    end
+
+    def phrase_prefix(column, *terms, max_expansion: nil)
+      flat = terms.flatten.compact
+      raise ArgumentError, "phrase_prefix requires at least one term" if flat.empty?
+
+      args = [array_node(flat.map { |term| quoted_value(term) })]
+      unless max_expansion.nil?
+        validate_integer!(max_expansion, :max_expansion)
+        args << quoted_value(max_expansion)
+      end
+      infix("@@@", column_node(column), ::Arel::Nodes::NamedFunction.new("pdb.phrase_prefix", args))
+    end
+
+    def parse(column, query, lenient: nil, conjunction_mode: nil)
+      args = [quoted_value(query)]
+      args << keyword_arg_node("lenient", lenient) unless lenient.nil?
+      args << keyword_arg_node("conjunction_mode", conjunction_mode) unless conjunction_mode.nil?
+      infix("@@@", column_node(column), ::Arel::Nodes::NamedFunction.new("pdb.parse", args))
+    end
+
+    def match_all(column)
+      infix("@@@", column_node(column), ::Arel::Nodes::NamedFunction.new("pdb.all", []))
+    end
+
+    def exists(column)
+      infix("@@@", column_node(column), ::Arel::Nodes::NamedFunction.new("pdb.exists", []))
+    end
+
+    def range(column, value = nil, gte: nil, gt: nil, lte: nil, lt: nil, type: nil)
+      range_node = build_range_node(value, gte: gte, gt: gt, lte: lte, lt: lt, type: type)
+      infix("@@@", column_node(column), ::Arel::Nodes::NamedFunction.new("pdb.range", [range_node]))
+    end
+
+    def range_term(column, value, relation: nil, range_type: nil)
+      infix("@@@", column_node(column), build_range_term_node(value, relation: relation, range_type: range_type))
+    end
+
+    def more_like_this(column, key, fields: nil, options: {})
+      args = [quoted_value(key)]
+      args << array_node(Array(fields).map { |field| quoted_value(field.to_s) }) unless fields.nil?
+      options.each { |name, value| args << mlt_option_node(name, value) }
+      infix("@@@", column_node(column), ::Arel::Nodes::NamedFunction.new("pdb.more_like_this", args))
+    end
+
+    def vector_distance(column, vector, metric: ParadeDB::Vector::DEFAULT_METRIC)
+      operator = ParadeDB::Vector::DISTANCE_OPERATORS.fetch(ParadeDB::Vector.normalize_metric(metric))
+      infix(operator, column_node(column), vector_operand(vector))
+    end
+
+    def score(key)
+      ::Arel::Nodes::NamedFunction.new("pdb.score", [column_node(key)])
+    end
+
+    def snippet(column, *args)
+      ::Arel::Nodes::NamedFunction.new("pdb.snippet", [column_node(column)] + args.map { |arg| quoted_value(arg) })
+    end
+
+    def snippets(column, start_tag: nil, end_tag: nil, max_num_chars: nil, limit: nil, offset: nil, sort_by: nil)
+      args = [column_node(column)]
+      args << keyword_arg_node("start_tag", start_tag) unless start_tag.nil?
+      args << keyword_arg_node("end_tag", end_tag) unless end_tag.nil?
+      args << keyword_arg_node("max_num_chars", max_num_chars) unless max_num_chars.nil?
+      args << keyword_arg_node("limit", limit, quoted_name: true) unless limit.nil?
+      args << keyword_arg_node("offset", offset, quoted_name: true) unless offset.nil?
+      args << keyword_arg_node("sort_by", sort_by) unless sort_by.nil?
+      ::Arel::Nodes::NamedFunction.new("pdb.snippets", args)
+    end
+
+    def snippet_positions(column)
+      ::Arel::Nodes::NamedFunction.new("pdb.snippet_positions", [column_node(column)])
+    end
+
+    def agg(json, exact: nil)
+      raise ArgumentError, "exact must be true, false, or nil" unless exact.nil? || exact == true || exact == false
+
+      args = [quoted_value(json)]
+      args << quoted_value(false) if exact == false
+      ::Arel::Nodes::NamedFunction.new("pdb.agg", args)
+    end
+
+    private
+
+    def infix(operator, left, right)
+      ::Arel::Nodes::InfixOperation.new(operator, left, right)
+    end
+
+    def column_node(column)
+      case column
+      when ::Arel::Attributes::Attribute, ::Arel::Nodes::Node, ::Arel::Nodes::SqlLiteral
+        column
+      when Symbol, String
+        @table ? arel_table[column.to_sym] : ::Arel.sql(column.to_s)
+      else
+        raise ArgumentError, "Unsupported column type: #{column.class}"
+      end
+    end
+
+    def quoted_value(value)
+      ::Arel::Nodes.build_quoted(value)
+    end
+
+    def array_node(values)
+      ::Arel.sql("ARRAY[#{Array.new(values.length, "?").join(", ")}]", *values)
+    end
+
+    def cast_node(node, type)
+      ::Arel.sql("?::#{type}", node)
+    end
+
+    def modifier_node(modifier)
+      node = search_value_node(modifier.value)
+
+      case modifier.type
+      when :boost
+        cast_node(node, "pdb.boost(#{modifier.options[:factor]})")
+      when :constant
+        node = cast_node(node, "pdb.query") if modifier.value.is_a?(Modifier) && %i[fuzzy slop].include?(modifier.value.type)
+        cast_node(node, "pdb.const(#{modifier.options[:score]})")
+      when :fuzzy
+        args = [modifier.options[:distance]]
+        if modifier.options[:transposition_cost_one]
+          args << %("#{modifier.options[:prefix] ? 'true' : 'false'}") << '"true"'
+        elsif modifier.options[:prefix]
+          args << '"true"'
+        end
+        cast_node(node, "pdb.fuzzy(#{args.join(", ")})")
+      when :slop
+        cast_node(node, "pdb.slop(#{modifier.options[:distance]})")
+      when :tokenizer
+        cast_node(node, modifier.options[:tokenizer].render)
+      end
+    end
+
+    def vector_operand(vector)
+      return vector if arel_expression?(vector)
+
+      cast_node(quoted_value(vector.is_a?(String) ? vector : ParadeDB::Vector.literal(vector)), "vector")
+    end
+
+    def proximity_query_node(proximity)
+      raise ArgumentError, "near requires a ParadeDB.proximity(...) clause" unless proximity.is_a?(ParadeDB::Proximity::Clause)
+      raise ArgumentError, "near requires at least one within clause" if proximity.clauses.empty?
+
+      compile_proximity_clause(proximity)
+    end
+
+    def compile_proximity_clause(clause)
+      current = proximity_operand_node(clause.operand, empty_message: "proximity requires at least one term")
+      clause.clauses.each do |within_clause|
+        validate_numeric!(within_clause.distance, :distance)
+        operator = within_clause.ordered ? "##>" : "##"
+        right = proximity_operand_node(within_clause.operand, empty_message: "within requires at least one term")
+        current = ::Arel::Nodes::Grouping.new(infix(operator, infix(operator, current, quoted_value(within_clause.distance)), right))
+      end
+      current
+    end
+
+    def prox_regex_node(pattern, max_expansions)
+      args = [quoted_value(pattern)]
+      unless max_expansions.nil?
+        validate_integer!(max_expansions, :max_expansions)
+        args << quoted_value(max_expansions)
+      end
+      ::Arel::Nodes::NamedFunction.new("pdb.prox_regex", args)
+    end
+
+    def proximity_operand_node(terms, empty_message:)
+      return compile_proximity_clause(terms) if terms.is_a?(ParadeDB::Proximity::Clause)
+
+      values = Array(terms).flatten.compact
+      raise ArgumentError, empty_message if values.empty?
+      return proximity_term_node(values.first) if values.length == 1
+
+      ::Arel::Nodes::NamedFunction.new("pdb.prox_array", values.map { |term| proximity_term_node(term) })
+    end
+
+    def proximity_term_node(term)
+      if term.is_a?(ParadeDB::Proximity::Clause)
+        raise ArgumentError, "nested proximity clauses must be passed directly, not inside an array"
+      end
+      return prox_regex_node(term.pattern, term.max_expansions) if term.is_a?(ParadeDB::Proximity::RegexTerm)
+
+      quoted_value(term)
+    end
+
+    def build_range_node(value, gte:, gt:, lte:, lt:, type:)
+      lower, upper, lower_inclusive, upper_inclusive = normalize_range_bounds(value, gte: gte, gt: gt, lte: lte, lt: lt)
+      range_type = normalize_range_type(type || infer_range_type(lower, upper))
+      bounds = "#{lower_inclusive ? "[" : "("}#{upper_inclusive ? "]" : ")"}"
+      ::Arel::Nodes::NamedFunction.new(range_type, [range_bound_node(lower), range_bound_node(upper), quoted_value(bounds)])
+    end
+
+    def normalize_range_bounds(value, gte:, gt:, lte:, lt:)
+      if value.is_a?(Range)
+        raise ArgumentError, "range bounds cannot be mixed with a Ruby Range value" if [gte, gt, lte, lt].any? { |bound| !bound.nil? }
+
+        return [value.begin, value.end, true, !value.exclude_end?]
+      end
+
+      raise ArgumentError, "range expects a Ruby Range or bound options (gte/gt/lte/lt)" unless value.nil?
+      raise ArgumentError, "range lower bound cannot include both gte and gt" if !gte.nil? && !gt.nil?
+      raise ArgumentError, "range upper bound cannot include both lte and lt" if !lte.nil? && !lt.nil?
+
+      lower = gt.nil? ? gte : gt
+      upper = lt.nil? ? lte : lt
+      raise ArgumentError, "range requires at least one bound" if lower.nil? && upper.nil?
+
+      [lower, upper, gt.nil?, lt.nil?]
+    end
+
+    def infer_range_type(lower, upper)
+      values = [lower, upper].compact
+      raise ArgumentError, "range requires at least one non-nil bound to infer type" if values.empty?
+      return "int8range" if values.all? { |value| value.is_a?(Integer) }
+      return "numrange" if values.all? { |value| value.is_a?(Numeric) }
+      return "daterange" if values.all? { |value| value.is_a?(Date) && !value.is_a?(DateTime) }
+      return "tsrange" if values.all? { |value| value.is_a?(Time) || value.is_a?(DateTime) }
+
+      raise ArgumentError, "Unable to infer range type from bound values; pass type: explicitly"
+    end
+
+    def normalize_range_type(range_type)
+      value = range_type.to_s
+      raise ArgumentError, "Unknown range type: #{range_type.inspect}. Expected one of: #{RANGE_TYPES.join(', ')}" unless RANGE_TYPES.include?(value)
+
+      value
+    end
+
+    def normalize_range_relation(relation)
+      value = relation.to_s.capitalize
+      raise ArgumentError, "Unknown range relation: #{relation.inspect}. Expected one of: #{RANGE_RELATIONS.join(', ')}" unless RANGE_RELATIONS.include?(value)
+
+      value
+    end
+
+    def build_range_term_node(value, relation:, range_type:)
+      if relation.nil?
+        raise ArgumentError, "range_type is only valid when relation is provided" unless range_type.nil?
+
+        return ::Arel::Nodes::NamedFunction.new("pdb.range_term", [quoted_value(value)])
+      end
+
+      raise ArgumentError, "relation requires range_type" if range_type.nil?
+
+      cast_value = cast_node(quoted_value(value), normalize_range_type(range_type))
+      ::Arel::Nodes::NamedFunction.new("pdb.range_term", [cast_value, quoted_value(normalize_range_relation(relation))])
+    end
+
+    def range_bound_node(value)
+      value.nil? ? ::Arel.sql("NULL") : quoted_value(value)
+    end
+
+    def mlt_option_node(name, value)
+      rendered = name.to_sym == :stopwords ? array_node(Array(value).map { |term| quoted_value(term.to_s) }) : quoted_value(value)
+      ::Arel::Nodes::InfixOperation.new("=>", ::Arel.sql(name.to_s), rendered)
+    end
+
+    def keyword_arg_node(name, value, quoted_name: false)
+      ::Arel::Nodes::InfixOperation.new("=>", ::Arel.sql(quoted_name ? %("#{name}") : name), quoted_value(value))
+    end
+
+    def term_query_node(term)
+      return search_value_node(term) if term.is_a?(Modifier) || arel_expression?(term)
+
+      joined = term.to_s
+      raise ArgumentError, "at least one search term is required" if joined.strip.empty?
+
+      quoted_value(joined)
+    end
+
+    def search_value_node(value)
+      return value if arel_expression?(value)
+      return modifier_node(value) if value.is_a?(Modifier)
+      return array_node(value.map { |item| quoted_value(item) }) if value.is_a?(Array)
+      return proximity_query_node(value) if value.is_a?(ParadeDB::Proximity::Clause)
+
+      quoted_value(value)
+    end
+
+    def arel_expression?(value)
+      value.is_a?(::Arel::Nodes::Node) || value.is_a?(::Arel::Attributes::Attribute)
+    end
+
+    def normalize_term_set_terms(terms)
+      values = Array(terms).flatten.compact
+      raise ArgumentError, "term_set requires at least one value" if values.empty?
+
+      values
+    end
+
+    def normalize_phrase_terms(terms)
+      values = Array(terms).flatten.compact.map(&:to_s)
+      raise ArgumentError, "phrase array input requires at least one term" if values.empty? || values.all?(&:empty?)
+
+      values
+    end
+
+    def normalize_regex_patterns(patterns)
+      values = Array(patterns).flatten.compact.map(&:to_s)
+      raise ArgumentError, "regex_phrase requires at least one pattern" if values.empty? || values.all?(&:empty?)
+
+      values
+    end
+
+    def validate_numeric!(value, name)
+      raise ArgumentError, "#{name} must be numeric, got #{value.class}" unless value.is_a?(Numeric)
+    end
+
+    def validate_fuzzy_distance!(distance)
+      validate_numeric!(distance, :distance)
+      raise ArgumentError, "distance must be between 0 and 2" unless (0..2).cover?(distance)
+    end
+
+    def validate_integer!(value, name)
+      raise ArgumentError, "#{name} must be an integer" unless value.is_a?(Integer)
+    end
+
+    def arel_table
+      @arel_table ||= ::Arel::Table.new(@table.to_s)
+    end
+  end
+end