Class: Mongoid::Criteria

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

Overview

The Criteria class is the core object needed in Mongoid to retrieve objects from the database. It is a DSL that essentially sets up the selector and options arguments that get passed on to a Mongo::Collection in the Ruby driver. Each method on the Criteria returns self to they can be chained in order to create a readable criterion to be executed against the database.

Example setup:

criteria = Criteria.new

criteria.select(:field => "value").only(:field).skip(20).limit(20)

criteria.execute

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(type) ⇒ Criteria

Create the new Criteria object. This will initialize the selector and options hashes, as well as the type of criteria.

Options:

type: One of :all, :first:, or :last



132
133
134
 
# File 'lib/mongoid/criteria.rb', line 132

def initialize(type)
  @selector, @options, @type = {}, {}, type
end

Instance Attribute Details

#options ⇒ Object (readonly)

Returns the value of attribute options.



17
18
19
 
# File 'lib/mongoid/criteria.rb', line 17

def options
  @options
end

#selector ⇒ Object (readonly)

Returns the value of attribute selector.



17
18
19
 
# File 'lib/mongoid/criteria.rb', line 17

def selector
  @selector
end

#type ⇒ Object (readonly)

Returns the value of attribute type.



17
18
19
 
# File 'lib/mongoid/criteria.rb', line 17

def type
  @type
end

Class Method Details

.translate(*args) ⇒ Object

Translate the supplied arguments into a Criteria object.

If the passed in args is a single String, then it will construct an id Criteria from it.

If the passed in args are a type and a hash, then it will construct the Criteria with the proper selector, options, and type.

Options:

args: either a String or a Symbol, +Hash combination.

Example:

Criteria.translate("4ab2bc4b8ad548971900005c")

Criteria.translate(:all, :conditions => { :field => "value"}, :limit => 20)

Returns a new Criteria object.



262
263
264
265
266
 
# File 'lib/mongoid/criteria.rb', line 262

def self.translate(*args)
  type, params = args[0], args[1] || {}
  return new(:first).id(type.to_s) if type.is_a?(String)
  return new(type).select(params.delete(:conditions)).extras(params)
end

Instance Method Details

#all(selections = {}) ⇒ Object

Adds a criterion to the Criteria that specifies values that must all be matched in order to return results. Similar to an “in” clause but the underlying conditional logic is an “AND” and not an “OR”. The MongoDB conditional operator that will be used is “$all”.

Options:

selections: A Hash where the key is the field name and the value is an Array of values that must all match.

Example:

criteria.all(:field => ["value1", "value2"])

criteria.all(:field1 => ["value1", "value2"], :field2 => ["value1"])

Returns: self



36
37
38
 
# File 'lib/mongoid/criteria.rb', line 36

def all(selections = {})
  selections.each { |key, value| @selector[key] = { "$all" => value } }; self
end

#excludes(exclusions = {}) ⇒ Object

Adds a criterion to the Criteria that specifies values that are not allowed to match any document in the database. The MongoDB conditional operator that will be used is “$ne”.

Options:

excludes: A Hash where the key is the field name and the value is a value that must not be equal to the corresponding field value in the database.

Example:

criteria.excludes(:field => "value1")

criteria.excludes(:field1 => "value1", :field2 => "value1")

Returns: self



56
57
58
 
# File 'lib/mongoid/criteria.rb', line 56

def excludes(exclusions = {})
  exclusions.each { |key, value| @selector[key] = { "$ne" => value } }; self
end

#execute(klass) ⇒ Object

Execute the criteria. This will take the internally built selector and options and pass them on to the Ruby driver’s find() method on the collection. The collection itself will be retrieved from the class provided, and once the query has returned new documents of the type of class provided will be instantiated.

If this is a Criteria to only find the first object, this will return a single object of the type of class provided.

If this is a Criteria to find multiple results, will return an Array of objects of the type of class provided.



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

def execute(klass)
  return klass.new(klass.collection.find_one(@selector, @options)) if type == :first
  return klass.collection.find(@selector, @options).collect { |doc| klass.new(doc) }
end

#extras(extras) ⇒ Object

Adds a criterion to the Criteria that specifies additional options to be passed to the Ruby driver, in the exact format for the driver.

Options:

extras: A Hash that gets set to the driver options.

Example:

