rails-paradedb 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 45e56dc6d44889df2b0916faf747ad9ecdd75772fb4664e766b7bb5d7e01b3cd
4
- data.tar.gz: 2f8792790f216eadf48e019539e9486b354564c01a9e073038c2cf1871b33ce9
3
+ metadata.gz: 148db8ed1633b56136004e6220b55028db22fb01d8e6389058c6dcd3579844f3
4
+ data.tar.gz: 4f3e67c57fb16dbf90f06af8df7222e5669783b7c6dcf9ebec94fd048baa4a07
5
5
  SHA512:
6
- metadata.gz: c49ab3e46f7e3286af552a941d85c5690f47b34af0e98009cfd20b602d7f1eb6c55c6122aac09f19b42d69078c02bbca24b17140a5e63612d7a9ba979e3bb0ed
7
- data.tar.gz: 6fb74d7ef61b3846dfe05cf8b06be300d2c57337498a82e6234f6352df4287b7efa27ddb771f2f7bc3e2bf9595c895bbf0378264162f976ed5197231cd008eac
6
+ metadata.gz: 1ef244e0fe057070524c7f31af2ea3d5c84893f6d4d2e1f2f35f18ab1bf448cb9b17d77c5bdfa606830d2575eb512b5c1ece3ca71b1dbf3cfc7164be19e30949
7
+ data.tar.gz: ad3c12f9979e07c18f4724168bc4fd539999fe07b7f707d61d4015d739caffe49a35dbd3918bd8c50985313a75fbc9aac7505f2e674e9f1d7f01abc9038836a4
data/CHANGELOG.md CHANGED
@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file. The format
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.15.0] - 2026-11-19
8
+
9
+ ### Added
10
+
11
+ - Synonym search using `ParadeDB.expand`, which builds the `pdb.expand` subquery for `match_any`, `match_all`, `phrase` and `parse`.
12
+ - `with_score_explanation`, which explains the BM25 score of a row as `search_score_explanation`.
13
+
14
+ ### Changed
15
+
16
+ - **Breaking:** Require ParadeDB 0.27.0 or newer.
17
+ - **Breaking:** Rename the index option `max_leaf_size` to `target_leaf_size` and replace `vector_fields` with `quantization` for ParadeDB 0.27.0.
18
+
7
19
  ## [0.14.0] - 2026-10-16
8
20
 
9
21
  ### Added
@@ -208,6 +220,7 @@ All notable changes to this project will be documented in this file. The format
208
220
  - Schema dump/load round-trip for tokenizer configuration and index options
209
221
  (including `target_segment_count`)
210
222
 
223
+ [0.15.0]: https://github.com/paradedb/rails-paradedb/compare/v0.14.0...v0.15.0
211
224
  [0.14.0]: https://github.com/paradedb/rails-paradedb/compare/v0.13.0...v0.14.0
