search-engine-for-typesense 30.1.6.2 → 30.1.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea3e7da2359ce1d9b4990147c6627e00a726cfa4e75cc340649ae561b32e42fe
-  data.tar.gz: 6b14b6b9e39cab91210e16ecced55f19948831d9f949cb2969f0be5731229cf1
+  metadata.gz: 228f70410334d2a324508d0d44dfd31aadbcb4a957f28425909108490a3129a2
+  data.tar.gz: 89fd3243af9aec91757d9819136ce9b0fd783845ff1ff6e6fe72467106d20ecb
 SHA512:
-  metadata.gz: 6c2252a8d88ebe47b54bb7ac7ed2d65f2e0ed82b3e011ffeb3f5fb3756bff75de417c055a1de8c71fa513e51a6cfcb70b1025e6463164ff5de7018b1fcec1df8
-  data.tar.gz: 5519c44a440ed906df1673baf2682b1630171c0a2efb103feeb3300700d2d2653d521432fa332d2bc344c2cf717ba0ae7aa4d3feaaa6dcc7c82cfc0ba1486a4f
+  metadata.gz: 42e556e2b25d40fd5ba85cb1ae1961223420d6affb6f532936642a48159dc013a8297398cba3724ef798f2cab05a0819140c9038d415b0035c7f9a95b2408e07
+  data.tar.gz: ea3aba9866079ade74da2712d73f6e2a7169cc0a013dff5814ccbc7034789e9f2d6ae38979e49761210e46e4a61f329fde3ae9bb356f02b643b14899a0d24d9d

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

@@ -11,8 +11,10 @@ module SearchEngine
         # Perform a vector (semantic / hybrid / ANN) search on an embedding field.
         #
         # Last call wins — Typesense supports a single `vector_query` per search.
+        # When +field+ is omitted the sole embedding declared on the model is
+        # used automatically; raises when the model has zero or multiple embeddings.
         #
-        # @param field [Symbol, String] embedding field name
+        # @param field [Symbol, String, nil] embedding field name (auto-resolved when nil)
         # @param k [Integer, nil] number of nearest neighbors
         # @param alpha [Float, nil] hybrid blend weight (0.0 = keyword, 1.0 = vector)
         # @param query [Array<Numeric>, nil] explicit embedding vector
@@ -24,11 +26,12 @@ module SearchEngine
         # @param ef [Integer, nil] HNSW ef override
         # @param flat_search_cutoff [Integer, nil] brute-force threshold
         # @return [SearchEngine::Relation]
-        def vector_search(field, k: nil, alpha: nil, query: nil, id: nil,
+        def vector_search(field = nil, k: nil, alpha: nil, query: nil, id: nil,
                           distance_threshold: nil, queries: nil, weights: nil,
                           ef: nil, flat_search_cutoff: nil)
+          resolved = resolve_vector_field(field)
           normalized = normalize_vector_search(
-            field, k: k, alpha: alpha, query: query, id: id,
+            resolved, k: k, alpha: alpha, query: query, id: id,
             distance_threshold: distance_threshold, queries: queries,
             weights: weights, ef: ef, flat_search_cutoff: flat_search_cutoff
           )
@@ -38,13 +41,15 @@ module SearchEngine
         # Find documents similar to a given document ID.
         #
         # Sugar over `vector_search` with `id:`.
+        # When +field+ is omitted the sole embedding declared on the model is
+        # used automatically (same resolution as {#vector_search}).
         #
         # @param document_id [#to_s] ID of the reference document
-        # @param field [Symbol, String] embedding field name
+        # @param field [Symbol, String, nil] embedding field name (auto-resolved when nil)
         # @param k [Integer, nil] number of nearest neighbors
         # @param distance_threshold [Float, nil] max cosine distance
         # @return [SearchEngine::Relation]
-        def find_similar(document_id, field:, k: nil, distance_threshold: nil)
+        def find_similar(document_id, field: nil, k: nil, distance_threshold: nil)
           vector_search(field, id: document_id, k: k, distance_threshold: distance_threshold)
         end
 
@@ -297,6 +302,40 @@ module SearchEngine
           )
         end
 
+        # -- Field resolution ---------------------------------------------------
+
+        # Auto-resolve the embedding field when none is given explicitly.
+        # Returns the field as-is when provided, or the sole embedding field
+        # declared on the model. Raises when resolution is ambiguous or impossible.
+        #
+        # @param field [Symbol, String, nil] explicit field or nil for auto-resolution
+        # @return [Symbol, String]
+        def resolve_vector_field(field)
+          return field unless field.nil?
+
+          embeddings = vector_embeddings_map
+          case embeddings.size
+          when 1
+            embeddings.each_key.first
+          when 0
+            raise SearchEngine::Errors::InvalidVectorQuery.new(
+              "InvalidVectorQuery: cannot auto-resolve embedding field \u2014 " \
+              "no embeddings declared on #{klass_name_for_inspect}",
+              hint: 'Declare one with `embedding` in your model DSL',
+              doc: VECTOR_SEARCH_DOC_URL
+            )
+          else
+            fields_list = embeddings.keys.map { |k| ":#{k}" }.join(', ')
+            raise SearchEngine::Errors::InvalidVectorQuery.new(
+              "InvalidVectorQuery: cannot auto-resolve embedding field \u2014 " \
+              "#{klass_name_for_inspect} has multiple embeddings (#{fields_list})",
+              hint: 'Pass the field explicitly: .vector_search(:field_name)',
+              doc: VECTOR_SEARCH_DOC_URL,
+              details: { available_embeddings: embeddings.keys }
+            )
+          end
+        end
+
         # -- Helpers ------------------------------------------------------------
 
         def vector_embeddings_map

data/lib/search_engine/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: search-engine-for-typesense
 version: !ruby/object:Gem::Version
-  version: 30.1.6.2
+  version: 30.1.6.3
 platform: ruby
 authors:
 - Nikita Shkoda