module Mongoid::Findable

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

@since 4.0.0

Public Instance Methods

count() click to toggle source

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

@example Get the count of matching documents.

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

@return [ Integer ] The number of matching documents.

# File lib/mongoid/findable.rb, line 59
def count
  with_default_scope.count
end
empty?() click to toggle source

Returns true if count is zero

@example Are there no saved documents for this model?

Person.empty?

@return [ true, false ] If the collection is empty.

# File lib/mongoid/findable.rb, line 79
def empty?
  count == 0
end
estimated_count() click to toggle source

Returns an estimated count of records in the database.

@example Get the count of matching documents.

Person.estimated_count

@return [ Integer ] The number of matching documents.

# File lib/mongoid/findable.rb, line 69
def estimated_count
  with_default_scope.estimated_count
end
exists?() click to toggle source

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

@example Do any documents exist for the conditions?

Person.exists?

@return [ true, false ] If any documents exist for the conditions.

# File lib/mongoid/findable.rb, line 90
def exists?
  with_default_scope.exists?
end
find(*args) click to toggle source

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.

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

@param [ Object | Array<Object> ] args The _id values to find or an

array thereof.

@return [ Document | Array<Document> | nil ] A document or matching documents.

@raise Errors::DocumentNotFound If not all documents are found and

the +raise_not_found_error+ Mongoid configuration option is truthy.
# File lib/mongoid/findable.rb, line 134
def find(*args)
  with_default_scope.find(*args)
end
find_by(attrs = {}) { |result| ... } click to toggle source

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.

@example Find the document by attribute other than id

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

@param [ Hash ] attrs The attributes to check.

@raise [ Errors::DocumentNotFound ] If no document found and Mongoid.raise_not_found_error is true.

@return [ Document, nil ] A matching document.

@since 3.0.0

# File lib/mongoid/findable.rb, line 154
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| ... } click to toggle source

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

@example Find the document by attribute other than id

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

@param [ Hash ] attrs The attributes to check.

@raise [ Errors::DocumentNotFound ] If no document found.

@return [ Document ] A matching document.

# File lib/mongoid/findable.rb, line 175
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() click to toggle source

Find the first Document given the conditions.

@example Find the first document.

Person.first

@return [ Document ] The first matching document.

# File lib/mongoid/findable.rb, line 188
def first
  with_default_scope.first
end
Also aliased as: one
last() click to toggle source

Find the last Document given the conditions.

@example Find the last document.

Person.last

@return [ Document ] The last matching document.

# File lib/mongoid/findable.rb, line 199
def last
  with_default_scope.last
end
one()
Alias for: first