mongo 1.1.5 → 1.3.0

data/lib/mongo/collection.rb

@@ -1,7 +1,7 @@
 # encoding: UTF-8
 
 # --
-# Copyright (C) 2008-2010 10gen Inc.
+# Copyright (C) 2008-2011 10gen Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -24,13 +24,13 @@ module Mongo
 
     # Initialize a collection object.
     #
-    # @param [DB] db a MongoDB database instance.
     # @param [String, Symbol] name the name of the collection.
+    # @param [DB] db a MongoDB database instance.
     #
-    # @option options [:create_pk] :pk (BSON::ObjectId) A primary key factory to use
+    # @option opts [:create_pk] :pk (BSON::ObjectId) A primary key factory to use
     #   other than the default BSON::ObjectId.
     #
-    # @option options [Boolean, Hash] :safe (false) Set the default safe-mode options
+    # @option opts [Boolean, Hash] :safe (false) Set the default safe-mode options
     #   for insert, update, and remove method called on this Collection instance. If no
     #   value is provided, the default value set on this instance's DB will be used. This
     #   default can be overridden for any invocation of insert, update, or remove.
@@ -44,7 +44,13 @@ module Mongo
     # @return [Collection]
     #
     # @core collections constructor_details
-    def initialize(db, name, options={})
+    def initialize(name, db, opts={})
+      if db.is_a?(String) && name.is_a?(Mongo::DB)
+        warn "Warning: the order of parameters to initialize a collection have changed. " +
+             "Please specify the collection name first, followed by the db."
+        db, name = name, db
+      end
+
       case name
       when Symbol, String
       else
@@ -63,23 +69,22 @@ module Mongo
         raise Mongo::InvalidNSName, "collection names must not start or end with '.'"
       end
 
-      if options.respond_to?(:create_pk) || !options.is_a?(Hash)
+      if opts.respond_to?(:create_pk) || !opts.is_a?(Hash)
         warn "The method for specifying a primary key factory on a Collection has changed.\n" +
           "Please specify it as an option (e.g., :pk => PkFactory)."
-        pk_factory = options
+        pk_factory = opts
       else
         pk_factory = nil
       end
 
       @db, @name  = db, name
       @connection = @db.connection
-      @logger     = @connection.logger
       @cache_time = @db.cache_time
       @cache = Hash.new(0)
       unless pk_factory
-        @safe       = options.has_key?(:safe) ? options[:safe] : @db.safe
+        @safe = opts.fetch(:safe, @db.safe)
       end
-      @pk_factory = pk_factory || options[:pk] || BSON::ObjectId
+      @pk_factory = pk_factory || opts[:pk] || BSON::ObjectId
       @hint = nil
     end
 
@@ -96,7 +101,7 @@ module Mongo
     #   the specified sub-collection
     def [](name)
       name = "#{self.name}.#{name}"
-      return Collection.new(db, name) if !db.strict? || db.collection_names.include?(name)
+      return Collection.new(name, db) if !db.strict? || db.collection_names.include?(name)
       raise "Collection #{name} doesn't exist. Currently in strict mode."
     end
 
@@ -134,7 +139,7 @@ module Mongo
     #   to Ruby 1.8).
     #
     # @option opts [Array, Hash] :fields field names that should be returned in the result
-    #   set ("_id" will always be included). By limiting results to a certain subset of fields,
+    #   set ("_id" will be included unless explicity excluded). By limiting results to a certain subset of fields,
     #   you can cut down on network traffic and decoding time. If using a Hash, keys should be field
     #   names and values should be either 1 or 0, depending on whether you want to include or exclude
     #   the given field.
@@ -152,6 +157,8 @@ module Mongo
     #   the normal cursor timeout behavior of the mongod process. When +false+, the returned cursor will never timeout. Note
     #   that disabling timeout will only work when #find is invoked with a block. This is to prevent any inadvertant failure to
     #   close the cursor, as the cursor is explicitly closed when block code finishes.
+    # @option opts [Block] :transformer (nil) a block for tranforming returned documents.
+    #   This is normally used by object mappers to convert each returned document to an instance of a class.
     #
     # @raise [ArgumentError]
     #   if timeout is set to false and find is not invoked in a block
@@ -170,6 +177,7 @@ module Mongo
       snapshot   = opts.delete(:snapshot)
       batch_size = opts.delete(:batch_size)
       timeout    = (opts.delete(:timeout) == false) ? false : true
+      transformer = opts.delete(:transformer)
 
       if timeout == false && !block_given?
         raise ArgumentError, "Collection#find must be invoked with a block when timeout is disabled."
@@ -183,8 +191,18 @@ module Mongo
 
       raise RuntimeError, "Unknown options [#{opts.inspect}]" unless opts.empty?
 
