Class Mongo::Collection
In: lib/mongo/collection.rb
Parent: Object

A named collection of documents in a database.

Methods

Included Modules

Mongo::Logging

Attributes

db  [R] 
hint  [R] 
name  [R] 
pk_factory  [R] 
safe  [R] 

Public Class methods

Initialize a collection object.

@param [String, Symbol] name the name of the collection. @param [DB] db a MongoDB database instance.

@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 options [: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 '.'

@raise [TypeError]

  if collection name is not a string or symbol

@return [Collection]

@core collections constructor_details

[Source]

# File lib/mongo/collection.rb, line 53
    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. 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

      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 '.'"
      end

      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 = 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 = opts.fetch(:safe, @db.safe)
        if value = opts[:read]
          Mongo::Support.validate_read_preference(value)
        else
          value = @db.read_preference
        end
        @read_preference = value.is_a?(Hash) ? value.dup : value
      end
      @pk_factory = pk_factory || opts[:pk] || BSON::ObjectId
      @hint = nil
    end

Public Instance methods

<<(doc_or_docs, opts={})

Alias for insert

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, Symbol] name

  the collection to return

@raise [Mongo::InvalidNSName]

  if passed an invalid collection name

@return [Collection]

  the specified sub-collection

[Source]

# File lib/mongo/collection.rb, line 126
    def [](name)
      name = "#{self.name}.#{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

Indicate whether this is a capped collection.

@raise [Mongo::OperationFailure]

  if the collection doesn't exist.

@return [Boolean]

[Source]

# File lib/mongo/collection.rb, line 111
    def capped?
      @db.command({:collstats => @name})['capped'] == 1
    end

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.

@return [Integer]

[Source]

# File lib/mongo/collection.rb, line 850
    def count(opts={})
      find(opts[:query],
           :skip => opts[:skip],
           :limit => opts[:limit]).count(true)
    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.

  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
  where the first two values represent x- and y-coordinates. Examples can be seen below.

  Also note that it is permissible to create compound indexes that include a geospatial index as
  long as the geospatial index comes first.

  If your code calls create_index frequently, you can use Collection#ensure_index to cache these calls
  and thereby prevent excessive round trips to the database.

