search-engine-for-typesense 30.8.24 → 30.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db1ad7dbacfe019861ce7dbe7f3511326d67f0afc8bbf22ed2929cdb300797ad
-  data.tar.gz: 5bfafebc3623ee781a1c519c799621bfb8ca62b19f21e6370e79d4d165bc3999
+  metadata.gz: f8363aa6879873e4b2d897181f0e87494b454b5c1ccf51f19d29f4590e992b24
+  data.tar.gz: bd13ccd5af83d57a4499227629bbc6caa360dd08e15457e8eb80067d174fc20e
 SHA512:
-  metadata.gz: b1ce3108ba2a8ef685803cf06264e88a9565dfe7e640f983465f198a03ba2f5b4cf059555c00b2e1016fa38f49aadb6be6bc7bcc538b5564a46c922e103f6db5
-  data.tar.gz: 9a2ddb0b81c46d8c81ce06e622f4b16adf1f81f50a4f4ccf2ff756c3d2542cf8d90111d31b7412f77e88dd441d7429106779457033e30bfc0c8d6b12e169342f
+  metadata.gz: d8d3847c59ab120f22f076d3c76aeebf7ea0e6b74ccf29771b72f30896f8a7789f213c1d139c40a8565ed4e63612adebafafbe81ae25eb1dd5190a7dc6215e92
+  data.tar.gz: 03700343db8c49a61e5d722992cae22e23ff0dfd51506d98124b2039fd0e7302f0da495914b549e0082718832199778d3ffbedd3d62e89c53f056c56b58c0250

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 30.9.0
+
+- Qualify geo/vector search and native caching against Typesense 30.2 while keeping the gem major
+  version aligned with the Typesense major version.
+- Expose model-level geo/vector query methods, preserve external hybrid weights and historical query
+  boundaries, and sort the active vector query with Typesense's native distance token.
+- Validate finite real vectors, declared field types/dimensions and integer options before execution.
+  Preserve backend vector distance on flat, grouped and multi-search hits.
+- Redact scientific-notation vector components and forward single/multi-search cache options through
+  the Ruby SDK's request parameters.
+- Preserve caller-owned history strings and IDs, reject invalid scalar conversions consistently, and
+  mask malformed vector values. Align single-search adapters, telemetry and shell-quoted cURL previews
+  with GET requests and URL cache controls.
+- Keep stale-deletion estimates uncached so maintenance previews observe current documents.
+- Add database-free query examples and isolated Typesense 30.2 integration checks, including scoped-key
+  cache isolation and opt-in model-backed search. Upgrade older servers before using scoped-key caching.
+
 ## 30.8.24
 
 - Adopt `{typesense_major}.{gem_minor}.{gem_patch}` versioning, omitting the Typesense minor component.

data/README.md

