Method: Mongoid::Findable#find

Defined in:
lib/mongoid/findable.rb

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

Parameters:

  • *args ([ Object | Array<Object> ]...) —

    The id(s) to find.

Returns:

Raises:

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



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