rails-paradedb 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cec3ad6c144476e82c57a3f9cba2b9ff497a838c34c032919b1eb785d4da435
-  data.tar.gz: 2af9e08e2bf7b9a12f9c005e99bc73f4a804f8a0c23f50c1fbc57637d6b87109
+  metadata.gz: 87745906c0e84ce264fcb243665c8edaf756218568745eecbe2781b0aa35f52f
+  data.tar.gz: 499f1837259b7a2c2a56ff6c55a98ff8dc6ef72e9de08517631215d9a7c091c2
 SHA512:
-  metadata.gz: 1af9bfba690e6ba816fc5972f576885b72408594e68504e6d3bbf063944f6392debcf3cf7a028b5d08ba626d6acfaaeb7dbcb526db4adafa96cec987902fb6fa
-  data.tar.gz: 384b58ba9857bc2edb9a984ab71bd60d455daf5add4b3fc83b0c53458892496d21959b84e71680daddf7acc48f7c2832dbf930185661fb3ff587a22399a4bd84
+  metadata.gz: ffcfe007ab852d8b36f69e9af1853dc1b0df485bfdbb0599749aa6ee27e1dd43707ea8958733c6b4c112fdd3d2ba6038d460dfb8c3062475e53826164d54a3f7
+  data.tar.gz: 236e0df31d2f705f3b7f015e5c051951e4aec16e3438961e5ff2a2757ab007f3a21565c312847aaa26fc844d3fd9c16e3c732634ba2d1d9b3c4a00f9a30263a9

data/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file. The format
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-07
+
+### Added
+
+- Index partitioning, target segment count, and vector quantization configuration.
+- Vector storage, configuration, and estimator diagnostics, plus aggregation visibility modes.
+- Snippet-position pagination with `limit` and `offset`.
+- Index layer sizes, background layer sizes, and mutable segment row limits.
+- Index search tokenizer configuration.
+
+### Changed
+
+- **Breaking:** Remove the key-field setting from index definitions, migration helpers, and schema dumps. Query helpers use the model primary key. Require ParadeDB 0.26.0 or newer.
+- **Breaking:** Update vector index build options to `training_sample_ratio` and `max_leaf_size` for ParadeDB 0.26.0 and remove the obsolete cluster replication option.
+
 ## [0.12.0] - 2026-08-13
 
 ### Changed
