mongo 1.3.0 → 1.12.5

data/lib/mongo/collection.rb

@@ -1,13 +1,10 @@
-# encoding: UTF-8
-
-# --
-# Copyright (C) 2008-2011 10gen Inc.
+# Copyright (C) 2009-2013 MongoDB, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
-#     http://www.apache.org/licenses/LICENSE-2.0
+#   http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
@@ -19,21 +16,52 @@ module Mongo
 
   # A named collection of documents in a database.
   class Collection
-
-    attr_reader :db, :name, :pk_factory, :hint, :safe
+    include Mongo::Logging
+    include Mongo::WriteConcern
+
+    attr_reader :db,
+                :name,
+                :pk_factory,
+                :hint,
+                :write_concern,
+                :capped,
+                :operation_writer,
+                :command_writer
+
+    # Read Preference
+    attr_accessor :read,
+                  :tag_sets,
+                  :acceptable_latency
 
     # Initialize a collection object.
     #
     # @param [String, Symbol] name the name of the collection.
     # @param [DB] db a MongoDB database instance.
     #
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged.
+    # @option opts [Integer] :wtimeout (nil) Set replica set acknowledgement timeout.
+    # @option opts [Boolean] :j (false) If true, block until write operations have been committed
+    #   to the journal. Cannot be used in combination with 'fsync'. Prior to MongoDB 2.6 this option was
+    #   ignored if the server was running without journaling. Starting with MongoDB 2.6, write operations will
+    #   fail with an exception if this option is used when the server is running without journaling.
+    # @option opts [Boolean] :fsync (false) If true, and the server is running without journaling, blocks until
+    #   the server has synced all data files to disk. If the server is running with journaling, this acts the same as
+    #   the 'j' option, blocking until write operations have been committed to the journal.
+    #   Cannot be used in combination with 'j'.
+    #
+    #   Notes about write concern:
+    #     These write concern options will be used for insert, update, and remove methods called on this
+    #     Collection instance. If no value is provided, the default values set on this instance's DB will be used.
+    #     These option values can be overridden for any invocation of insert, update, or remove.
+    #
     # @option opts [:create_pk] :pk (BSON::ObjectId) A primary key factory to use
     #   other than the default BSON::ObjectId.
-    #
-    # @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.
+    # @option opts [:primary, :secondary] :read The default read preference for queries
+    #   initiates from this connection object. If +:secondary+ is chosen, reads will be sent
+    #   to one of the closest available secondary nodes. If a secondary node cannot be located, the
+    #   read will be sent to the primary. If this option is left unspecified, the value of the read
+    #   preference for this collection's associated Mongo::DB object will be used.
     #
     # @raise [InvalidNSName]
     #   if collection name is empty, contains '$', or starts or ends with '.'
@@ -42,56 +70,69 @@ module Mongo
     #   if collection name is not a string or symbol
     #
     # @return [Collection]
-    #
-    # @core collections constructor_details
     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."
+             "Please specify the collection name first, followed by the db. This will be made permanent" +
+             "in v2.0."
         db, name = name, db
       end
 
-      case name
-      when Symbol, String
-      else
-        raise TypeError, "new_name must be a string or symbol"
-      end
-
+      raise TypeError,
+        "Collection name must be a String or Symbol." unless [String, Symbol].include?(name.class)
       name = name.to_s
 
-      if name.empty? or name.include? ".."
-        raise Mongo::InvalidNSName, "collection names cannot be empty"
-      end
-      if name.include? "$"
-        raise Mongo::InvalidNSName, "collection names must not contain '$'" unless name =~ /((^\$cmd)|(oplog\.\$main))/
-      end
-      if name.match(/^\./) or name.match(/\.$/)
-        raise Mongo::InvalidNSName, "collection names must not start or end with '.'"
+      raise Mongo::InvalidNSName,
+        "Collection names cannot be empty." if name.empty? || name.include?("..")
+
+      if name.include?("$")
+        raise Mongo::InvalidNSName,
+          "Collection names must not contain '$'" unless name =~ /((^\$cmd)|(oplog\.\$main))/
       end
 
+      raise Mongo::InvalidNSName,
+        "Collection names must not start or end with '.'" if name.match(/^\./) || name.match(/\.$/)
+
+      pk_factory = nil
       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)."
+             "Please specify it as an option (e.g., :pk => PkFactory)."
         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)
+      @cache      = Hash.new(0)
       unless pk_factory
-        @safe = opts.fetch(:safe, @db.safe)
+        @write_concern = get_write_concern(opts, db)
+        @read =  opts[:read] || @db.read
+        Mongo::ReadPreference::validate(@read)
+        @capped             = opts[:capped]
+        @tag_sets           = opts.fetch(:tag_sets, @db.tag_sets)
+        @acceptable_latency = opts.fetch(:acceptable_latency, @db.acceptable_latency)
       end
       @pk_factory = pk_factory || opts[:pk] || BSON::ObjectId
       @hint = nil
+      @operation_writer = CollectionOperationWriter.new(self)
+      @command_writer = CollectionCommandWriter.new(self)
+    end
+
+    # Indicate whether this is a capped collection.
+    #
+    # @raise [Mongo::OperationFailure]
+    #   if the collection doesn't exist.
+    #
+    # @return [Boolean]
+    def capped?
+      @capped ||= [1, true].include?(@db.command({:collstats => @name})['capped'])
     end
 
     # Return a sub-collection of this collection by name. If 'users' is a collection, then
     # 'users.comments' is a sub-collection of users.
     #
-    # @param [String] name
+    # @param [String, Symbol] name
     #   the collection to return
     #
     # @raise [Mongo::InvalidNSName]
@@ -101,7 +142,8 @@ module Mongo
     #   the specified sub-collection
     def [](name)
       name = "#{self.name}.#{name}"
-      return Collection.new(name, db) if !db.strict? || db.collection_names.include?(name)
+      return Collection.new(name, db) if !db.strict? ||
+        db.collection_names.include?(name.to_s)
       raise "Collection #{name} doesn't exist. Currently in strict mode."
     end
 
@@ -116,6 +158,13 @@ module Mongo
       self
     end
 
+    # Set a hint field using a named index.
+    # @param [String] hint index name
+    def named_hint=(hint=nil)
+      @hint = hint
+      self
+    end
+
     # Query the database.
     #
     # The +selector+ argument is a prototype document that all results must
