mongoid 9.0.11 → 9.1.0

data/lib/mongoid/search_indexable.rb

@@ -55,6 +55,96 @@ module Mongoid
       self.search_index_specs = []
     end
 
+    # Performs a vector search for documents similar to this one, using
+    # this document's stored embedding as the query vector. The document
+    # itself is excluded from the results.
+    #
+    # @example Find articles similar to this one.
+    #   article.vector_search(limit: 5, filter: { status: 'published' })
+    #
+    # @param [ String | Symbol | nil ] index The name of the vector search
+    #   index to use (optional if only one is declared on the model).
+    # @param [ String | Symbol | nil ] path The field containing the stored
+    #   vector (optional if unambiguous from the index definition).
+    # @param [ Integer ] limit The maximum number of results (default: 10).
+    # @param [ Integer | nil ] num_candidates The number of candidates to
+    #   consider during the ANN search; defaults to limit * 10.
+    # @param [ Hash | nil ] filter An optional MongoDB filter to pre-filter
+    #   candidates before scoring.
+    # @param [ Array ] pipeline Additional aggregation stages to append after
+    #   the vector search and score projection.
+    #
+    # @return [ Array<Mongoid::Document> ] matching documents, each with
+    #   a populated +vector_search_score+ attribute.
+    def vector_search(index: nil, path: nil, limit: 10, num_candidates: nil, filter: nil, pipeline: [])
+      _index, resolved_path = self.class.send(:resolve_vector_index, index, path)
+      query_vector = public_send(resolved_path)
+
+      if query_vector.nil?
+        raise ArgumentError,
+              "#{resolved_path} is nil on this document; cannot perform vector search"
+      end
+
+      self_filter = { '_id' => { '$ne' => _id } }
+      combined_filter = filter ? { '$and' => [ self_filter, filter ] } : self_filter
+
+      self.class.vector_search(
+        query_vector,
+        index: index,
+        path: path,
+        limit: limit,
+        num_candidates: num_candidates,
+        filter: combined_filter,
+        pipeline: pipeline
+      )
+    end
+
+    # Performs an Atlas Vector Search query for documents with text similar
+    # to this document's stored text field, using auto-embedding. The current
+    # document is excluded from the results.
+    #
+    # @example Find articles with similar descriptions.
+    #   article.auto_embed_search(limit: 5, filter: { status: 'published' })
+    #
+    # @param [ String | Symbol | nil ] index The name of the auto-embed index
+    #   to use (optional when only one is declared on the model).
+    # @param [ String | Symbol | nil ] path The indexed text field path
+    #   (optional if unambiguous from the index definition).
+    # @param [ Integer ] limit Maximum number of results (default: 10).
+    # @param [ Integer | nil ] num_candidates Candidates for ANN search;
+    #   defaults to limit * 10. Ignored when exact: true.
+    # @param [ Hash | nil ] filter Optional MongoDB filter for pre-filtering.
+    # @param [ true | false ] exact Use exact nearest-neighbor search (default: false).
+    # @param [ String | nil ] model Query-time embedding model override.
+    # @param [ Array ] pipeline Additional aggregation stages to append.
+    #
+    # @return [ Array<Mongoid::Document> ] matching documents, each with
+    #   a populated +vector_search_score+ attribute.
+    def auto_embed_search(index: nil, path: nil, limit: 10, num_candidates: nil, filter: nil, exact: false, model: nil, pipeline: []) # rubocop:disable Metrics/ParameterLists
+      _index, resolved_path = self.class.send(:resolve_auto_embed_index, index, path)
+      text = public_send(resolved_path)
+
+      if text.nil?
+        raise ArgumentError,
+              "#{resolved_path} is nil on this document; cannot perform auto-embed search"
+      end
+
+      self_filter = { '_id' => { '$ne' => _id } }
+      combined_filter = filter ? { '$and' => [ self_filter, filter ] } : self_filter
+
+      self.class.auto_embed_search(
+        text,
+        index: index,
+        path: path,
+        limit: limit,
+        num_candidates: num_candidates,
+        filter: combined_filter,
+        exact: exact,
+        model: model,
+        pipeline: pipeline
+      )
+    end
+
     # Implementations for the feature's class-level methods.
     module ClassMethods
       # Request the creation of all registered search indices. Note
