Specify a Query

Sample Data

The examples in this guide use the Band model, which represents a band or musical group. The definition of the Band model might be different for each section to demonstrate different query functionalities. Some sections might use other models to demonstrate query functionality.

Field Syntax

The field querying syntax uses the basic Ruby hashes. The keys can be symbols or strings and correspond to field names in MongoDB documents.

The following code shows two equivalent queries that use field querying syntax to retrieve documents in which the name field value is 'Depeche Mode':

Band.where(name: 'Depeche Mode')
Band.where('name' => 'Depeche Mode')

Query API Syntax

You can specify a Query API operator on any field by using the hash syntax, as shown by the following equivalent queries:

Band.where(founded: {'$gt' => 1980})
Band.where('founded' => {'$gt' => 1980})

Symbol Operator Syntax

You can specify Query API operators as methods on symbols for the respective field name, as shown in the following code:

Band.where(:founded.gt => 1980)

Defined Fields

To query on a field, the field does not need to be in the the model class definition. However, if a field is defined in the model class, Mongoid coerces query values to match the defined field types when constructing the query.

The following code specifies a string value when querying on the founded field. Because the founded field is defined in the model class to have Integer values, Mongoid coerces the string '2020' to 2020 when performing the query:

Band.where(founded: '2020')

To learn more about defining fields in Mongoid, see the Field Types guide.

Raw Values

To bypass Mongoid's query type coercion behavior and query directly for the raw-typed value in the database, wrap the query value in the Mongoid::RawValue class, as shown in the following code:

Band.where(founded: Mongoid::RawValue('2020'))

Field Aliases

Queries follow the storage field names and field aliases that you might have set in your model class definition.

The id and _id fields are aliases, so you can use either field name in queries:

Band.where(id: '5ebdeddfe1b83265a376a760')
Band.where(_id: '5ebdeddfe1b83265a376a760')

Embedded Documents

To query on values of fields of embedded documents, you can use dot notation. The following code retrieves documents in which the name field of the embedded Manager document is 'Smith':

Band.where('manager.name' => 'Smith')

The following code demonstrates how to use a symbol operator when querying on an embedded field:

Band.where(:'manager.name'.ne => 'Smith')

Operator Combinations

The logical operators have the the same semantics as those from Active Record.

When conditions are specified on the same field multiple times, all conditions are added to the criteria, as shown by the queries in the following code:

# Combines as "and"
Band.where(name: 'Swans').where(name: 'Feist')
# Combines as "or"
Band.where(name: 'Swans').or(name: 'Feist')

The any_of, none_of, nor, and not operations behave similarly.

When you use and, or, and nor logical operators, they operate on the criteria built up to that point:

# "or" applies to the first condition, and the second is combined
# as "and"
Band.or(name: 'Sun').where(label: 'Trust')
# Same as previous example - "where" and "and" are aliases
Band.or(name: 'Sun').and(label: 'Trust')
# Same operator can be stacked any number of times
Band.or(name: 'Sun').or(label: 'Trust')
# The last label condition is added to the top level as "and"
Band.where(name: 'Sun').or(label: 'Trust').where(label: 'Feist')
# Interpreted query:
# {"$or"=>[{"name"=>"Sun"}, {"label"=>"Trust"}], "label"=>"Feist"}

not Behavior

You can use the not method without arguments, in which case it negates the next condition that is specified. The not method can be called with one or more hash conditions or Criteria objects, which are all negated and added to the criteria.

The following examples demonstrate the behavior of not:

# "not" negates "where"
Band.not.where(name: 'Best')
# The second "where" is added as "$and"
Band.not.where(name: 'Best').where(label: /Records/)
# "not" negates its argument
Band.not(name: 'Best')

# String negation - uses "$ne"
Band.not.where(name: 'Best')
 
# Regex negation - uses "$not"
Band.not.where(name: /Best/)

Similarly to and, the not operation negates individual conditions for simple field criteria. For complex conditions and when a field already has a condition defined on it, Mongoid emulates $not by using an {'$and' => [{'$nor' => ...}]} construct, because MongoDB supports the $not operator only on a per-field basis rather than globally:

