Class: Mongo::Collection

Inherits:
Object show all
Includes:
Logging, WriteConcern
Defined in:
lib/mongo/collection.rb,
lib/mongo/bulk_write_collection_view.rb

Overview

A named collection of documents in a database.

Constant Summary

Constant Summary

Constants included from WriteConcern

WriteConcern::DEFAULT_WRITE_CONCERN, WriteConcern::VALID_KEYS

Instance Attribute Summary (collapse)

Attributes included from WriteConcern

#legacy_write_concern

Instance Method Summary (collapse)

Methods included from WriteConcern

#get_write_concern, gle?, #write_concern_from_legacy

Methods included from Logging

#instrument, instrumenter, instrumenter=, #log, #write_logging_startup_message

Constructor Details

- (Collection) initialize(name, db, opts = {})

Initialize a collection object.

Parameters:

  • name (String, Symbol)

    the name of the collection.

  • db (DB)

    a MongoDB database instance.

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :w (String, Integer, Symbol) — default: 1

    Set default number of nodes to which a write should be acknowledged.

  • :wtimeout (Integer) — default: nil

    Set replica set acknowledgement timeout.

  • :j (Boolean) — default: 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.

  • :fsync (Boolean) — default: 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.
  • :pk (:create_pk) — default: BSON::ObjectId

    A primary key factory to use other than the default BSON::ObjectId.

  • :read (:primary, :secondary)

    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.

Raises:

  • (InvalidNSName)

    if collection name is empty, contains ‘$’, or starts or ends with ‘.’

  • (TypeError)

    if collection name is not a string or symbol



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
# File 'lib/mongo/collection.rb', line 73

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

  raise TypeError,
    "Collection name must be a String or Symbol." unless [String, Symbol].include?(name.class)
  name = name.to_s

  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)."
    pk_factory = opts
  end

  @db, @name  = db, name
  @connection = @db.connection
  @logger     = @connection.logger
  @cache_time = @db.cache_time
  @cache      = Hash.new(0)
  unless pk_factory
    @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

Instance Attribute Details

- (Object) acceptable_latency

Read Preference



32
33
34
# File 'lib/mongo/collection.rb', line 32

def acceptable_latency
  @acceptable_latency
end

- (Object) capped (readonly)

Returns the value of attribute capped



22
23
24
# File 'lib/mongo/collection.rb', line 22

def capped
  @capped
end

- (Object) command_writer (readonly)

Returns the value of attribute command_writer



22
23
24
# File 'lib/mongo/collection.rb', line 22

def command_writer
  @command_writer
end

- (Object) db (readonly)

Returns the value of attribute db



22
23
24
# File 'lib/mongo/collection.rb', line 22

def db
  @db
end

- (Object) hint

Returns the value of attribute hint



22
23
24
# File 'lib/mongo/collection.rb', line 22

def hint
  @hint
end

- (Object) name (readonly)

Returns the value of attribute name



22
23
24
# File 'lib/mongo/collection.rb', line 22

def name
  @name
end

- (Object) operation_writer (readonly)

Returns the value of attribute operation_writer



22
23
24
# File 'lib/mongo/collection.rb', line 22

def operation_writer
  @operation_writer
end

- (Object) pk_factory (readonly)

Returns the value of attribute pk_factory



22
23
24
# File 'lib/mongo/collection.rb', line 22

def pk_factory
  @pk_factory
end

- (Object) read

Read Preference



32
33
34
# File 'lib/mongo/collection.rb', line 32

def read
  @read
end

- (Object) tag_sets

Read Preference



32
33
34
# File 'lib/mongo/collection.rb', line 32

def tag_sets
  @tag_sets
end

- (Object) write_concern (readonly)

Returns the value of attribute write_concern



22
23
24
# File 'lib/mongo/collection.rb', line 22

def write_concern
  @write_concern
end

Instance Method Details

- (Collection) [](name)

Return a sub-collection of this collection by name. If 'users' is a collection, then 'users.comments' is a sub-collection of users.

Parameters:

  • name (String, Symbol)

    the collection to return

Returns:

Raises:



143
144
145
146
147
148
# File 'lib/mongo/collection.rb', line 143

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

- (Array) aggregate(pipeline = nil, opts = {})

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 ($).

Perform an aggregation using the aggregation framework on the current collection.

Examples:

Define the pipeline as an array of operator hashes:

coll.aggregate([ {"$project" => {"last_name" => 1, "first_name" => 1 }}, {"$match" => {"last_name" => "Jones"}} ])

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 => {} )

