Module: Mongoid::Findable

Extended by:
Forwardable
Defined in:
lib/mongoid/findable.rb

Overview

This module defines the finder methods that hang off the document at the class level.

Instance Method Summary collapse

Instance Method Details

#any? ⇒ true | false

Return true if any documents exist in the criteria.

Examples:

Determine if any documents exist

Model.any?

Returns:

  • If any documents exist.



125
126
127
 
# File 'lib/mongoid/findable.rb', line 125

def any?
  limit(1).count > 0
end

#count ⇒ Integer

Returns a count of records in the database. If you want to specify conditions use where.

Examples:

Get the count of matching documents.

Person.count
Person.where(title: "Sir").count

Returns:

  • The number of matching documents.



74
75
76
 
# File 'lib/mongoid/findable.rb', line 74

def count
  with_default_scope.count
end

#empty? ⇒ true | false

Returns true if count is zero

Examples:

Are there no saved documents for this model?

Person.empty?

Returns:

  • If the collection is empty.



94
95
96
 
# File 'lib/mongoid/findable.rb', line 94

def empty?
  count == 0
end

#estimated_count ⇒ Integer

Returns an estimated count of records in the database.

Examples:

Get the count of matching documents.

Person.estimated_count

Returns:

  • The number of matching documents.



84
85
86
 
# File 'lib/mongoid/findable.rb', line 84

def estimated_count
  with_default_scope.estimated_count
end

#exists?(id_or_conditions = :none) ⇒ true | false

Returns true if there are on document in database based on the provided arguments.

Examples:

Do any documents exist for the conditions?

Person.exists?

Do any documents exist for given _id.

Person.exists?(BSON::ObjectId(...))

Do any documents exist for given conditions.

Person.exists?(name: "...")

Parameters:

  • (defaults to: :none)

    an _id to search for, a hash of conditions, nil or false.

Returns:

  • If any documents exist for the conditions. Always false if passed nil or false.



115
116
117
 
# File 'lib/mongoid/findable.rb', line 115

def exists?(id_or_conditions = :none)
  with_default_scope.exists?(id_or_conditions)
end

#find(*args, &block) ⇒ Document | Array<Document> | nil

Note:

Each argument can be an individual id, an array of ids or a nested array. Each array will be flattened.

Finds a Document or multiple documents by their _id values.

If a single non-Array argument is given, this argument is interpreted as the _id value of a document to find. If there is a matching document in the database, this document is returned; otherwise, if the raise_not_found_error Mongoid configuration option is truthy (which is the default), Errors::DocumentNotFound is raised, and if raise_not_found_error is falsy, find returns nil.

If multiple arguments are given, or an Array argument is given, the array is flattened and each array element is interpreted as the _id value of the document to find. Mongoid then attempts to retrieve all documents with the provided _id values. The return value is an array of found documents. Each document appears one time in the returned array, even if its _id is given multiple times in the argument to find. If the raise_not_found_error Mongoid configuration option is truthy, Errors::DocumentNotFound exception is raised if any of the specified _ids were not found in the database. If the raise_not_found_error Mongoid configuration option is falsy, only those documents which are found are returned; if no documents are found, the return value is an empty array.

Note that MongoDB does not allow the _id field to be an array.

The argument undergoes customary Mongoid type conversions based on the type declared for the _id field. By default the _id field is a BSON::ObjectId; this allows strings to be passed to find and the strings will be transparently converted to BSON::ObjectId instances during query construction.

If this method is given a block, it delegates to Enumerable#find and returns the first document of those found by the current Criteria object for which the block returns a truthy value. If both a block and ids are given, the block is ignored and the documents for the given ids are returned. If a block and a Proc are given, the method delegates to Enumerable#find and uses the proc as the default.

The find method takes into account the default scope defined on the model class, if any.

Raises:

  • Errors::DocumentNotFound If not all documents are found and the raise_not_found_error Mongoid configuration option is truthy.

Parameters:

  • The id(s) to find.

Returns:

  • A document or matching documents.



198
199
200
201
202
203
204
205
 
# File 'lib/mongoid/findable.rb', line 198

def find(*args, &block)
  empty_or_proc = args.empty? || (args.length == 1 && args.first.is_a?(Proc))
  if block_given? && empty_or_proc
    with_default_scope.find(*args, &block)
  else
    with_default_scope.find(*args)
  end
end

#find_by(attrs = {}) {|result| ... } ⇒ Document | nil

Find the first Document given the conditions. If a matching Document is not found and Mongoid.raise_not_found_error is true it raises Mongoid::Errors::DocumentNotFound, return null nil elsewise.

and Mongoid.raise_not_found_error is true.

Examples:

Find the document by attribute other than id

Person.find_by(:username => "superuser")

Yields:

  • (result)

Raises:

  • If no document found

Parameters:

  • (defaults to: {})

    The attributes to check.

Returns:

  • A matching document.



221
222
223
224
225
226
227
228
 
# File 'lib/mongoid/findable.rb', line 221

def find_by(attrs = {})
  result = where(attrs).find_first
  if result.nil? && Mongoid.raise_not_found_error
    raise(Errors::DocumentNotFound.new(self, attrs))
  end
  yield(result) if result && block_given?
  result
end

#find_by!(attrs = {}) {|result| ... } ⇒ Document

Find the first Document given the conditions, or raises Mongoid::Errors::DocumentNotFound

Examples:

Find the document by attribute other than id

Person.find_by(:username => "superuser")

Yields:

  • (result)

Raises:

  • If no document found.

Parameters:

  • (defaults to: {})

    The attributes to check.

Returns:

  • A matching document.



241
242
243
244
245
246
 
# File 'lib/mongoid/findable.rb', line 241

def find_by!(attrs = {})
  result = where(attrs).find_first
  raise(Errors::DocumentNotFound.new(self, attrs)) unless result
  yield(result) if result && block_given?
  result
end

#first(limit = nil) ⇒ Document Also known as: one

Find the first Document given the conditions.

Examples:

Find the first document.

Person.first

Parameters:

  • (defaults to: nil)

    The number of documents to return.

Returns:

  • The first matching document.



256
257
258
 
# File 'lib/mongoid/findable.rb', line 256

def first(limit = nil)
  with_default_scope.first(limit)
end

#last(limit = nil) ⇒ Document

Find the last Document given the conditions.

Examples:

Find the last document.

Person.last

Parameters:

  • (defaults to: nil)

    The number of documents to return.

Returns:

  • The last matching document.



269
270
271
 
# File 'lib/mongoid/findable.rb', line 269

def last(limit = nil)
  with_default_scope.last(limit)
end

#many? ⇒ true | false

Return true if more than one document exists in the criteria.

Examples:

Determine if many documents exist

Model.many?

Returns:

  • If many documents exist.



145
146
147
 
# File 'lib/mongoid/findable.rb', line 145

def many?
  limit(2).count > 1
end

#one? ⇒ true | false

Return true if only one document exists in the criteria.

Examples:

Determine if only one document exists

Model.one?

Returns:

  • If only one document exists.



135
136
137
 
# File 'lib/mongoid/findable.rb', line 135

def one?
  limit(2).count == 1
end