mongoid 9.0.12 → 9.1.0

data/lib/mongoid/fields.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
-require "mongoid/fields/standard"
-require "mongoid/fields/encrypted"
-require "mongoid/fields/foreign_key"
-require "mongoid/fields/localized"
-require "mongoid/fields/validators"
+require 'mongoid/fields/standard'
+require 'mongoid/fields/encrypted'
+require 'mongoid/fields/foreign_key'
+require 'mongoid/fields/localized'
+require 'mongoid/fields/validators'
 
 module Mongoid
-
   # This module defines behavior for fields.
   module Fields
     extend ActiveSupport::Concern
@@ -42,7 +40,7 @@ module Mongoid
     # This does not include aliases of _id field.
     #
     # @api private
-    IDS = [ :_id, '_id', ].freeze
+    IDS = [ :_id, '_id' ].freeze
 
     # BSON classes that are not supported as field types
     #
@@ -50,7 +48,7 @@ module Mongoid
     INVALID_BSON_CLASSES = [ BSON::Decimal128, BSON::Int32, BSON::Int64 ].freeze
 
     # The suffix for generated translated fields.
-    # 
+    #
     # @api private
     TRANSLATIONS_SFX = '_translations'
 
@@ -106,17 +104,17 @@ module Mongoid
           ar.each_with_index do |fn, i|
             key = fn
             unless klass.fields.key?(fn) || klass.relations.key?(fn)
-              if fn.end_with?(TRANSLATIONS_SFX)
-                key = fn.delete_suffix(TRANSLATIONS_SFX)
-              else
-                key = fn
-              end
+              key = if fn.end_with?(TRANSLATIONS_SFX)
+                      fn.delete_suffix(TRANSLATIONS_SFX)
+                    else
+                      fn
+                    end
 
             end
             res.push(key)
 
             if klass.fields.key?(fn)
-              res.push(ar.drop(i+1).join('.')) unless i == ar.length - 1
+              res.push(ar.drop(i + 1).join('.')) unless i == ar.length - 1
               break
             elsif klass.relations.key?(fn)
               klass = klass.relations[key].klass
@@ -133,7 +131,7 @@ module Mongoid
       class_attribute :pre_processed_defaults
       class_attribute :post_processed_defaults
 
-      self.aliased_fields = { "id" => "_id" }
+      self.aliased_fields = { 'id' => '_id' }
       self.fields = {}
       self.localized_fields = {}
       self.pre_processed_defaults = []
@@ -141,7 +139,7 @@ module Mongoid
 
       field(
         :_id,
-        default: ->{ BSON::ObjectId.new },
+        default: -> { BSON::ObjectId.new },
         pre_processed: true,
         type: BSON::ObjectId
       )
@@ -181,15 +179,14 @@ module Mongoid
     #
     # @param [ String ] name The name of the field.
     def apply_default(name)
-      unless attributes.key?(name)
-        if field = fields[name]
-          default = field.eval_default(self)
-          unless default.nil? || field.lazy?
-            attribute_will_change!(name)
-            attributes[name] = default
-          end
-        end
-      end
+      return if attributes.key?(name)
+      return unless field = fields[name]
+
+      default = field.eval_default(self)
+      return if default.nil? || field.lazy?
+
+      attribute_will_change!(name)
+      attributes[name] = default
     end
 
     # Apply all the defaults at once.
@@ -274,13 +271,12 @@ module Mongoid
     #
     # @param [ String ] name The field name.
     def validate_writable_field_name!(name)
-      if dot_dollar_field?(name)
-        raise Errors::InvalidDotDollarAssignment.new(self.class, name)
-      end
+      return unless dot_dollar_field?(name)
+
+      raise Errors::InvalidDotDollarAssignment.new(self.class, name)
     end
 
     class << self
-
       # Stores the provided block to be run when the option name specified is
       # defined on a field.
       #
@@ -324,7 +320,7 @@ module Mongoid
       # @param [ String ] key The key used to search the association tree.
       # @param [ Hash ] fields The fields to begin the search with.
       # @param [ Hash ] associations The associations to begin the search with.