Parameters:

  • pipeline (Array) (defaults to: nil)

    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.

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :read (:primary, :secondary)

    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.

  • :comment (String) — default: nil

    a comment to include in profiling logs

  • :cursor (Hash)

    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.

Returns:

  • (Array)

    An Array with the aggregate command’s results.

Raises:

  • MongoArgumentError if operators either aren’t supplied or aren’t in the correct format.

  • MongoOperationFailure if the aggregate command fails.



705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
# File 'lib/mongo/collection.rb', line 705

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']

    seed = {
      :cursor_id => cursor_info['id'],
      :first_batch => cursor_info['firstBatch'],
      :pool => @connection.pinned_pool
    }

    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

- (Boolean) capped?

Indicate whether this is a capped collection.

Returns:

  • (Boolean)

Raises:



128
129
130
# File 'lib/mongo/collection.rb', line 128

def capped?
  @capped ||= [1, true].include?(@db.command({:collstats => @name})['capped'])
end

- (Integer) count(opts = {}) Also known as: size

Get the number of documents in this collection.

Parameters:

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :query (Hash) — default: {}

    A query selector for filtering the documents counted.

  • :skip (Integer) — default: nil

    The number of documents to skip.

  • :limit (Integer) — default: nil

    The number of documents to limit.

  • :hint (String, Array, OrderedHash)

    hint for query optimizer, usually not necessary if using MongoDB > 1.1. This option is only supported with #count in server version > 2.6.

  • :named_hint (String)

    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.

  • :read (:primary, :secondary)

    Read preference for this command. See Collection#find for more details.

  • :comment (String) — default: nil

    a comment to include in profiling logs

Returns:

  • (Integer)


1051
1052
1053
1054
1055
1056
1057
1058
1059
# File 'lib/mongo/collection.rb', line 1051

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

- (String) create_index(spec, opts = {})

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.

Create a new index.

Examples:

Creating a compound index using a hash: (Ruby 1.9+ Syntax)

@posts.create_index({'subject' => Mongo::ASCENDING, 'created_at' => Mongo::DESCENDING})

Creating a compound index:

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

Creating a geospatial index using a hash: (Ruby 1.9+ Syntax)

@restaurants.create_index(:location => Mongo::GEO2D)

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

A geospatial index with alternate longitude and latitude:

@restaurants.create_index([['location', Mongo::GEO2D]], :min => 500, :max => 500)

Parameters:

  • spec (String, Array)

    should be either a single field name or an array of

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

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :unique (Boolean) — default: false

    if true, this index will enforce a uniqueness constraint.

  • :background (Boolean) — default: false

    indicate that the index should be built in the background. This feature is only available in MongoDB >= 1.3.2.

  • :drop_dups (Boolean) — default: 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.

  • :bucket_size (Integer) — default: nil

    For use with geoHaystack indexes. Number of documents to group together within a certain proximity to a given longitude and latitude.

  • :min (Integer) — default: nil

    specify the minimum longitude and latitude for a geo index.

  • :max (Integer) — default: nil

    specify the maximum longitude and latitude for a geo index.

Returns:

  • (String)

    the name of the index created.



554
555
556
557
558
559
560
561
562
563
# File 'lib/mongo/collection.rb', line 554

def create_index(spec, 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

- (Array) distinct(key, query = nil, opts = {})

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.

Examples:

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]

Parameters:

  • key (String, Symbol, OrderedHash)

    or hash to group by.

  • query (Hash) (defaults to: nil)

    a selector for limiting the result set over which to group.

  • opts (Hash) (defaults to: {})

    the options for this distinct operation.

Options Hash (opts):

  • :read (:primary, :secondary)

    Read preference indicating which server to perform this query on. See Collection#find for more details.

  • :comment (String) — default: nil

    a comment to include in profiling logs

Returns:

  • (Array)

    an array of distinct values.

Raises:



972
973
974
975
976
977
978
979
980
# File 'lib/mongo/collection.rb', line 972

def distinct(key, query=nil, opts={})
  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, command_options(opts))["values"]
end

- (Object) drop

Drop the entire collection. USE WITH CAUTION.



623
624
625
# File 'lib/mongo/collection.rb', line 623

def drop
  @db.drop_collection(@name)
end

- (Object) drop_index(name)

Drop a specified index.

Parameters:



606
607
608
609
610
611
612
# File 'lib/mongo/collection.rb', line 606

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

- (Object) drop_indexes

Drop all indexes.



615
616
617
618
619
620
# File 'lib/mongo/collection.rb', line 615