@@ -139,45 +188,70 @@ module Mongo
     #   to Ruby 1.8).
     #
     # @option opts [Array, Hash] :fields field names that should be returned in the result
-    #   set ("_id" will be included unless explicity excluded). By limiting results to a certain subset of fields,
+    #   set ("_id" will be included unless explicitly 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.
+    # @option opts [:primary, :secondary] :read The default read preference for queries
+    #   initiates from this connection object. If +:secondary+ is chosen, reads will be sent
+    #   to one of the closest available secondary nodes. If a secondary node cannot be located, the
+    #   read will be sent to the primary. If this option is left unspecified, the value of the read
+    #   preference for this Collection object will be used.
     # @option opts [Integer] :skip number of documents to skip from the beginning of the result set
     # @option opts [Integer] :limit maximum number of documents to return
     # @option opts [Array]   :sort an array of [key, direction] pairs to sort by. Direction should
     #   be specified as Mongo::ASCENDING (or :ascending / :asc) or Mongo::DESCENDING (or :descending / :desc)
-    # @option opts [String, Array, OrderedHash] :hint hint for query optimizer, usually not necessary if using MongoDB > 1.1
+    # @option opts [String, Array, OrderedHash] :hint hint for query optimizer, usually not necessary if
+    #   using MongoDB > 1.1
+    # @option opts [String] :named_hint for specifying a named index as a hint, will be overriden by :hint
+    #   if :hint is also provided.
     # @option opts [Boolean] :snapshot (false) if true, snapshot mode will be used for this query.
     #   Snapshot mode assures no duplicates are returned, or objects missed, which were preset at both the start and
-    #   end of the query's execution. For details see http://www.mongodb.org/display/DOCS/How+to+do+Snapshotting+in+the+Mongo+Database
-    # @option opts [Boolean] :batch_size (100) the number of documents to returned by the database per GETMORE operation. A value of 0
-    #   will let the database server decide how many results to returns. This option can be ignored for most use cases.
+    #   end of the query's execution.
+    #   For details see http://www.mongodb.org/display/DOCS/How+to+do+Snapshotting+in+the+Mongo+Database
+    # @option opts [Boolean] :batch_size (100) the number of documents to returned by the database per
+    #   GETMORE operation. A value of 0 will let the database server decide how many results to return.
+    #   This option can be ignored for most use cases.
     # @option opts [Boolean] :timeout (true) when +true+, the returned cursor will be subject to
-    #   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.
+    #   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 inadvertent failure to close the cursor, as the cursor is explicitly
+    #   closed when block code finishes.
+    # @option opts [Integer] :max_scan (nil) Limit the number of items to scan on both collection scans and indexed queries..
+    # @option opts [Boolean] :show_disk_loc (false) Return the disk location of each query result (for debugging).
+    # @option opts [Boolean] :return_key (false) Return the index key used to obtain the result (for debugging).
+    # @option opts [Block] :transformer (nil) a block for transforming returned documents.
     #   This is normally used by object mappers to convert each returned document to an instance of a class.
+    # @option opts [String] :comment (nil) a comment to include in profiling logs
+    # @option opts [Boolean] :compile_regex (true) whether BSON regex objects should be compiled into Ruby regexes.
+    #   If false, a BSON::Regex object will be returned instead.
     #
     # @raise [ArgumentError]
     #   if timeout is set to false and find is not invoked in a block
     #
     # @raise [RuntimeError]
     #   if given unknown options
-    #
-    # @core find find-instance_method
     def find(selector={}, opts={})
-      fields = opts.delete(:fields)
-      fields = ["_id"] if fields && fields.empty?
-      skip   = opts.delete(:skip) || skip || 0
-      limit  = opts.delete(:limit) || 0
-      sort   = opts.delete(:sort)
-      hint   = opts.delete(:hint)
-      snapshot   = opts.delete(:snapshot)
-      batch_size = opts.delete(:batch_size)
-      timeout    = (opts.delete(:timeout) == false) ? false : true
-      transformer = opts.delete(:transformer)
+      opts               = opts.dup
+      fields             = opts.delete(:fields)
+      fields             = ["_id"] if fields && fields.empty?
+      skip               = opts.delete(:skip) || skip || 0
+      limit              = opts.delete(:limit) || 0
+      sort               = opts.delete(:sort)
+      hint               = opts.delete(:hint)
+      named_hint         = opts.delete(:named_hint)
+      snapshot           = opts.delete(:snapshot)
+      batch_size         = opts.delete(:batch_size)
+      timeout            = (opts.delete(:timeout) == false) ? false : true
+      max_scan           = opts.delete(:max_scan)
+      return_key         = opts.delete(:return_key)
+      transformer        = opts.delete(:transformer)
+      show_disk_loc      = opts.delete(:show_disk_loc)
+      comment            = opts.delete(:comment)
+      read               = opts.delete(:read) || @read
+      tag_sets           = opts.delete(:tag_sets) || @tag_sets
+      acceptable_latency = opts.delete(:acceptable_latency) || @acceptable_latency
+      compile_regex      = opts.key?(:compile_regex) ? opts.delete(:compile_regex) : true
 
       if timeout == false && !block_given?
         raise ArgumentError, "Collection#find must be invoked with a block when timeout is disabled."
@@ -192,21 +266,32 @@ 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,
-        :transformer => transformer,
+        :selector           => selector,
+        :fields             => fields,
+        :skip               => skip,
+        :limit              => limit,
+        :order              => sort,
+        :hint               => hint || named_hint,
+        :snapshot           => snapshot,
+        :timeout            => timeout,
+        :batch_size         => batch_size,
+        :transformer        => transformer,
+        :max_scan           => max_scan,
+        :show_disk_loc      => show_disk_loc,
+        :return_key         => return_key,
+        :read               => read,
+        :tag_sets           => tag_sets,
+        :comment            => comment,
+        :acceptable_latency => acceptable_latency,
+        :compile_regex      => compile_regex
       })
 
       if block_given?
-        yield cursor
-        cursor.close
+        begin
+          yield cursor
+        ensure
+          cursor.close
+        end
         nil
       else
         cursor
@@ -218,8 +303,8 @@ module Mongo
     # @return [OrderedHash, Nil]
     #   a single document or nil if no result is found.
     #