@@ -152,6 +242,136 @@ module Mongoid
         search_index_specs.push(spec)
       end
 
+      # Adds a vector search index definition. Also defines a read-only
+      # +vector_search_score+ field on the model the first time it is called,
+      # which is populated on documents returned by +vector_search+.
+      #
+      # @example Create a vector search index.
+      #   class Person
+      #     include Mongoid::Document
+      #     vector_search_index({ fields: [...] })
+      #     vector_search_index :my_vector_index, { fields: [...] }
+      #   end
+      #
+      # @param [ Symbol | String | Hash ] name_or_defn Either the name of the index to
+      #    define, or the index definition.
+      # @param [ Hash ] defn The vector search index definition.
+      def vector_search_index(name_or_defn, defn = nil)
+        name = name_or_defn
+        name, defn = nil, name if name.is_a?(Hash)
+
+        spec = { type: 'vectorSearch', definition: defn }.tap { |s| s[:name] = name.to_s if name }
+        search_index_specs.push(spec)
+
+        return if fields.key?('vector_search_score')
+
+        field :vector_search_score, type: Float
+        attr_readonly :vector_search_score
+      end
+
+      # Performs an Atlas Vector Search query and returns matching documents.
+      # Each returned document has a +vector_search_score+ attribute populated
+      # with its relevance score.
+      #
+      # The vector field (given by +path:+) is excluded from the returned
+      # documents by default, as vectors are large and rarely useful after
+      # retrieval.
+      #
+      # @example Search by an explicit query vector.
+      #   Article.vector_search(embedding, limit: 5, filter: { status: 'published' })
+      #
+      # @param [ Array<Numeric> ] vector The query vector.
+      # @param [ String | Symbol | nil ] index The name of the vector search
+      #   index to use (optional if only one is declared on the model).
+      # @param [ String | Symbol | nil ] path The field containing the stored
+      #   vector (optional if unambiguous from the index definition).
+      # @param [ Integer ] limit The maximum number of results (default: 10).
+      # @param [ Integer | nil ] num_candidates The number of candidates to
+      #   consider during the ANN search; defaults to limit * 10.
+      # @param [ Hash | nil ] filter An optional MongoDB filter to pre-filter
+      #   candidates before scoring.
+      # @param [ Array ] pipeline Additional aggregation stages to append after
+      #   the vector search and score projection.
+      #
+      # @return [ Array<Mongoid::Document> ] matching documents, each with
+      #   a populated +vector_search_score+ attribute.
+      def vector_search(vector, index: nil, path: nil, limit: 10, num_candidates: nil, filter: nil, pipeline: []) # rubocop:disable Metrics/ParameterLists
+        resolved_index, resolved_path = resolve_vector_index(index, path)
+        num_candidates ||= limit * 10
+
+        vs_options = {
+          'index' => resolved_index,
+          'path' => resolved_path,
+          'queryVector' => vector,
+          'numCandidates' => num_candidates,
+          'limit' => limit
+        }
+        vs_options['filter'] = filter if filter
+
+        agg_pipeline = [
+          { '$vectorSearch' => vs_options },
+          { '$addFields'    => { 'vector_search_score' => { '$meta' => 'vectorSearchScore' } } },
+          { '$project'      => { resolved_path => 0 } }
+        ]
+        agg_pipeline.concat(Array(pipeline))
+
+        collection.aggregate(agg_pipeline).map { |doc| instantiate(doc) }
+      end
+
+      # Performs an Atlas Vector Search query using auto-embedding. Atlas
+      # generates the query vector from the supplied text at query time; no
+      # pre-computed embedding is required.
+      #
+      # Each returned document has a +vector_search_score+ attribute populated
+      # with its relevance score. Unlike +vector_search+, the indexed text field
+      # is retained in returned documents.
+      #
+      # @example Search by text.
+      #   Article.auto_embed_search('machine learning', limit: 5)
+      #
+      # @example Exact nearest-neighbor search (no numCandidates).
+      #   Article.auto_embed_search('deep learning', exact: true, limit: 5)
+      #
+      # @param [ String ] text The query text.
+      # @param [ String | Symbol | nil ] index The name of the auto-embed index
+      #   to use (optional when only one is declared on the model).
+      # @param [ String | Symbol | nil ] path The indexed text field path
+      #   (optional if unambiguous from the index definition).
+      # @param [ Integer ] limit Maximum number of results (default: 10).
+      # @param [ Integer | nil ] num_candidates Candidates for ANN search;
+      #   defaults to limit * 10. Ignored when exact: true.
+      # @param [ Hash | nil ] filter Optional MongoDB filter for pre-filtering.
+      # @param [ true | false ] exact Use exact nearest-neighbor (ENN) search
+      #   instead of ANN (default: false). When true, numCandidates is omitted.
+      # @param [ String | nil ] model Query-time embedding model override.
+      # @param [ Array ] pipeline Additional aggregation stages appended after
+      #   the vector search and score projection.
+      #
+      # @return [ Array<Mongoid::Document> ] matching documents, each with
+      #   a populated +vector_search_score+ attribute.
+      def auto_embed_search(text, index: nil, path: nil, limit: 10, num_candidates: nil, filter: nil, exact: false, model: nil, pipeline: []) # rubocop:disable Metrics/ParameterLists
+        resolved_index, resolved_path = resolve_auto_embed_index(index, path)
+
+        vs_options = {
+          'index' => resolved_index,
+          'path' => resolved_path,
+          'query' => { 'text' => text },
+          'limit' => limit
+        }
+        vs_options['numCandidates'] = num_candidates || (limit * 10) unless exact
+        vs_options['exact'] = true if exact
+        vs_options['filter'] = filter if filter
+        vs_options['model'] = model if model
+
+        agg_pipeline = [
+          { '$vectorSearch' => vs_options },
+          { '$addFields'    => { 'vector_search_score' => { '$meta' => 'vectorSearchScore' } } }
+        ]
+        agg_pipeline.concat(Array(pipeline))
+
+        collection.aggregate(agg_pipeline).map { |doc| instantiate(doc) }
+      end
+
       private
 
       # Retrieves the index records for the indexes with the given names.