-      # @param [ Hash ] aliased_associations The alaised associations to begin
+      # @param [ Hash ] aliased_associations The aliased associations to begin
       #   the search with.
       # @param &block The block.
       # @yieldparam [ Symbol ] The current method.
@@ -341,9 +337,9 @@ module Mongoid
         klass = nil
         field = nil
         key.split('.').each_with_index do |meth, i|
-          fs = i == 0 ? fields : klass&.fields
-          rs = i == 0 ? associations : klass&.relations
-          as = i == 0 ? aliased_associations : klass&.aliased_associations
+          fs = (i == 0) ? fields : klass&.fields
+          rs = (i == 0) ? associations : klass&.relations
+          as = (i == 0) ? aliased_associations : klass&.aliased_associations
 
           # Associations can possibly have two "keys", their name and their alias.
           # The fields name is what is used to store it in the klass's relations
@@ -364,8 +360,8 @@ module Mongoid
           elsif rs && rel = rs[aliased]
             klass = rel.klass
             yield(meth, rel, false) if block_given?
-          else
-            yield(meth, nil, false) if block_given?
+          elsif block_given?
+            yield(meth, nil, false)
           end
         end
         field
@@ -413,7 +409,7 @@ module Mongoid
       #
       # @api private
       def database_field_name(name, relations, aliased_fields, aliased_associations)
-        return "" unless name.present?
+        return '' unless name.present?
 
         key = name.to_s
         segment, remaining = key.split('.', 2)
@@ -441,7 +437,6 @@ module Mongoid
     end
 
     module ClassMethods
-
       # Returns an array of names for the attributes available on this object.
       #
       # Provides the field names in an ORM-agnostic way. Rails v3.1+ uses this
@@ -465,6 +460,105 @@ module Mongoid
         Fields.database_field_name(name, relations, aliased_fields, aliased_associations)
       end
 
+      # Declares a vector embedding field and registers a corresponding Atlas
+      # Vector Search index for it in one step.
+      #
+      # The field is stored as an Array. For advanced index options
+      # (quantization, indexing method, HNSW tuning) use the explicit
+      # +field+ + +vector_search_index+ combination instead.
+      #
+      # @example Minimal declaration.
+      #   class Article
+      #     include Mongoid::Document
+      #     vector_field :embedding, dimensions: 1536
+      #   end
+      #
+      # @example With all options.
+      #   class Article
+      #     include Mongoid::Document
+      #     vector_field :embedding, dimensions: 1536,
+      #                              similarity: 'dotProduct',
+      #                              index: :article_vectors
+      #   end
+      #
+      # @param [ Symbol | String ] name The name of the embedding field.
+      # @param [ Integer ] dimensions The number of vector dimensions. Required.
+      # @param [ String ] similarity The similarity metric to use: 'cosine'
+      #   (default), 'euclidean', or 'dotProduct'.
+      # @param [ Symbol | String | nil ] index The name for the vector search
+      #   index. If omitted the index is unnamed and Atlas calls it 'default'.
+      def vector_field(name, dimensions:, similarity: 'cosine', index: nil)
+        field(name, type: Array)
+
+        field_spec = {
+          type: 'vector',
+          path: name.to_s,
+          numDimensions: dimensions,
+          similarity: similarity
+        }
+
+        if index
+          vector_search_index(index, fields: [ field_spec ])
+        else
+          vector_search_index(fields: [ field_spec ])
+        end
+      end
+
+      # Declares a text field and registers a corresponding Atlas Vector Search
+      # index for it using the auto-embedding (autoEmbed) type. Atlas generates
+      # the embeddings automatically at index and query time; no pre-computed
+      # vectors are required.
+      #
+      # @example Minimal declaration.
+      #   class Article
+      #     include Mongoid::Document
+      #     auto_embed_field :description
+      #   end
+      #
+      # @example With all options.
+      #   class Article
+      #     include Mongoid::Document
+      #     auto_embed_field :description,
+      #                      model: 'voyage-4',
+      #                      num_dimensions: 512,
+      #                      quantization: 'binary',
+      #                      similarity: 'cosine',
+      #                      index: :article_embed
+      #   end
+      #
+      # @param [ Symbol | String ] name The name of the text field to declare
+      #   and auto-embed.
+      # @param [ String ] model The embedding model name. Defaults to 'voyage-4'
+      #   (recommended). Supported values at Public Preview: voyage-4-large,
+      #   voyage-4, voyage-4-lite, voyage-code-3.
+      # @param [ Integer | nil ] num_dimensions Number of vector dimensions.
+      #   Supported values: 256, 512, 1024, 2048. Default: 1024.
+      # @param [ String | nil ] quantization Quantization type: float, scalar,
+      #   binary, or binaryNoRescore. Default: scalar.
+      # @param [ String | nil ] similarity Similarity function: dotProduct,
+      #   cosine, or euclidean.
+      # @param [ Symbol | String | nil ] index The index name. If omitted the
+      #   index is unnamed and Atlas calls it 'default'.
+      def auto_embed_field(name, model: 'voyage-4', num_dimensions: nil, quantization: nil, similarity: nil, index: nil)
+        field(name, type: String)
+
+        field_spec = {
+          type: 'autoEmbed',
+          modality: 'text',
+          path: name.to_s,
+          model: model
+        }
+        field_spec[:numDimensions] = num_dimensions if num_dimensions
+        field_spec[:quantization]  = quantization  if quantization
+        field_spec[:similarity]    = similarity    if similarity
+
+        if index
+          vector_search_index(index, fields: [ field_spec ])
+        else
+          vector_search_index(fields: [ field_spec ])
+        end
+      end
+
       # Defines all the fields that are accessible on the Document
       # For each field that is defined, a getter and setter will be
       # added as an instance method to the Document.