-      cursor = Cursor.new(self, :selector => selector, :fields => fields, :skip => skip, :limit => limit,
-        :order => sort, :hint => hint, :snapshot => snapshot, :timeout => timeout, :batch_size => batch_size)
+      cursor = Cursor.new(self, {
+        :selector    => selector, 
+        :fields      => fields, 
+        :skip        => skip, 
+        :limit       => limit,
+        :order       => sort, 
+        :hint        => hint, 
+        :snapshot    => snapshot, 
+        :timeout     => timeout, 
+        :batch_size  => batch_size,
+        :transformer => transformer,
+      })
 
       if block_given?
         yield cursor
@@ -271,10 +289,10 @@ module Mongo
     # @see DB#remove for options that can be passed to :safe.
     #
     # @core insert insert-instance_method
-    def insert(doc_or_docs, options={})
+    def insert(doc_or_docs, opts={})
       doc_or_docs = [doc_or_docs] unless doc_or_docs.is_a?(Array)
       doc_or_docs.collect! { |doc| @pk_factory.create_pk(doc) }
-      safe = options.has_key?(:safe) ? options[:safe] : @safe
+      safe = opts.fetch(:safe, @safe)
       result = insert_documents(doc_or_docs, @name, true, safe)
       result.size > 1 ? result : result.first
     end
@@ -310,18 +328,19 @@ module Mongo
     # @core remove remove-instance_method
     def remove(selector={}, opts={})
       # Initial byte is 0.
-      safe = opts.has_key?(:safe) ? opts[:safe] : @safe
+      safe = opts.fetch(:safe, @safe)
       message = BSON::ByteBuffer.new("\0\0\0\0")
       BSON::BSON_RUBY.serialize_cstr(message, "#{@db.name}.#{@name}")
       message.put_int(0)
       message.put_binary(BSON::BSON_CODER.serialize(selector, false, true).to_s)
 
-      @logger.debug("MONGODB #{@db.name}['#{@name}'].remove(#{selector.inspect})") if @logger
-      if safe
-        @connection.send_message_with_safe_check(Mongo::Constants::OP_DELETE, message, @db.name, nil, safe)
-      else
-        @connection.send_message(Mongo::Constants::OP_DELETE, message)
-        true
+      @connection.instrument(:remove, :database => @db.name, :collection => @name, :selector => selector) do
+        if safe
+          @connection.send_message_with_safe_check(Mongo::Constants::OP_DELETE, message, @db.name, nil, safe)
+        else
+          @connection.send_message(Mongo::Constants::OP_DELETE, message)
+          true
+        end
       end
     end
 
@@ -336,8 +355,8 @@ module Mongo
     #   a hash specifying the fields to be changed in the selected document,
     #   or (in the case of an upsert) the document to be inserted
     #
-    # @option [Boolean] :upsert (+false+) if true, performs an upsert (update or insert)
-    # @option [Boolean] :multi (+false+) update all documents matching the selector, as opposed to
+    # @option opts [Boolean] :upsert (+false+) if true, performs an upsert (update or insert)
+    # @option opts [Boolean] :multi (+false+) update all documents matching the selector, as opposed to
     #   just the first matching document. Note: only works in MongoDB 1.1.3 or later.
     # @option opts [Boolean] :safe (+false+) 
     #   If true, check that the save succeeded. OperationFailure
@@ -350,22 +369,24 @@ module Mongo
     #   Otherwise, returns true.
     #
     # @core update update-instance_method
-    def update(selector, document, options={})
+    def update(selector, document, opts={})
       # Initial byte is 0.
-      safe = options.has_key?(:safe) ? options[:safe] : @safe
+      safe = opts.fetch(:safe, @safe)
       message = BSON::ByteBuffer.new("\0\0\0\0")
       BSON::BSON_RUBY.serialize_cstr(message, "#{@db.name}.#{@name}")
       update_options  = 0
-      update_options += 1 if options[:upsert]
-      update_options += 2 if options[:multi]
+      update_options += 1 if opts[:upsert]
+      update_options += 2 if opts[:multi]
       message.put_int(update_options)
       message.put_binary(BSON::BSON_CODER.serialize(selector, false, true).to_s)
       message.put_binary(BSON::BSON_CODER.serialize(document, false, true).to_s)
-      @logger.debug("MONGODB #{@db.name}['#{@name}'].update(#{selector.inspect}, #{document.inspect})") if @logger
-      if safe
-        @connection.send_message_with_safe_check(Mongo::Constants::OP_UPDATE, message, @db.name, nil, safe)
-      else
-        @connection.send_message(Mongo::Constants::OP_UPDATE, message, nil)
+
+      @connection.instrument(:update, :database => @db.name, :collection => @name, :selector => selector, :document => document) do
+        if safe
+          @connection.send_message_with_safe_check(Mongo::Constants::OP_UPDATE, message, @db.name, nil, safe)
+        else
+          @connection.send_message(Mongo::Constants::OP_UPDATE, message, nil)
+        end
       end
     end
 