-    # @param [Hash, ObjectId, Nil] spec_or_object_id a hash specifying elements 
-    #   which must be present for a document to be included in the result set or an 
+    # @param [Hash, ObjectId, Nil] spec_or_object_id a hash specifying elements
+    #   which must be present for a document to be included in the result set or an
     #   instance of ObjectId to be used as the value for an _id query.
     #   If nil, an empty selector, {}, will be used.
     #
@@ -239,7 +324,9 @@ module Mongo
              else
                raise TypeError, "spec_or_object_id must be an instance of ObjectId or Hash, or nil"
              end
-      find(spec, opts.merge(:limit => -1)).next_document
+      timeout = opts.delete(:max_time_ms)
+      cursor = find(spec, opts.merge(:limit => -1))
+      timeout ? cursor.max_time_ms(timeout).next_document : cursor.next_document
     end
 
     # Save a document to this collection.
@@ -251,22 +338,30 @@ module Mongo
     #
     # @return [ObjectId] the _id of the saved document.
     #
-    # @option opts [Boolean, Hash] :safe (+false+)
-    #   run the operation in safe mode, which run a getlasterror command on the
-    #   database to report any assertion. In addition, a hash can be provided to
-    #   run an fsync and/or wait for replication of the save (>= 1.5.1). See the options
-    #   for DB#error.
-    #
-    # @raise [OperationFailure] when :safe mode fails.
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged.
+    # @option opts [Integer] :wtimeout (nil) Set replica set acknowledgement timeout.
+    # @option opts [Boolean] :j (false) If true, block until write operations have been committed
+    #   to the journal. Cannot be used in combination with 'fsync'. Prior to MongoDB 2.6 this option was
+    #   ignored if the server was running without journaling. Starting with MongoDB 2.6, write operations will
+    #   fail with an exception if this option is used when the server is running without journaling.
+    # @option opts [Boolean] :fsync (false) If true, and the server is running without journaling, blocks until
+    #   the server has synced all data files to disk. If the server is running with journaling, this acts the same as
+    #   the 'j' option, blocking until write operations have been committed to the journal.
+    #   Cannot be used in combination with 'j'.
+    #
+    #   Options provided here will override any write concern options set on this collection,
+    #   its database object, or the current connection. See the options
+    #   for DB#get_last_error.
     #
-    # @see DB#remove for options that can be passed to :safe.
+    # @raise [Mongo::OperationFailure] will be raised iff :w > 0 and the operation fails.
     def save(doc, opts={})
       if doc.has_key?(:_id) || doc.has_key?('_id')
         id = doc[:_id] || doc['_id']
-        update({:_id => id}, doc, :upsert => true, :safe => opts.fetch(:safe, @safe))
+        update({:_id => id}, doc, opts.merge!({:upsert => true}))
         id
       else
-        insert(doc, :safe => opts.fetch(:safe, @safe))
+        insert(doc, opts)
       end
     end
 
@@ -277,24 +372,53 @@ module Mongo
     #
     # @return [ObjectId, Array]
     #   The _id of the inserted document or a list of _ids of all inserted documents.
-    #
-    # @option opts [Boolean, Hash] :safe (+false+)
-    #   run the operation in safe mode, which run a getlasterror command on the
-    #   database to report any assertion. In addition, a hash can be provided to
-    #   run an fsync and/or wait for replication of the insert (>= 1.5.1). Safe
-    #   options provided here will override any safe options set on this collection,
-    #   its database object, or the current connection. See the options on
-    #   for DB#get_last_error.
-    #
-    # @see DB#remove for options that can be passed to :safe.
-    #
-    # @core insert insert-instance_method
+    # @return [[ObjectId, Array], [Hash, Array]]
+    #   1st, the _id of the inserted document or a list of _ids of all inserted documents.
+    #   2nd, a list of invalid documents.
+    #   Return this result format only when :collect_on_error is true.
+    #
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged.
+    # @option opts [Integer] :wtimeout (nil) Set replica set acknowledgement timeout.
+    # @option opts [Boolean] :j (false) If true, block until write operations have been committed
+    #   to the journal. Cannot be used in combination with 'fsync'. Prior to MongoDB 2.6 this option was
+    #   ignored if the server was running without journaling. Starting with MongoDB 2.6, write operations will
+    #   fail with an exception if this option is used when the server is running without journaling.
+    # @option opts [Boolean] :fsync (false) If true, and the server is running without journaling, blocks until
+    #   the server has synced all data files to disk. If the server is running with journaling, this acts the same as
+    #   the 'j' option, blocking until write operations have been committed to the journal.
+    #   Cannot be used in combination with 'j'.
+    #
+    #   Notes on write concern:
+    #     Options provided here will override any write concern options set on this collection,
+    #     its database object, or the current connection. See the options for +DB#get_last_error+.
+    #
+    # @option opts [Boolean] :continue_on_error (+false+) If true, then
+    #   continue a bulk insert even if one of the documents inserted
+    #   triggers a database assertion (as in a duplicate insert, for instance).
+    #   If not acknowledging writes, the list of ids returned will
+    #   include the object ids of all documents attempted on insert, even
+    #   if some are rejected on error. When acknowledging writes, any error will raise an
+    #   OperationFailure exception.
+    #   MongoDB v2.0+.
+    # @option opts [Boolean] :collect_on_error (+false+) if true, then
+    #   collects invalid documents as an array. Note that this option changes the result format.
+    #
+    # @raise [Mongo::OperationFailure] will be raised iff :w > 0 and the operation fails.
     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 = opts.fetch(:safe, @safe)
-      result = insert_documents(doc_or_docs, @name, true, safe)
-      result.size > 1 ? result : result.first
+      if doc_or_docs.respond_to?(:collect!)
+        doc_or_docs.collect! { |doc| @pk_factory.create_pk(doc) }
+        error_docs, errors, write_concern_errors, rest_ignored = batch_write(:insert, doc_or_docs, true, opts)
+        errors = write_concern_errors + errors
+        raise errors.last if !opts[:collect_on_error] && !errors.empty?
+        inserted_docs = doc_or_docs - error_docs
+        inserted_ids = inserted_docs.collect {|o| o[:_id] || o['_id']}
+        opts[:collect_on_error] ? [inserted_ids, error_docs] : inserted_ids
+      else
+        @pk_factory.create_pk(doc_or_docs)
+        send_write(:insert, nil, doc_or_docs, true, opts)
+        return doc_or_docs[:_id] || doc_or_docs['_id']
+      end
     end
     alias_method :<<, :insert
 
@@ -303,12 +427,22 @@ module Mongo
     # @param [Hash] selector
     #   If specified, only matching documents will be removed.
     #
-    # @option opts [Boolean, Hash] :safe (+false+)
-    #   run the operation in safe mode, which will run a getlasterror command on the
-    #   database to report any assertion. In addition, a hash can be provided to
-    #   run an fsync and/or wait for replication of the remove (>= 1.5.1). Safe
-    #   options provided here will override any safe options set on this collection,
-    #   its database, or the current connection. See the options for DB#get_last_error for more details.
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged.
+    # @option opts [Integer] :wtimeout (nil) Set replica set acknowledgement timeout.
+    # @option opts [Boolean] :j (false) If true, block until write operations have been committed
+    #   to the journal. Cannot be used in combination with 'fsync'. Prior to MongoDB 2.6 this option was
+    #   ignored if the server was running without journaling. Starting with MongoDB 2.6, write operations will
+    #   fail with an exception if this option is used when the server is running without journaling.
+    # @option opts [Boolean] :fsync (false) If true, and the server is running without journaling, blocks until
+    #   the server has synced all data files to disk. If the server is running with journaling, this acts the same as
+    #   the 'j' option, blocking until write operations have been committed to the journal.
+    #   Cannot be used in combination with 'j'.
+    # @option opts [Integer] :limit (0) Set limit option, currently only 0 for all or 1 for just one.
+    #
+    #   Notes on write concern:
+    #     Options provided here will override any write concern options set on this collection,
+    #     its database object, or the current connection. See the options for +DB#get_last_error+.
     #
     # @example remove all documents from the 'users' collection:
     #   users.remove
@@ -317,31 +451,12 @@ module Mongo
     # @example remove only documents that have expired:
     #   users.remove({:expire => {"$lte" => Time.now}})
     #
-    # @return [Hash, true] Returns a Hash containing the last error object if running in safe mode.
+    # @return [Hash, true] Returns a Hash containing the last error object if acknowledging writes
     #   Otherwise, returns true.
     #
-    # @raise [Mongo::OperationFailure] an exception will be raised iff safe mode is enabled
-    #   and the operation fails.
-    #
-    # @see DB#remove for options that can be passed to :safe.
-    #
-    # @core remove remove-instance_method
+    # @raise [Mongo::OperationFailure] will be raised iff :w > 0 and the operation fails.
     def remove(selector={}, opts={})
-      # Initial byte is 0.
-      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)
-
-      @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
+      send_write(:delete, selector, nil, nil, opts)
     end
 
     # Update one or more documents in this collection.
@@ -358,44 +473,37 @@ module Mongo
     # @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
-    #   will be raised on an error. Note that a safe check requires an extra
-    #   round-trip to the database. Safe options provided here will override any safe
-    #   options set on this collection, its database object, or the current collection.
-    #   See the options for DB#get_last_error for details.
-    #
-    # @return [Hash, true] Returns a Hash containing the last error object if running in safe mode.
+    # @option opts [String, Integer, Symbol] :w (1) Set default number of nodes to which a write
+    #   should be acknowledged.
+    # @option opts [Integer] :wtimeout (nil) Set replica set acknowledgement timeout.
+    # @option opts [Boolean] :j (false) If true, block until write operations have been committed
+    #   to the journal. Cannot be used in combination with 'fsync'. Prior to MongoDB 2.6 this option was
+    #   ignored if the server was running without journaling. Starting with MongoDB 2.6, write operations will
+    #   fail with an exception if this option is used when the server is running without journaling.
+    # @option opts [Boolean] :fsync (false) If true, and the server is running without journaling, blocks until
+    #   the server has synced all data files to disk. If the server is running with journaling, this acts the same as
+    #   the 'j' option, blocking until write operations have been committed to the journal.
+    #   Cannot be used in combination with 'j'.
+    #
+    #   Notes on write concern:
+    #     Options provided here will override any write concern options set on this collection,
+    #     its database object, or the current connection. See the options for DB#get_last_error.
+    #
+    # @return [Hash, true] Returns a Hash containing the last error object if acknowledging writes.
     #   Otherwise, returns true.
     #
-    # @core update update-instance_method
+    # @raise [Mongo::OperationFailure] will be raised iff :w > 0 and the operation fails.
     def update(selector, document, opts={})
-      # Initial byte is 0.
-      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 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)
-
-      @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
+      send_write(:update, selector, document, !document.keys.first.to_s.start_with?("$"), opts)
     end
 
     # Create a new index.
     #
     # @param [String, Array] spec
     #   should be either a single field name or an array of
-    #   [field name, direction] pairs. Directions should be specified
-    #   as Mongo::ASCENDING, Mongo::DESCENDING, or Mongo::GEO2D.
+    #   [field name, type] pairs. Index types should be specified
+    #   as Mongo::ASCENDING, Mongo::DESCENDING, Mongo::GEO2D, Mongo::GEO2DSPHERE, Mongo::GEOHAYSTACK,
+    #   Mongo::TEXT or Mongo::HASHED.
     #
     #   Note that geospatial indexing only works with versions of MongoDB >= 1.3.3+. Keep in mind, too,
     #   that in order to geo-index a given field, that field must reference either an array or a sub-object
@@ -410,14 +518,23 @@ module Mongo
     # @option opts [Boolean] :unique (false) if true, this index will enforce a uniqueness constraint.
     # @option opts [Boolean] :background (false) indicate that the index should be built in the background. This
     #   feature is only available in MongoDB >= 1.3.2.
-    # @option opts [Boolean] :drop_dups (nil) If creating a unique index on a collection with pre-existing records,
-    #   this option will keep the first document the database indexes and drop all subsequent with duplicate values.
+    # @option opts [Boolean] :drop_dups (nil) (DEPRECATED) If creating a unique index on a collection with
+    #   pre-existing records, this option will keep the first document the database indexes and drop all subsequent
+    #   with duplicate values.
+    # @option opts [Integer] :bucket_size (nil) For use with geoHaystack indexes. Number of documents to group
+    #   together within a certain proximity to a given longitude and latitude.
     # @option opts [Integer] :min (nil) specify the minimum longitude and latitude for a geo index.
     # @option opts [Integer] :max (nil) specify the maximum longitude and latitude for a geo index.
     #
+    # @example Creating a compound index using a hash: (Ruby 1.9+ Syntax)
+    #   @posts.create_index({'subject' => Mongo::ASCENDING, 'created_at' => Mongo::DESCENDING})
+    #
     # @example Creating a compound index:
     #   @posts.create_index([['subject', Mongo::ASCENDING], ['created_at', Mongo::DESCENDING]])
     #
+    # @example Creating a geospatial index using a hash: (Ruby 1.9+ Syntax)
+    #   @restaurants.create_index(:location => Mongo::GEO2D)
+    #
     # @example Creating a geospatial index:
     #   @restaurants.create_index([['location', Mongo::GEO2D]])
     #
@@ -429,44 +546,59 @@ module Mongo
     # @example A geospatial index with alternate longitude and latitude:
     #   @restaurants.create_index([['location', Mongo::GEO2D]], :min => 500, :max => 500)
     #
-    # @return [String] the name of the index created.
+    # @note The :drop_dups option is no longer supported by MongoDB starting with server version 2.7.5.
+    #   The option is silently ignored by the server and unique index builds using the option will
+    #   fail if a duplicate value is detected.
     #
-    # @core indexes create_index-instance_method
+    # @note Note that the options listed may be subset of those available.
+    #   See the MongoDB documentation for a full list of supported options by server version.
+    #
+    # @return [String] the name of the index created.
     def create_index(spec, opts={})
-      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)
+      options              = opts.dup
+      options[:dropDups]   = options.delete(:drop_dups) if options[:drop_dups]
+      options[:bucketSize] = options.delete(:bucket_size) if options[:bucket_size]
+      field_spec           = parse_index_spec(spec)
+      name                 = options.delete(:name) || generate_index_name(field_spec)
+      name                 = name.to_s if name
+      generate_indexes(field_spec, name, options)
       name
     end
 
     # Calls create_index and sets a flag to not do so again for another X minutes.
     # this time can be specified as an option when initializing a Mongo::DB object as options[:cache_time]
-    # Any changes to an index will be propogated through regardless of cache time (e.g., a change of index direction)
+    # Any changes to an index will be propagated through regardless of cache time (e.g., a change of index direction)
     #
     # The parameters and options for this methods are the same as those for Collection#create_index.
     #
-    # @example Call sequence:
-    #   Time t: @posts.ensure_index([['subject', Mongo::ASCENDING])  -- calls create_index and
+    # @example Call sequence (Ruby 1.9+ Syntax):
+    #   Time t: @posts.ensure_index(:subject => Mongo::ASCENDING) -- calls create_index and
     #     sets the 5 minute cache
-    #   Time t+2min : @posts.ensure_index([['subject', Mongo::ASCENDING])  -- doesn't do anything
-    #   Time t+3min : @posts.ensure_index([['something_else', Mongo::ASCENDING])  -- calls create_index
+    #   Time t+2min : @posts.ensure_index(:subject => Mongo::ASCENDING) -- doesn't do anything
+    #   Time t+3min : @posts.ensure_index(:something_else => Mongo::ASCENDING) -- calls create_index
     #     and sets 5 minute cache
-    #   Time t+10min : @posts.ensure_index([['subject', Mongo::ASCENDING])  -- calls create_index and
+    #   Time t+10min : @posts.ensure_index(:subject => Mongo::ASCENDING) -- calls create_index and
     #     resets the 5 minute counter
     #
+    # @note The :drop_dups option is no longer supported by MongoDB starting with server version 2.7.5.
+    #   The option is silently ignored by the server and unique index builds using the option will
+    #   fail if a duplicate value is detected.
+    #
+    # @note Note that the options listed may be subset of those available.
+    #   See the MongoDB documentation for a full list of supported options by server version.
+    #
     # @return [String] the name of the index.
     def ensure_index(spec, opts={})
-      now = Time.now.utc.to_i
-      field_spec = parse_index_spec(spec)
-
-      name = opts.delete(:name) || generate_index_name(field_spec)
-      name = name.to_s if name
+      now                  = Time.now.utc.to_i
+      options              = opts.dup
+      options[:dropDups]   = options.delete(:drop_dups) if options[:drop_dups]
+      options[:bucketSize] = options.delete(:bucket_size) if options[:bucket_size]
+      field_spec           = parse_index_spec(spec)
+      name                 = options.delete(:name) || generate_index_name(field_spec)
+      name                 = name.to_s if name
 
       if !@cache[name] || @cache[name] <= now
-        generate_indexes(field_spec, name, opts)
+        generate_indexes(field_spec, name, options)
       end
 
       # Reset the cache here in case there are any errors inserting. Best to be safe.
@@ -477,16 +609,15 @@ module Mongo
     # Drop a specified index.
     #
     # @param [String] name
-    #
-    # @core indexes
     def drop_index(name)
+      if name.is_a?(Array)
+        return drop_index(index_name(name))
+      end
       @cache[name.to_s] = nil
       @db.drop_index(@name, name)
     end
 
     # Drop all indexes.
-    #
-    # @core indexes
     def drop_indexes
       @cache = {}
 
@@ -501,25 +632,114 @@ module Mongo
 
     # Atomically update and return a document using MongoDB's findAndModify command. (MongoDB > 1.3.0)
     #
-    # @option opts [Hash] :query ({}) a query selector document for matching the desired document.
-    # @option opts [Hash] :update (nil) the update operation to perform on the matched document.
-    # @option opts [Array, String, OrderedHash] :sort ({}) specify a sort option for the query using any
-    #   of the sort options available for Cursor#sort. Sort order is important if the query will be matching
-    #   multiple documents since only the first matching document will be updated and returned.
-    # @option opts [Boolean] :remove (false) If true, removes the the returned document from the collection.
-    # @option opts [Boolean] :new (false) If true, returns the updated document; otherwise, returns the document
-    #   prior to update.
+    # @option opts [Hash] :query ({}) a query selector document for matching
+    #  the desired document.
+    # @option opts [Hash] :update (nil) the update operation to perform on the
+    #  matched document.
+    # @option opts [Array, String, OrderedHash] :sort ({}) specify a sort
+    #  option for the query using any
+    #  of the sort options available for Cursor#sort. Sort order is important
+    #  if the query will be matching multiple documents since only the first
+    #  matching document will be updated and returned.
+    # @option opts [Boolean] :remove (false) If true, removes the returned
+    #  document from the collection.
+    # @option opts [Boolean] :new (false) If true, returns the updated
+    #  document; otherwise, returns the document prior to update.
+    # @option opts [Boolean] :upsert (false) If true, creates a new document
+    #  if the query returns no document.
+    # @option opts [Hash] :fields (nil) A subset of fields to return.
+    #  Specify an inclusion of a field with 1. _id is included by default and must
+    #  be explicitly excluded.
+    # @option opts [Boolean] :full_response (false) If true, returns the entire
+    #  response object from the server including 'ok' and 'lastErrorObject'.
     #
     # @return [Hash] the matched document.
-    #
-    # @core findandmodify find_and_modify-instance_method
     def find_and_modify(opts={})
+      full_response = opts.delete(:full_response)
+
       cmd = BSON::OrderedHash.new
       cmd[:findandmodify] = @name
       cmd.merge!(opts)
-      cmd[:sort] = Mongo::Support.format_order_clause(opts[:sort]) if opts[:sort]
 
-      @db.command(cmd)['value']
+      cmd[:sort] =
+        Mongo::Support.format_order_clause(opts[:sort]) if opts[:sort]
+
+      full_response ? @db.command(cmd) : @db.command(cmd)['value']
+    end
+
+    # Perform an aggregation using the aggregation framework on the current collection.
+    # @note Aggregate requires server version >= 2.1.1
+    # @note Field References: Within an expression, field names must be quoted and prefixed by a dollar sign ($).
+    #
+    # @example Define the pipeline as an array of operator hashes:
+    #   coll.aggregate([ {"$project" => {"last_name" => 1, "first_name" => 1 }}, {"$match" => {"last_name" => "Jones"}} ])
+    #
+    # @example With server version 2.5.1 or newer, pass a cursor option to retrieve unlimited aggregation results:
+    #   coll.aggregate([ {"$group" => { :_id => "$_id", :count => { "$sum" => "$members" }}} ], :cursor => {} )
+    #
+    # @param [Array] pipeline Should be a single array of pipeline operator hashes.
+    #
+    #   '$project' Reshapes a document stream by including fields, excluding fields, inserting computed fields,
+    #   renaming fields,or creating/populating fields that hold sub-documents.
+    #
+    #   '$match' Query-like interface for filtering documents out of the aggregation pipeline.
+    #
+    #   '$limit' Restricts the number of documents that pass through the pipeline.
+    #
+    #   '$skip' Skips over the specified number of documents and passes the rest along the pipeline.
+    #
+    #   '$unwind' Peels off elements of an array individually, returning one document for each member.
+    #
+    #   '$group' Groups documents for calculating aggregate values.
+    #
+    #   '$sort' Sorts all input documents and returns them to the pipeline in sorted order.
+    #
+    #   '$out' The name of a collection to which the result set will be saved.
+    #
+    # @option opts [:primary, :secondary] :read Read preference indicating which server to perform this operation
+    #  on. If $out is specified and :read is not :primary, the aggregation will be rerouted to the primary with
+    #  a warning. See Collection#find for more details.
+    # @option opts [String]  :comment (nil) a comment to include in profiling logs
+    # @option opts [Hash] :cursor return a cursor object instead of an Array.  Takes an optional batchSize parameter
+    #  to specify the maximum size, in documents, of the first batch returned.
+    #
+    # @return [Array] An Array with the aggregate command's results.
+    #
+    # @raise MongoArgumentError if operators either aren't supplied or aren't in the correct format.
+    # @raise MongoOperationFailure if the aggregate command fails.
+    #
+    def aggregate(pipeline=nil, opts={})
+      raise MongoArgumentError, "pipeline must be an array of operators" unless pipeline.class == Array
+      raise MongoArgumentError, "pipeline operators must be hashes" unless pipeline.all? { |op| op.class == Hash }
+
+      selector = BSON::OrderedHash.new
+      selector['aggregate'] = self.name
+      selector['pipeline'] = pipeline
+
+      result = @db.command(selector, command_options(opts))
+      unless Mongo::Support.ok?(result)
+        raise Mongo::OperationFailure, "aggregate failed: #{result['errmsg']}"
+      end
+
+      if result.key?('cursor')
+        cursor_info = result['cursor']
+        pinned_pool = @connection.pinned_pool
+        pinned_pool = pinned_pool[:pool] if pinned_pool.respond_to?(:keys)
+
+        seed = {
+          :cursor_id => cursor_info['id'],
+          :first_batch => cursor_info['firstBatch'],
+          :pool => pinned_pool,
+          :ns => cursor_info['ns']
+        }
+
+        return Cursor.new(self, seed.merge!(opts))
+
+      elsif selector['pipeline'].any? { |op| op.key?('$out') || op.key?(:$out) }
+        return result
+      end
+
+      result['result'] || result
     end
 
     # Perform a map-reduce operation on the current collection.
@@ -534,25 +754,28 @@ 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) 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
+    # @option opts [String, Hash] :out Location of the result of the map-reduce operation. You can output to a
+    #   collection, output to a collection with an action, or output inline. You may output to a collection
+    #   when performing map reduce operations on the primary members of the set; on secondary members you
+    #   may only use the inline output. See the server mapReduce documentation for available options.
+    # @option opts [Boolean] :keeptemp (false) if true, the generated collection will be persisted. The default
     #   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. 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
+    #   map-reduce output (as, for example, when using :out => { :inline => 1 }), then you must specify this option
     #   or an ArgumentError will be raised.
+    # @option opts [:primary, :secondary] :read Read preference indicating which server to run this map-reduce
+    #  on. See Collection#find for more details.
+    # @option opts [String]  :comment (nil) a comment to include in profiling logs
     #
     # @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.
+    # @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.
-    #
-    # @core mapreduce map_reduce-instance_method
     def map_reduce(map, reduce, opts={})
+      opts = opts.dup
       map    = BSON::Code.new(map) unless map.is_a?(BSON::Code)
       reduce = BSON::Code.new(reduce) unless reduce.is_a?(BSON::Code)
       raw    = opts.delete(:raw)
@@ -561,17 +784,25 @@ module Mongo
       hash['mapreduce'] = self.name
       hash['map'] = map
       hash['reduce'] = reduce
-      hash.merge! opts
+      hash['out'] = opts.delete(:out)
+      hash['sort'] = Mongo::Support.format_order_clause(opts.delete(:sort)) if opts.key?(:sort)
 
-      result = @db.command(hash)
+      result = @db.command(hash, command_options(opts))
       unless Mongo::Support.ok?(result)
         raise Mongo::OperationFailure, "map-reduce failed: #{result['errmsg']}"
       end
 
       if raw
         result
-      elsif result["result"]
-        @db[result["result"]]
+      elsif result['result']
+        if result['result'].is_a?(BSON::OrderedHash) &&
+            result['result'].key?('db') &&
+            result['result'].key?('collection')
+          otherdb = @db.connection[result['result']['db']]
+          otherdb[result['result']['collection']]
+        else
+          @db[result["result"]]
+        end
       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."
@@ -593,16 +824,23 @@ module Mongo
     # @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.
+    # @option opts [:primary, :secondary] :read Read preference indicating which server to perform this group
+    #  on. See Collection#find for more details.
+    # @option opts [String]  :comment (nil) a comment to include in profiling logs
     #
     # @return [Array] the command response consisting of grouped items.
     def group(opts, condition={}, initial={}, reduce=nil, finalize=nil)
+      opts = opts.dup
       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"
+      elsif 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
 
+      warn "Collection#group no longer takes a list of parameters. This usage is deprecated and will be removed in v2.0." +
+             "Check out the new API at http://api.mongodb.org/ruby/current/Mongo/Collection.html#group-instance_method"
+
       reduce = BSON::Code.new(reduce) unless reduce.is_a?(BSON::Code)
 
       group_command = {
@@ -614,11 +852,6 @@ module Mongo
         }
       }
 
-      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"
@@ -646,13 +879,44 @@ module Mongo
       end
     end
 
+    # Scan this entire collection in parallel.
+    # Returns a list of up to num_cursors cursors that can be iterated concurrently. As long as the collection
+    # is not modified during scanning, each document appears once in one of the cursors' result sets.
+    #
+    # @note Requires server version >= 2.5.5
+    #
+    # @param [Integer] num_cursors the number of cursors to return.
+    # @param [Hash] opts
+    #
+    # @return [Array] An array of up to num_cursors cursors for iterating over the collection.
+    def parallel_scan(num_cursors, opts={})
+      cmd                          = BSON::OrderedHash.new
+      cmd[:parallelCollectionScan] = self.name
+      cmd[:numCursors]             = num_cursors
+      result                       = @db.command(cmd, command_options(opts))
+
+      result['cursors'].collect do |cursor_info|
+        pinned_pool = @connection.pinned_pool
+        pinned_pool = pinned_pool[:pool] if pinned_pool.respond_to?(:keys)
+
+        seed = {
+          :cursor_id   => cursor_info['cursor']['id'],
+          :first_batch => cursor_info['cursor']['firstBatch'],
+          :pool        => pinned_pool,
+          :ns          => cursor_info['ns']
+        }
+        Cursor.new(self, seed.merge!(opts))
+      end
+
+    end
+
     private
 
     def new_group(opts={})
-      reduce   =  opts[:reduce]
-      finalize =  opts[:finalize]
-      cond     =  opts.fetch(:cond, {})
-      initial  =  opts[:initial]
+      reduce   =  opts.delete(:reduce)
+      finalize =  opts.delete(:finalize)
+      cond     =  opts.delete(:cond) || {}
+      initial  =  opts.delete(:initial)
 
       if !(reduce && initial)
         raise MongoArgumentError, "Group requires at minimum values for initial and reduce."
@@ -671,18 +935,18 @@ module Mongo
         cmd['group']['finalize'] = finalize.to_bson_code
       end
 
-      if key = opts[:key]
+      if key = opts.delete(: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]
+      elsif keyf = opts.delete(:keyf)
         cmd["group"]["$keyf"] = keyf.to_bson_code
       end
 
-      result = @db.command(cmd)
+      result = @db.command(cmd, command_options(opts))
       result["retval"]
     end
 
@@ -694,6 +958,11 @@ module Mongo
     #
     # @param [String, Symbol, OrderedHash] key or hash to group by.
     # @param [Hash] query a selector for limiting the result set over which to group.
+    # @param [Hash] opts the options for this distinct operation.
+    #
+    # @option opts [:primary, :secondary] :read Read preference indicating which server to perform this query
+    #  on. See Collection#find for more details.
+    # @option opts [String]  :comment (nil) a comment to include in profiling logs
     #
     # @example Saving zip codes and ages and returning distinct results.
     #   @collection.save({:zip => 10010, :name => {:age => 27}})
@@ -713,14 +982,14 @@ module Mongo
     #     [27]
     #
     # @return [Array] an array of distinct values.
-    def distinct(key, query=nil)
+    def distinct(key, query=nil, opts={})
       raise MongoArgumentError unless [String, Symbol].include?(key.class)
-      command = BSON::OrderedHash.new
+      command            = BSON::OrderedHash.new
       command[:distinct] = @name
       command[:key]      = key.to_s
       command[:query]    = query
 
-      @db.command(command)["values"]
+      @db.command(command, command_options(opts))["values"]
     end
 
     # Rename this collection.
@@ -759,8 +1028,6 @@ module Mongo
     # Get information on the indexes for this collection.
     #
     # @return [Hash] a hash where the keys are index names.
-    #
-    # @core indexes
     def index_information
       @db.index_information(@name)
     end
@@ -770,7 +1037,7 @@ module Mongo
     #
     # @return [Hash] options that apply to this collection.
     def options
-      @db.collections_info(@name).next_document['options']
+      @db.collections_info(@name).first['options']
     end
 
     # Return stats on the collection. Uses MongoDB's collstats command.
@@ -782,15 +1049,38 @@ module Mongo
 
     # Get the number of documents in this collection.
     #
+    # @option opts [Hash] :query ({}) A query selector for filtering the documents counted.
+    # @option opts [Integer] :skip (nil) The number of documents to skip.
+    # @option opts [Integer] :limit (nil) The number of documents to limit.
+    # @option opts [String, Array, OrderedHash] :hint hint for query optimizer, usually not necessary if
+    #   using MongoDB > 1.1. This option is only supported with #count in server version > 2.6.
+    # @option opts [String] :named_hint for specifying a named index as a hint, will be overridden by :hint
+    #   if :hint is also provided. This option is only supported with #count in server version > 2.6.
+    # @option opts [:primary, :secondary] :read Read preference for this command. See Collection#find for
+    #  more details.
+    # @option opts [String]  :comment (nil) a comment to include in profiling logs
+    #
     # @return [Integer]