def drop_indexes
  @cache = {}

  # Note: calling drop_indexes with no args will drop them all.
  @db.drop_index(@name, '*')
end

- (String) ensure_index(spec, opts = {})

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.

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

Examples:

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

Returns:

  • (String)

    the name of the index.



585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
# File 'lib/mongo/collection.rb', line 585

def ensure_index(spec, opts={})
  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, options)
  end

  # Reset the cache here in case there are any errors inserting. Best to be safe.
  @cache[name] = now + @cache_time
  name
end

- (Object) find(selector = {}, opts = {})

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.

Parameters:

  • selector (Hash) (defaults to: {})

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

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :fields (Array, Hash)

    field names that should be returned in the result 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.

  • :read (:primary, :secondary)

    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.

  • :skip (Integer)

    number of documents to skip from the beginning of the result set

  • :limit (Integer)

    maximum number of documents to return

  • :sort (Array)

    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)

  • :hint (String, Array, OrderedHash)

    hint for query optimizer, usually not necessary if using MongoDB > 1.1

  • :named_hint (String)

    for specifying a named index as a hint, will be overriden by :hint if :hint is also provided.

  • :snapshot (Boolean) — default: 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 www.mongodb.org/display/DOCS/How+to+do+Snapshotting+in+the+Mongo+Database

  • :batch_size (Boolean) — default: 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.

  • :timeout (Boolean) — default: 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 inadvertent failure to close the cursor, as the cursor is explicitly closed when block code finishes.

  • :max_scan (Integer) — default: nil

    Limit the number of items to scan on both collection scans and indexed queries..

  • :show_disk_loc (Boolean) — default: false

    Return the disk location of each query result (for debugging).

  • :return_key (Boolean) — default: false

    Return the index key used to obtain the result (for debugging).

  • :transformer (Block) — default: 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.

  • :comment (String) — default: nil

    a comment to include in profiling logs

  • :compile_regex (Boolean) — default: true

    whether BSON regex objects should be compiled into Ruby regexes. If false, a BSON::Regex object will be returned instead.

Raises:

  • (ArgumentError)

    if timeout is set to false and find is not invoked in a block

  • (RuntimeError)

    if given unknown options



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
# File 'lib/mongo/collection.rb', line 234

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)
  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."
  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 || 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?
    begin
      yield cursor
    ensure
      cursor.close
    end
    nil
  else
    cursor
  end
end

- (Hash) find_and_modify(opts = {})

Atomically update and return a document using MongoDB's findAndModify command. (MongoDB > 1.3.0)

Parameters:

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :query (Hash) — default: {}

    a query selector document for matching the desired document.

  • :update (Hash) — default: nil

    the update operation to perform on the matched document.

  • :sort (Array, String, OrderedHash) — default: {}

    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.

  • :remove (Boolean) — default: false

    If true, removes the returned document from the collection.

  • :new (Boolean) — default: false

    If true, returns the updated document; otherwise, returns the document prior to update.

  • :upsert (Boolean) — default: false

    If true, creates a new document if the query returns no document.

  • :fields (Hash) — default: 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.

  • :full_response (Boolean) — default: false

    If true, returns the entire response object from the server including ‘ok’ and ‘lastErrorObject’.

Returns:

  • (Hash)

    the matched document.



651
652
653
654
655
656
657
658
659
660
661
662
# File 'lib/mongo/collection.rb', line 651

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]

  full_response ? @db.command(cmd) : @db.command(cmd)['value']
end

- (OrderedHash, Nil) find_one(spec_or_object_id = nil, opts = {})

Return a single object from the database.

Parameters:

  • spec_or_object_id (Hash, ObjectId, Nil) (defaults to: nil)

    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.

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • any (Hash)

    valid options that can be send to Collection#find

Returns:

  • (OrderedHash, Nil)

    a single document or nil if no result is found.

Raises:

  • (TypeError)

    if the argument is of an improper type.



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
# File 'lib/mongo/collection.rb', line 316

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

- (Array) group(opts, condition = {}, initial = {}, reduce = nil, finalize = nil)

Perform a group aggregation.

Parameters:

  • opts (Hash)

    the options for this group operation. The minimum required are :initial and :reduce.

