search-engine-for-typesense 30.1.6.1 → 30.1.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2107cc318bf6916c602aa10cd0804afc83f8148eac15b66572526644ffd10fd5
-  data.tar.gz: ef5327d92e2140487b6a407bba9b140aa5e70636f063aaa146e9345f6723eb87
+  metadata.gz: 228f70410334d2a324508d0d44dfd31aadbcb4a957f28425909108490a3129a2
+  data.tar.gz: 89fd3243af9aec91757d9819136ce9b0fd783845ff1ff6e6fe72467106d20ecb
 SHA512:
-  metadata.gz: eef349f62ec8a29de651d8511f0d678bf874fff636ce566709c247464df5861da8257d1f95cfa7446a9d8f9ac6e35dd04ea6df13cd33c1511638dbf27f46801f
-  data.tar.gz: a5a72915fc94ee24751ac255bb5920d85d4f94da9dab0dbe53382456b017363de1d025bba46c6ac871e02d80bbbecc4f8c2d35a131430397d187716b21eb2c8e
+  metadata.gz: 42e556e2b25d40fd5ba85cb1ae1961223420d6affb6f532936642a48159dc013a8297398cba3724ef798f2cab05a0819140c9038d415b0035c7f9a95b2408e07
+  data.tar.gz: ea3aba9866079ade74da2712d73f6e2a7169cc0a013dff5814ccbc7034789e9f2d6ae38979e49761210e46e4a61f329fde3ae9bb356f02b643b14899a0d24d9d

data/lib/search_engine/base/model_dsl.rb

@@ -96,7 +96,9 @@ module SearchEngine
         #
         # @param name [#to_sym]
         # @param type [Object] type descriptor (e.g., :string, :integer)
-        # @param index [Boolean, nil] when false, omit from compiled Typesense schema (still hydrated/displayed)
+        # @param index [Boolean, nil] when false, omit from compiled Typesense schema (still
+        #   hydrated/displayed). Fields referenced by an embedding's `from:` are kept in the
+        #   schema with Typesense-native `"index": false` instead of being omitted entirely.
         # @param locale [String, nil]
         # @param optional [Boolean, nil]
         # @param sort [Boolean, nil]

data/lib/search_engine/mapper.rb

@@ -566,7 +566,7 @@ module SearchEngine
         base_fields.reject! { |fname| fname.to_s.include?('.') }
         required = base_fields.to_set
         opts.each do |fname, o|
-          next unless o.is_a?(Hash) && o[:optional]
+          next unless o.is_a?(Hash) && (o[:optional] || o[:index] == false)
 
           required.delete(fname.to_sym)
         end

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/schema.rb

@@ -35,7 +35,7 @@ module SearchEngine
     }.freeze
 
     FIELD_COMPARE_KEYS = %i[
-      type reference async_reference locale sort optional infix facet
+      type reference async_reference locale sort optional index infix facet
       embed num_dim hnsw_params
     ].freeze
     PHYSICAL_SUFFIX_RE = /_\d{8}_\d{6}_\d{3}\z/
@@ -44,9 +44,14 @@ module SearchEngine
       # Build a Typesense-compatible schema hash from a model class DSL.
       #
       # The output includes only keys that are supported and declared via the DSL.
-      # Fields explicitly marked with `index: false` are intentionally omitted
-      # from the compiled schema (they can still be sent in documents and will
-      # be hydrated/displayed, but are not indexed in memory).
+      # Fields explicitly marked with `index: false` are generally omitted from
+      # the compiled schema (they can still be sent in documents and will be
+      # hydrated/displayed, but are not indexed in memory).
+      #
+      # **Exception:** fields with `index: false` that are referenced by an
+      # embedding's `from:` list are included with Typesense-native
+      # `"index": false` and `"optional": true` so the embedding model can
+      # read their values without keyword-indexing them.
       #
       # @param klass [Class] model class inheriting from {SearchEngine::Base}
       # @return [Hash] frozen schema hash with symbol keys
@@ -462,6 +467,7 @@ module SearchEngine
         attribute_options = klass.respond_to?(:attribute_options) ? (klass.attribute_options || {}) : {}
         references_by_local_key = build_references_by_local_key(klass, client: client)
         async_reference_by_local_key = build_async_reference_by_local_key(klass)
+        embed_source_fields = collect_embed_source_fields(attribute_options)
 
         fields_array = []
         needs_nested_fields = false
@@ -470,14 +476,16 @@ module SearchEngine
           validate_attribute_type!(attribute_name, type_descriptor)
 
           opts = attribute_options[attribute_name.to_sym] || {}
-          # Skip non-indexed attributes and any nested fields under a non-indexed base
+          # Skip non-indexed attributes and any nested fields under a non-indexed base,
+          # unless the field is referenced by an embedding's from: list.
           base_index_false = false
           if attribute_name.to_s.include?('.')
             base_sym = attribute_name.to_s.split('.', 2).first.to_sym
             base_opts = attribute_options[base_sym] || {}
             base_index_false = (base_opts[:index] == false)
           end
-          next if opts[:index] == false || base_index_false
+          effectively_unindexed = opts[:index] == false || base_index_false
+          next if effectively_unindexed && !embed_source_fields.include?(attribute_name.to_sym)
 
           ts_type = typesense_type_for(type_descriptor)
 
@@ -536,14 +544,34 @@ module SearchEngine
         %w[object object[]].include?(ts_type)
       end
 
+      # Collect field names referenced by any embedding's from: list.
+      # @param attribute_options [Hash] model attribute options
+      # @return [Set<Symbol>] field names used as embedding sources
+      def collect_embed_source_fields(attribute_options)
+        sources = Set.new
+        attribute_options.each_value do |opts|
+          next unless opts.is_a?(Hash)
+
+          embed = opts[:embed]
+          next unless embed.is_a?(Hash)
+
+          from = embed[:from] || embed['from']
+          Array(from).each { |f| sources << f.to_sym }
+        end
+        sources
+      end
+      private :collect_embed_source_fields
+
       def build_field_entry(attribute_name, ts_type, references_by_local_key, async_reference_by_local_key, opts)
+        unindexed = opts[:index] == false
         {
           name: attribute_name.to_s,
           type: ts_type,
           **{
+            index: unindexed ? false : nil,
             locale: opts[:locale],
             sort: opts[:sort],
-            optional: opts[:optional],
+            optional: unindexed ? true : opts[:optional],
             infix: opts[:infix],
             facet: opts[:facet],
             reference: references_by_local_key[attribute_name.to_sym],
@@ -621,7 +649,7 @@ module SearchEngine
         entry = { name: fname, type: normalize_type(ftype) }
         entry[:reference] = fref.to_s unless fref.nil? || fref.to_s.strip.empty?
 
-        %i[locale sort optional infix facet async_reference].each do |k|
+        %i[locale sort optional index infix facet async_reference].each do |k|
           val = field[k] || field[k.to_s]
           entry[k] = val unless val.nil?
         end

data/lib/search_engine/version.rb

@@ -3,5 +3,5 @@
 module SearchEngine
   # Current gem version.
   # @return [String]
-  VERSION = '30.1.6.1'
+  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.1
+  version: 30.1.6.3
 platform: ruby
 authors:
 - Nikita Shkoda