@@ -183,6 +198,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.13.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.13.0
 [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

data/README.md

@@ -10,16 +10,16 @@
 </h1>
 
 <p align="center">
-  <b>Search without a second system.</b><br/>
+  <b>Just use Postgres.</b><br/>
   One Postgres for your application data, full-text search, vector retrieval, and aggregations.
 </p>
 
 <h3 align="center">
   <a href="https://paradedb.com">Website</a> &bull;
-  <a href="https://docs.paradedb.com">Docs</a> &bull;
+  <a href="https://www.paradedb.com/docs/start/introduction">Docs</a> &bull;
   <a href="https://paradedb.com/slack/">Community</a> &bull;
   <a href="https://paradedb.com/blog/">Blog</a> &bull;
-  <a href="https://docs.paradedb.com/changelog/">Changelog</a>
+  <a href="https://www.paradedb.com/docs/project/changelog">Changelog</a>
 </h3>
 
 <p align="center">
@@ -36,29 +36,17 @@
 
 ## ParadeDB for Rails
 
-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.
+The official [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html) integration for ParadeDB. Get started with the [setup guide](https://www.paradedb.com/docs/start/connect-your-app#rails).
 
 ## Requirements & Compatibility
 
-| 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)
-
-See [examples/README.md](examples/README.md) for setup instructions and a description of each example.
+| Component            | Supported                                                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Ruby                 | 3.2+                                                                                                                          |
+| Rails                | 7.2+                                                                                                                          |
+| PostgreSQL           | 15+                                                                                                                           |
+| pgvector             | 0.7.0+ (provides vector types for ParadeDB’s [native vector search](https://www.paradedb.com/docs/reference/vector/overview)) |
+| ParadeDB / pg_search | 0.26.0+                                                                                                                       |
 
 ## Contributing
 
@@ -66,15 +54,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, running tests, lin
 
 ## Support
 
-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).
-
-To get community support, you can:
-
-- 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)
-
-If you need commercial support, please [contact the ParadeDB team](mailto:sales@paradedb.com).
+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, join the [ParadeDB Slack Community](https://paradedb.com/slack).
 
 ## Acknowledgments
 

data/lib/generators/parade_db/index/templates/index.rb.tt

@@ -2,7 +2,6 @@
 
 class <%= class_name %>Index < ParadeDB::Index
   self.table_name = :<%= table_name %>
-  self.key_field  = :id
   self.fields     = {
     id: {},
 <% fields.each do |field| -%>

data/lib/parade_db/diagnostics.rb

@@ -13,6 +13,25 @@ module ParadeDB
       execute_table_function(connection, sql)
     end
 
+    def vector_info(index, field, connection: ActiveRecord::Base.connection)
+      args = "#{connection.quote(index.to_s)}::regclass, #{connection.quote(field.to_s)}::text"
+      execute_table_function(connection, "SELECT * FROM paradedb.vector_info(#{args})")
+    end
+
+    def vector_config(index, field, connection: ActiveRecord::Base.connection)
+      args = "#{connection.quote(index.to_s)}::regclass, #{connection.quote(field.to_s)}::text"
+      execute_table_function(connection, "SELECT * FROM paradedb.vector_config(#{args})")
+    end
+
+    def vector_estimator_info(index, field, queries: nil, connection: ActiveRecord::Base.connection)
+      args = "#{connection.quote(index.to_s)}::regclass, #{connection.quote(field.to_s)}::text"
+      unless queries.nil?
+        vectors = queries.map { |query| connection.quote("[#{query.map { |value| Float(value) }.join(',')}]") }
+        args += ", ARRAY[#{vectors.join(', ')}]::vector[]"
+      end
+      execute_table_function(connection, "SELECT * FROM paradedb.vector_estimator_info(#{args})")
+    end
+
     def verify_index(
       index,
       heapallindexed: false,

data/lib/parade_db/index.rb

@@ -6,16 +6,12 @@ require_relative "vector"
 module ParadeDB
   class Index
     class << self
-      attr_writer :table_name, :key_field, :index_name, :fields, :index_options, :where
+      attr_writer :table_name, :index_name, :fields, :index_options, :where
 
       def table_name
         @table_name
       end
 
-      def key_field
-        @key_field
-      end
-
       def index_name
         @index_name || default_index_name
       end
@@ -83,15 +79,14 @@ module ParadeDB
     # Consumed by migration helpers; validates and normalizes the DSL class
     class DefinitionCompiler
       FIELD_OPTION_KEYS = %i[fast record normalizer expand_dots].freeze
-      INDEX_OPTION_KEYS = %i[target_segment_count centroid_ratio training_samples_per_centroid cluster_replication].freeze
-      POSITIVE_INTEGER_INDEX_OPTION_KEYS = %i[target_segment_count training_samples_per_centroid cluster_replication].freeze
+      INDEX_OPTION_KEYS = %i[target_segment_count training_sample_ratio max_leaf_size partition_by vector_fields search_tokenizer layer_sizes background_layer_sizes mutable_segment_rows].freeze
+      POSITIVE_INTEGER_INDEX_OPTION_KEYS = %i[target_segment_count max_leaf_size].freeze
 
       class Compiled
-        attr_reader :table_name, :key_field, :index_name, :entries, :index_options, :field_options, :where
+        attr_reader :table_name, :index_name, :entries, :index_options, :field_options, :where
 
-        def initialize(table_name:, key_field:, index_name:, entries:, index_options:, field_options:, where:)
+        def initialize(table_name:, index_name:, entries:, index_options:, field_options:, where:)
           @table_name = table_name
-          @key_field = key_field
           @index_name = index_name
           @entries = entries
           @index_options = index_options
@@ -104,7 +99,6 @@ module ParadeDB
       class << self
         def compile!(klass)
           table_name = require_symbol!(klass.table_name, "table_name")
-          key_field = require_symbol!(klass.key_field, "key_field")
           index_name = klass.index_name.to_s
           raise InvalidIndexDefinition, "index_name must be present" if index_name.strip.empty?
 
@@ -116,12 +110,10 @@ module ParadeDB
 
           index_options = normalize_index_options(klass.index_options)
 
-          validate_key_field_shape!(key_field.to_s, entries)
           validate_query_key_collisions!(entries)
 
           Compiled.new(
             table_name: table_name,
-            key_field: key_field,
             index_name: index_name,
             entries: entries,
             index_options: index_options,
@@ -255,14 +247,29 @@ module ParadeDB
             end
           end
 
-          if normalized.key?(:centroid_ratio)
-            ratio = normalized[:centroid_ratio]
+          if normalized[:search_tokenizer].is_a?(ParadeDB::Tokenizer)
+            normalized[:search_tokenizer] = normalized[:search_tokenizer].render_search
+          end
+          %i[search_tokenizer layer_sizes background_layer_sizes].each do |key|
+            if normalized.key?(key) && (!normalized[key].is_a?(String) || normalized[key].strip.empty?)
+              raise InvalidIndexDefinition, "index_options[#{key.inspect}] must be a non-empty string"
+            end
+          end
+          if normalized.key?(:mutable_segment_rows) && (!normalized[:mutable_segment_rows].is_a?(Integer) || !(0..10000).cover?(normalized[:mutable_segment_rows]))
+            raise InvalidIndexDefinition, "mutable_segment_rows must be an integer between 0 and 10000"
+          end
+          if normalized.key?(:training_sample_ratio)
+            ratio = normalized[:training_sample_ratio]
             unless ratio.is_a?(Numeric) && ratio >= 0.000001 && ratio <= 1.0
               raise InvalidIndexDefinition,
-                    "index_options[:centroid_ratio] must be a Numeric between 0.000001 and 1.0"
+                    "index_options[:training_sample_ratio] must be a Numeric between 0.000001 and 1.0"
             end
           end
 
+          if normalized.key?(:vector_fields) && !normalized[:vector_fields].is_a?(Hash)
+            raise InvalidIndexDefinition, "index_options[:vector_fields] must be a Hash"
+          end
+
           normalized
         end
 
@@ -288,23 +295,7 @@ module ParadeDB
           end
         end
 
-        def validate_key_field_shape!(key_field_name, entries)
-          unless entries.any? { |entry| entry.source == key_field_name }
-            raise InvalidIndexDefinition,
-                  "key_field #{key_field_name.inspect} must be present in fields."
-          end
 
-          first_entry = entries.first
-          unless first_entry.source == key_field_name
-            raise InvalidIndexDefinition,
-                  "key_field #{key_field_name.inspect} must be first in fields."
-          end
-
-          return if first_entry.tokenizer.nil?
-
-          raise InvalidIndexDefinition,
-                "key_field #{key_field_name.inspect} must not be tokenized."
-        end
       end
     end
   end

data/lib/parade_db/migration_helpers.rb

@@ -25,11 +25,10 @@ module ParadeDB
       remember_schema_index_reference(resolved)
     end
 
-    def add_paradedb_index(table, fields:, key_field:, name: nil, index_options: nil, where: nil, if_not_exists: false, concurrently: false)
+    def add_paradedb_index(table, fields:, name: nil, index_options: nil, where: nil, if_not_exists: false, concurrently: false)
       ensure_postgresql_adapter!
       anonymous = Class.new(ParadeDB::Index)
       anonymous.table_name = table
-      anonymous.key_field = key_field
       anonymous.index_name = name unless name.nil?
       anonymous.fields = fields
       anonymous.index_options = index_options unless index_options.nil?
@@ -86,26 +85,30 @@ module ParadeDB
       prefix = if_not_exists ? "IF NOT EXISTS " : ""
       fields_sql = compiled.entries.map { |entry| paradedb_entry_sql(entry) }.join(", ")
       with_options_sql = paradedb_with_options_sql(compiled)
+      with_clause = with_options_sql.empty? ? "" : "\nWITH (#{with_options_sql})"
       where_sql = compiled.where ? "\nWHERE #{compiled.where}" : ""
 
       <<~SQL.strip.gsub(/\s+/, " ")
         CREATE INDEX#{modifier} #{prefix}#{quote_table_name(compiled.index_name)} ON #{quote_table_name(compiled.table_name)}
-        USING paradedb (#{fields_sql})
-        WITH (#{with_options_sql})#{where_sql}
+        USING paradedb (#{fields_sql})#{with_clause}#{where_sql}
       SQL
     end
 
     def paradedb_with_options_sql(compiled)
       options = []
-      options << "key_field=#{quote(compiled.key_field.to_s)}"
-
       compiled.index_options.each do |key, value|
         name = key.to_sym
         case name
-        when :target_segment_count, :training_samples_per_centroid, :cluster_replication
+        when :target_segment_count, :max_leaf_size, :mutable_segment_rows
           options << "#{name}=#{Integer(value)}"
-        when :centroid_ratio
-          options << "centroid_ratio=#{Float(value)}"
+        when :partition_by
+          options << "#{name}=#{quote(value.join(","))}"
+        when :search_tokenizer, :layer_sizes, :background_layer_sizes
+          options << "#{name}=#{quote(value.to_s)}"
+        when :vector_fields
+          options << "vector_fields=#{quote(JSON.generate(value))}"
+        when :training_sample_ratio
+          options << "training_sample_ratio=#{Float(value)}"
         else
           raise ParadeDB::InvalidIndexDefinition, "unsupported index option #{key.inspect}"
         end
@@ -322,12 +325,11 @@ module ParadeDB
       table = row["table_name"]
       name = row["index_name"]
 
-      key_field = extract_paradedb_key_field(indexdef)
       index_options = extract_paradedb_index_options(row["reloptions"])
       fields_sql = extract_paradedb_fields_sql(indexdef)
       where = normalize_paradedb_where_clause(row["where_clause"])
 
-      if key_field && fields_sql
+      if fields_sql
         field_sqls = split_paradedb_top_level(fields_sql).map(&:strip)
         parsed = field_sqls.map { |f| paradedb_parse_column_entry(f) }
 
@@ -350,9 +352,8 @@ module ParadeDB
         end
 
         statement = "add_paradedb_index #{table.to_sym.inspect}, " \
-          "fields: { #{fields_pairs.join(', ')} }, " \
-          "key_field: #{key_field.to_sym.inspect}, " \
-          "name: #{name.inspect}"
+          "fields: { #{fields_pairs.join(', ')} }, "
+        statement += "name: #{name.inspect}"
         unless index_options.empty?
           statement += ", index_options: #{ruby_hash_literal(index_options)}"
         end
@@ -363,28 +364,24 @@ module ParadeDB
       end
     end
 
-    def extract_paradedb_key_field(indexdef)
-      quoted = indexdef.match(/WITH\s*\([^)]*key_field\s*=\s*'((?:[^']|'')*)'/i)
-      return quoted[1].gsub("''", "'") if quoted
-
-      unquoted = indexdef.match(/WITH\s*\([^)]*key_field\s*=\s*([a-zA-Z_][a-zA-Z0-9_]*)/i)
-      return unquoted[1] if unquoted
-
-      nil
-    end
-
     def extract_paradedb_index_options(reloptions)
       paradedb_reloption_entries(reloptions).each_with_object({}) do |entry, options|
         key, separator, value = entry.to_s.partition("=")
         next if separator.empty?
 
         case key
-        when "target_segment_count", "training_samples_per_centroid", "cluster_replication"
+        when "target_segment_count", "max_leaf_size", "mutable_segment_rows"
           parsed = Integer(value, 10, exception: false)
           options[key.to_sym] = parsed if parsed
-        when "centroid_ratio"
+        when "partition_by"
+          options[key.to_sym] = value.split(",")
+        when "search_tokenizer", "layer_sizes", "background_layer_sizes"
+          options[key.to_sym] = value
+        when "vector_fields"
+          options[:vector_fields] = JSON.parse(value)
+        when "training_sample_ratio"
           parsed = Float(value, exception: false)
-          options[:centroid_ratio] = parsed if parsed
+          options[:training_sample_ratio] = parsed if parsed
         end
       end
     end
@@ -868,11 +865,10 @@ if defined?(ActiveRecord::Migration)
         connection.replace_paradedb_index(index_klass)
       end
 
-      def add_paradedb_index(table, fields:, key_field:, name: nil, index_options: nil, where: nil, if_not_exists: false, concurrently: false)
+      def add_paradedb_index(table, fields:, name: nil, index_options: nil, where: nil, if_not_exists: false, concurrently: false)
         connection.add_paradedb_index(
           table,
           fields: fields,
-          key_field: key_field,
           name: name,
           index_options: index_options,
           where: where,

data/lib/parade_db/model.rb

@@ -23,7 +23,6 @@ module ParadeDB
       :paradedb_index_class,
       :paradedb_index_classes,
       :paradedb_indexed_fields,
-      :paradedb_key_field,
       :paradedb_index_name,
       :paradedb_validate_index!
     ].freeze
@@ -155,11 +154,6 @@ module ParadeDB
         definition.entries.map(&:query_key).uniq
       end
 
-      def paradedb_key_field
-        definition = paradedb_index_definition
-        definition&.key_field
-      end
-
       def paradedb_index_name
         definition = paradedb_index_definition
         definition&.index_name

data/lib/parade_db/query_builder.rb

@@ -159,14 +159,21 @@ module ParadeDB
       ::Arel::Nodes::NamedFunction.new("pdb.snippets", args)
     end
 
-    def snippet_positions(column)
-      ::Arel::Nodes::NamedFunction.new("pdb.snippet_positions", [column_node(column)])
+    def snippet_positions(column, limit: nil, offset: nil)
+      args = [column_node(column)]
+      args << keyword_arg_node("limit", limit, quoted_name: true) unless limit.nil?
+      args << keyword_arg_node("offset", offset, quoted_name: true) unless offset.nil?
+      ::Arel::Nodes::NamedFunction.new("pdb.snippet_positions", args)
     end
 
-    def agg(json, exact: nil)
+    def agg(json, exact: nil, visibility: nil)
       raise ArgumentError, "exact must be true, false, or nil" unless exact.nil? || exact == true || exact == false
 
       args = [quoted_value(json)]
+      unless visibility.nil?
+        raise ArgumentError, "Specify visibility or exact, not both" unless exact.nil?
+        args << quoted_value(visibility.to_s)
+      end
       args << quoted_value(false) if exact == false
       ::Arel::Nodes::NamedFunction.new("pdb.agg", args)
     end

data/lib/parade_db/search_methods.rb

@@ -246,9 +246,9 @@ module ParadeDB
 
     def more_like_this(key, fields: nil, **options)
       ensure_paradedb_runtime!
-      runtime_key_field = paradedb_runtime_key_field
-      key_value = more_like_this_key_value(key, runtime_key_field)
-      pk_node = builder[runtime_key_field]
+      row_identifier = primary_key
+      key_value = more_like_this_key_value(key, row_identifier)
+      pk_node = builder[row_identifier]
       mlt_options = normalize_more_like_this_options(options)
       node = builder.more_like_this(pk_node, key_value, fields: fields, options: mlt_options)
       where(grouped(node))
@@ -257,7 +257,7 @@ module ParadeDB
     # ---- Decorators ----
 
     def with_score
-      with_projection(builder.score(paradedb_runtime_key_field).as("search_score"))
+      with_projection(builder.score(primary_key).as("search_score"))
     end
 
     def with_snippet(column, start_tag: nil, end_tag: nil, max_chars: nil)
@@ -299,14 +299,14 @@ module ParadeDB
       with_projection(snippets.as(normalize_projection_alias(as, "#{column}_snippets")))
     end
 
-    def with_snippet_positions(column, as: nil)
-      positions = builder.snippet_positions(column)
+    def with_snippet_positions(column, as: nil, limit: nil, offset: nil)
+      positions = builder.snippet_positions(column, limit: normalize_integer_option!(limit, "limit"), offset: normalize_integer_option!(offset, "offset"))
       with_projection(positions.as(normalize_projection_alias(as, "#{column}_snippet_positions")))
     end
 
     # ---- Facets ----
 
-    def facets(*fields, size: 10, order: :count_desc, missing: nil, agg: nil, exact: nil)
+    def facets(*fields, size: 10, order: :count_desc, missing: nil, agg: nil, exact: nil, visibility: nil)
       ensure_paradedb_runtime!
       validate_exact_option!(exact)
       if exact == false
@@ -319,23 +319,24 @@ module ParadeDB
         order: order,
         missing: missing,
         agg: agg,
-        exact: exact
+        exact: exact,
+        visibility: visibility
       ).execute
     end
 
-    def facets_agg(exact: nil, **named_aggregations)
+    def facets_agg(exact: nil, visibility: nil, **named_aggregations)
       validate_exact_option!(exact)
       agg_specs = normalize_named_aggregation_specs(named_aggregations)
-      build_aggregation_query(agg_specs, exact: exact).execute
+      build_aggregation_query(agg_specs, exact: exact, visibility: visibility).execute
     end
 
     # Internal method to build facet query (for testing)
-    def build_facet_query(fields:, size: 10, order: :count_desc, missing: nil, agg: nil, exact: nil)
+    def build_facet_query(fields:, size: 10, order: :count_desc, missing: nil, agg: nil, exact: nil, visibility: nil)
       ensure_paradedb_runtime!
       facet_args = normalize_facet_inputs(fields: fields, size: size, order: order, missing: missing, agg: agg)
       FacetQuery.build(
         relation: self,
-        primary_key: paradedb_runtime_key_field,
+        primary_key: primary_key,
         builder: builder,
         fields: facet_args[:fields],
         size: facet_args[:size],
@@ -343,11 +344,12 @@ module ParadeDB
         missing: facet_args[:missing],
         agg: facet_args[:agg],
         exact: exact,
+        visibility: visibility,
         connection: connection
       )
     end
 
-    def with_facets(*fields, size: 10, order: :count_desc, missing: nil, agg: nil, exact: nil)
+    def with_facets(*fields, size: 10, order: :count_desc, missing: nil, agg: nil, exact: nil, visibility: nil)
       ensure_paradedb_runtime!
       validate_exact_option!(exact)
       facet_args = normalize_facet_inputs(fields: fields, size: size, order: order, missing: missing, agg: agg)
@@ -370,14 +372,14 @@ module ParadeDB
       # Add window aggregates to SELECT using native Arel nodes.
       facet_selects = facet_fields.map do |field|
         json = facet_args[:agg] || facet_json(field, opts)
-        builder.agg(json, exact: exact).over.as("_#{field}_facet")
+        builder.agg(json, exact: exact, visibility: visibility).over.as("_#{field}_facet")
       end
 
       rel = rel.select(klass.arel_table[::Arel.star]) if rel.select_values.empty?
       rel.select(*facet_selects)
     end
 
-    def with_agg(exact: nil, **named_aggregations)
+    def with_agg(exact: nil, visibility: nil, **named_aggregations)
       ensure_paradedb_runtime!
       validate_exact_option!(exact)
       agg_specs = normalize_named_aggregation_specs(named_aggregations)
@@ -389,7 +391,7 @@ module ParadeDB
       end
 
       facet_selects = agg_specs.map do |alias_name, agg_spec|
-        render_aggregation_node(agg_spec, exact: exact).over.as("_#{alias_name}_facet")
+        render_aggregation_node(agg_spec, exact: exact, visibility: visibility).over.as("_#{alias_name}_facet")
       end
 
       rel = rel.select(klass.arel_table[::Arel.star]) if rel.select_values.empty?
@@ -398,7 +400,7 @@ module ParadeDB
 
     # Grouped ParadeDB aggregations:
     #   Product.search(:id).match_all.aggregate_by(:rating, agg: ParadeDB::Aggregations.value_count(:id))
-    def aggregate_by(*group_fields, exact: nil, **named_aggregations)
+    def aggregate_by(*group_fields, exact: nil, visibility: nil, **named_aggregations)
       ensure_paradedb_runtime!
       validate_exact_option!(exact)
       normalized_group_fields = normalize_group_fields(group_fields)
@@ -409,14 +411,14 @@ module ParadeDB
 
       group_nodes = normalized_group_fields.map { |field| resolve_group_field_node(field) }
       aggregate_nodes = agg_specs.map do |alias_name, agg_spec|
-        render_aggregation_node(agg_spec, exact: exact).as(alias_name.to_s)
+        render_aggregation_node(agg_spec, exact: exact, visibility: visibility).as(alias_name.to_s)
       end
 
       rel.except(:select, :group).select(*group_nodes, *aggregate_nodes).group(*group_nodes)
     end
 
     # Orders by vector distance for Top-K pushdown inside the ParadeDB index.
-    # Adds `key_field @@@ pdb.all()` when the relation has no ParadeDB predicate,
+    # Adds `primary_key @@@ pdb.all()` when the relation has no ParadeDB predicate,
     # since vector ordering requires a @@@ predicate to activate the index scan.
     # Callers must add `.limit(k)`; the metric defaults to the index opclass metric.
     def nearest(column, vector, metric: nil)
@@ -434,7 +436,7 @@ module ParadeDB
 
     def ensure_paradedb_predicate
       # Add pdb.all() sentinel to force aggregate pushdown
-      where(grouped(builder.match_all(paradedb_runtime_key_field)))
+      where(grouped(builder.match_all(primary_key)))
     end
 
     private
@@ -445,15 +447,6 @@ module ParadeDB
       klass.send(:paradedb_index_entry, column)&.metric
     end
 
-    def paradedb_runtime_key_field
-      return primary_key unless klass.respond_to?(:paradedb_key_field)
-
-      key_field = klass.paradedb_key_field
-      return primary_key if key_field.nil? || key_field.to_s.empty?
-
-      key_field
-    end
-
     def default_range_type_for_field(field)
       column = klass.columns_hash[field.to_s]
       return nil unless column
@@ -483,13 +476,13 @@ module ParadeDB
       sql_type if QueryBuilder::RANGE_TYPES.include?(sql_type)
     end
 
-    def more_like_this_key_value(key, runtime_key_field)
-      return key.public_send(runtime_key_field) if key.respond_to?(runtime_key_field)
-      return key.id if runtime_key_field.to_s == "id" && key.respond_to?(:id)
+    def more_like_this_key_value(key, row_identifier)
+      return key.public_send(row_identifier) if key.respond_to?(row_identifier)
+      return key.id if row_identifier.to_s == "id" && key.respond_to?(:id)
       return key if scalar_more_like_this_key?(key)
 
       raise ArgumentError,
-            "more_like_this key object must respond to #{runtime_key_field.inspect} or be a scalar id/document value"
+            "more_like_this key object must respond to #{row_identifier.inspect} or be a scalar id/document value"
     end
 
     def scalar_more_like_this_key?(key)
@@ -591,8 +584,8 @@ module ParadeDB
         end
     end
 
-    def render_aggregation_node(agg_spec, exact:, builder_override: builder)
-      agg_node = builder_override.agg(agg_spec[:json], exact: exact)
+    def render_aggregation_node(agg_spec, exact:, visibility: nil, builder_override: builder)
+      agg_node = builder_override.agg(agg_spec[:json], exact: exact, visibility: visibility)
       filter = resolve_agg_filter_node(agg_spec[:filter], builder_override)
       return agg_node if filter.nil?
 
@@ -632,13 +625,14 @@ module ParadeDB
       raise ArgumentError, "exact must be true, false, or nil"
     end
 
-    def build_aggregation_query(agg_specs, exact: nil)
+    def build_aggregation_query(agg_specs, exact: nil, visibility: nil)
       AggregationQuery.build(
         relation: self,
-        primary_key: paradedb_runtime_key_field,
+        primary_key: primary_key,
         builder: builder,
         agg_specs: agg_specs,
         exact: exact,
+        visibility: visibility,
         connection: connection
       )
     end
@@ -845,7 +839,7 @@ module ParadeDB
     class FacetQuery
       attr_reader :relation, :connection
 
-      def self.build(relation:, primary_key:, builder:, fields:, size:, order:, missing:, agg:, exact:, connection:)
+      def self.build(relation:, primary_key:, builder:, fields:, size:, order:, missing:, agg:, exact:, visibility: nil, connection:)
         new(
           relation: relation,
           primary_key: primary_key,
@@ -856,11 +850,12 @@ module ParadeDB
           missing: missing,
           agg: agg,
           exact: exact,
+          visibility: visibility,
           connection: connection
         )
       end
 
-      def initialize(relation:, primary_key:, builder:, fields:, size:, order:, missing:, agg:, exact:, connection:)
+      def initialize(relation:, primary_key:, builder:, fields:, size:, order:, missing:, agg:, exact:, visibility: nil, connection:)
         @connection = connection
         @relation = build_relation(
           relation: relation,
@@ -871,7 +866,8 @@ module ParadeDB
           order: order,
           missing: missing,
           agg: agg,
-          exact: exact
+          exact: exact,
+          visibility: visibility
         )
       end
 
@@ -885,7 +881,7 @@ module ParadeDB
 
       private
 
-      def build_relation(relation:, primary_key:, builder:, fields:, size:, order:, missing:, agg:, exact:)
+      def build_relation(relation:, primary_key:, builder:, fields:, size:, order:, missing:, agg:, exact:, visibility: nil)
         predicate_scope = relation.except(:select, :order, :limit, :offset, :group, :having, :distinct)
         predicate_scope = predicate_scope.select(relation.klass.arel_table[::Arel.star]) if predicate_scope.select_values.empty?
 
@@ -895,18 +891,18 @@ module ParadeDB
 
         source_alias = "paradedb_facet_source"
         source = predicate_scope.arel.as(source_alias)
-        projections = build_facet_projections(relation, builder, fields, size, order, missing, agg, exact)
+        projections = build_facet_projections(relation, builder, fields, size, order, missing, agg, exact, visibility)
 
         relation.klass.unscoped.from(source).select(*projections)
       end
 
-      def build_facet_projections(relation, builder, fields, size, order, missing, agg, exact)
-        return [builder.agg(relation.send(:normalize_agg_json, agg), exact: exact).as("agg_facet")] if agg
+      def build_facet_projections(relation, builder, fields, size, order, missing, agg, exact, visibility)
+        return [builder.agg(relation.send(:normalize_agg_json, agg), exact: exact, visibility: visibility).as("agg_facet")] if agg
 
         fields.map do |field|
           opts = { size: size, order: order, missing: missing }
           json = relation.send(:facet_json, field, opts)
-          builder.agg(json, exact: exact).as("#{field}_facet")
+          builder.agg(json, exact: exact, visibility: visibility).as("#{field}_facet")
         end
       end
 
@@ -939,18 +935,19 @@ module ParadeDB
     class AggregationQuery
       attr_reader :relation, :connection
 
-      def self.build(relation:, primary_key:, builder:, agg_specs:, exact:, connection:)
+      def self.build(relation:, primary_key:, builder:, agg_specs:, exact:, visibility: nil, connection:)
         new(
           relation: relation,
           primary_key: primary_key,
           builder: builder,
           agg_specs: agg_specs,
           exact: exact,
+          visibility: visibility,
           connection: connection
         )
       end
 
-      def initialize(relation:, primary_key:, builder:, agg_specs:, exact:, connection:)
+      def initialize(relation:, primary_key:, builder:, agg_specs:, exact:, visibility: nil, connection:)
         @connection = connection
         @agg_specs = agg_specs
         @relation = build_relation(
@@ -958,7 +955,8 @@ module ParadeDB
           primary_key: primary_key,
           builder: builder,
           agg_specs: agg_specs,
-          exact: exact
+          exact: exact,
+          visibility: visibility
         )
       end
 
@@ -975,7 +973,7 @@ module ParadeDB
 
       attr_reader :agg_specs
 
-      def build_relation(relation:, primary_key:, builder:, agg_specs:, exact:)
+      def build_relation(relation:, primary_key:, builder:, agg_specs:, exact:, visibility: nil)
         predicate_scope = relation.except(:select, :order, :limit, :offset, :group, :having, :distinct)
         predicate_scope = predicate_scope.select(relation.klass.arel_table[::Arel.star]) if predicate_scope.select_values.empty?
 
@@ -991,6 +989,7 @@ module ParadeDB
             :render_aggregation_node,
             agg_spec,
             exact: exact,
+            visibility: visibility,
             builder_override: projection_builder
           )
           agg_node.as("#{alias_name}_facet")

data/lib/parade_db/tokenizer.rb

@@ -24,6 +24,12 @@ module ParadeDB
       return "pdb.#{name}(#{args.join(",")})"
     end
 
+    def render_search
+      args = Array(positional_args).map(&:to_s)
+      args.concat((options || {}).map { |key, value| "#{key}=#{value}" })
+      name + (args.empty? ? "" : "(#{args.join(',')})")
+    end
+
     def self.whitespace(options: nil)
       new("whitespace", nil, options)
     end

data/lib/parade_db/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-paradedb
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - ParadeDB
@@ -83,8 +83,8 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
-description: Elastic-quality full-text search, vector retrieval, and aggregations
-  in Postgres via ParadeDB and ActiveRecord.
+description: One Postgres for your application data, full-text search, vector retrieval,
+  and aggregations.
 email:
 - support@paradedb.com
 executables: []
@@ -118,7 +118,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/paradedb/rails-paradedb
   source_code_uri: https://github.com/paradedb/rails-paradedb
-  documentation_uri: https://docs.paradedb.com
+  documentation_uri: https://paradedb.com/docs
   changelog_uri: https://github.com/paradedb/rails-paradedb/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/paradedb/rails-paradedb/issues
 rdoc_options: []
@@ -137,5 +137,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Official ParadeDB integration for ActiveRecord
+summary: The official ActiveRecord integration for ParadeDB.
 test_files: []