@@ -8,15 +8,18 @@ Mountless Rails::Engine for [Typesense](https://typesense.org). Expressive Relat
 
 ## Versioning
 
-Versions use `{typesense_major}.{gem_minor}.{gem_patch}`. The first component identifies the targeted Typesense server major version; the remaining components track gem enhancements and fixes independently of Typesense minor releases.
+Versions use `{typesense_major}.{gem_minor}.{gem_patch}`. The first component identifies the targeted
+Typesense server major version; the remaining components track gem enhancements and fixes independently
+of Typesense minor releases.
 
-Example: `30.8.24` targets Typesense `30.x`. Typesense minor versions are not encoded in the gem version.
+Gem `30.9.0` targets Typesense **30.x** and is tested against **30.2**. Typesense minor versions are not
+encoded in the gem version.
 
 ## Quickstart
 
 ```ruby
 # Gemfile
-gem "search-engine-for-typesense"
+gem "search-engine-for-typesense", "~> 30.9"
 ```
 
 ```ruby
@@ -180,8 +183,56 @@ SearchEngine::Venue
 # Access geo distance on results (present when order_geo is used)
 result = SearchEngine::Venue.all.order_geo(:location, from: { lat: 54.69, lng: 25.28 }).execute
 result.hits.first.geo_distance_meters # => { "location" => 1234 }
+
+# External vectors: supply embeddings generated by your application
+class SearchEngine::Article < SearchEngine::Base
+  collection :articles
+  identify_by :id
+  attribute :title, :string
+  embedding :embedding, suffix: false, num_dim: 3
+  query_by :title
+end
+
+result = SearchEngine::Article
+  .search('chair')
+  .vector_search(query: [1, 0, 0], alpha: 0.8, k: 20)
+  .order(vector_distance: :asc)
+  .execute
+result.hits.first.vector_distance # Exact backend distance, including 0
+SearchEngine::Article.find_similar('article-42', k: 20).to_a
 ```
 
+`where_geo`, `order_geo`, `order_eval`, `vector_search` and `find_similar` work directly on models
+and on relations. They build lazy queries. Vector distance ordering uses the active query's native
+`_vector_distance` sort; it does not generate another embedding. The metadata reader is present when
+the backend supplies a distance, including grouped and multi-search hits. It takes precedence over
+a same-named document reader; the original document remains in `result.raw`.
+
+Vectors must contain finite real numbers and match declared dimensions. Integer options (`k`, `ef`,
+`flat_search_cutoff`) reject fractional values and accept integer strings. Historical queries preserve
+commas, parentheses and brackets; colons, backticks, control characters and surrounding whitespace
+raise `InvalidVectorQuery`. Similarity IDs reject commas, colons, parentheses, control characters and
+surrounding whitespace. Weight sums keep the configurable wrapper tolerance (default `0.01`), but
+Typesense 30.1/30.2 require a sum of 1.0; a server rejection propagates as `Errors::Api`.
+
+Typesense **30.2** is the tested server baseline. Geo, external vectors, auto-embedded hybrid search,
+historical queries and native caching are checked against that version. Earlier 30.1 qualification
+exposed the scoped-cache isolation defect described below; upgrade before using scoped-key caching.
+See the [vector guide](https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30/vector-search)
+for auto-embedding declarations and query modes.
+
+Run the database-free examples from the gem root:
+
+```bash
+bundle exec ruby examples/demo_shop/bin/query_smoke
+```
+
+This compiles geo/vector requests and checks metadata fixtures without HTTP requests or model downloads.
+See [the demo instructions](examples/demo_shop/README.md#query-examples) for explicitly isolated live execution,
+including highlighting through `Client#search` and `hit.snippet_for`.
+CI uses a disposable `typesense/typesense:30.2` service for geo, vector, cache and live CLI checks,
+including the built-in embedding model. The default unit suite runs separately without integration ENV.
+
 `upsert_bulk` defaults to `on_failure: :raise`. Use the exact symbol `:return` when the caller needs to
 handle valid Typesense row failures itself. Malformed responses and response/document count mismatches always
 raise in either mode; the gem never guesses which submitted document a missing response row belongs to.
@@ -207,6 +258,28 @@ You can control this explicitly with:
 
 If you set `SearchEngine.configure { |c| c.client = ... }`, the custom client is always used.
 
+## Native search caching
+
+The gem defaults to `use_cache: true` and `cache_ttl_s: 60`. Single-search cache options are sent as
+GET parameters; multi-search options apply to the whole request URL, outside individual search bodies.
+Use `Model.cache(false).count` or `.to_a` for fresh maintenance reads.
+
+On Typesense 30.1/30.2, cached responses remained stale after document writes and alias swaps until
+expiry or explicit clearing. A direct key's URL `cache_ttl` did not override the native default;
+embed `cache_ttl` in a scoped search key when controlling TTL. Revoked keys fail authentication even
+when a matching response is cached.
+
+**Typesense 30.1 has a scoped-cache isolation defect:** identical single/multi-search requests with
+different scoped filters can receive each other's cached results. The same checks pass on 30.2.
+On 30.1, set `c.use_cache = false` or use `.cache(false)` for scoped authorization; upgrade to 30.2
+before enabling it. The integration tests retain strict isolation assertions and expose this server
+failure rather than skipping it. The gem's existing global cache default is unchanged.
+
+`SearchEngine::Cache.clear` clears the contacted server's native search cache. For incremental outbox
+writes, `postgres_outbox.clear_cache_after_write` remains opt-in: clearing occurs before database
+acknowledgement, and clearing failures propagate. No Redis response-cache layer is required for
+sharing cached searches across application processes reaching the same Typesense node.
+
 ## Async partition indexing
 
 Async partition indexing is an advanced opt-in mode for partitioned full indexing. The default remains

data/lib/search_engine/base/relation_delegation.rb

@@ -19,6 +19,7 @@ module SearchEngine
         # Delegate materializers and query dsl to `.all` so callers can do `Model.first` etc.
         %i[
           where rewhere merge order preset ranking prefix search
+          where_geo order_geo order_eval vector_search find_similar
           pin hide curate clear_curation
           facet_by facet_query group_by unscope
           limit offset page per_page per options cache

data/lib/search_engine/client/http_adapter.rb

@@ -31,7 +31,7 @@ module SearchEngine
       # {Response#body}.
       #
       # Supported forms (current usage):
-      # - POST `/collections/:collection/documents/search` (with `common_params`)
+      # - GET `/collections/:collection/documents/search` (with URL search/cache parameters)
       #
       # @param request [SearchEngine::Client::RequestBuilder::Request] normalized request
       # @return [Response] response wrapper with status, headers and raw body
@@ -40,22 +40,14 @@ module SearchEngine
       def perform(request)
         method = request.http_method.to_sym
         path = request.path.to_s
-        if method == :post && path.match?(%r{\A/collections/[^/]+/documents/search\z})
+        if method == :get && path.match?(%r{\A/collections/[^/]+/documents/search\z})
           collection = path.split('/')[2]
           docs = @typesense.collections[collection].documents
-          begin
-            params = docs.method(:search).parameters
-            supports_common = params.any? { |(kind, _)| %i[key keyreq keyrest].include?(kind) }
-          rescue StandardError
-            supports_common = false
-          end
-          raw = supports_common ? docs.search(request.body, common_params: request.params) : docs.search(request.body)
+          raw = docs.search(request.params)
           # The official client returns parsed JSON (Hash). No headers/status exposed here.
           return Response.new(status: 200, headers: {}, body: raw)
         end
 
-        # Fallback: attempt a generic call via low-level typesense endpoint access if available.
-        # This keeps adapter permissive for future endpoints without adding Faraday here.
         raise ArgumentError, "Unsupported request path for adapter: #{request.http_method} #{request.path}"
       end
     end

data/lib/search_engine/client/request_builder.rb

@@ -63,17 +63,15 @@ module SearchEngine
       # @see `https://typesense.org/docs/latest/api/documents.html#search-document`
       def self.build_search(collection:, compiled_params:, url_opts: {})
         name = collection.to_s
-        body_hash = sanitize_body_params(compiled_params.to_h)
-        # Ensure deterministic ordering even after sanitization
-        body_json = SearchEngine::CompiledParams.from(body_hash).to_json
+        query_params = sanitize_body_params(compiled_params.to_h).merge(url_opts || {})
 
         Request.new(
-          http_method: :post,
+          http_method: :get,
           path: COLLECTIONS_PREFIX + name + DOCUMENTS_SEARCH_SUFFIX,
-          params: url_opts || {},
+          params: query_params,
           headers: DEFAULT_HEADERS_JSON,
-          body: body_hash,
-          body_json: body_json
+          body: nil,
+          body_json: nil
         )
       end
 

data/lib/search_engine/client/services/search.rb

@@ -21,8 +21,8 @@ module SearchEngine
 
           result = instrumented_search(collection, params_obj, cache_params, path, payload, start)
           duration = current_monotonic_ms - start
-          instrument(:post, path, duration, cache_params, request_token: start)
-          log_success(:post, path, start, cache_params)
+          instrument(:get, path, duration, cache_params, request_token: start)
+          log_success(:get, path, start, cache_params)
 
           klass = begin
             SearchEngine.collection_for(collection)
@@ -45,7 +45,7 @@ module SearchEngine
           bodies = Array(searches).map { |s| sanitize_body_params(s) }
 
           result = with_exception_mapping(:post, path, cache_params, start) do
-            typesense.multi_search.perform({ searches: bodies }, common_params: cache_params)
+            typesense.multi_search.perform({ searches: bodies }, cache_params)
           end
 
           instrument(:post, path, current_monotonic_ms - start, cache_params, request_token: start)
@@ -64,7 +64,7 @@ module SearchEngine
             result = nil
             SearchEngine::Instrumentation.instrument('search_engine.search', se_payload) do |ctx|
               ctx[:params_preview] = SearchEngine::Instrumentation.redact(params_obj.to_h)
-              result = with_exception_mapping(:post, path, cache_params, start) do
+              result = with_exception_mapping(:get, path, cache_params, start) do
                 docs = typesense.collections[collection].documents
                 documents_search(docs, payload, cache_params)
               end
@@ -80,7 +80,7 @@ module SearchEngine
             end
             result
           else
-            with_exception_mapping(:post, path, cache_params, start) do
+            with_exception_mapping(:get, path, cache_params, start) do
               docs = typesense.collections[collection].documents
               documents_search(docs, payload, cache_params)
             end
@@ -170,19 +170,7 @@ module SearchEngine
         end
 
         def documents_search(docs, payload, common_params)
-          if documents_search_supports_common_params?(docs)
-            docs.search(payload, common_params: common_params)
-          else
-            docs.search(payload)
-          end
-        end
-
-        def documents_search_supports_common_params?(docs)
-          m = docs.method(:search)
-          params = m.parameters
-          params.any? { |(kind, _)| %i[key keyreq keyrest].include?(kind) }
-        rescue StandardError
-          false
+          docs.search(payload.merge(common_params))
         end
       end
     end

data/lib/search_engine/indexer.rb

@@ -241,7 +241,7 @@ module SearchEngine
         client = SearchEngine.client
         payload = { q: '*', query_by: cfg.default_query_by, per_page: 0, filter_by: filter }
         params = SearchEngine::CompiledParams.new(payload)
-        res = client.search(collection: into, params: params, url_opts: {})
+        res = client.search(collection: into, params: params, url_opts: { use_cache: false })
         res&.found
       rescue StandardError
         nil

data/lib/search_engine/observability.rb

@@ -141,12 +141,21 @@ module SearchEngine
     # @param vq [String]
     # @return [String]
     def self.redact_vector_query(vq)
-      return vq unless vq.is_a?(String)
-      return vq if SearchEngine.config.observability.redact_vectors == false
+      return vq if vq.nil? || SearchEngine.config.observability.redact_vectors == false
+      return '[REDACTED]' unless vq.is_a?(String)
 
-      vq.gsub(/\[(-?\d+(?:\.\d+)?(?:\s*,\s*-?\d+(?:\.\d+?))*)\]/) do
-        dims = Regexp.last_match(1).split(',').size
-        "[<#{dims} dims>]"
+      vector_array = /\A([^:]+:\(\s*)\[([^\[\]]*)\](?=\s*[,)])/
+      return '[REDACTED]' unless vq.match?(vector_array)
+
+      vq.sub(vector_array) do
+        prefix = Regexp.last_match(1)
+        values = Regexp.last_match(2)
+        next "#{prefix}[]" if values.strip.empty?
+        next "#{prefix}[#{values}]" if values.match?(/\A<\d+ dims>\z/)
+
+        numbers = values.split(',', -1).map(&:strip)
+        numeric = numbers.all? { |number| number.match?(/\A[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?\z/) }
+        "#{prefix}#{numeric ? "[<#{numbers.size} dims>]" : '[REDACTED]'}"
       end
     end
 

data/lib/search_engine/relation/compiler.rb

@@ -518,7 +518,6 @@ module SearchEngine
 
         auto_include_embedding_in_query_by!(params, vq, field)
         auto_exclude_embedding_from_response!(params, field)
-        resolve_vector_distance_sort!(params, field)
         instrument_vector_compile(vq, params, field)
       end
 
@@ -538,7 +537,10 @@ module SearchEngine
           parts << "#{key}:#{vq[key]}" if vq.key?(key)
         end
         parts << "alpha:#{vq[:alpha]}" if vq.key?(:alpha) && hybrid_vector_mode?(params, vq)
-        parts << "queries:[#{vq[:queries].join(', ')}]" if vq[:queries]
+        if vq[:queries]
+          queries = vq[:queries].map { |query| "`#{query}`" }
+          parts << "queries:[#{queries.join(', ')}]"
+        end
         parts << "query_weights:[#{vq[:weights].join(', ')}]" if vq[:weights]
 
         inner = [vector_part, *parts].join(', ')
@@ -547,9 +549,10 @@ module SearchEngine
 
       # Hybrid mode: auto-append the embedding field to `query_by` so that
       # Typesense performs rank-fusion between keyword and vector results.
-      # Hybrid = text query present AND no explicit embedding vector supplied.
+      # Explicit vectors already supply the embedding and need no query_by addition.
       def auto_include_embedding_in_query_by!(params, vq, field)
         return unless hybrid_vector_mode?(params, vq)
+        return if vq.key?(:query)
 
         current = params[:query_by].to_s
         fields = current.split(',').map(&:strip)
@@ -571,19 +574,8 @@ module SearchEngine
         params[:exclude_fields] = current.empty? ? field : "#{current},#{field}"
       end
 
-      # Replace the `_vector_distance` sentinel produced by order normalization
-      # with the real Typesense sort token that references the embedding field.
-      def resolve_vector_distance_sort!(params, vq_field)
-        sort = params[:sort_by]
-        return unless sort&.include?(VECTOR_DISTANCE_SENTINEL)
-
-        params[:sort_by] = sort.gsub(/#{VECTOR_DISTANCE_SENTINEL}:(asc|desc)/) do
-          "_vector_query(#{vq_field}:([])):#{Regexp.last_match(1)}"
-        end
-      end
-
       def hybrid_vector_mode?(params, vq)
-        params[:q].to_s != '*' && !vq.key?(:query) && !vq.key?(:id) && !vq.key?(:queries)
+        params[:q].to_s != '*' && !vq.key?(:id) && !vq.key?(:queries)
       end
 
       def explicitly_selected_field?(field_name)

data/lib/search_engine/relation/dsl/vectors.rb

@@ -63,6 +63,9 @@ module SearchEngine
 
           validate_vector_query_mode_exclusivity!(query, id, queries)
           validate_vector_query_array!(query)
+          validate_vector_dimensions!(field_sym, query) if query
+          normalized_id = id.to_s unless id.nil?
+          validate_vector_id!(normalized_id)
           validate_vector_queries!(queries)
           validate_vector_weights!(weights, queries)
 
@@ -75,11 +78,11 @@ module SearchEngine
           result = { field: field_sym }
           result[:k] = coerced_k if coerced_k
           result[:alpha] = Float(alpha) if alpha
-          result[:query] = query if query
-          result[:id] = id.to_s if id
+          result[:query] = query.map(&:to_f) if query
+          result[:id] = normalized_id.dup unless normalized_id.nil?
           result[:distance_threshold] = Float(distance_threshold) if distance_threshold
-          result[:queries] = queries if queries
-          result[:weights] = weights if weights
+          result[:queries] = queries.map(&:dup) if queries
+          result[:weights] = weights.map(&:to_f) if weights
           result[:ef] = coerced_ef if coerced_ef
           result[:flat_search_cutoff] = coerced_flat if coerced_flat
           result
@@ -106,11 +109,19 @@ module SearchEngine
 
           sym = field.to_sym
           attrs = safe_attributes_map
-          return if attrs.nil? || attrs.empty?
+          return if attrs.nil?
 
           embeddings = vector_embeddings_map
 
-          return if attrs.key?(sym) || embeddings.key?(sym)
+          return if embeddings.key?(sym) || [:vector, [:float], :'float[]', 'float[]'].include?(attrs[sym])
+
+          if attrs.key?(sym)
+            raise SearchEngine::Errors::InvalidVectorQuery.new(
+              "InvalidVectorQuery: field :#{sym} must be a vector or float array",
+              doc: VECTOR_SEARCH_DOC_URL,
+              details: { field: sym, type: attrs[sym] }
+            )
+          end
 
           known = (attrs.keys + embeddings.keys).uniq
           suggestions = suggest_fields(sym, known)
@@ -128,9 +139,9 @@ module SearchEngine
 
         def validate_vector_query_mode_exclusivity!(query, id, queries)
           modes = []
-          modes << :query if query
-          modes << :id if id
-          modes << :queries if queries
+          modes << :query unless query.nil?
+          modes << :id unless id.nil?
+          modes << :queries unless queries.nil?
           return if modes.length <= 1
 
           raise SearchEngine::Errors::InvalidVectorQuery.new(
@@ -146,9 +157,9 @@ module SearchEngine
         def validate_vector_query_array!(query)
           return if query.nil?
 
-          unless query.is_a?(Array) && query.all? { |v| v.is_a?(Numeric) }
+          unless query.is_a?(Array) && query.all? { |v| finite_vector_number?(v) }
             raise SearchEngine::Errors::InvalidVectorQuery.new(
-              'InvalidVectorQuery: query: must be an Array of Numeric values',
+              'InvalidVectorQuery: query: must be an Array of finite real numbers',
               hint: 'Pass a float array like [0.1, 0.2, ...]',
               doc: VECTOR_SEARCH_DOC_URL,
               details: { query_class: query.class.name }
@@ -164,6 +175,35 @@ module SearchEngine
           )
         end
 
+        def finite_vector_number?(value)
+          value.is_a?(Numeric) && value.real? && value.to_f.finite?
+        end
+
+        def validate_vector_dimensions!(field, query)
+          metadata = vector_embeddings_map[field] || {}
+          options = @klass.respond_to?(:attribute_options) ? @klass.attribute_options[field] || {} : {}
+          dimension = metadata[:num_dim] || options[:num_dim]
+          return if dimension.nil? || query.size == Integer(dimension)
+
+          raise SearchEngine::Errors::InvalidVectorQuery.new(
+            "InvalidVectorQuery: field :#{field} expects #{dimension} dimensions (got #{query.size})",
+            doc: VECTOR_SEARCH_DOC_URL,
+            details: { field: field, expected: dimension, actual: query.size }
+          )
+        end
+
+        def validate_vector_id!(id)
+          return if id.nil?
+
+          value = id.to_s
+          return if !value.empty? && value == value.strip && !value.match?(/[:,()[:cntrl:]]/)
+
+          raise SearchEngine::Errors::InvalidVectorQuery.new(
+            'InvalidVectorQuery: id: cannot be blank or contain vector-query delimiters or surrounding whitespace',
+            doc: VECTOR_SEARCH_DOC_URL
+          )
+        end
+
         def validate_vector_queries!(queries)
           return if queries.nil?
 
@@ -183,6 +223,14 @@ module SearchEngine
             )
           end
 
+          if queries.any? { |query| query != query.strip || query.match?(/[:`[:cntrl:]]/) }
+            raise SearchEngine::Errors::InvalidVectorQuery.new(
+              'InvalidVectorQuery: queries: cannot contain unsupported delimiters or surrounding whitespace',
+              hint: 'Colons, backticks and control characters cannot be represented in historical queries',
+              doc: VECTOR_SEARCH_DOC_URL
+            )
+          end
+
           blank_indices = queries.each_index.select { |i| queries[i].strip.empty? }
           return if blank_indices.empty?
 
@@ -197,9 +245,9 @@ module SearchEngine
         def validate_vector_weights!(weights, queries)
           return if weights.nil?
 
-          unless weights.is_a?(Array) && weights.all? { |v| v.is_a?(Numeric) }
+          unless weights.is_a?(Array) && weights.all? { |v| finite_vector_number?(v) }
             raise SearchEngine::Errors::InvalidVectorQuery.new(
-              'InvalidVectorQuery: weights: must be an Array of Numeric',
+              'InvalidVectorQuery: weights: must be an Array of finite real numbers',
               doc: VECTOR_SEARCH_DOC_URL,
               details: { weights_class: weights.class.name }
             )
@@ -221,7 +269,7 @@ module SearchEngine
             )
           end
 
-          sum = weights.sum.to_f
+          sum = weights.sum(&:to_f)
           tolerance = SearchEngine.config.embedding.weights_sum_tolerance
           return if (sum - 1.0).abs <= tolerance
 
@@ -239,7 +287,7 @@ module SearchEngine
 
           begin
             fv = Float(alpha)
-          rescue ArgumentError, TypeError
+          rescue ArgumentError, TypeError, RangeError
             raise SearchEngine::Errors::InvalidVectorQuery.new(
               "InvalidVectorQuery: alpha: must be a Numeric between 0.0 and 1.0 (got #{alpha.inspect})",
               doc: VECTOR_SEARCH_DOC_URL,
@@ -262,7 +310,7 @@ module SearchEngine
 
           begin
             fv = Float(distance_threshold)
-          rescue ArgumentError, TypeError
+          rescue ArgumentError, TypeError, RangeError
             raise SearchEngine::Errors::InvalidVectorQuery.new(
               'InvalidVectorQuery: distance_threshold: must be a non-negative Numeric ' \
               "(got #{distance_threshold.inspect})",
@@ -285,7 +333,7 @@ module SearchEngine
 
           begin
             iv = Integer(value)
-          rescue ArgumentError, TypeError
+          rescue ArgumentError, TypeError, RangeError
             raise SearchEngine::Errors::InvalidVectorQuery.new(
               "InvalidVectorQuery: #{name}: must be a positive Integer (got #{value.inspect})",
               doc: VECTOR_SEARCH_DOC_URL,
@@ -293,10 +341,10 @@ module SearchEngine
             )
           end
 
-          return iv if iv.positive?
+          return iv if iv.positive? && (value.is_a?(String) || value == iv)
 
           raise SearchEngine::Errors::InvalidVectorQuery.new(
-            "InvalidVectorQuery: #{name}: must be > 0 (got #{iv})",
+            "InvalidVectorQuery: #{name}: must be a positive Integer without truncation",
             doc: VECTOR_SEARCH_DOC_URL,
             details: { name => iv }
           )
@@ -342,8 +390,6 @@ module SearchEngine
           return {} unless @klass.respond_to?(:embeddings_config)
 
           @klass.embeddings_config || {}
-        rescue StandardError
-          {}
         end
 
         def build_vector_field_suggestion(suggestions)

data/lib/search_engine/relation/dsl.rb

@@ -548,8 +548,7 @@ module SearchEngine
       ORDER_ALIASES = { 'text_match' => '_text_match', 'vector_distance' => '_vector_distance' }.freeze
 
       # Map DSL sort aliases to Typesense internal tokens.
-      # `_vector_distance` is a sentinel resolved by the compiler once the
-      # embedding field name is known.
+      # `_vector_distance` sorts the active vector query without re-embedding it.
       def resolve_order_alias(field)
         ORDER_ALIASES.fetch(field, field)
       end

data/lib/search_engine/relation/dx/dry_run.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'shellwords'
 
 module SearchEngine
   class Relation
@@ -36,13 +37,17 @@ module SearchEngine
           end
         end
 
-        # Build a single-line curl string with redacted body.
+        # Build a shell-quoted GET search command with redacted URL parameters.
         # @param url [String]
         # @param params [Hash]
+        # @param url_opts [Hash] request-level cache controls
         # @return [String]
-        def self.curl(url, params)
-          body_json = JSON.generate(redact_params(params))
-          %(curl -X POST #{url} -H 'Content-Type: application/json' -H 'X-TYPESENSE-API-KEY: ***' -d '#{body_json}')
+        def self.curl(url, params, url_opts: {})
+          query = redact_params(params).reject { |key, _value| key == :_hits }
+          query.merge!(SearchEngine::Observability.filtered_url_opts(url_opts))
+          arguments = ['curl', '--get', url, '-H', 'X-TYPESENSE-API-KEY: ***']
+          query.each { |key, value| arguments.concat(['--data-urlencode', "#{key}=#{value}"]) }
+          Shellwords.join(arguments)
         end
 
         # Return a structured dry-run payload with redacted JSON body and url options.

data/lib/search_engine/relation/dx.rb

@@ -11,7 +11,7 @@ module SearchEngine
     # DX helpers are mixed into `Relation` to offer redaction‑aware, zero‑I/O explain and preview utilities.
     # These helpers are pure and never mutate relation state.
     module Dx
-      # Return the request body JSON after compile, fully redacted.
+      # Return the compiled search parameters as fully redacted JSON.
       # @param pretty [Boolean] pretty-print with stable key ordering when true
       # @return [String]
       # @since M8
@@ -22,14 +22,14 @@ module SearchEngine
         SearchEngine::Relation::Dx::DryRun.to_json(redacted, pretty: pretty)
       end
 
-      # Return a single-line curl command with redacted API key and JSON body.
+      # Return a shell-quoted GET curl command with redacted API key and parameters.
       # @return [String]
       # @since M8
       # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/dx
       def to_curl
         url = compiled_url
         params = SearchEngine::CompiledParams.from(to_typesense_params).to_h
-        SearchEngine::Relation::Dx::DryRun.curl(url, params)
+        SearchEngine::Relation::Dx::DryRun.curl(url, params, url_opts: compiled_url_opts)
       end
 
       # Compile and validate without performing network I/O.

data/lib/search_engine/result.rb

@@ -96,6 +96,7 @@ module SearchEngine
           attach_curation!(obj, entry)
           attach_highlighting!(obj, entry)
           attach_geo_distance!(obj, entry)
+          attach_vector_distance!(obj, entry)
           hydrated << obj
         end
         @hits = hydrated.freeze
@@ -296,6 +297,14 @@ module SearchEngine
       end
     end
 
+    # Backend vector distance metadata, distinct from document attributes.
+    module VectorDistance
+      # @return [Numeric, nil] the unmodified distance supplied by Typesense
+      def vector_distance
+        instance_variable_get(:@__se_vector_distance__)
+      end
+    end
+
     # Per-hit curation mixin: added onto hydrated objects when Typesense
     # returns curated metadata for the hit.
     module HitCuration
@@ -414,6 +423,7 @@ module SearchEngine
           attach_curation!(obj, sym_sub)
           attach_highlighting!(obj, sym_sub)
           attach_geo_distance!(obj, sym_sub)
+          attach_vector_distance!(obj, sym_sub)
           hydrated << obj
         end
 
@@ -569,6 +579,14 @@ module SearchEngine
       obj
     end
 
+    def attach_vector_distance!(obj, hit_entry)
+      return obj unless hit_entry.key?(:vector_distance)
+
+      obj.singleton_class.prepend(VectorDistance)
+      obj.instance_variable_set(:@__se_vector_distance__, hit_entry[:vector_distance])
+      obj
+    end
+
     def attach_geo_distance!(obj, hit_entry)
       raw_geo = hit_entry[:geo_distance_meters]
       return obj unless raw_geo.is_a?(Hash) && !raw_geo.empty?

data/lib/search_engine/version.rb

@@ -3,5 +3,5 @@
 module SearchEngine
   # Current gem version.
   # @return [String]
-  VERSION = '30.8.24'
+  VERSION = '30.9.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: search-engine-for-typesense
 version: !ruby/object:Gem::Version
-  version: 30.8.24
+  version: 30.9.0
 platform: ruby
 authors:
 - Nikita Shkoda
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby