rails-paradedb 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e28ebb1ec7734474a1ed321766b2e652f4aa1d56aadcc16d48667ac4ddbfc5bc
-  data.tar.gz: 51c25b12045eed272ad0e71475c22f9a670c4da6ff46fcad6d99ce32e3bc1f6e
+  metadata.gz: 25216744f6402f3ffdc06d8381f8ed801acec379dc15c71b92187b9e28a61b6d
+  data.tar.gz: 64dfcdcefa05ff52d0cd6b4b0292c005a0f4c2cf3a193ee07ac27bdae175ddd0
 SHA512:
-  metadata.gz: 4fced3ee50bef2ef4c59567246e9c5382a7e2e3f60293a785d33fe4e9e857abea685740fcf2c2da38c98dce4371d13010f9eacbbbe1c580df760208a20542f3d
-  data.tar.gz: 2e3efbf965bb99866dffe45de2963528ccf9ebfaa4a947abe5b72211306409d5b006eb1e90621cc6591e72f473d91593348b0d1bcaaa1e96cbc08cbe252e8615
+  metadata.gz: f3fb68ca97ffc5a30f6d503f15e97b02bc8db1de5aaeab020991848f777bc401fc62d06049490790ef75416b80c6a226edeb8cfe91e2bd8d8c3d76d12e95accb
+  data.tar.gz: 6c1e58314734c06d138a32f8a6928d13c7178e7db44e8460a45efbfb128e168d81f22dac53f74bc57ccd19f88f4ad0fdf60c3590dfcfd8d04e39b80d39faf531

data/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+[0.9.0] - 2026-07-14
+
+### Added
+
+- Allow SQL/Arel function nodes as `match_all` and `match_any` query arguments.
+
+### Changed
+
+- **BREAKING**: Restrict match APIs to a single query argument.
+- **BREAKING**: Rename relation query methods `matching_all` and `matching_any`
+  to `match_all` and `match_any`.
+
+### Removed
+
+- **BREAKING**: Removed max_term_freq from the more_like_this API.
+
+## [0.8.0] - 2026-06-15
+
+### Changed
+
+- **BREAKING**: The `Tokenizer` class is now namespaced as `ParadeDB::Tokenizer`. Update references from `Tokenizer.simple(...)` to `ParadeDB::Tokenizer.simple(...)`. Schema dumps (`schema.rb`) now emit the fully-qualified constant.
+
 ## [0.7.0] - 2026-04-21
 
 ### Changed
