Class: Mongoid::Collection

Inherits:
Object show all
Defined in:
lib/mongoid/collection.rb

Overview

This class is the Mongoid wrapper to the Mongo Ruby driver’s collection object.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(klass, name) ⇒ Collection

Initialize a new Mongoid::Collection, setting up the master, slave, and name attributes. Masters will be used for writes, slaves for reads.

Examples:

Create the new collection.

Collection.new(masters, slaves, "test")

Parameters:

  • klass (Class) —

    The class the collection is for.

  • name (String) —

    The name of the collection.



82
83
84
 
# File 'lib/mongoid/collection.rb', line 82

def initialize(klass, name)
  @klass, @name = klass, name
end

Instance Attribute Details

#counter ⇒ Object (readonly)

Returns the value of attribute counter.



13
14
15
 
# File 'lib/mongoid/collection.rb', line 13

def counter
  @counter
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



13
14
15
 
# File 'lib/mongoid/collection.rb', line 13

def name
  @name
end

Instance Method Details

#directed(options = {}) ⇒ Master, Slaves

Determines where to send the next read query. If the slaves are not defined then send to master. If the read counter is under the configured maximum then return the master. In any other case return the slaves.

Examples:

Send the operation to the master or slaves.

collection.directed

Parameters:

  • options (Hash) (defaults to: {}) —

    The operation options.

Options Hash (options):

  • :cache (true, false) —

    Should the query cache in memory?

  • :enslave (true, false) —

    Send the write to the slave?

Returns:

  • (Master, Slaves) —

    The connection to use.



37
38
39
40
41
 
# File 'lib/mongoid/collection.rb', line 37

def directed(options = {})
  options.delete(:cache)
  enslave = options.delete(:enslave) || @klass.enslaved?
  enslave ? master_or_slaves : master
end

#find(selector = {}, options = {}) ⇒ Cursor

Find documents from the database given a selector and options.

Examples:

Find documents in the collection.

collection.find({ :test => "value" })

Parameters:

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

    The query selector.

  • options (Hash) (defaults to: {}) —

    The options to pass to the db.

Returns:



52
53
54
55
56
57
58
59
 
# File 'lib/mongoid/collection.rb', line 52

def find(selector = {}, options = {})
  cursor = Mongoid::Cursor.new(@klass, self, directed(options).find(selector, options))
  if block_given?
    yield cursor; cursor.close
  else
    cursor
  end
end

#find_one(selector = {}, options = {}) ⇒ Document?

Find the first document from the database given a selector and options.

Examples:

Find one document.

collection.find_one({ :test => "value" })

Parameters:

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

    The query selector.

  • options (Hash) (defaults to: {}) —

    The options to pass to the db.

Returns:

  • (Document, nil) —

    A matching document or nil if none found.



70
71
72
 
# File 'lib/mongoid/collection.rb', line 70

def find_one(selector = {}, options = {})
  directed(options).find_one(selector, options)
end

#map_reduce(map, reduce, options = {}) ⇒ Cursor Also known as: mapreduce

Perform a map/reduce on the documents.

Examples:

Perform the map/reduce.

collection.map_reduce(map, reduce)

Parameters:

  • map (String) —

    The map javascript function.

  • reduce (String) —

    The reduce javascript function.

  • options (Hash) (defaults to: {}) —

    The options to pass to the db.

Returns:



96
97
98
 
# File 'lib/mongoid/collection.rb', line 96

def map_reduce(map, reduce, options = {})
  directed(options).map_reduce(map, reduce, options)
end

#master ⇒ Master

Return the object responsible for writes to the database. This will always return a collection associated with the Master DB.

Examples:

Get the master connection.

collection.master

Returns:

  • (Master) —

    The master connection.



108
109
110
111
 
# File 'lib/mongoid/collection.rb', line 108

def master
  db = Mongoid.databases[@klass.database] || Mongoid.master
  @master ||= Collections::Master.new(db, @name)
end

#slaves ⇒ Slaves

Return the object responsible for reading documents from the database. This is usually the slave databases, but in their absence the master will handle the task.

Examples:

Get the slaves array.

collection.slaves

Returns:

  • (Slaves) —

    The pool of slave connections.



121
122
123
124
 
# File 'lib/mongoid/collection.rb', line 121

def slaves
  slaves = Mongoid.databases["#{@klass.database}_slaves"] || Mongoid.slaves
  @slaves ||= Collections::Slaves.new(slaves, @name)
end

#update(selector, document, options = {}) ⇒ Object

Updates one or more documents in the collection.

Examples:

Update documents.

collection.update(
  { "_id" => BSON::OjectId.new },
  { "$push" => { "addresses" => { "_id" => "street" } } },
  :safe => true
)

Parameters:

  • selector (Hash) —

    The document selector.

  • document (Hash) —

    The modifier.

  • options (Hash) (defaults to: {}) —

    The options.

Since:

  • 2.0.0



140
141
142
143
144
145
146
147
 
# File 'lib/mongoid/collection.rb', line 140

def update(selector, document, options = {})
  updater = Thread.current[:mongoid_atomic_update]
  if updater
    updater.consume(selector, document, options)
  else
    master.update(selector, document, options)
  end
end