@@ -512,7 +606,7 @@ module Mongoid
       #
       # @return [ true | false ] If the class uses BSON::ObjectIds for the id.
       def using_object_ids?
-        fields["_id"].object_id_field?
+        fields['_id'].object_id_field?
       end
 
       # Traverse down the association tree and search for the field for the
@@ -548,12 +642,12 @@ module Mongoid
       def add_defaults(field)
         default, name = field.default_val, field.name.to_s
         remove_defaults(name)
-        unless default.nil?
-          if field.pre_processed?
-            pre_processed_defaults.push(name)
-          else
-            post_processed_defaults.push(name)
-          end
+        return if default.nil?
+
+        if field.pre_processed?
+          pre_processed_defaults.push(name)
+        else
+          post_processed_defaults.push(name)
         end
       end
 
@@ -599,9 +693,7 @@ module Mongoid
         field_options = field.options
 
         Fields.options.each_pair do |option_name, handler|
-          if field_options.key?(option_name)
-            handler.call(self, field, field_options[option_name])
-          end
+          handler.call(self, field, field_options[option_name]) if field_options.key?(option_name)
         end
       end
 
@@ -627,11 +719,11 @@ module Mongoid
         create_field_setter(name, meth, field)
         create_field_check(name, meth)
 
-        if options[:localize]
-          create_translations_getter(name, meth)
-          create_translations_setter(name, meth, field)
-          localized_fields[name] = field
-        end
+        return unless options[:localize]
+
+        create_translations_getter(name, meth)
+        create_translations_setter(name, meth, field)
+        localized_fields[name] = field
       end
 
       # Create the getter method for the provided field.
@@ -694,9 +786,7 @@ module Mongoid
         generated_methods.module_eval do
           re_define_method("#{meth}=") do |value|
             val = write_attribute(name, value)
-            if field.foreign_key?
-              remove_ivar(field.association.name)
-            end
+            remove_ivar(field.association.name) if field.foreign_key?
             val
           end
         end
@@ -774,6 +864,7 @@ module Mongoid
         @generated_methods ||= begin
           mod = Module.new
           include(mod)