@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 [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:

  @posts.create_index([['subject', Mongo::ASCENDING], ['created_at', Mongo::DESCENDING]])

@example Creating a geospatial index:

  @restaurants.create_index([['location', Mongo::GEO2D]])

  # Note that this will work only if 'location' represents x,y coordinates:
  {'location': [0, 50]}
  {'location': {'x' => 0, 'y' => 50}}
  {'location': {'latitude' => 0, 'longitude' => 50}}

@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.

@core indexes create_index-instance_method

[Source]

# File lib/mongo/collection.rb, line 480
    def create_index(spec, opts={})
      opts[:dropDups] = opts[:drop_dups] if opts[:drop_dups]
      field_spec = parse_index_spec(spec)
      opts = opts.dup
      name = opts.delete(:name) || generate_index_name(field_spec)
      name = name.to_s if name

      generate_indexes(field_spec, name, opts)
      name
    end

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.

@param [String, Symbol, OrderedHash] key or hash to group by. @param [Hash] query a selector for limiting the result set over which to group.

@example Saving zip codes and ages and returning distinct results.

  @collection.save({:zip => 10010, :name => {:age => 27}})
  @collection.save({:zip => 94108, :name => {:age => 24}})
  @collection.save({:zip => 10010, :name => {:age => 27}})
  @collection.save({:zip => 99701, :name => {:age => 24}})
  @collection.save({:zip => 94108, :name => {:age => 27}})

  @collection.distinct(:zip)
    [10010, 94108, 99701]
  @collection.distinct("name.age")
    [27, 24]

  # You may also pass a document selector as the second parameter
  # to limit the documents over which distinct is run:
  @collection.distinct("name.age", {"name.age" => {"$gt" => 24}})
    [27]

@return [Array] an array of distinct values.

[Source]

# File lib/mongo/collection.rb, line 776
    def distinct(key, query=nil)
      raise MongoArgumentError unless [String, Symbol].include?(key.class)
      command = BSON::OrderedHash.new
      command[:distinct] = @name
      command[:key]      = key.to_s
      command[:query]    = query

      @db.command(command)["values"]
    end

Drop the entire collection. USE WITH CAUTION.

[Source]

# File lib/mongo/collection.rb, line 548
    def drop
      @db.drop_collection(@name)
    end

Drop a specified index.

@param [String] name

@core indexes

[Source]

# File lib/mongo/collection.rb, line 529
    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

[Source]

# File lib/mongo/collection.rb, line 540
    def drop_indexes
      @cache = {}

      # Note: calling drop_indexes with no args will drop them all.
      @db.drop_index(@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)

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
    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
    and sets 5 minute cache
  Time t+10min : @posts.ensure_index([['subject', Mongo::ASCENDING])  -- calls create_index and
    resets the 5 minute counter

@return [String] the name of the index.

[Source]

# File lib/mongo/collection.rb, line 507
    def ensure_index(spec, opts={})
      now = Time.now.utc.to_i
      opts[:dropDups] = opts[:drop_dups] if opts[:drop_dups]
      field_spec = parse_index_spec(spec)

      name = opts[:name] || generate_index_name(field_spec)
      name = name.to_s if name

      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
      name
    end

Query the database.

The selector argument is a prototype document that all results must match. For example:

  collection.find({"hello" => "world"})

only matches documents that have a key "hello" with value "world". Matches can have other keys *in addition* to "hello".

If given an optional block find will yield a Cursor to that block, close the cursor, and then return nil. This guarantees that partially evaluated cursors will be closed. If given no block find returns a cursor.

@param [Hash] selector

  a document specifying elements which must be present for a
  document to be included in the result set. Note that in rare cases,
  (e.g., with $near queries), the order of keys will matter. To preserve
  key order on a selector, use an instance of BSON::OrderedHash (only applies
  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,
  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 [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.

@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 [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 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

@raise [RuntimeError]

  if given unknown options

@core find find-instance_method

[Source]

# File lib/mongo/collection.rb, line 207
    def find(selector={}, opts={})
      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)
      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)
      read          = opts.delete(:read) || @read_preference

      if timeout == false && !block_given?
        raise ArgumentError, "Collection#find must be invoked with a block when timeout is disabled."
      end

      if hint
        hint = normalize_hint_fields(hint)
      else
        hint = @hint        # assumed to be normalized already
      end

      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,
        :max_scan    => max_scan,
        :show_disk_loc => show_disk_loc,
        :return_key    => return_key,
        :read          => read
      })

      if block_given?
        yield cursor
        cursor.close
        nil
      else
        cursor
      end
    end

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.

@return [Hash] the matched document.

@core findandmodify find_and_modify-instance_method

[Source]

# File lib/mongo/collection.rb, line 566
    def find_and_modify(opts={})
      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']
    end

Return a single object from the database.

@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
  instance of ObjectId to be used as the value for an _id query.
  If nil, an empty selector, {}, will be used.

@option opts [Hash]

  any valid options that can be send to Collection#find

@raise [TypeError]

  if the argument is of an improper type.

[Source]

# File lib/mongo/collection.rb, line 277
    def find_one(spec_or_object_id=nil, opts={})
      spec = case spec_or_object_id
             when nil
               {}
             when BSON::ObjectId
               {:_id => spec_or_object_id}
             when Hash
               spec_or_object_id
             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
    end

Perform a group aggregation.

@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.

[Source]

# File lib/mongo/collection.rb, line 651
    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 and will be remove in v2.0." +
             "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 = {
        "group" => {
          "ns"      => @name,
          "$reduce" => reduce,
          "cond"    => condition,
          "initial" => initial
        }
      }

      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 = {}
          opts.each { |k| key_value[k] = 1 }
        else
          key_type  = "$keyf"
          key_value = opts.is_a?(BSON::Code) ? opts : BSON::Code.new(opts)
        end

        group_command["group"][key_type] = key_value
      end

      finalize = BSON::Code.new(finalize) if finalize.is_a?(String)
      if finalize.is_a?(BSON::Code)
        group_command['group']['finalize'] = finalize
      end

      result = @db.command(group_command)

      if Mongo::Support.ok?(result)
        result["retval"]
      else
        raise OperationFailure, "group command failed: #{result['errmsg']}"
      end
    end

Set a hint field for query optimizer. Hint may be a single field name, array of field names, or a hash (preferably an [OrderedHash]). If using MongoDB > 1.1, you probably don‘t ever need to set a hint.

@param [String, Array, OrderedHash] hint a single field, an array of

  fields, or a hash specifying fields

[Source]

# File lib/mongo/collection.rb, line 139
    def hint=(hint=nil)
      @hint = normalize_hint_fields(hint)
      self
    end

Get information on the indexes for this collection.

@return [Hash] a hash where the keys are index names.

@core indexes

[Source]

# File lib/mongo/collection.rb, line 824
    def index_information
      @db.index_information(@name)
    end

Insert one or more documents into the collection.