Options Hash (opts):

  • :key (Array, String, Symbol) — default: nil

    Either the name of a field or a list of fields to group by (optional).

  • :keyf (String, BSON::Code) — default: nil

    A JavaScript function to be used to generate the grouping keys (optional).

  • :cond (String, BSON::Code) — default: {}

    A document specifying a query for filtering the documents over which the aggregation is run (optional).

  • :initial (Hash)

    the initial value of the aggregation counter object (required).

  • :reduce (String, BSON::Code) — default: nil

    a JavaScript aggregation function (required).

  • :finalize (String, BSON::Code) — default: 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.

  • :read (:primary, :secondary)

    Read preference indicating which server to perform this group on. See Collection#find for more details.

  • :comment (String) — default: nil

    a comment to include in profiling logs

Returns:

  • (Array)

    the command response consisting of grouped items.



823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
# File 'lib/mongo/collection.rb', line 823

def group(opts, condition={}, initial={}, reduce=nil, finalize=nil)
  opts = opts.dup
  if opts.is_a?(Hash)
    return new_group(opts)
  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 = {
    "group" => {
      "ns"      => @name,
      "$reduce" => reduce,
      "cond"    => condition,
      "initial" => initial
    }
  }

  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

- (Hash) index_information

Get information on the indexes for this collection.

Returns:

  • (Hash)

    a hash where the keys are index names.



1018
1019
1020
# File 'lib/mongo/collection.rb', line 1018

def index_information
  @db.index_information(@name)
end

- (BulkWriteCollectionView) initialize_ordered_bulk_op

Initialize an ordered bulk write view for this collection Execution will stop at the first occurrence of an error for an ordered bulk operation.



371
372
373
# File 'lib/mongo/bulk_write_collection_view.rb', line 371

def initialize_ordered_bulk_op
  BulkWriteCollectionView.new(self, :ordered => true)
end

- (BulkWriteCollectionView) initialize_unordered_bulk_op

Initialize an unordered bulk write view for this collection The unordered bulk operation will be executed and may take advantage of parallelism. There are no guarantees for the order of execution of the operations on the server. Execution will continue even if there are errors for an unordered bulk operation.



381
382
383
# File 'lib/mongo/bulk_write_collection_view.rb', line 381

def initialize_unordered_bulk_op
  BulkWriteCollectionView.new(self, :ordered => false)
end

- (ObjectId, ...) insert(doc_or_docs, opts = {}) Also known as: <<

Insert one or more documents into the collection.

Parameters:

  • doc_or_docs (Hash, Array)

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

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :w (String, Integer, Symbol) — default: 1

    Set default number of nodes to which a write should be acknowledged.

  • :wtimeout (Integer) — default: nil

    Set replica set acknowledgement timeout.

  • :j (Boolean) — default: 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.

  • :fsync (Boolean) — default: 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+.
  • :continue_on_error (Boolean) — default: +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+.

  • :collect_on_error (Boolean) — default: +false+

    if true, then collects invalid documents as an array. Note that this option changes the result format.

Returns:

  • (ObjectId, Array)

    The _id of the inserted document or a list of _ids of all inserted documents.

  • ([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.

Raises:



408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
# File 'lib/mongo/collection.rb', line 408

def insert(doc_or_docs, opts={})
  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

- (Collection, Hash) map_reduce(map, reduce, opts = {}) Also known as: mapreduce

Perform a map-reduce operation on the current collection.

Parameters:

  • map (String, BSON::Code)

    a map function, written in JavaScript.

  • reduce (String, BSON::Code)

    a reduce function, written in JavaScript.

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :query (Hash) — default: {}

    a query selector document, like what’s passed to #find, to limit the operation to a subset of the collection.

  • :sort (Array) — default: []

    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)

  • :limit (Integer) — default: nil

    if passing a query, number of objects to return from the collection.

  • :finalize (String, BSON::Code) — default: nil

    a javascript function to apply to the result set after the map/reduce operation has finished.

  • :out (String, Hash)

    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.

  • :keeptemp (Boolean) — default: 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.

  • :verbose (Boolean) — default: false

    if true, provides statistics on job execution time.

  • :raw (Boolean) — default: 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.

  • :read (:primary, :secondary)

    Read preference indicating which server to run this map-reduce on. See Collection#find for more details.

  • :comment (String) — default: nil

    a comment to include in profiling logs

Returns:

  • (Collection, Hash)

    a Mongo::Collection object or a Hash with the map-reduce command’s results.

Raises:

  • ArgumentError if you specify { :out => { :inline => true }} but don’t specify :raw => true.

See Also:



768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
# File 'lib/mongo/collection.rb', line 768

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)

  hash = BSON::OrderedHash.new
  hash['mapreduce'] = self.name
  hash['map'] = map
  hash['reduce'] = reduce
  hash['out'] = opts.delete(:out)
  hash['sort'] = Mongo::Support.format_order_clause(opts.delete(:sort)) if opts.key?(:sort)

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