+
           mod
         end
       end
@@ -805,6 +896,7 @@ module Mongoid
         return Fields::Localized.new(name, opts) if options[:localize]
         return Fields::ForeignKey.new(name, opts) if options[:identity]
         return Fields::Encrypted.new(name, opts) if options[:encrypt]
+
         Fields::Standard.new(name, opts)
       end
 
@@ -821,7 +913,7 @@ module Mongoid
       # @api private
       def retrieve_and_validate_type(name, type)
         result = TYPE_MAPPINGS[type] || unmapped_type(type)
-        raise Errors::InvalidFieldType.new(self, name, type) if !result.is_a?(Class)
+        raise Errors::InvalidFieldType.new(self, name, type) unless result.is_a?(Class)
 
         if unsupported_type?(result)
           warn_message = "Using #{result} as the field type is not supported. "
@@ -845,7 +937,7 @@ module Mongoid
       #
       # @api private
       def unmapped_type(type)
-        if "Boolean" == type.to_s
+        if 'Boolean' == type.to_s
           Mongoid::Boolean
         else
           type || Object
@@ -862,6 +954,7 @@ module Mongoid
       # @api private
       def unsupported_type?(type)
         return !Mongoid::Config.allow_bson5_decimal128? if type == BSON::Decimal128
+
         INVALID_BSON_CLASSES.include?(type)
       end
     end

data/lib/mongoid/findable.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
-
   # This module defines the finder methods that hang off the document at the
   # class level.
   module Findable
@@ -16,52 +14,53 @@ module Mongoid
     # These are methods defined on the criteria that should also be accessible
     # directly from the class level.
     def_delegators :with_default_scope,
-      :aggregates,
-      :avg,
-      :create_with,
-      :distinct,
-      :each,
-      :each_with_index,
-      :extras,
-      :fifth,
-      :fifth!,
-      :find_one_and_delete,
-      :find_one_and_replace,
-      :find_one_and_update,
-      :find_or_create_by,
-      :find_or_create_by!,
-      :find_or_initialize_by,
-      :first!,
-      :first_or_create,
-      :first_or_create!,
-      :first_or_initialize,
-      :for_js,
-      :fourth,
-      :fourth!,
-      :includes,
-      :last!,
-      :map_reduce,
-      :max,
-      :min,
-      :none,
-      :pick,
-      :pluck,
-      :read,
-      :second,
-      :second!,
-      :second_to_last,
-      :second_to_last!,
-      :sum,
-      :take,
-      :take!,
-      :tally,
-      :text_search,
-      :third,
-      :third!,
-      :third_to_last,
-      :third_to_last!,
-      :update,
-      :update_all,
+                   :aggregates,
+                   :avg,
+                   :create_with,
+                   :distinct,
+                   :each,
+                   :each_with_index,
+                   :eager_load,
+                   :extras,
+                   :fifth,
+                   :fifth!,
+                   :find_one_and_delete,
+                   :find_one_and_replace,
+                   :find_one_and_update,
+                   :find_or_create_by,
+                   :find_or_create_by!,
+                   :find_or_initialize_by,
+                   :first!,
+                   :first_or_create,
+                   :first_or_create!,
+                   :first_or_initialize,
+                   :for_js,
+                   :fourth,
+                   :fourth!,
+                   :includes,
+                   :last!,
+                   :map_reduce,
+                   :max,
+                   :min,
+                   :none,
+                   :pick,
+                   :pluck,
+                   :raw,
+                   :read,
+                   :second,
+                   :second!,
+                   :second_to_last,
+                   :second_to_last!,
+                   :sum,
+                   :take,
+                   :take!,
+                   :tally,
+                   :third,
+                   :third!,
+                   :third_to_last,
+                   :third_to_last!,
+                   :update,
+                   :update_all
 
     # Returns a count of records in the database.
     # If you want to specify conditions use where.
@@ -116,6 +115,36 @@ module Mongoid
       with_default_scope.exists?(id_or_conditions)
     end
 