@@ -415,6 +436,7 @@ module Mongo
       opts[:dropDups] = opts.delete(:drop_dups) if opts[:drop_dups]
       field_spec = parse_index_spec(spec)
       name = opts.delete(:name) || generate_index_name(field_spec)
+      name = name.to_s if name
 
       generate_indexes(field_spec, name, opts)
       name
@@ -437,18 +459,15 @@ module Mongo
     #
     # @return [String] the name of the index.
     def ensure_index(spec, opts={})
-      valid = BSON::OrderedHash.new
       now = Time.now.utc.to_i
       field_spec = parse_index_spec(spec)
 
-      field_spec.each do |key, value|
-        cache_key = generate_index_name({key => value})
-        timeout = @cache[cache_key] || 0
-        valid[key] = value if timeout <= now
-      end
+      name = opts.delete(:name) || generate_index_name(field_spec)
+      name = name.to_s if name
 
-      name = opts.delete(:name) || generate_index_name(valid)
-      generate_indexes(valid, name, opts) if valid.any?
+      if !@cache[name] || @cache[name] <= now
+        generate_indexes(field_spec, name, opts)
+      end
 
       # Reset the cache here in case there are any errors inserting. Best to be safe.
       @cache[name] = now + @cache_time
@@ -461,7 +480,7 @@ module Mongo
     #
     # @core indexes
     def drop_index(name)
-      @cache[name] = nil
+      @cache[name.to_s] = nil
       @db.drop_index(@name, name)
     end
 
@@ -503,7 +522,7 @@ module Mongo
       @db.command(cmd)['value']
     end
 
-    # Perform a map/reduce operation on the current collection.
+    # Perform a map-reduce operation on the current collection.
     #
     # @param [String, BSON::Code] map a map function, written in JavaScript.
     # @param [String, BSON::Code] reduce a reduce function, written in JavaScript.
@@ -515,13 +534,20 @@ module Mongo
     # @option opts [Integer] :limit (nil) if passing a query, number of objects to return from the collection.
     # @option opts [String, BSON::Code] :finalize (nil) a javascript function to apply to the result set after the
     #   map/reduce operation has finished.
-    # @option opts [String] :out (nil) the name of the output collection. If specified, the collection will not be treated as temporary.
-    # @option opts [Boolean] :keeptemp (false) if true, the generated collection will be persisted. default is false.
+    # @option opts [String] :out (nil) a valid output type. In versions of MongoDB prior to v1.7.6,
+    #   this option takes the name of a collection for the output results. In versions 1.7.6 and later,
+    #   this option specifies the output type. See the core docs for available output types.
+    # @option opts [Boolean] :keeptemp (false) if true, the generated collection will be persisted. The defualt
+    #   is false. Note that this option has no effect is versions of MongoDB > v1.7.6.
     # @option opts [Boolean ] :verbose (false) if true, provides statistics on job execution time.
     # @option opts [Boolean] :raw (false) if true, return the raw result object from the map_reduce command, and not
-    #   the instantiated collection that's returned by default.
+    #   the instantiated collection that's returned by default. Note if a collection name isn't returned in the
+    #   map-reduce output (as, for example, when using :out => {:inline => 1}), then you must specify this option
+    #   or an ArgumentError will be raised.
     #
-    # @return [Collection] a collection containing the results of the operation.
+    # @return [Collection, Hash] a Mongo::Collection object or a Hash with the map-reduce command's results.
+    #
+    # @raise ArgumentError if you specify {:out => {:inline => true}} but don't specify :raw => true.
     #
     # @see http://www.mongodb.org/display/DOCS/MapReduce Offical MongoDB map/reduce documentation.
     #
@@ -544,25 +570,39 @@ module Mongo
 
       if raw
         result
-      else
+      elsif result["result"]
         @db[result["result"]]
+      else
+        raise ArgumentError, "Could not instantiate collection from result. If you specified " +
+          "{:out => {:inline => true}}, then you must also specify :raw => true to get the results."
       end
     end
     alias :mapreduce :map_reduce
 
     # Perform a group aggregation.
     #