212
225
  [0.13.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.13.0
213
226
  [0.12.0]: https://github.com/paradedb/rails-paradedb/releases/tag/v0.12.0
data/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
  </h1>
11
11
 
12
12
  <p align="center">
13
- <b>Just use Postgres.</b><br/>
13
+ <b>Just use Postgres</b><br/>
14
14
  One Postgres for your application data, full-text search, vector retrieval, and aggregations.
15
15
  </p>
16
16
 
@@ -46,7 +46,7 @@ The official [ActiveRecord](https://guides.rubyonrails.org/active_record_basics.
46
46
  | Rails | 7.2+ |
47
47
  | PostgreSQL | 15+ |
48
48
  | pgvector | 0.7.0+ (provides vector types for ParadeDB’s [native vector search](https://www.paradedb.com/docs/reference/vector/overview)) |
49
- | ParadeDB / pg_search | 0.26.2+ |
49
+ | ParadeDB / pg_search | 0.27.0+ |
50
50
 
51
51
  ## Contributing
52
52
 
@@ -79,8 +79,8 @@ module ParadeDB
79
79
  # Consumed by migration helpers; validates and normalizes the DSL class
80
80
  class DefinitionCompiler
81
81
  FIELD_OPTION_KEYS = %i[fast record normalizer expand_dots].freeze
82
- 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
83
- POSITIVE_INTEGER_INDEX_OPTION_KEYS = %i[target_segment_count max_leaf_size].freeze
82
+ INDEX_OPTION_KEYS = %i[target_segment_count training_sample_ratio target_leaf_size partition_by quantization search_tokenizer layer_sizes background_layer_sizes mutable_segment_rows].freeze
83
+ POSITIVE_INTEGER_INDEX_OPTION_KEYS = %i[target_segment_count target_leaf_size].freeze
84
84
 
85
85
  class Compiled
86
86
  attr_reader :table_name, :index_name, :entries, :index_options, :field_options, :where
@@ -266,8 +266,12 @@ module ParadeDB
266
266
  end
267
267
  end
268
268
 
269
- if normalized.key?(:vector_fields) && !normalized[:vector_fields].is_a?(Hash)
270
- raise InvalidIndexDefinition, "index_options[:vector_fields] must be a Hash"
269
+ if normalized.key?(:quantization)
270
+ quantization = normalized[:quantization]
271
+ layers = quantization.is_a?(Array) && !quantization.empty? && quantization.all?(Integer)
272
+ unless layers || (quantization.is_a?(Integer) && quantization.zero?)
273
+ raise InvalidIndexDefinition, "index_options[:quantization] must be 0 or an Array of layer widths"
274
+ end
271
275
  end
272
276
 
273
277
  normalized
@@ -99,14 +99,14 @@ module ParadeDB
99
99
  compiled.index_options.each do |key, value|
100
100
  name = key.to_sym
101
101
  case name
102
- when :target_segment_count, :max_leaf_size, :mutable_segment_rows
102
+ when :target_segment_count, :target_leaf_size, :mutable_segment_rows
103
103
  options << "#{name}=#{Integer(value)}"
104
104
  when :partition_by
105
105
  options << "#{name}=#{quote(value.join(","))}"
106
106
  when :search_tokenizer, :layer_sizes, :background_layer_sizes
107
107
  options << "#{name}=#{quote(value.to_s)}"
108
- when :vector_fields
109
- options << "vector_fields=#{quote(JSON.generate(value))}"
108
+ when :quantization
109
+ options << "quantization=#{quote(JSON.generate(value))}"
110
110
  when :training_sample_ratio
111
111
  options << "training_sample_ratio=#{Float(value)}"
112
112
  else
@@ -370,15 +370,15 @@ module ParadeDB
370
370
  next if separator.empty?
371
371
 
372
372
  case key
373
- when "target_segment_count", "max_leaf_size", "mutable_segment_rows"
373
+ when "target_segment_count", "target_leaf_size", "mutable_segment_rows"
374
374
  parsed = Integer(value, 10, exception: false)
375
375
  options[key.to_sym] = parsed if parsed
376
376
  when "partition_by"
377
377
  options[key.to_sym] = value.split(",")
378
378
  when "search_tokenizer", "layer_sizes", "background_layer_sizes"
379
379
  options[key.to_sym] = value
380
- when "vector_fields"
381
- options[:vector_fields] = JSON.parse(value)
380
+ when "quantization"
381
+ options[:quantization] = JSON.parse(value)
382
382
  when "training_sample_ratio"
383
383
  parsed = Float(value, exception: false)
384
384
  options[:training_sample_ratio] = parsed if parsed
@@ -8,6 +8,10 @@ module ParadeDB
8
8
  RANGE_TYPES = %w[int4range int8range numrange daterange tsrange tstzrange].freeze
9
9
  RANGE_RELATIONS = %w[Intersects Contains Within].freeze
10
10
  Modifier = Data.define(:type, :value, :options)
11
+ # `parse` has to tell an expansion from the other Arel nodes that it takes as a query string.
12
+ Expansion = Module.new
13
+ # The subquery returns the one row of an aggregate, so these clauses would not pick rules.
14
+ UNSUPPORTED_RULES_CLAUSES = %i[limit offset distinct group having lock from eager_load].freeze
11
15
  attr_reader :table
12
16
 
13
17
  def initialize(table = nil)
@@ -48,6 +52,17 @@ module ParadeDB
48
52
  Modifier.new(type: :tokenizer, value: value, options: { tokenizer: tokenizer })
49
53
  end
50
54
 
55
+ def expand(text, rules, column)
56
+ raise ArgumentError, "expand requires non-empty search text" unless text.is_a?(String) && !text.strip.empty?
57
+ raise ArgumentError, "expand requires a rule column name" unless column.is_a?(Symbol) || column.is_a?(String)
58
+
59
+ relation = expand_rules_relation(rules)
60
+ call = ::Arel::Nodes::NamedFunction.new("pdb.expand", [quoted_value(text), relation.table[column]])
61
+ # The planner reads a synonym index only when `pdb.expand` is the subquery's one output and its WHERE
62
+ # matches the index predicate. A bind parameter can't match in a generic plan, so `to_sql` inlines the values.
63
+ ::Arel::Nodes::Grouping.new(::Arel.sql(relation.except(:select, :order).select(call).to_sql)).extend(Expansion)
64
+ end
65
+
51
66
  def match(column, term = nil)
52
67
  infix("&&&", column_node(column), term_query_node(term))
53
68
  end
@@ -105,6 +120,13 @@ module ParadeDB
105
120
  end
106
121
 
107
122
  def parse(column, query, lenient: nil, conjunction_mode: nil)
123
+ # `pdb.parse` takes only text, and `expand` already returns a query.
124
+ if expansion?(query)
125
+ raise ArgumentError, "parse options do not apply to an expansion" unless lenient.nil? && conjunction_mode.nil?
126
+
127
+ return infix("@@@", column_node(column), search_value_node(query))
128
+ end
129
+
108
130
  args = [quoted_value(query)]
109
131
  args << keyword_arg_node("lenient", lenient) unless lenient.nil?
110
132
  args << keyword_arg_node("conjunction_mode", conjunction_mode) unless conjunction_mode.nil?
@@ -144,6 +166,10 @@ module ParadeDB
144
166
  ::Arel::Nodes::NamedFunction.new("pdb.score", [column_node(key)])
145
167
  end
146
168
 
169
+ def explain_score(key)
170
+ ::Arel::Nodes::NamedFunction.new("pdb.explain_score", [column_node(key)])
171
+ end
172
+
147
173
  def snippet(column, *args)
148
174
  ::Arel::Nodes::NamedFunction.new("pdb.snippet", [column_node(column)] + args.map { |arg| quoted_value(arg) })
149
175
  end
@@ -237,6 +263,18 @@ module ParadeDB
237
263
  end
238
264
  end
239
265
 
266
+ def expand_rules_relation(rules)
267
+ relation = rules.is_a?(Class) && rules < ::ActiveRecord::Base ? rules.all : rules
268
+ unless relation.is_a?(::ActiveRecord::Relation)
269
+ raise ArgumentError, "expand requires a model class or relation for the rules table, got #{rules.class}"
270
+ end
271
+
272
+ unsupported = UNSUPPORTED_RULES_CLAUSES.select { |clause| relation.values[clause].present? }
273
+ raise ArgumentError, "expand does not take rules with #{unsupported.join(', ')}" unless unsupported.empty?
274
+
275
+ relation
276
+ end
277
+
240
278
  def vector_operand(vector)
241
279
  return vector if arel_expression?(vector)
242
280
 
@@ -387,6 +425,11 @@ module ParadeDB
387
425
  value.is_a?(::Arel::Nodes::Node) || value.is_a?(::Arel::Attributes::Attribute)
388
426
  end
389
427
 
428
+ def expansion?(value)
429
+ value = value.value while value.is_a?(Modifier)
430
+ value.is_a?(Expansion)
431
+ end
432
+
390
433
  def normalize_term_set_terms(terms)
391
434
  values = Array(terms).flatten.compact
392
435
  raise ArgumentError, "term_set requires at least one value" if values.empty?
@@ -260,6 +260,10 @@ module ParadeDB
260
260
  with_projection(builder.score(primary_key).as("search_score"))
261
261
  end
262
262
 
263
+ def with_score_explanation
264
+ with_projection(builder.explain_score(primary_key).as("search_score_explanation"))
265
+ end
266
+
263
267
  def with_snippet(column, start_tag: nil, end_tag: nil, max_chars: nil)
264
268
  formatted_args = []
265
269
  formatted_args << start_tag unless start_tag.nil?
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module ParadeDB
4
- VERSION = "0.14.0"
4
+ VERSION = "0.15.0"
5
5
  end
data/lib/parade_db.rb CHANGED
@@ -105,5 +105,9 @@ module ParadeDB
105
105
  QueryBuilder.new.tokenize(value, tokenizer)
106
106
  end
107
107
 
108
+ def expand(text, rules, column)
109
+ QueryBuilder.new.expand(text, rules, column)
110
+ end
111
+
108
112
  private_constant :QueryBuilder
109
113
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: rails-paradedb
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.14.0
4
+ version: 0.15.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - ParadeDB
@@ -135,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
135
135
  - !ruby/object:Gem::Version
136
136
  version: '0'
137
137
  requirements: []
138
- rubygems_version: 4.0.3
138
+ rubygems_version: 4.0.20
139
139
  specification_version: 4
140
140
  summary: The official ActiveRecord integration for ParadeDB.
141
141
  test_files: []