@@ -132,7 +154,9 @@ 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`)
 
-[Unreleased]: https://github.com/paradedb/rails-paradedb/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/paradedb/rails-paradedb/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.9.0
+[0.8.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.8.0
 [0.7.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.7.0
 [0.6.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.6.0
 [0.5.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.5.0

data/README.md

@@ -1,11 +1,17 @@
-<!-- ParadeDB: Postgres for Search and Analytics -->
 <h1 align="center">
-  <a href="https://paradedb.com"><img src="https://github.com/paradedb/paradedb/raw/main/docs/logo/readme.svg" alt="ParadeDB"></a>
-<br>
+  <a href="https://paradedb.com">
+    <picture align=center>
+      <source media="(prefers-color-scheme: dark)" srcset="https://github.com/paradedb/paradedb/raw/main/docs/logo/paradedb-logo-dark-large.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://github.com/paradedb/paradedb/raw/main/docs/logo/paradedb-logo-light-large.svg">
+      <img alt="The ParadeDB logo." src="https://github.com/paradedb/paradedb/raw/main/docs/logo/paradedb-logo-light-large.svg">
+    </picture>
+  </a>
+  <br>
 </h1>
 
 <p align="center">
-  <b>Simple, Elastic-quality search for Postgres</b><br/>
+  <b>Search without a second system.</b><br/>
+  One Postgres for your application data, full-text search, vector retrieval, and aggregations.
 </p>
 
 <h3 align="center">
@@ -30,7 +36,7 @@
 
 ## ParadeDB for Rails
 
-The official ActiveRecord integration for [ParadeDB](https://paradedb.com), including first-class support for managing BM25 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 integration for [ParadeDB](https://paradedb.com) (powered by the [`pg_search`](https://github.com/paradedb/paradedb) Postgres extension), including first-class support for managing BM25 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.
 
 ## Requirements & Compatibility
 

data/lib/parade_db/arel/builder.rb

@@ -21,7 +21,7 @@ module ParadeDB
 
       def match(
         column,
-        *terms,
+        term = nil,
         tokenizer: nil,
         distance: nil,
         prefix: nil,
@@ -35,7 +35,7 @@ module ParadeDB
           prefix: prefix,
           transposition_cost_one: transposition_cost_one
         )
-        rhs = quoted_value(join_terms(terms))
+        rhs = term_query_node(term)
         rhs = apply_fuzzy(
           rhs,
           distance: distance,
@@ -50,7 +50,7 @@ module ParadeDB
 
       def match_any(
         column,
-        *terms,
+        term = nil,
         tokenizer: nil,
         distance: nil,
         prefix: nil,
@@ -64,7 +64,7 @@ module ParadeDB
           prefix: prefix,
           transposition_cost_one: transposition_cost_one
         )
-        rhs = quoted_value(join_terms(terms))
+        rhs = term_query_node(term)
         rhs = apply_fuzzy(
           rhs,
           distance: distance,
@@ -302,7 +302,7 @@ module ParadeDB
       def apply_tokenizer(node, tokenizer)
         return node if tokenizer.nil?
 
-        unless tokenizer.is_a?(Tokenizer)
+        unless tokenizer.is_a?(ParadeDB::Tokenizer)
           raise ArgumentError, "tokenizer must be a Tokenizer"
         end
 
@@ -538,12 +538,24 @@ module ParadeDB
         )
       end
 
-      def join_terms(terms)
-        joined = terms.flatten.compact.map(&:to_s).join(" ")
+      def join_term(term)
+        joined = term.to_s
         raise ArgumentError, "at least one search term is required" if joined.strip.empty?
         joined
       end
 
+      def term_query_node(term)
+        return term if arel_expression?(term)
+
+        quoted_value(join_term(term))
+      end
+
+      def arel_expression?(value)
+        value.is_a?(::Arel::Nodes::Node) ||
+          value.is_a?(::Arel::Attributes::Attribute) ||
+          value.is_a?(::Arel::Nodes::SqlLiteral)
+      end
+
       def normalize_term_set_terms(terms)
         values = Array(terms).flatten.compact
         raise ArgumentError, "term_set requires at least one value" if values.empty?

data/lib/parade_db/arel/predications.rb

@@ -7,16 +7,16 @@ module ParadeDB
       TOKENIZER_EXPRESSION = /\A[a-zA-Z_][a-zA-Z0-9_]*(?:(?:::|\.)[a-zA-Z_][a-zA-Z0-9_]*)*(?:\(\s*[a-zA-Z0-9_'".,=\s:-]*\s*\))?\z/.freeze
       BUILDER = Builder.new.freeze
 
-      def pdb_match(*terms, tokenizer: nil, distance: nil, prefix: nil, transposition_cost_one: nil, boost: nil)
-        rhs = pdb_quoted(pdb_join_terms(terms))
+      def pdb_match(term = nil, tokenizer: nil, distance: nil, prefix: nil, transposition_cost_one: nil, boost: nil)
+        rhs = pdb_term_query_node(term)
         rhs = pdb_apply_fuzzy(rhs, distance: distance, prefix: prefix, transposition_cost_one: transposition_cost_one)
         rhs = pdb_apply_tokenizer(rhs, tokenizer)
         rhs = pdb_apply_boost(rhs, boost)
         ::Arel::Nodes::InfixOperation.new("&&&", self, rhs)
       end
 
-      def pdb_match_any(*terms, tokenizer: nil, distance: nil, prefix: nil, transposition_cost_one: nil, boost: nil)
-        rhs = pdb_quoted(pdb_join_terms(terms))
+      def pdb_match_any(term = nil, tokenizer: nil, distance: nil, prefix: nil, transposition_cost_one: nil, boost: nil)
+        rhs = pdb_term_query_node(term)
         rhs = pdb_apply_fuzzy(rhs, distance: distance, prefix: prefix, transposition_cost_one: transposition_cost_one)
         rhs = pdb_apply_tokenizer(rhs, tokenizer)
         rhs = pdb_apply_boost(rhs, boost)
@@ -193,11 +193,19 @@ module ParadeDB
         ::Arel::Nodes.build_quoted(value)
       end
 
-      def pdb_join_terms(terms)
-        joined = terms.flatten.compact.map(&:to_s).join(" ")
+      def pdb_term_query_node(term)
+        return term if pdb_arel_expression?(term)
+
+        joined = term.to_s
         raise ArgumentError, "at least one search term is required" if joined.strip.empty?
 
-        joined
+        pdb_quoted(joined)
+      end
+
+      def pdb_arel_expression?(value)
+        value.is_a?(::Arel::Nodes::Node) ||
+          value.is_a?(::Arel::Attributes::Attribute) ||
+          value.is_a?(::Arel::Nodes::SqlLiteral)
       end
 
       def pdb_validate_numeric!(value, name)

data/lib/parade_db/index.rb

@@ -53,7 +53,7 @@ module ParadeDB
 
       class << self
         def parse(source_name, tokenizer, context:)
-          unless tokenizer.is_a?(Tokenizer)
+          unless tokenizer.is_a?(ParadeDB::Tokenizer)
             raise InvalidIndexDefinition, "#{context} for #{source_name.inspect} must be a Tokenizer"
           end
 

data/lib/parade_db/migration_helpers.rb

@@ -422,7 +422,7 @@ module ParadeDB
 
       with_sql = indexdef[start..pos - 2]
       trailing_sql = indexdef[pos..]&.strip
-      trailing_sql = nil if trailing_sql&.empty?
+      trailing_sql = nil if trailing_sql == ""
 
       [with_sql, trailing_sql]
     end
@@ -695,13 +695,13 @@ module ParadeDB
     end
 
     def bm25_tokenizer_ruby(name, positional_args, options)
-      if name.match?(/\A[a-z_][a-z0-9_]*\z/) && Tokenizer.respond_to?(name)
+      if name.match?(/\A[a-z_][a-z0-9_]*\z/) && ParadeDB::Tokenizer.respond_to?(name)
         args = positional_args.map { |arg| ruby_literal(arg) }
         args << "options: #{ruby_hash_literal(options)}" unless options.empty?
-        return "Tokenizer.#{name}(#{args.join(', ')})"
+        return "ParadeDB::Tokenizer.#{name}(#{args.join(', ')})"
       end
 
-      "Tokenizer.new(#{name.inspect}, #{ruby_literal(positional_args.empty? ? nil : positional_args)}, #{ruby_literal(options.empty? ? nil : options)})"
+      "ParadeDB::Tokenizer.new(#{name.inspect}, #{ruby_literal(positional_args.empty? ? nil : positional_args)}, #{ruby_literal(options.empty? ? nil : options)})"
     end
 
     def split_sql_arguments(args_sql)

data/lib/parade_db/search_methods.rb

@@ -13,8 +13,6 @@ module ParadeDB
       max_query_terms: :max_query_terms,
       min_doc_freq: :min_doc_frequency,
       min_doc_frequency: :min_doc_frequency,
-      max_term_freq: :max_term_frequency,
-      max_term_frequency: :max_term_frequency,
       max_doc_freq: :max_doc_frequency,
       max_doc_frequency: :max_doc_frequency,
       min_word_length: :min_word_length,
@@ -25,7 +23,6 @@ module ParadeDB
       min_term_frequency
       max_query_terms
       min_doc_frequency
-      max_term_frequency
       max_doc_frequency
       min_word_length
       max_word_length
@@ -34,13 +31,11 @@ module ParadeDB
       min_term_frequency
       max_query_terms
       min_doc_frequency
-      max_term_frequency
       max_doc_frequency
       min_word_length
       max_word_length
       stopwords
     ].freeze
-
     # Internal state tracking
     attr_accessor :_paradedb_current_field
     attr_accessor :_paradedb_facet_fields
@@ -120,8 +115,8 @@ module ParadeDB
       extending(SearchMethods).tap { |rel| rel._paradedb_current_field = search_column }
     end
 
-    def matching_all(
-      *terms,
+    def match_all(
+      term = nil,
       tokenizer: nil,
       distance: nil,
       prefix: nil,
@@ -131,21 +126,26 @@ module ParadeDB
     )
       require_search_field!
 
-      node = builder.match(
-        _paradedb_current_field,
-        *terms,
-        tokenizer: tokenizer,
-        distance: distance,
-        prefix: prefix,
-        transposition_cost_one: transposition_cost_one,
-        boost: boost,
-        constant_score: constant_score
-      )
+      node =
+        if term.nil? && tokenizer.nil? && distance.nil? && prefix.nil? && transposition_cost_one.nil?
+          builder.match_all(_paradedb_current_field, boost: boost, constant_score: constant_score)
+        else
+          builder.match(
+            _paradedb_current_field,
+            term,
+            tokenizer: tokenizer,
+            distance: distance,
+            prefix: prefix,
+            transposition_cost_one: transposition_cost_one,
+            boost: boost,
+            constant_score: constant_score
+          )
+        end
       where(grouped(node))
     end
 
-    def matching_any(
-      *terms,
+    def match_any(
+      term,
       tokenizer: nil,
       distance: nil,
       prefix: nil,
@@ -157,7 +157,7 @@ module ParadeDB
 
       node = builder.match_any(
         _paradedb_current_field,
-        *terms,
+        term,
         tokenizer: tokenizer,
         distance: distance,
         prefix: prefix,
@@ -168,10 +168,10 @@ module ParadeDB
       where(grouped(node))
     end
 
-    def excluding(*terms)
+    def excluding(term)
       require_search_field!
 
-      neg = builder.match(_paradedb_current_field, *terms)
+      neg = builder.match(_paradedb_current_field, term)
       where(grouped(neg.not))
     end
 
@@ -273,14 +273,6 @@ module ParadeDB
       where(grouped(node))
     end
 
-    # Match-all wrapper for APIs that need an explicit ParadeDB predicate.
-    # Use with `.search(:id)` (or any indexed field): `Product.search(:id).match_all`.
-    def match_all(boost: nil, constant_score: nil)
-      require_search_field!
-
-      where(grouped(builder.match_all(_paradedb_current_field, boost: boost, constant_score: constant_score)))
-    end
-
     # Exists wrapper to match rows where the indexed field has a value.
     # Use with `.search(:id)` (or another exists-compatible indexed field).
     def exists(boost: nil, constant_score: nil)

data/lib/parade_db/tokenizer.rb

@@ -1,95 +1,97 @@
-class Tokenizer
-  attr_reader :name, :positional_args, :options
+module ParadeDB
+  class Tokenizer
+    attr_reader :name, :positional_args, :options
+
+    def initialize(name, positional_args, options)
+      @name = name
+      @positional_args = positional_args
+      @options = options
+    end
 
-  def initialize(name, positional_args, options)
-    @name = name
-    @positional_args = positional_args
-    @options = options
-  end
+    def render()
+      if options.nil? && positional_args.nil?
+        return "pdb.#{name}"
+      end
 
-  def render()
-    if options.nil? && positional_args.nil?
-      return "pdb.#{name}"
-    end
+      args = []
+      if !positional_args.nil?
+        args.concat(positional_args.map { |x| render_positional_arg(x) })
+      end
+      if !options.nil?
+        args.concat(options.map {|k, v| quote_term("#{k}=#{v}")})
+      end
 
-    args = []
-    if !positional_args.nil?
-      args.concat(positional_args.map { |x| render_positional_arg(x) })
-    end
-    if !options.nil?
-      args.concat(options.map {|k, v| quote_term("#{k}=#{v}")})
+      return "pdb.#{name}(#{args.join(",")})"
     end
 
-    return "pdb.#{name}(#{args.join(",")})"
-  end
-
-  def self.whitespace(options: nil)
-    new("whitespace", nil, options)
-  end
+    def self.whitespace(options: nil)
+      new("whitespace", nil, options)
+    end
 
-  def self.unicode_words(options: nil)
-    new("unicode_words", nil, options)
-  end
+    def self.unicode_words(options: nil)
+      new("unicode_words", nil, options)
+    end
 
-  def self.ngram(min_gram, max_gram, options: nil)
-    new("ngram", [min_gram, max_gram], options)
-  end
+    def self.ngram(min_gram, max_gram, options: nil)
+      new("ngram", [min_gram, max_gram], options)
+    end
 
-  def self.simple(options: nil)
-    new("simple", nil, options)
-  end
+    def self.simple(options: nil)
+      new("simple", nil, options)
+    end
 
-  def self.literal(options: nil)
-    new("literal", nil, options)
-  end
+    def self.literal(options: nil)
+      new("literal", nil, options)
+    end
 
-  def self.literal_normalized(options: nil)
-    new("literal_normalized", nil, options)
-  end
+    def self.literal_normalized(options: nil)
+      new("literal_normalized", nil, options)
+    end
 
-  def self.edge_ngram(min_gram, max_gram, options: nil)
-    new("edge_ngram", [min_gram, max_gram], options)
-  end
+    def self.edge_ngram(min_gram, max_gram, options: nil)
+      new("edge_ngram", [min_gram, max_gram], options)
+    end
 
-  def self.regex_pattern(pattern, options: nil)
-    new("regex_pattern", [pattern], options)
-  end
+    def self.regex_pattern(pattern, options: nil)
+      new("regex_pattern", [pattern], options)
+    end
 
-  def self.chinese_compatible(options: nil)
-    new("chinese_compatible", nil, options)
-  end
+    def self.chinese_compatible(options: nil)
+      new("chinese_compatible", nil, options)
+    end
 
-  def self.lindera(dictionary, options: nil)
-    new("lindera", [dictionary], options)
-  end
+    def self.lindera(dictionary, options: nil)
+      new("lindera", [dictionary], options)
+    end
 
-  def self.icu(options: nil)
-    new("icu", nil, options)
-  end
+    def self.icu(options: nil)
+      new("icu", nil, options)
+    end
 
-  def self.jieba(options: nil)
-    new("jieba", nil, options)
-  end
+    def self.jieba(options: nil)
+      new("jieba", nil, options)
+    end
 
-  def self.source_code(options: nil)
-    new("source_code", nil, options)
-  end
+    def self.source_code(options: nil)
+      new("source_code", nil, options)
+    end
 
-  private
+    private
 
-  def quote_term(value)
-    escaped = value.gsub("'", "''")
-    "'#{escaped}'"
-  end
+    def quote_term(value)
+      escaped = value.gsub("'", "''")
+      "'#{escaped}'"
+    end
 
-  def render_positional_arg(value)
-    case value
-    when true, false, Numeric
-      value.to_s
-    when String
-      quote_term(value)
-    else
-      raise InvalidArgumentError, "Unsupported tokenizer arg type: #{value.class}"
+    def render_positional_arg(value)
+      case value
+      when true, false, Numeric
+        value.to_s
+      when String
+        quote_term(value)
+      else
+        raise ArgumentError, "Unsupported tokenizer arg type: #{value.class}"
+      end
     end
   end
 end

data/lib/parade_db/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ParadeDB
-  VERSION = "0.7.0"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-paradedb
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - ParadeDB
@@ -83,7 +83,8 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
-description: Simple, Elastic-quality search for Postgres via ParadeDB and ActiveRecord.
+description: Elastic-quality full-text search, vector retrieval, and aggregations
+  in Postgres via ParadeDB and ActiveRecord.
 email:
 - support@paradedb.com
 executables: []
@@ -99,7 +100,6 @@ files:
 - lib/parade_db.rb
 - lib/parade_db/aggregations.rb
 - lib/parade_db/arel.rb
-- lib/parade_db/arel/README.md
 - lib/parade_db/arel/builder.rb
 - lib/parade_db/arel/nodes.rb
 - lib/parade_db/arel/predications.rb

data/lib/parade_db/arel/README.md

@@ -1,76 +0,0 @@
-# ParadeDB Arel Guide
-
-This guide covers the low-level Arel API used by `rails-paradedb`.
-Use it when you need explicit AST composition or direct SQL rendering.
-
-## Quickstart
-
-```ruby
-require "parade_db/arel"
-
-arel = ParadeDB::Arel::Builder.new(:products)
-
-predicate = arel.match(:description, "running", "shoes")
-               .and(arel.regex(:description, "run.*"))
-               .and(arel.term(:in_stock, true))
-
-sql = ParadeDB::Arel.to_sql(predicate, Product.connection)
-# => ("products"."description" &&& 'running shoes' AND "products"."description" @@@ pdb.regex('run.*') AND "products"."in_stock" === TRUE)
-
-Product.where(Arel.sql(sql))
-```
-
-Render any node with `ParadeDB::Arel.to_sql(node)`. All nodes respond to
-`.and`, `.or`, and `.not`.
-
-## Builder Methods
-
-| Method                                                                                                                    | ParadeDB SQL                                                                          |
-| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `match(column, *terms, tokenizer: nil, distance:, prefix:, transposition_cost_one:, boost: nil, constant_score: nil)`     | `column &&& 'a b'::pdb.whitespace::pdb.fuzzy(...)::pdb.boost(N)`                      |
-| `match_any(column, *terms, tokenizer: nil, distance:, prefix:, transposition_cost_one:, boost: nil, constant_score: nil)` | `column \|\|\| 'a b'::pdb.whitespace::pdb.fuzzy(...)::pdb.boost(N)`                   |
-| `phrase(column, text_or_terms, slop: n, tokenizer: nil, boost: nil, constant_score: nil)`                                 | `column ### 'text'::pdb.slop(n)::pdb.whitespace` / `### ARRAY['a', 'b']::pdb.slop(n)` |
-| `term(column, term, distance:, prefix:, transposition_cost_one:, boost: nil, constant_score: nil)`                        | `column === 'term'::pdb.fuzzy(...)::pdb.boost(N)`                                     |
-| `term_set(column, *terms, boost: nil, constant_score: nil)`                                                               | `column @@@ pdb.term_set(ARRAY[...])`                                                 |
-| `regex(column, pattern, boost: nil, constant_score: nil)`                                                                 | `column @@@ pdb.regex('pattern')`                                                     |
-| `regex_phrase(column, *patterns, slop: nil, max_expansions: nil, boost: nil, constant_score: nil)`                        | `column @@@ pdb.regex_phrase(ARRAY['a', 'b'], slop => 2)`                             |
-| `near(column, ParadeDB.proximity('a').within(d, 'b'))`                                                                    | `column @@@ ('a' ## d ## 'b')`                                                        |
-| `near(column, ParadeDB.proximity('a', 'b').within(d, ParadeDB.regex_term('c')).within(e, 'd'))`                           | `column @@@ ((pdb.prox_array('a', 'b') ## d ## pdb.prox_regex('c')) ## e ## 'd')`     |
-| `near(column, ParadeDB.proximity('a').within(d, 'b'), boost: 2.0)`                                                        | `column @@@ ('a' ## d ## 'b')::pdb.boost(2.0)`                                        |
-| `near(column, ParadeDB.proximity('a').within(d, 'b'), const: 1.0)`                                                        | `column @@@ ('a' ## d ## 'b')::pdb.const(1.0)`                                        |
-| `phrase_prefix(column, *terms, max_expansion: nil, boost: nil, constant_score: nil)`                                      | `column @@@ pdb.phrase_prefix(ARRAY['a','b'][, 100])`                                 |
-| `parse(column, query, lenient: nil, conjunction_mode: nil, boost: nil, constant_score: nil)`                              | `column @@@ pdb.parse('q', lenient => true, conjunction_mode => true)`                |
-| `full_text(column, expr)`                                                                                                 | `column @@@ expr` (raw right-hand value)                                              |
-| `match_all(column, boost: nil, constant_score: nil)`                                                                      | `column @@@ pdb.all()`                                                                |
-| `exists(column, boost: nil, constant_score: nil)`                                                                         | `column @@@ pdb.exists()`                                                             |
-| `range(column, value = nil, gte:, gt:, lte:, lt:, type:, boost: nil, constant_score: nil)`                                | `column @@@ pdb.range(int8range(3, 5, '[)'))`                                         |
-| `range_term(column, value, relation: nil, range_type: nil, boost: nil, constant_score: nil)`                              | `column @@@ pdb.range_term(1)` / `pdb.range_term('(1,2]'::int4range, 'Intersects')`   |
-| `more_like_this(column, key, fields: [:f1, :f2], options: {}, boost: nil, constant_score: nil)`                           | `column @@@ pdb.more_like_this(key, ARRAY['f1','f2'])`                                |
-| `score(key_field)`                                                                                                        | `pdb.score(key_field)`                                                                |
-| `snippet(column, start, finish, max)`                                                                                     | `pdb.snippet(column, start, finish, max)`                                             |
-| `snippets(column, start_tag:, end_tag:, max_num_chars:, limit:, offset:, sort_by:)`                                       | `pdb.snippets(column, ...)`                                                           |
-| `snippet_positions(column)`                                                                                               | `pdb.snippet_positions(column)`                                                       |
-| `agg(json, exact: nil)`                                                                                                   | `pdb.agg(json[, false])`                                                              |
-
-`Builder#[]` returns a column node for manual composition: `arel[:description]`.
-
-> **Note:** `Builder` has no access to ActiveRecord model metadata.
-> When calling `range_term` with a `relation:`, you must pass `range_type:` explicitly.
-> The `SearchMethods` layer (`.search(:col).range_term(...)`) auto-infers `range_type` from the column's SQL type.
-> Tokenizer overrides on `match`/`match_any` are mutually exclusive with fuzzy options.
-
-## Composition
-
-Boolean composition uses the standard helpers:
-
-```ruby
-fast = arel.match(:description, "running").and(arel.term(:rating, 4))
-cheap = arel.match(:description, "budget")
-predicate = fast.or(cheap.not)
-```
-
-`predicate` renders to:
-
-```sql
-(("products"."description" &&& 'running' AND "products"."rating" === 4) OR NOT ("products"."description" &&& 'budget'))
-```