@@ -162,6 +382,116 @@ module Mongoid
       def get_indexes(names)
         collection.search_indexes.select { |i| names.include?(i['name']) }
       end
+
+      # Resolves the index name and vector path from the declared specs,
+      # applying inference when either is omitted.
+      #
+      # @param [ String | Symbol | nil ] index The requested index name.
+      # @param [ String | Symbol | nil ] path The requested field path.
+      #
+      # @return [ Array<String> ] the resolved [ index_name, field_path ] pair.
+      def resolve_vector_index(index, path)
+        vector_specs = search_index_specs.select { |s| s[:type] == 'vectorSearch' }
+
+        raise ArgumentError, "No vector search indexes declared on #{name}" if vector_specs.empty?
+
+        spec = if index
+                 found = vector_specs.find { |s| s[:name] == index.to_s }
+                 raise ArgumentError, "No vector search index '#{index}' declared on #{name}" unless found
+
+                 found
+               elsif vector_specs.size == 1
+                 vector_specs.first
+               else
+                 raise ArgumentError,
+                       "#{name} has multiple vector search indexes; specify index: to select one"
+               end
+
+        resolved_index = spec[:name] || 'default'
+        resolved_path  = path ? path.to_s : infer_vector_path(spec)
+
+        [ resolved_index, resolved_path ]
+      end
+
+      # Infers the vector field path from the index definition by locating
+      # the first field declared with type 'vector'.
+      #
+      # @param [ Hash ] spec The vector search index spec.
+      #
+      # @return [ String ] the field path.
+      def infer_vector_path(spec)
+        field_list = spec.dig(:definition, :fields) || spec.dig(:definition, 'fields') || []
+        vector_field = field_list.find { |f| (f[:type] || f['type']) == 'vector' }
+
+        unless vector_field
+          raise ArgumentError,
+                "Cannot infer vector path on #{name}: no 'vector' type field in index definition; specify path:"
+        end
+
+        (vector_field[:path] || vector_field['path']).to_s
+      end
+
+      # Resolves the index name and text field path for an auto-embedding
+      # query, applying inference when either is omitted.
+      #
+      # @param [ String | Symbol | nil ] index The requested index name.
+      # @param [ String | Symbol | nil ] path The requested field path.
+      #
+      # @return [ Array<String> ] the resolved [ index_name, field_path ] pair.
+      def resolve_auto_embed_index(index, path)
+        auto_embed_specs = search_index_specs.select do |s|
+          s[:type] == 'vectorSearch' &&
+            (s.dig(:definition, :fields) || s.dig(:definition, 'fields') || [])
+              .any? { |f| (f[:type] || f['type']) == 'autoEmbed' }
+        end
+
+        raise ArgumentError, "No auto-embed indexes declared on #{name}" if auto_embed_specs.empty?
+
+        # Extracted to keep cyclomatic complexity within RuboCop's threshold.
+        spec = select_auto_embed_spec(auto_embed_specs, index)
+        resolved_index = spec[:name] || 'default'
+        resolved_path  = path ? path.to_s : infer_auto_embed_path(spec)
+
+        [ resolved_index, resolved_path ]
+      end
+
+      # Picks one spec from the list of auto-embed specs, guided by +index+.
+      #
+      # @param [ Array<Hash> ] specs The candidate auto-embed specs.
+      # @param [ String | Symbol | nil ] index The requested index name.
+      #
+      # @return [ Hash ] the selected spec.
+      def select_auto_embed_spec(specs, index)
+        if index
+          found = specs.find { |s| s[:name] == index.to_s }
+          raise ArgumentError, "No auto-embed index '#{index}' declared on #{name}" unless found
+
+          found
+        elsif specs.size == 1
+          specs.first
+        else
+          raise ArgumentError,
+                "#{name} has multiple auto-embed indexes; specify index: to select one"
+        end
+      end
+
+      # Infers the text field path from an index definition by locating
+      # the first field declared with type 'autoEmbed'.
+      #
+      # @param [ Hash ] spec The vector search index spec.
+      #
+      # @return [ String ] the field path.
+      def infer_auto_embed_path(spec)
+        field_list = spec.dig(:definition, :fields) || spec.dig(:definition, 'fields') || []
+        ae_field   = field_list.find { |f| (f[:type] || f['type']) == 'autoEmbed' }
+
+        unless ae_field
+          raise ArgumentError,
+                "Cannot infer path on #{name}: no 'autoEmbed' field in index definition; specify path:"
+        end
+
+        (ae_field[:path] || ae_field['path']).to_s
+      end
     end
   end
 end