-    def count
-      find().count()
+    def count(opts={})
+      find(opts[:query],
+           :skip       => opts[:skip],
+           :limit      => opts[:limit],
+           :named_hint => opts[:named_hint] || @hint,
+           :hint       => opts[:hint] || @hint,
+           :read       => opts[:read],
+           :comment    => opts[:comment]).count(true)
     end
-
     alias :size :count
 
     protected
 
+    # Provide required command options if they are missing in the command options hash.
+    #
+    # @return [Hash] The command options hash
+    def command_options(opts)
+      opts[:read] ? opts : opts.merge(:read => @read)
+    end
+
     def normalize_hint_fields(hint)
       case hint
       when String
@@ -808,78 +1098,95 @@ module Mongo
 
     private
 
+    def send_write(op_type, selector, doc_or_docs, check_keys, opts, collection_name=@name)
+      write_concern = get_write_concern(opts, self)
+      if @db.connection.use_write_command?(write_concern)
+        @command_writer.send_write_command(op_type, selector, doc_or_docs, check_keys, opts, write_concern, collection_name)
+      else
+        @operation_writer.send_write_operation(op_type, selector, doc_or_docs, check_keys, opts, write_concern, collection_name)
+      end
+    end
+
+    def index_name(spec)
+      field_spec = parse_index_spec(spec)
+      index_information.each do |index|
+        return index[0] if index[1]['key'] == field_spec
+      end
+      nil
+    end
+
     def parse_index_spec(spec)
       field_spec = BSON::OrderedHash.new
       if spec.is_a?(String) || spec.is_a?(Symbol)
         field_spec[spec.to_s] = 1
+      elsif spec.is_a?(Hash)
+        if RUBY_VERSION < '1.9' && !spec.is_a?(BSON::OrderedHash)
+          raise MongoArgumentError, "Must use OrderedHash in Ruby < 1.9.0"
+        end
+        validate_index_types(spec.values)
+        field_spec = spec.is_a?(BSON::OrderedHash) ? spec : BSON::OrderedHash.try_convert(spec)
       elsif spec.is_a?(Array) && spec.all? {|field| field.is_a?(Array) }
         spec.each do |f|
-          if [Mongo::ASCENDING, Mongo::DESCENDING, Mongo::GEO2D].include?(f[1])
-            field_spec[f[0].to_s] = f[1]
-          else
-            raise MongoArgumentError, "Invalid index field #{f[1].inspect}; " + 
-              "should be one of Mongo::ASCENDING (1), Mongo::DESCENDING (-1) or Mongo::GEO2D ('2d')."
-          end
+          validate_index_types(f[1])
+          field_spec[f[0].to_s] = f[1]
         end
       else
-        raise MongoArgumentError, "Invalid index specification #{spec.inspect}; " + 
-          "should be either a string, symbol, or an array of arrays."
+        raise MongoArgumentError, "Invalid index specification #{spec.inspect}; " +
+          "should be either a hash (OrderedHash), string, symbol, or an array of arrays."
       end
       field_spec
     end
 
+    def validate_index_types(*types)
+      types.flatten!
+      types.each do |t|
+        unless Mongo::INDEX_TYPES.values.include?(t)
+          raise MongoArgumentError, "Invalid index field #{t.inspect}; " +
+                "should be one of " + Mongo::INDEX_TYPES.map {|k,v| "Mongo::#{k} (#{v})"}.join(', ')
+        end
+      end
+    end
+
     def generate_indexes(field_spec, name, opts)
       selector = {
         :name   => name,
-        :ns     => "#{@db.name}.#{@name}",
         :key    => field_spec
       }
       selector.merge!(opts)
 
       begin
-      insert_documents([selector], Mongo::DB::SYSTEM_INDEX_COLLECTION, false, true)
-
-      rescue Mongo::OperationFailure => e
-        if selector[:dropDups] && e.message =~ /^11000/
-          # NOP. If the user is intentionally dropping dups, we can ignore duplicate key errors.
+        cmd = BSON::OrderedHash[:createIndexes, @name, :indexes, [selector]]
+        @db.command(cmd)
+      rescue Mongo::OperationFailure => ex
+        if Mongo::ErrorCode::COMMAND_NOT_FOUND_CODES.include?(ex.error_code)
+          selector[:ns] = "#{@db.name}.#{@name}"
+          send_write(:insert, nil, selector, false, {:w => 1}, Mongo::DB::SYSTEM_INDEX_COLLECTION)
         else
           raise Mongo::OperationFailure, "Failed to create index #{selector.inspect} with the following error: " +
-           "#{e.message}"
+           "#{ex.message}"
         end
       end
 
       nil
     end
 
-    # Sends a Mongo::Constants::OP_INSERT message to the database.
-    # Takes an array of +documents+, an optional +collection_name+, and a
-    # +check_keys+ setting.
-    def insert_documents(documents, collection_name=@name, check_keys=true, safe=false)
-      # Initial byte is 0.
-      message = BSON::ByteBuffer.new("\0\0\0\0")
-      BSON::BSON_RUBY.serialize_cstr(message, "#{@db.name}.#{collection_name}")
-      documents.each do |doc|
-        message.put_binary(BSON::BSON_CODER.serialize(doc, check_keys, true).to_s)
-      end
-      raise InvalidOperation, "Exceded maximum insert size of 16,000,000 bytes" if message.size > 16_000_000
-
-      @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
-
     def generate_index_name(spec)
       indexes = []
-      spec.each_pair do |field, direction|
-        indexes.push("#{field}_#{direction}")
+      spec.each_pair do |field, type|
+        indexes.push("#{field}_#{type}")
       end
       indexes.join("_")
     end
+
+    def batch_write(op_type, documents, check_keys=true, opts={})
+      write_concern = get_write_concern(opts, self)
+      if @db.connection.use_write_command?(write_concern)
+        return @command_writer.batch_write(op_type, documents, check_keys, opts)
+      else
+        return @operation_writer.batch_write(op_type, documents, check_keys, opts)
+      end
+    end
+
   end
 
 end