# Simple condition
Band.not(name: /Best/)
# Complex conditions
Band.where(name: /Best/).not(name: 'Astral Projection')
# Symbol operator syntax
Band.not(:name.ne => 'Astral Projection')

If you are using not with arrays or regular expressions, view the limitations of $not in the Server manual.

Merge Strategies

Mongoid provides the following merge strategies:

• Override: The new operator instance replaces any existing conditions on the same field by using the same operator.

• Intersect: If there already is a condition using the same operator on the same field, the values of the existing condition are intersected with the values of the new condition and the result is stored as the operator value.

• Union: If there already is a condition using the same operator on the same field, the values of the new condition are added to the values of the existing condition and the result is stored as the operator value.

The following code demonstrates how the merge strategies produce criteria by using in as the example operator:

Band.in(name: ['a']).override.in(name: ['b'])
# Interpreted query:
# {"name"=>{"$in"=>["b"]}}
Band.in(name: ['a', 'b']).intersect.in(name: ['b', 'c'])
# Interpreted query:
# {"name"=>{"$in"=>["b"]}}
Band.in(name: ['a']).union.in(name: ['b'])
# Interpreted query:
# {"name"=>{"$in"=>["a", "b"]}}

The strategy is requested by calling override, intersect or union on a Criteria instance. The requested strategy applies to the next condition method called on the query. If the next condition method called does not support merge strategies, the strategy is reset, as shown in the following example:

Band.in(name: ['a']).union.ne(name: 'c').in(name: ['b'])
# Interpreted query:
# {"name"=>{"$in"=>["a"], "$ne"=>"c"}, "$and"=>[{"name"=>{"$in"=>["b"]}}]}

Because ne does not support merge strategies, the union strategy is ignored and reset. Then, when in is invoked the second time, there is no active strategy.

Supported Operator Methods

The following operator methods support merge strategies:

• all

• in

• nin

The set of methods might be expanded in future releases of Mongoid. To ensure future compatibility, invoke a strategy method only when the next method call is an operator that supports merge strategies.

Merge strategies are applied only when conditions are added through the designated methods. In the following example, the merge strategy is not applied because the second condition is added as where, not by using in:

Band.in(name: ['a']).union.where(name: {'$in' => 'b'})
# Interpreted query:
# {"foo"=>{"$in"=>["a"]}, "$and"=>[{"foo"=>{"$in"=>"b"}}]}

Operator Value Expansion

Operator methods that support merge strategies take Array as their value type. Mongoid expands Array-compatible types, such as a Range, when they are used with these operator methods.

The following example demonstrates how you can pass a Range object as the query value when using the in method:

Band.in(year: 1950..1960)
# Interpreted query:
# {"year"=>{"$in"=>[1950, 1951, 1952, 1953, 1954, 1955, 1956, 1957, 1958, 1959, 1960]}}

Mongoid wraps non-Array values in arrays, as the shown in the following example:

Band.in(year: 1950)
# Interpreted query: {"year"=>{"$in"=>[1950]}}

Associations

You can use the elem_match method to match embedded associations.

This example uses the following models that define an embedded association between Band and Tour:

class Band
    include Mongoid::Document
    field :name, type: String
    embeds_many :tours
end
class Tour
  include Mongoid::Document
  field :city, type: String
  field :year, type: Integer
  embedded_in :band
end

The following code creates a Band object and embedded Tour objects, then uses the elem_match method to query on the city field:

aerosmith = Band.create!(name: 'Aerosmith')
Tour.create!(band: aerosmith, city: 'London', year: 1995)
Tour.create!(band: aerosmith, city: 'New York', year: 1999)
# Returns the "Aerosmith" document
Band.elem_match(tours: {city: 'London'})

You can use elem_match to query recursively embedded associations, as shown in the following example:

class Tag
    include Mongoid::Document
    field name:, type: String
    recursively_embeds_many
end
# Creates the root Tag
root = Tag.create!(name: 'root')
# Adds embedded Tags
sub1 = Tag.new(name: 'sub_tag_1', child_tags: [Tag.new(name: 'sub_sub_tag_1')])
root.child_tags << sub1
root.child_tags << Tag.new(name: 'sub_tag_2')
root.save!
# Searches for Tag in which one child Tag tame is "sub_tag_1"
Tag.elem_match(child_tags: {name: 'sub_tag_1'})
# Searches for a child Tag in which one child Tag tame is "sub_sub_tag_1"
root.child_tags.elem_match(child_tags: {name: 'sub_sub_tag_1'})