data/lib/mongoid/selectable.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
-
   # Provides behavior for generating the selector for a specific document.
   module Selectable
     extend ActiveSupport::Concern
@@ -44,7 +42,7 @@ module Mongoid
     #
     # @return [ Hash ] The root document selector.
     def root_atomic_selector_in_db
-      { "_id" => _id }.merge!(shard_key_selector_in_db)
+      { '_id' => _id }.merge!(shard_key_selector_in_db)
     end
   end
 end

data/lib/mongoid/serializable.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
-
   # This module provides the extra behavior for including associations in JSON
   # and XML serialization.
   module Serializable
@@ -11,15 +9,15 @@ module Mongoid
     # We need to redefine where the JSON configuration is getting defined,
     # similar to +ActiveRecord+.
     included do
-
       class << self
+        # These methods are previously defined by ActiveModel which we override to include default behavior.
+        remove_method :include_root_in_json if method_defined?(:include_root_in_json)
+        remove_method :include_root_in_json= if method_defined?(:include_root_in_json=)
         def include_root_in_json
           @include_root_in_json.nil? ? ::Mongoid.include_root_in_json : @include_root_in_json
         end
 
-        def include_root_in_json=(new_value)
-          @include_root_in_json = new_value
-        end
+        attr_writer :include_root_in_json
       end
     end
 
@@ -78,9 +76,9 @@ module Mongoid
 
       only = Array.wrap(options[:only]).map(&:to_s)
       except = Array.wrap(options[:except]).map(&:to_s)
-      except |= [self.class.discriminator_key] unless Mongoid.include_type_for_serialization
+      except |= [ self.class.discriminator_key ] unless Mongoid.include_type_for_serialization
 
