mongoid-multi-db 3.0.0

data/lib/mongoid/criterion/builder.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+
+    # This module defines criteria behavior for building documents for
+    # specified conditions.
+    module Builder
+
+      # Build a document given the selector and return it.
+      # Complex criteria, such as $in and $or operations will get ignored.
+      #
+      # @example build the document.
+      #   Person.where(:title => "Sir").build
+      #
+      # @example Build with selectors getting ignored.
+      #   Person.where(:age.gt => 5).build
+      #
+      # @return [ Document ] A non-persisted document.
+      #
+      # @since 2.0.0
+      def build(attrs = {})
+        klass.new(
+          selector.inject(attrs) do |hash, (key, value)|
+            hash.tap do |attrs|
+              unless key.to_s =~ /\$/ || value.is_a?(Hash)
+                attrs[key] = value
+              end
+            end
+          end
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/criterion/complex.rb

@@ -0,0 +1,84 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+
+    # Complex criterion are used when performing operations on symbols to get
+    # get a shorthand syntax for where clauses.
+    #
+    # @example Conversion of a simple to complex criterion.
+    #   { :field => { "$lt" => "value" } }
+    #   becomes:
+    #   { :field.lt => "value }
+    class Complex
+      attr_accessor :key, :operator
+
+      # Create the new complex criterion.
+      #
+      # @example Instantiate a new complex criterion.
+      #   Complex.new(:key => :field, :operator => "$gt")
+      #
+      # @param [ Hash ] opts The options to convert.
+      def initialize(opts = {})
+        @key, @operator = opts[:key], opts[:operator]
+      end
+
+      # Get the criterion as a hash.
+      #
+      # @example Get the criterion as a hash.
+      #   criterion.hash
+      #
+      # @return [ Hash ] The keys and operators.
+      def hash
+        [@key, @operator].hash
+      end
+
+      # Create a mongo query with given value
+      #
+      # @example Create query
+      #   criterion.to_mongo_hash(value)
+      #
+      # @params [] Whatever is a valid input for given operator
+      # @return [ Hash ] The query
+      def to_mongo_query(v)
+        {"$#{self.operator}" => v}
+      end
+
+      # Is the criterion equal to the other?
+      #
+      # @example Check equality.
+      #   criterion.eql?(other)
+      #
+      # @param [ Complex ] other The other complex criterion.
+      #
+      # @return [ true, false ] If they are equal.
+      def eql?(other)
+        self == (other)
+      end
+
+      # Is the criterion equal to the other?
+      #
+      # @example Check equality.
+      #   criterion == other
+      #
+      # @param [ Complex ] other The other complex criterion.
+      #
+      # @return [ true, false ] If they are equal.
+      def ==(other)
+        return false unless other.is_a?(self.class)
+        self.key == other.key && self.operator == other.operator
+      end
+
+      # Returns the name of the key as a string.
+      #
+      # @example Get the name of the key.
+      #   criterion.to_s
+      #
+      # @return [ String ] The field name.
+      #
+      # @since 2.1.0
+      def to_s
+        key.to_s
+      end
+    end
+  end
+end

data/lib/mongoid/criterion/creational.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+
+    # This module defines criteria behavior for creating documents in the
+    # database for specified conditions.
+    module Creational
+
+      # Create a document in the database given the selector and return it.
+      # Complex criteria, such as $in and $or operations will get ignored.
+      #
+      # @example Create the document.
+      #   Person.where(:title => "Sir").create
+      #
+      # @example Create with selectors getting ignored.
+      #   Person.where(:age.gt => 5).create
+      #
+      # @return [ Document ] A newly created document.
+      #
+      # @since 2.0.0.rc.1
+      def create(attrs = {})
+        klass.create(
+          selector.inject(attrs) do |hash, (key, value)|
+            hash.tap do |attrs|
+              unless key.to_s =~ /\$/ || value.is_a?(Hash)
+                attrs[key] = value
+              end
+            end
+          end
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/criterion/exclusion.rb

@@ -0,0 +1,108 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+
+    # This module contains criteria behaviour for exclusion of values.
+    module Exclusion
+
+      # Adds a criterion to the +Criteria+ that specifies values that are not
+      # allowed to match any document in the database. The MongoDB
+      # conditional operator that will be used is "$ne".
+      #
+      # @example Match documents without these values.
+      #   criteria.excludes(:field => "value1")
+      #   criteria.excludes(:field1 => "value1", :field2 => "value1")
+      #
+      # @param [ Hash ] attributes: A +Hash+ where the key is the field
+      #   name and the value is a value that must not be equal to the
+      #   corresponding field value in the database.
+      #
+      # @return [ Criteria ] A newly cloned copy.
+      def excludes(attributes = {})
+        mongo_id = attributes.delete(:id)
+        attributes = attributes.merge(:_id => mongo_id) if mongo_id
+        update_selector(attributes, "$ne")
+      end
+
+      # Used when wanting to set the fields options directly using a hash
+      # instead of going through only or without.
+      #
+      # @example Set the limited fields.
+      #   criteria.fields(:field => 1)
+      #
+      # @param [ Hash ] attributes The field options.
+      #
+      # @return [ Criteria ] A newly cloned copy.
+      #
+      # @since 2.0.2
+      def fields(attributes = nil)
+        clone.tap { |crit| crit.options[:fields] = attributes || {} }
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies values where none
+      # should match in order to return results. This is similar to an SQL
+      # "NOT IN" clause. The MongoDB conditional operator that will be
+      # used is "$nin".
+      #
+      # @example Match documents with values not in the provided.
+      #   criteria.not_in(:field => ["value1", "value2"])
+      #   criteria.not_in(:field1 => ["value1", "value2"], :field2 => ["value1"])
+      #
+      # @param [ Hash ] attributes A +Hash+ where the key is the field name
+      #   and the value is an +Array+ of values that none can match.
+      #
+      # @return [ Criteria ] A newly cloned copy.
+      def not_in(attributes)
+        update_selector(attributes, "$nin")
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies the fields that will
+      # get returned from the Document. Used mainly for list views that do not
+      # require all fields to be present. This is similar to SQL "SELECT" values.
+      #
+      # @example Limit the fields to only the specified.
+      #   criteria.only(:field1, :field2, :field3)
+      #
+      # @note #only and #without cannot be used together.
+      #
+      # @param [ Array<Symbol> ] args A list of field names to limit to.
+      #
+      # @return [ Criteria ] A newly cloned copy.
+      def only(*args)
+        clone.tap do |crit|
+          if args.any?
+            crit.options[:fields] = {:_type => 1}
+            crit.field_list = args.flatten
+            crit.field_list.each do |f|
+              crit.options[:fields][f] = 1
+            end
+          end
+        end
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies the fields that will
+      # not get returned by the document.
+      #
+      # @example Filter out specific fields.
+      #   criteria.without(:field2, :field2)
+      #
+      # @note #only and #without cannot be used together.
+      #
+      # @param [ Array<Symbol> args A list of fields to exclude.
+      #
+      # @return [ Criteria ] A newly cloned copy.
+      #
+      # @since 2.0.0
+      def without(*args)
+        clone.tap do |crit|
+          if args.any?
+            crit.options[:fields] = {}
+            args.flatten.each do |f|
+              crit.options[:fields][f] = 0
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/criterion/inclusion.rb

@@ -0,0 +1,305 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+    module Inclusion
+
+      # Adds a criterion to the +Criteria+ that specifies values that must all
+      # be matched in order to return results. Similar to an "in" clause but the
+      # underlying conditional logic is an "AND" and not an "OR". The MongoDB
+      # conditional operator that will be used is "$all".
+      #
+      # @example Adding the criterion.
+      #   criteria.all(:field => ["value1", "value2"])
+      #   criteria.all(:field1 => ["value1", "value2"], :field2 => ["value1"])
+      #
+      # @param [ Hash ] attributes Name/value pairs that all must match.
+      #
+      # @return [ Criteria ] A new criteria with the added selector.
+      def all(attributes = {})
+        update_selector(attributes, "$all")
+      end
+      alias :all_in :all
+
+      # Adds a criterion to the criteria that specifies multiple expressions
+      # that *all* must match. This uses MongoDB's $and operator under the
+      # covers.
+      #
+      # @example Match all provided expressions.
+      #   criteria.all_of(:name => value, :age.gt => 18)
+      #
+      # @param [ Array<Hash> ] Multiple hash expressions.
+      #
+      # @return [ Criteria ] The criteria object.
+      #
+      # @since 2.3.0
+      def all_of(*args)
+        clone.tap do |crit|
+          unless args.empty?
+            criterion = @selector["$and"] || []
+            converted = BSON::ObjectId.convert(klass, args.flatten)
+            expanded = converted.collect { |hash| hash.expand_complex_criteria }
+            crit.selector["$and"] = criterion.concat(expanded)
+          end
+        end
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies values where any can
+      # be matched in order to return results. This is similar to an SQL "IN"
+      # clause. The MongoDB conditional operator that will be used is "$in".
+      # Any previously matching "$in" arrays will be unioned with new
+      # arguments.
+      #
+      # @example Adding the criterion.
+      #   criteria.in(:field => ["value1"]).also_in(:field => ["value2"])
+      #
+      # @param [ Hash ] attributes Name/value pairs any can match.
+      #
+      # @return [ Criteria ] A new criteria with the added selector.
+      def also_in(attributes = {})
+        update_selector(attributes, "$in")
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies values that must
+      # be matched in order to return results. This is similar to a SQL "WHERE"
+      # clause. This is the actual selector that will be provided to MongoDB,
+      # similar to the Javascript object that is used when performing a find()
+      # in the MongoDB console.
+      #
+      # @example Adding the criterion.
+      #   criteria.and(:field1 => "value1", :field2 => 15)
+      #
+      # @param [ Hash ] selectior Name/value pairs that all must match.
+      #
+      # @return [ Criteria ] A new criteria with the added selector.
+      def and(selector = nil)
+        where(selector)
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies a set of expressions
+      # to match if any of them return true. This is a $or query in MongoDB and
+      # is similar to a SQL OR. This is named #any_of and aliased "or" for
+      # readability.
+      #
+      # @example Adding the criterion.
+      #   criteria.any_of({ :field1 => "value" }, { :field2 => "value2" })
+      #
+      # @param [ Array<Hash> ] args A list of name/value pairs any can match.
+      #
+      # @return [ Criteria ] A new criteria with the added selector.
+      def any_of(*args)
+        clone.tap do |crit|
+          criterion = @selector["$or"] || []
+          converted = BSON::ObjectId.convert(klass, args.flatten)
+          expanded = converted.collect { |hash| hash.expand_complex_criteria }
+          crit.selector["$or"] = criterion.concat(expanded)
+        end
+      end
+      alias :or :any_of
+
+      # Find the matchind document in the criteria, either based on id or
+      # conditions.
+      #
+      # @todo Durran: DRY up duplicated code in a few places.
+      #
+      # @example Find by an id.
+      #   criteria.find(BSON::ObjectId.new)
+      #
+      # @example Find by multiple ids.
+      #   criteria.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
+      #
+      # @example Conditionally find all matching documents.
+      #   criteria.find(:all, :conditions => { :title => "Sir" })
+      #
+      # @example Conditionally find the first document.
+      #   criteria.find(:first, :conditions => { :title => "Sir" })
+      #
+      # @example Conditionally find the last document.
+      #   criteria.find(:last, :conditions => { :title => "Sir" })
+      #
+      # @param [ Symbol, BSON::ObjectId, Array<BSON::ObjectId> ] arg The
+      #   argument to search with.
+      # @param [ Hash ] options The options to search with.
+      #
+      # @return [ Document, Criteria ] The matching document(s).
+      def find(*args)
+        type, crit = search(*args)
+        case type
+        when :first then crit.one
+        when :last then crit.last
+        when :ids then crit.execute_or_raise(args)
+        else
+          crit
+        end
+      end
+
+      # Execute the criteria or raise an error if no documents found.
+      #
+      # @example Execute or raise
+      #   criteria.execute_or_raise(id, criteria)
+      #
+      # @param [ Object ] args The arguments passed.
+      # @param [ Criteria ] criteria The criteria to execute.
+      #
+      # @raise [ Errors::DocumentNotFound ] If nothing returned.
+      #
+      # @return [ Document, Array<Document> ] The document(s).
+      #
+      # @since 2.0.0
+      def execute_or_raise(args)
+        (args[0].is_a?(Array) ? entries : from_map_or_db).tap do |result|
+          if Mongoid.raise_not_found_error && !args.flatten.blank?
+            raise Errors::DocumentNotFound.new(klass, args) if result._vacant?
+          end
+        end
+      end
+
+      # Get the document from the identity map, and if not found hit the
+      # database.
+      #
+      # @example Get the document from the map or criteria.
+      #   criteria.from_map_or_db(criteria)
+      #
+      # @param [ Criteria ] The cloned criteria.
+      #
+      # @return [ Document ] The found document.
+      #
+      # @since 2.2.1
+      def from_map_or_db
+        doc = IdentityMap.get(klass, extract_id)
+        doc && doc.matches?(selector) ? doc : first
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies values where any can
+      # be matched in order to return results. This is similar to an SQL "IN"
+      # clause. The MongoDB conditional operator that will be used is "$in".
+      #
+      # @example Adding the criterion.
+      #   criteria.in(:field => ["value1", "value2"])
+      #   criteria.in(:field1 => ["value1", "value2"], :field2 => ["value1"])
+      #
+      # @param [ Hash ] attributes Name/value pairs any can match.
+      #
+      # @return [ Criteria ] A new criteria with the added selector.
+      def in(attributes = {})
+        update_selector(attributes, "$in", :&)
+      end
+      alias :any_in :in
+
+      # Eager loads all the provided relations. Will load all the documents
+      # into the identity map who's ids match based on the extra query for the
+      # ids.
+      #
+      # @note This will only work if Mongoid's identity map is enabled. To do
+      #   so set identity_map_enabled: true in your mongoid.yml
+      #
+      # @note This will work for embedded relations that reference another
+      #   collection via belongs_to as well.
+      #
+      # @note Eager loading brings all the documents into memory, so there is a
+      #   sweet spot on the performance gains. Internal benchmarks show that
+      #   eager loading becomes slower around 100k documents, but this will
+      #   naturally depend on the specific application.
+      #
+      # @example Eager load the provided relations.
+      #   Person.includes(:posts, :game)
+      #
+      # @param [ Array<Symbol> ] relations The names of the relations to eager
+      #   load.
+      #
+      # @return [ Criteria ] The cloned criteria.
+      #
+      # @since 2.2.0
+      def includes(*relations)
+        relations.each do |name|
+          inclusions.push(klass.reflect_on_association(name))
+        end
+        clone
+      end
+
+      # Get a list of criteria that are to be executed for eager loading.
+      #
+      # @example Get the eager loading inclusions.
+      #   Person.includes(:game).inclusions
+      #
+      # @return [ Array<Metadata> ] The inclusions.
+      #
+      # @since 2.2.0
+      def inclusions
+        @inclusions ||= []
+      end
+
+      # Loads an array of ids only for the current criteria. Used by eager
+      # loading to determine the documents to load.
+      #
+      # @example Load the related ids.
+      #   criteria.load_ids("person_id")
+      #
+      # @param [ String ] key The id or foriegn key string.
+      #
+      # @return [ Array<String, BSON::ObjectId> ] The ids to load.
+      #
+      # @since 2.2.0
+      def load_ids(key)
+        driver.find(selector, { :fields => { key => 1 }}).map { |doc| doc[key] }
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies values to do
+      # geospacial searches by. The field must be indexed with the "2d" option.
+      #
+      # @example Adding the criterion.
+      #   criteria.near(:field1 => [30, -44])
+      #
+      # @param [ Hash ] attributes The fields with lat/long values.
+      #
+      # @return [ Criteria ] A new criteria with the added selector.
+      def near(attributes = {})
+        update_selector(attributes, "$near")
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies values that must
+      # be matched in order to return results. This is similar to a SQL "WHERE"
+      # clause. This is the actual selector that will be provided to MongoDB,
+      # similar to the Javascript object that is used when performing a find()
+      # in the MongoDB console.
+      #
+      # @example Adding the criterion.
+      #   criteria.where(:field1 => "value1", :field2 => 15)
+      #
+      # @param [ Hash ] selector Name/value pairs where all must match.
+      #
+      # @return [ Criteria ] A new criteria with the added selector.
+      def where(selector = nil)
+        clone.tap do |crit|
+          selector = case selector
+            when String then {"$where" => selector}
+            else
+              BSON::ObjectId.convert(klass, selector || {}, false).expand_complex_criteria
+          end
+
+          # @todo: Durran: 3.0.0: refactor the merging into separate strategies
+          # to clean this funkiness up.
+          selector.each_pair do |key, value|
+            if crit.selector.has_key?(key)
+              if key.mongoid_id?
+                if crit.selector.has_key?("$and")
+                  crit.selector["$and"] << { key => value }
+                else
+                  crit.selector["$and"] = [{ key => crit.selector.delete(key) }, { key => value }]
+                end
+              elsif crit.selector[key].respond_to?(:merge) && value.respond_to?(:merge)
+                crit.selector[key] =
+                  crit.selector[key].merge(value) do |key, old, new|
+                    key == '$in' ? old & new : new
+                  end
+              else
+                crit.selector[key] = value
+              end
+            else
+              crit.selector[key] = value
+            end
+          end
+        end
+      end
+    end
+  end
+end