To learn more about associations, see the Associations guide.

Count Documents

You can use the count and estimated_count methods to count the number of documents in a collection.

You can count the number of documents that match filter criteria by using the count method:

# Counts all documents in collection
Band.count
# Counts documents that match criteria
Band.where(country: 'England').count

You can get an approximate number of documents in the collection from the collection metadata by using the estimated_count method:

Band.estimated_count

The estimated_count method does not accept query conditions, including conditions set by a scope on the model. If you are calling this method on a model that has a default scope, you must first call the unscoped method to disable the scope.

Ordinal Methods

The methods described in the following list allow you to select a specific result from the list of returned documents based on its position.

• first: Returns the first matching document. You can get the first n documents by passing an integer-valued parameter. This method automatically uses a sort on the _id field. See lines 1-8 in the following code for examples.

• last: Returns the last matching document. You can get the last n documents by passing an integer-valued parameter. This method automatically uses a sort on the _id field. See line 11 in the following code for an example.

• first_or_create: Returns the first matching document. If no document matches, creates and returns a newly saved one.

• first_or_initialize: Returns the first matching document. If no document matches, returns a new one.

• second: Returns the second matching document. Automatically uses a sort on the _id field.

• third: Returns the third matching document. Automatically uses a sort on the _id field.

• fourth: Returns the fourth matching document. Automatically uses a sort on the _id field.

• fifth: Returns the fifth matching document. Automatically uses a sort on the _id field.

• second_to_last: Returns the second-to-last matching document. Automatically uses a sort on the _id field. See line 14 in the following code for an example.

• third_to_last: Returns the third-to-last matching document. Automatically uses a sort on the _id field.

The following code demonstrates how to use some methods described in the preceding list:

1
# Returns the first document in the collection
2
Band.first
3
4
# Returns the first matching document
5
Band.where(founded: {'$gt' => 1980}).first
6
7
# Returns the first two matching documents
8
Band.first(2)
9
10
# Returns the last matching document
11
Band.where(founded: {'$gt' => 1980}).last
12
13
# Returns the second to last document
14
Band.second_to_last

Survey Field Values

To inspect the values of specified fields of documents in a collection, you can use the following methods:

• distinct: Gets a list of distinct values for a single field. See lines 1-7 in the following code for examples.

• pick: Gets the values from one document for the provided fields. Returns nil for unset fields and for non-existent fields. See line 10 in the following code for an example.

• pluck: Gets all values for the provided field. Returns nil for unset fields and for non-existent fields. See line 13 in the following code for an example.

• tally: Gets a mapping of values to counts for the specified field. See line 16 in the following code for an example.

The preceding methods accept field names referenced by using dot notation, which allows you to reference fields in embedded associations. They also respect field aliases, including those defined in embedded documents.

The following code demonstrates how to use these methods:

1
Band.distinct(:name)
2
# Example output: "Ghost Mountain" "Hello Goodbye" "She Said"
3
4
Band.where(:members.gt => 2).distinct(:name)
5
# Example output: "Arctic Monkeys" "The Smiths"
6
7
Band.distinct('tours.city')
8
# Example output: "London" "Sydney" "Amsterdam"
9
10
Band.all.pick(:name)
11
# Example output: "The Smiths"
12
13
Band.all.pluck(:country)
14
# Example output: "England" "Spain" "England" "Japan"
15
16
Band.all.tally(:country)
17
# Example output: ["England",2] ["Italy",3]

Miscellaneous

The following list describes Mongoid methods that do not fit into another category:

• each: Iterates over all matching documents.

# Print each matching document "name" to console
Band.where(:members.gt => 1).each do |band|
  p band.name
end

• exists?: Determines if any matching documents exist, returning true if at least one matching document is found.

# Checks existence of any document
Band.exists?
# Checks existence based on query
Band.where(name: "Le Tigre").exists?
Band.exists?(name: "Le Tigre")
# Checks existence based on "_id" value
Band.exists?('6320d96a3282a48cfce9e72c')
# Always returns false
Band.exists?(false)
Band.exists?(nil)