-      if !only.empty?
+      if !options[:only].nil? && (!Mongoid.serializable_hash_with_legacy_only || !only.empty?)
         names &= only
       elsif !except.empty?
         names -= except

data/lib/mongoid/shardable.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
-
   # This module contains behavior for adding shard key fields to updates.
   module Shardable
     extend ActiveSupport::Concern
@@ -94,8 +92,8 @@ module Mongoid
     #
     # @api private
     def shard_key_field_value(field, prefer_persisted:)
-      if field.include?(".")
-        relation, remaining = field.split(".", 2)
+      if field.include?('.')
+        relation, remaining = field.split('.', 2)
         send(relation)&.shard_key_field_value(remaining, prefer_persisted: prefer_persisted)
       elsif prefer_persisted && !new_record?
         attribute_was(field)
@@ -105,7 +103,6 @@ module Mongoid
     end
 
     module ClassMethods
-
       # Specifies a shard key with the field(s) specified.
       #
       # @example Specify the shard key.
@@ -120,34 +117,28 @@ module Mongoid
       def shard_key(*args)
         unless args.first.is_a?(Hash)
           # Shorthand syntax
-          if args.last.is_a?(Hash)
-            raise ArgumentError, 'Shorthand shard_key syntax does not permit options'
-          end
+          raise ArgumentError, 'Shorthand shard_key syntax does not permit options' if args.last.is_a?(Hash)
 
           spec = Hash[args.map do |name|
-            [name, 1]
+            [ name, 1 ]
           end]
 
           return shard_key(spec)
         end
 
-        if args.length > 2
-          raise ArgumentError, 'Full shard_key syntax requires 1 or 2 arguments'
-        end
+        raise ArgumentError, 'Full shard_key syntax requires 1 or 2 arguments' if args.length > 2
 
         spec, options = args
 
         spec = Hash[spec.map do |name, value|
-          if value.is_a?(Symbol)
-            value = value.to_s
-          end
-          [database_field_name(name).to_sym, value]
+          value = value.to_s if value.is_a?(Symbol)
+          [ database_field_name(name).to_sym, value ]
         end]
 
         self.shard_key_fields = spec.keys
         self.shard_config = {
           key: spec.freeze,
-          options: (options || {}).dup.freeze,
+          options: (options || {}).dup.freeze
         }.freeze
       end
     end

data/lib/mongoid/stateful.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
-
   # Mixin module included into Mongoid::Document which adds behavior for
   # getting the various lifecycle states a document can transition through.
   module Stateful
-
     attr_writer :destroyed, :flagged_for_destroy, :previously_new_record
 
     # Sets whether the document has been persisted to the database.
@@ -16,9 +13,7 @@ module Mongoid
     # @return [ true | false ] The set value.
     def new_record=(new_value)
       @new_record ||= false
-      if @new_record && !new_value
-        @previously_new_record = true
-      end
+      @previously_new_record = true if @new_record && !new_value
       @new_record = new_value
     end
 
@@ -73,10 +68,10 @@ module Mongoid
     def flagged_for_destroy?
       @flagged_for_destroy ||= false
     end
-    alias :marked_for_destruction? :flagged_for_destroy?
-    alias :_destroy :flagged_for_destroy?
+    alias marked_for_destruction? flagged_for_destroy?
+    alias _destroy flagged_for_destroy?
 
-    # Returns true if the +Document+ has been succesfully destroyed, and false
+    # Returns true if the +Document+ has been successfully destroyed, and false
     # if it hasn't. This is determined by the variable @destroyed and NOT
     # by checking the database.
     #
@@ -126,7 +121,7 @@ module Mongoid
     # @return [ true | false ] If the document is readonly.
     def readonly?
       if Mongoid.legacy_readonly
-        __selected_fields != nil
+        !__selected_fields.nil?
       else
         @readonly ||= false
       end

data/lib/mongoid/stringified_symbol.rb

@@ -1,14 +1,10 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
-
   # A class which sends values to the database as Strings but returns
   # them to the user as Symbols.
   class StringifiedSymbol
-
     class << self
-
       # Convert the object from its mongo friendly ruby type to this type.
       #
       # @example Demongoize the object.