@param [Hash, Array] doc_or_docs

  a document (as a hash) or array of documents to be inserted.

@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.

@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).
  MongoDB v2.0+.

@core insert insert-instance_method

[Source]

# File lib/mongo/collection.rb, line 339
    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, opts)
      result.size > 1 ? result : result.first
    end

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.

@option opts [Hash] :query ({}) a query selector document, like what‘s passed to find, to limit

  the operation to a subset of the collection.

@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 [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

  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
  or an ArgumentError will be raised.

@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 www.mongodb.org/display/DOCS/MapReduce Offical MongoDB map/reduce documentation.

@core mapreduce map_reduce-instance_method

[Source]

# File lib/mongo/collection.rb, line 605
    def map_reduce(map, reduce, opts={})
      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)

      hash = BSON::OrderedHash.new
      hash['mapreduce'] = self.name
      hash['map'] = map
      hash['reduce'] = reduce
      hash.merge! opts
      if hash[:sort]
        hash[:sort] = Mongo::Support.format_order_clause(hash[:sort])
      end

      result = @db.command(hash)
      unless Mongo::Support.ok?(result)
        raise Mongo::OperationFailure, "map-reduce failed: #{result['errmsg']}"
      end

      if raw
        result
      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
mapreduce(map, reduce, opts={})

Alias for map_reduce

Return a hash containing options that apply to this collection. For all possible keys and values, see DB#create_collection.

@return [Hash] options that apply to this collection.

[Source]

# File lib/mongo/collection.rb, line 832
    def options
      @db.collections_info(@name).next_document['options']
    end

The value of the read preference. This will be either +:primary+, +:secondary+, or an object representing the tags to be read from.

[Source]

# File lib/mongo/collection.rb, line 705
    def read_preference
      @read_preference
    end

Remove all documents from this collection.

@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.

@example remove all documents from the ‘users’ collection:

  users.remove
  users.remove({})

@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.

  Otherwise, returns true.

@raise [Mongo::OperationFailure] an exception will be raised iff safe mode is enabled

  and the operation fails.

@core remove remove-instance_method

[Source]

# File lib/mongo/collection.rb, line 374
    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, @connection.max_bson_size).to_s)

      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

Rename this collection.

Note: If operating in auth mode, the client must be authorized as an admin to perform this operation.

@param [String] new_name the new name for this collection

@return [String] the name of the new collection.

@raise [Mongo::InvalidNSName] if new_name is an invalid collection name.

[Source]

# File lib/mongo/collection.rb, line 796
    def rename(new_name)
      case new_name
      when Symbol, String
      else
        raise TypeError, "new_name must be a string or symbol"
      end

      new_name = new_name.to_s

      if new_name.empty? or new_name.include? ".."
        raise Mongo::InvalidNSName, "collection names cannot be empty"
      end
      if new_name.include? "$"
        raise Mongo::InvalidNSName, "collection names must not contain '$'"
      end
      if new_name.match(/^\./) or new_name.match(/\.$/)
        raise Mongo::InvalidNSName, "collection names must not start or end with '.'"
      end

      @db.rename_collection(@name, new_name)
      @name = new_name
    end

Save a document to this collection.

@param [Hash] doc

  the document to be saved. If the document already has an '_id' key,
  then an update (upsert) operation will be performed, and any existing
  document with that _id is overwritten. Otherwise an insert operation is performed.

@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.

[Source]

# File lib/mongo/collection.rb, line 307
    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))
        id
      else
        insert(doc, :safe => opts.fetch(:safe, @safe))
      end
    end
size(opts={})

Alias for count

Return stats on the collection. Uses MongoDB‘s collstats command.

@return [Hash]

[Source]

# File lib/mongo/collection.rb, line 839
    def stats
      @db.command({:collstats => @name})
    end

Update one or more documents in this collection.

@param [Hash] selector

  a hash specifying elements which must be present for a document to be updated. Note:
  the update command currently updates only the first document matching the
  given selector. If you want all matching documents to be updated, be sure
  to specify :multi => true.

@param [Hash] document

  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 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.

  Otherwise, returns true.

@core update update-instance_method

[Source]

# File lib/mongo/collection.rb, line 417
    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, @connection.max_bson_size).to_s)

      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)
        end
      end
    end

Protected Instance methods

[Source]

# File lib/mongo/collection.rb, line 860
    def normalize_hint_fields(hint)
      case hint
      when String
        {hint => 1}
      when Hash
        hint
      when nil
        nil
      else
        h = BSON::OrderedHash.new
        hint.to_a.each { |k| h[k] = 1 }
        h
      end
    end

[Validate]