+    # Return true if any documents exist in the criteria.
+    #
+    # @example Determine if any documents exist
+    #   Model.any?
+    #
+    # @return [ true | false ] If any documents exist.
+    def any?
+      limit(1).count > 0
+    end
+
+    # Return true if only one document exists in the criteria.
+    #
+    # @example Determine if only one document exists
+    #   Model.one?
+    #
+    # @return [ true | false ] If only one document exists.
+    def one?
+      limit(2).count == 1
+    end
+
+    # Return true if more than one document exists in the criteria.
+    #
+    # @example Determine if many documents exist
+    #   Model.many?
+    #
+    # @return [ true | false ] If many documents exist.
+    def many?
+      limit(2).count > 1
+    end
+
     # Finds a +Document+ or multiple documents by their _id values.
     #
     # If a single non-Array argument is given, this argument is interpreted
@@ -147,7 +176,7 @@ module Mongoid
     # during query construction.
     #
     # If this method is given a block, it delegates to +Enumerable#find+ and
-    # returns the first document of those found by the current Crieria object
+    # returns the first document of those found by the current Criteria object
     # for which the block returns a truthy value. If both a block and ids are
     # given, the block is ignored and the documents for the given ids are
     # returned. If a block and a Proc are given, the method delegates to
@@ -190,9 +219,8 @@ module Mongoid
     # @return [ Document | nil ] A matching document.
     def find_by(attrs = {})
       result = where(attrs).find_first
-      if result.nil? && Mongoid.raise_not_found_error
-        raise(Errors::DocumentNotFound.new(self, attrs))
-      end
+      raise(Errors::DocumentNotFound.new(self, attrs)) if result.nil? && Mongoid.raise_not_found_error
+
       yield(result) if result && block_given?
       result
     end
@@ -211,6 +239,7 @@ module Mongoid
     def find_by!(attrs = {})
       result = where(attrs).find_first
       raise(Errors::DocumentNotFound.new(self, attrs)) unless result
+
       yield(result) if result && block_given?
       result
     end
@@ -226,7 +255,7 @@ module Mongoid
     def first(limit = nil)
       with_default_scope.first(limit)
     end
-    alias :one :first
+    alias one first
 
     # Find the last +Document+ given the conditions.
     #

data/lib/mongoid/indexable/specification.rb

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
   module Indexable
-
     # Encapsulates behavior around an index specification.
     class Specification
-
       # The mappings of nice Ruby-style names to the corresponding driver
       # option name.
       MAPPINGS = {
@@ -30,7 +27,25 @@ module Mongoid
       #
       # @return [ true | false ] If the specs are equal.
       def ==(other)
-        fields == other.fields && key == other.key
+        superficial_match?(key: other.key)
+      end
+
+      # Performs a superficial comparison with the given criteria, checking
+      # only the key and (optionally) the name. Options are not compared.
+      #
+      # Note that the ordering of the fields in the key is significant. Two
+      # keys with different orderings will not match, here.
+      #
+      # @param [ Hash ] key the key that defines the index.
+      # @param [ String | nil ] name the name given to the index, or nil to
+      #    ignore the name.
+      #
+      # @return [ true | false ] the result of the comparison, true if this
+      #   specification matches the criteria, and false otherwise.
+      def superficial_match?(key: {}, name: nil)
+        (name && name == self.name) ||
+          (fields == key.keys &&
+            self.key == key)
       end
 
       # Instantiate a new index specification.
@@ -57,7 +72,7 @@ module Mongoid
       #
       # @return [ String ] name The index name.
       def name
-        @name ||= key.reduce([]) do |n, (k,v)|
+        @name ||= key.reduce([]) do |n, (k, v)|
           n << "#{k}_#{v}"
         end.join('_')
       end
@@ -94,7 +109,6 @@ module Mongoid
       #
       # @return [ Hash ] The normalized options.
       def normalize_options!(options)
-
         options.transform_keys! do |option|
           option = option.to_sym
           MAPPINGS[option] || option