-    # @param [Array, String, BSON::Code, Nil] :key either 1) an array of fields to group by,
-    #   2) a javascript function to generate the key object, or 3) nil.
-    # @param [Hash] condition an optional document specifying a query to limit the documents over which group is run.
-    # @param [Hash] initial initial value of the aggregation counter object
-    # @param [String, BSON::Code] reduce aggregation function, in JavaScript
-    # @param [String, BSON::Code] finalize :: optional. a JavaScript function that receives and modifies
-    #              each of the resultant grouped objects. Available only when group is run
-    #              with command set to true.
-    #
-    # @return [Array] the grouped items.
-    def group(key, condition, initial, reduce, finalize=nil)
+    # @param [Hash] opts the options for this group operation. The minimum required are :initial
+    #   and :reduce.
+    #
+    # @option opts [Array, String, Symbol] :key (nil) Either the name of a field or a list of fields to group by (optional).
+    # @option opts [String, BSON::Code] :keyf (nil) A JavaScript function to be used to generate the grouping keys (optional).
+    # @option opts [String, BSON::Code] :cond ({}) A document specifying a query for filtering the documents over
+    #   which the aggregation is run (optional).
+    # @option opts [Hash] :initial the initial value of the aggregation counter object (required).
+    # @option opts [String, BSON::Code] :reduce (nil) a JavaScript aggregation function (required).
+    # @option opts [String, BSON::Code] :finalize (nil) a JavaScript function that receives and modifies
+    #   each of the resultant grouped objects. Available only when group is run with command
+    #   set to true.
+    #
+    # @return [Array] the command response consisting of grouped items.
+    def group(opts, condition={}, initial={}, reduce=nil, finalize=nil)
+      if opts.is_a?(Hash)
+        return new_group(opts)
+      else
+        warn "Collection#group no longer take a list of parameters. This usage is deprecated." +
+             "Check out the new API at http://api.mongodb.org/ruby/current/Mongo/Collection.html#group-instance_method"
+      end
+
       reduce = BSON::Code.new(reduce) unless reduce.is_a?(BSON::Code)
 
       group_command = {
@@ -574,14 +614,19 @@ module Mongo
         }
       }
 
-      unless key.nil?
-        if key.is_a? Array
+      if opts.is_a?(Symbol)
+        raise MongoArgumentError, "Group takes either an array of fields to group by or a JavaScript function" +
+          "in the form of a String or BSON::Code."
+      end
+
+      unless opts.nil?
+        if opts.is_a? Array
           key_type = "key"
           key_value = {}
-          key.each { |k| key_value[k] = 1 }
+          opts.each { |k| key_value[k] = 1 }
         else
           key_type  = "$keyf"
-          key_value = key.is_a?(BSON::Code) ? key : BSON::Code.new(key)
+          key_value = opts.is_a?(BSON::Code) ? opts : BSON::Code.new(opts)
         end
 
         group_command["group"][key_type] = key_value
@@ -601,6 +646,48 @@ module Mongo
       end
     end
 
+    private
+
+    def new_group(opts={})
+      reduce   =  opts[:reduce]
+      finalize =  opts[:finalize]
+      cond     =  opts.fetch(:cond, {})
+      initial  =  opts[:initial]
+
+      if !(reduce && initial)
+        raise MongoArgumentError, "Group requires at minimum values for initial and reduce."
+      end
+
+      cmd = {
+        "group" => {
+          "ns"      => @name,
+          "$reduce" => reduce.to_bson_code,
+          "cond"    => cond,
+          "initial" => initial
+        }
+      }
+
+      if finalize
+        cmd['group']['finalize'] = finalize.to_bson_code
+      end
+
+      if key = opts[:key]
+        if key.is_a?(String) || key.is_a?(Symbol)
+          key = [key]
+        end
+        key_value = {}
+        key.each { |k| key_value[k] = 1 }
+        cmd["group"]["key"] = key_value
+      elsif keyf = opts[:keyf]
+        cmd["group"]["$keyf"] = keyf.to_bson_code
+      end
+
+      result = @db.command(cmd)
+      result["retval"]
+    end
+
+    public
+
     # Return a list of distinct values for +key+ across all
     # documents in the collection. The key may use dot notation
     # to reach into an embedded object.
@@ -776,11 +863,12 @@ module Mongo
       end
       raise InvalidOperation, "Exceded maximum insert size of 16,000,000 bytes" if message.size > 16_000_000
 
-      @logger.debug("MONGODB #{@db.name}['#{collection_name}'].insert(#{documents.inspect})") if @logger
-      if safe
-        @connection.send_message_with_safe_check(Mongo::Constants::OP_INSERT, message, @db.name, nil, safe)
-      else
-        @connection.send_message(Mongo::Constants::OP_INSERT, message, nil)
+      @connection.instrument(:insert, :database => @db.name, :collection => collection_name, :documents => documents) do
+        if safe
+          @connection.send_message_with_safe_check(Mongo::Constants::OP_INSERT, message, @db.name, nil, safe)
+        else
+          @connection.send_message(Mongo::Constants::OP_INSERT, message, nil)
+        end
       end
       documents.collect { |o| o[:_id] || o['_id'] }
     end