@@ -39,11 +35,11 @@ module Mongoid
       #
       # @api private
       def mongoize(object)
-         if object.nil?
-           object
-         else
-           object.to_s
-         end
+        if object.nil?
+          object
+        else
+          object.to_s
+        end
       end
 
       # Turn the object from the Ruby type into the type

data/lib/mongoid/tasks/database.rake

@@ -1,62 +1,61 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 namespace :db do
   namespace :mongoid do
     task :load_models do
-      ::Mongoid.load_models
+      Mongoid.load_models
     end
 
-    desc "Create collections for Mongoid models"
-    task :create_collections => [:environment, :load_models] do
-      ::Mongoid::Tasks::Database.create_collections
+    desc 'Create collections for Mongoid models'
+    task create_collections: %i[environment load_models] do
+      Mongoid::Tasks::Database.create_collections
     end
 
-    desc "Create indexes specified in Mongoid models"
-    task :create_indexes => [:environment, :load_models] do
-      ::Mongoid::Tasks::Database.create_indexes
+    desc 'Create indexes specified in Mongoid models'
+    task create_indexes: %i[environment load_models] do
+      Mongoid::Tasks::Database.create_indexes
     end
 
-    desc "Create search indexes specified in Mongoid models"
-    task :create_search_indexes => [:environment, :load_models] do
+    desc 'Create search indexes specified in Mongoid models'
+    task create_search_indexes: %i[environment load_models] do
       wait = Mongoid::Utils.truthy_string?(ENV['WAIT_FOR_SEARCH_INDEXES'] || '1')
-      ::Mongoid::Tasks::Database.create_search_indexes(wait: wait)
+      Mongoid::Tasks::Database.create_search_indexes(wait: wait)
     end
 
-    desc "Remove indexes that exist in the database but are not specified in Mongoid models"
-    task :remove_undefined_indexes => [:environment, :load_models] do
-      ::Mongoid::Tasks::Database.remove_undefined_indexes
+    desc 'Remove indexes that exist in the database but are not specified in Mongoid models'
+    task remove_undefined_indexes: %i[environment load_models] do
+      Mongoid::Tasks::Database.remove_undefined_indexes
     end
 
-    desc "Remove indexes specified in Mongoid models"
-    task :remove_indexes => [:environment, :load_models] do
-      ::Mongoid::Tasks::Database.remove_indexes
+    desc 'Remove indexes specified in Mongoid models'
+    task remove_indexes: %i[environment load_models] do
+      Mongoid::Tasks::Database.remove_indexes
     end
 
-    desc "Remove search indexes specified in Mongoid models"
-    task :remove_search_indexes => [:environment, :load_models] do
-      ::Mongoid::Tasks::Database.remove_search_indexes
+    desc 'Remove search indexes specified in Mongoid models'
+    task remove_search_indexes: %i[environment load_models] do
+      Mongoid::Tasks::Database.remove_search_indexes
     end
 
-    desc "Shard collections with shard keys specified in Mongoid models"
-    task :shard_collections => [:environment, :load_models] do
-      ::Mongoid::Tasks::Database.shard_collections
+    desc 'Shard collections with shard keys specified in Mongoid models'
+    task shard_collections: %i[environment load_models] do
+      Mongoid::Tasks::Database.shard_collections
     end
 
-    desc "Drop the database of the default Mongoid client"
-    task :drop => :environment do
-      ::Mongoid::Clients.default.database.drop
+    desc 'Drop the database of the default Mongoid client'
+    task drop: :environment do
+      Mongoid::Clients.default.database.drop
     end
 
-    desc "Drop all non-system collections"
-    task :purge => :environment do
-      ::Mongoid.purge!
+    desc 'Drop all non-system collections'
+    task purge: :environment do
+      Mongoid.purge!
     end
 
     namespace :create_collections do
-      desc "Drop and create collections for Mongoid models"
-      task :force => [:environment, :load_models] do
-        ::Mongoid::Tasks::Database.create_collections(force: true)
+      desc 'Drop and create collections for Mongoid models'
+      task force: %i[environment load_models] do
+        Mongoid::Tasks::Database.create_collections(force: true)
       end
     end
   end