criteria.extras(:limit => 20, :skip => 40)

Returns: self



87
88
89
 
# File 'lib/mongoid/criteria.rb', line 87

def extras(extras)
  @options = extras; self
end

#id(object_id) ⇒ Object

Adds a criterion to the Criteria that specifies an id that must be matched.

Options:

object_id: A String representation of a Mongo::ObjectID

Example:

criteria.id("4ab2bc4b8ad548971900005c")

Returns: self



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

def id(object_id)
  @selector[:_id] = Mongo::ObjectID.from_string(object_id); self
end

#in(inclusions = {}) ⇒ Object

Adds a criterion to the Criteria that specifies values where any can be matched in order to return results. This is similar to an SQL “IN” clause. The MongoDB conditional operator that will be used is “$in”.

Options:

inclusions: A Hash where the key is the field name and the value is an Array of values that any can match.

Example:

criteria.in(:field => ["value1", "value2"])

criteria.in(:field1 => ["value1", "value2"], :field2 => ["value1"])

Returns: self



107
108
109
 
# File 'lib/mongoid/criteria.rb', line 107

def in(inclusions = {})
  inclusions.each { |key, value| @selector[key] = { "$in" => value } }; self
end

#limit(value = 20) ⇒ Object

Adds a criterion to the Criteria that specifies the maximum number of results to return. This is mostly used in conjunction with skip() to handle paginated results.

Options:

value: An Integer specifying the max number of results. Defaults to 20.

Example:

criteria.limit(100)

Returns: self



149
150
151
 
# File 'lib/mongoid/criteria.rb', line 149

def limit(value = 20)
  @options[:limit] = value; self
end

#not_in(exclusions) ⇒ Object

Adds a criterion to the Criteria that specifies values where none should match in order to return results. This is similar to an SQL “NOT IN” clause. The MongoDB conditional operator that will be used is “$nin”.

Options:

exclusions: A Hash where the key is the field name and the value is an Array of values that none can match.

Example:

criteria.not_in(:field => ["value1", "value2"])

criteria.not_in(:field1 => ["value1", "value2"], :field2 => ["value1"])

Returns: self



188
189
190
 
# File 'lib/mongoid/criteria.rb', line 188

def not_in(exclusions)
  exclusions.each { |key, value| @selector[key] = { "$nin" => value } }; self
end

#only(*args) ⇒ Object

Adds a criterion to the Criteria that specifies the fields that will get returned from the Document. Used mainly for list views that do not require all fields to be present. This is similar to SQL “SELECT” values.

Options:

params: A list of field names to retrict the returned fields to.

Example:

criteria.only(:field1, :field2, :field3)

Returns: self



221
222
223
 
# File 'lib/mongoid/criteria.rb', line 221

def only(*args)
  @options[:fields] = args.flatten; self
end

#order_by(params = []) ⇒ Object

Adds a criterion to the Criteria that specifies the sort order of the returned documents in the database. Similar to a SQL “ORDER BY”.

Options:

params: An Array of [field, direction] sorting pairs.

Example:

criteria.order_by([[:field1, :asc], [:field2, :desc]])

Returns: self



204
205
206
 
# File 'lib/mongoid/criteria.rb', line 204

def order_by(params = [])
  @options[:sort] = params; self
end

#select(selector = {}) ⇒ Object

Adds a criterion to the Criteria that specifies values that must be matched in order to return results. This is similar to a SQL “WHERE” clause. This is the actual selector that will be provided to MongoDB, similar to the Javascript object that is used when performing a find() in the MongoDB console.

Options:

selectior: A Hash that must match the attributes of the Document.

Example:

criteria.select(:field1 => "value1", :field2 => 15)

Returns: self



168
169
170
 
# File 'lib/mongoid/criteria.rb', line 168

def select(selector = {})
  @selector = selector; self
end

#skip(value = 0) ⇒ Object

Adds a criterion to the Criteria that specifies how many results to skip when returning Documents. This is mostly used in conjunction with limit() to handle paginated results, and is similar to the traditional “offset” parameter.

Options:

value: An Integer specifying the number of results to skip. Defaults to 0.

Example:

criteria.skip(20)

Returns: self



239
240
241
 
# File 'lib/mongoid/criteria.rb', line 239

def skip(value = 0)
  @options[:skip] = value; self
end