- (Object) named_hint=(hint = nil)

Set a hint field using a named index.

Parameters:

  • hint (String) (defaults to: nil)

    index name



163
164
165
166
# File 'lib/mongo/collection.rb', line 163

def named_hint=(hint=nil)
  @hint = hint
  self
end

- (Hash) options

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

Returns:

  • (Hash)

    options that apply to this collection.



1026
1027
1028
# File 'lib/mongo/collection.rb', line 1026

def options
  @db.collections_info(@name).next_document['options']
end

- (Array) parallel_scan(num_cursors, opts = {})

Note:

Requires server version >= 2.5.5

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.

Parameters:

  • num_cursors (Integer)

    the number of cursors to return.

  • opts (Hash) (defaults to: {})

Returns:

  • (Array)

    An array of up to num_cursors cursors for iterating over the collection.



883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
# File 'lib/mongo/collection.rb', line 883

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|
    seed = {
      :cursor_id   => cursor_info['cursor']['id'],
      :first_batch => cursor_info['cursor']['firstBatch'],
      :pool        => @connection.pinned_pool
    }
    Cursor.new(self, seed.merge!(opts))
  end

end

- (Hash, true) remove(selector = {}, opts = {})

Remove all documents from this collection.

Examples:

remove all documents from the ‘users’ collection:

users.remove
users.remove({})

remove only documents that have expired:

users.remove({:expire => {"$lte" => Time.now}})

Parameters:

  • selector (Hash) (defaults to: {})

    If specified, only matching documents will be removed.

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :w (String, Integer, Symbol) — default: 1

    Set default number of nodes to which a write should be acknowledged.

  • :wtimeout (Integer) — default: nil

    Set replica set acknowledgement timeout.

  • :j (Boolean) — default: 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.

  • :fsync (Boolean) — default: 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’.

  • :limit (Integer) — default: 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+.

Returns:

  • (Hash, true)

    Returns a Hash containing the last error object if acknowledging writes Otherwise, returns true.

Raises:



458
459
460
# File 'lib/mongo/collection.rb', line 458

def remove(selector={}, opts={})
  send_write(:delete, selector, nil, nil, opts)
end

- (String) rename(new_name)

Rename this collection.

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

Parameters:

  • new_name (String)

    the new name for this collection

Returns:

  • (String)

    the name of the new collection.

Raises:



992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
# File 'lib/mongo/collection.rb', line 992

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

- (ObjectId) save(doc, opts = {})

Save a document to this collection.

Parameters:

  • doc (Hash)

    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.

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :w (String, Integer, Symbol) — default: 1

    Set default number of nodes to which a write should be acknowledged.

  • :wtimeout (Integer) — default: nil

    Set replica set acknowledgement timeout.

  • :j (Boolean) — default: 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.

  • :fsync (Boolean) — default: 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.

Returns:

  • (ObjectId)

    the _id of the saved document.

Raises:



358
359
360
361
362
363
364
365
366
# File 'lib/mongo/collection.rb', line 358

def save(doc, opts={})
  if doc.has_key?(:_id) || doc.has_key?('_id')
    id = doc[:_id] || doc['_id']
    update({:_id => id}, doc, opts.merge!({:upsert => true}))
    id
  else
    insert(doc, opts)
  end
end

- (Hash) stats

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

Returns:



1033
1034
1035
# File 'lib/mongo/collection.rb', line 1033

def stats
  @db.command({:collstats => @name})
end

- (Hash, true) update(selector, document, opts = {})

Update one or more documents in this collection.

Parameters:

  • selector (Hash)

    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.

  • document (Hash)

    a hash specifying the fields to be changed in the selected document, or (in the case of an upsert) the document to be inserted

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :upsert (Boolean) — default: +false+

    if true, performs an upsert (update or insert)

  • :multi (Boolean) — default: +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.

  • :w (String, Integer, Symbol) — default: 1

    Set default number of nodes to which a write should be acknowledged.

  • :wtimeout (Integer) — default: nil

    Set replica set acknowledgement timeout.

  • :j (Boolean) — default: 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.

  • :fsync (Boolean) — default: 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.

Returns:

  • (Hash, true)

    Returns a Hash containing the last error object if acknowledging writes. Otherwise, returns true.

Raises:



496
497
498
# File 'lib/mongo/collection.rb', line 496

def update(selector, document, opts={})
  send_write(:update, selector, document, !document.keys.first.to_s.start_with?("$"), opts)
end