Specify a Query

Overview

In this guide, you can learn how to use Django MongoDB Backend to specify a database query.

You can refine the set of documents that a query returns by creating a query filter. A query filter is an expression that specifies the search criteria MongoDB uses to match documents in a read or write operation. In a query filter, you can prompt Django MongoDB Backend to search for documents with an exact match to your query, or you can compose query filters to express more complex matching criteria.

Query API

The Django QuerySet API provides methods that allow you to retrieve model objects. To run a MongoDB database query, call QuerySet methods on your model's manager. The Manager class handles database operations and allows you to interact with your MongoDB data by referencing Django models. By default, Django adds a Manager named objects to every model class.

When you assign a QuerySet to a variable, Django MongoDB Backend does not perform the operation until you evaluate the variable. After evaluating the QuerySet, Django saves the query results in the QuerySet cache. Future evaluations of the QuerySet use the cached results.

Tip

To learn more about the Django QuerySet API, see QuerySet in the Django documentation.

Sample Data

The examples in this guide use the Movie model, which represents the sample_mflix.movies collection from the Atlas sample datasets. The Movie model contains an embedded Award model as the value of its awards field. These model classes have the following definitions:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import EmbeddedModelField, ArrayField
class Award(EmbeddedModel):
    wins = models.IntegerField(default=0)
    nominations = models.IntegerField(default=0)
    text = models.CharField(max_length=100)
class Movie(models.Model):
    title = models.CharField(max_length=200)
    plot = models.TextField(blank=True)
    runtime = models.IntegerField(default=0)
    released = models.DateTimeField("release date", null=True, blank=True)
    awards = EmbeddedModelField(Award)
    genres = ArrayField(models.CharField(max_length=100), null=True, blank=True)
    imdb = models.JSONField(null=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

The Movie model includes an inner Meta class, which specifies model metadata, and a __str__() method, which defines the model's string representation. To learn about these model features, see Define a Model in the Create Models guide.

Run Code Examples

You can use the Python interactive shell to run the code examples. To enter the shell, run the following command from your project's root directory:

python manage.py shell

After entering the Python shell, ensure that you import the following models and modules:

from <your application name>.models import Movie, Award
from django.utils import timezone
from datetime import datetime

To learn how to create a Django application that uses the Movie model and the Python interactive shell to interact with MongoDB documents, visit the Get Started with Django MongoDB Backend tutorial.

Run a Query

To query your MongoDB data, call a QuerySet method on your model's manager and specify your matching criteria in a query filter.

This section describes how to use the following methods from the QuerySet API:

all()
filter()
get()
exclude()
raw_aggregate()

Retrieve All Documents

To retrieve all documents from a collection, call the all() method on your model's manager.

The following example calls the all() method to retrieve all documents in the sample_mflix.movies collection:

Movie.objects.all()

<QuerySet [<Movie: The Great Train Robbery>, <Movie: A Corner in Wheat>,
<Movie: Winsor McCay, the Famous Cartoonist of the N.Y. Herald and His Moving Comics>,
<Movie: Traffic in Souls>, <Movie: Gertie the Dinosaur>,
<Movie: In the Land of the Head Hunters>, <Movie: The Perils of Pauline>,
<Movie: The Italian>, <Movie: Regeneration>, <Movie: Civilization>,
'...(remaining elements truncated)...']>

Retrieve Matching Documents

To query a collection for documents that match a set of criteria, call the filter() method on your model's manager. Pass a query filter to the filter() method that specifies your query criteria.

The following example calls the filter() method to query the sample_mflix.movies collection for documents that have a runtime value of 300:

Movie.objects.filter(runtime=300)

<QuerySet [<Movie: Wild Palms>, <Movie: Streets of Laredo>,
<Movie: The Way We Live Now>]>

Retrieve One Document

To retrieve one document from a collection, call the get() method on your model's manager. Pass a query filter to the get() method that specifies your query criteria.

Important

If your query matches no documents or multiple documents, the get() method generates an error. To retrieve one document from a query that might match multiple, use the first() method.

The following example calls the get() method to retrieve one document that has a title value of "Finding Nemo":

Movie.objects.get(title="Finding Nemo")

<Movie: Finding Nemo>

Exclude Matching Documents

To query a collection for documents that do not meet your search criteria, call the exclude() method on your model's manager. Pass the exclusion criteria as an argument to the exclude() method.

The following example calls the exclude() method to exclude documents released before datetime(1980, 1, 1) (January 1, 1980) from the results:

Movie.objects.exclude(released__lt=timezone.make_aware(datetime(1980, 1, 1)))

<QuerySet [<Movie: The Iron Horse>, <Movie: Le grand jeu>,
<Movie: The Devil Is a Woman>, <Movie: Children in the Wind>,
<Movie: Too Much Johnson>, <Movie: Dots>, <Movie: The Blood of Jesus>,
<Movie: The Land>, <Movie: The Brothers and Sisters of the Toda Family>,
<Movie: Begone Dull Care>, '...(remaining elements truncated)...']>

Tip

The preceding example uses the lt field lookup to query the collection. To learn more about comparison lookups, see the Use Comparison Lookups section in this guide.

Run Raw Database Queries

If you want to run complex queries that Django's query API does not support, you can use the raw_aggregate() method. This method allows you to specify your query criteria in a MongoDB aggregation pipeline, which you pass as an argument to raw_aggregate().

To learn how to run raw database queries, see the Perform Raw Database Queries guide.

Customize Your Query Filter

You can further refine your query criteria by using a field lookup in your query filter. Field lookups allow you to clarify the relationship between the field you're querying and the value you want to query for. Use the following syntax to specify a field lookup:

Model.objects.filter(<field name>__<lookup type>=<value>)

You can use different lookup types to perform advanced queries, such as partial text matching, array element queries, regular expression matching, and year value matching for datetime fields.

Tip

To view a full list of lookup types, see Field lookups in the QuerySet Django API reference.

This section describes how to refine your query filters in the following ways:

Use Text Match Lookups
Use Comparison Lookups
Combine Lookups

Use Text Match Lookups

The following table describes some of the lookup types that you can use to run queries that include specific matching criteria for text values:

Lookup Type	Description
`exact`	Specifies an exact text match. If you do not provide a lookup type in your query filter, Django MongoDB Backend uses this type by default. You can specify a case-insensitive exact text match by using `iexact`.
`contains`	Specifies a partial text match. You can specify a case-insensitive partial text match by using `icontains`.
`startswith`	Matches field values that begin with the specified text. You can specify a case-insensitive partial text match by using `istartswith`.
`endswith`	Matches field values that end with the specified text. You can specify a case-insensitive partial text match by using `iendswith`.

Example

The following example uses the contains lookup to query for documents in which the plot value includes the text "coming-of-age":

Movie.objects.filter(plot__contains="coming-of-age")

<QuerySet [<Movie: Murmur of the Heart>, <Movie: Desert Bloom>,
<Movie: Girls Town>, <Movie: Get Real>, <Movie: Man of Steel>,
<Movie: The Holy Land>, <Movie: Secondhand Lions>, <Movie: How to Be Louise>,
<Movie: Mouth to Mouth>, <Movie: Che ne sarè di noi>, <Movie: Roll Bounce>,
'...(remaining elements truncated)...']>

Use Comparison Lookups

The following table describes some of the lookup types that you can use to run queries that evaluate a field value against a specified value:

Lookup Type	Description
`gt`	Matches field values that are greater than the specified value.
`gte`	Matches field values that are greater than or equal to the specified value.
`lt`	Matches field values that are less than the specified value.
`lte`	Matches field values that are less or equal to than the specified value.

Example

The following example uses the lte lookup to query for documents in which the runtime value is less than or equal to 50:

Movie.objects.filter(runtime__lte=50)

<QuerySet [<Movie: The Great Train Robbery>, <Movie: A Corner in Wheat>,
<Movie: Winsor McCay, the Famous Cartoonist of the N.Y. Herald and His Moving Comics>,
<Movie: Gertie the Dinosaur>, <Movie: From Hand to Mouth>,
<Movie: High and Dizzy>, <Movie: One Week>, <Movie: Now or Never>,
'...(remaining elements truncated)...']>

Combine Lookups

You can run queries that use multiple sets of matching criteria in the following ways:

Pass multiple query filters to your query method, separated by commas. To view an example, see Retrieving objects in the Django documentation.
Chain query methods together. To learn more, see Chaining filters in the Django documentation.
Use Q objects and separate each object with a logical operator. To learn more, see Complex lookups with Q objects in the Django documentation.

Q Object Example

You can use Q objects to run queries with multiple sets of matching criteria. To create a Q object, pass your query filter to the Q() method. You can pass multiple Q objects as arguments to your query method and separate each Q object by an OR (|), AND (&), or XOR (^) operator. You can also negate Q objects by prefixing them with the ~ symbol.

This example uses Q objects to query for documents that meet the following query conditions:

title field value begins either with the text "Funny" or "Laugh"
genres array field does not contain the value "Comedy"

Movie.objects.filter(
    (Q(title__startswith="Funny") | Q(title__startswith="Laugh")) 
    & ~Q(genres__contains=["Comedy"])
)

<QuerySet [<Movie: Laugh, Clown, Laugh>, <Movie: Funny Games>]>

Tip

The preceding example uses a field lookup on an ArrayField value. For more information about querying an ArrayField, see the Query an ArrayField section in this guide.

Modify Query Results

This section describes how to modify your query results in the following ways:

Sort Results
Skip and Limit Results
Retrieve the First Result

Sort Results

You can provide a sort order for your query results by using the order_by() method. To specify an ascending sort based on values of a given field, pass the field name as an argument. To specify a descending sort, pass the field name prefixed with a minus symbol (-) as an argument.

You can pass multiple field names, separated by commas, to the order_by() method. Django MongoDB Backend sorts results by each field in the order provided.

Example

This example performs the following actions:

Calls the filter() method on the Movie model's manager to query the sample_mflix.movies collection
Queries documents that have a title value starting with the text "Rocky"
Sorts the results in ascending order of their released field values

Movie.objects.filter(title__startswith="Rocky").order_by("released")

<QuerySet [<Movie: Rocky>, <Movie: Rocky II>, <Movie: Rocky III>,
<Movie: Rocky IV>, <Movie: Rocky V>, <Movie: Rocky Marciano>,
<Movie: Rocky Balboa>]>

Skip and Limit Results

You can specify the number of results that a query returns by using Python's array-slicing syntax, as shown in the following code:

Model.objects.filter(<query filter>)[<start>:<end>]

Replace the <start> and <end> placeholders with integer values representing the subset of results you want to return. The start value is exclusive and the end value is inclusive.

If you omit the <start> value, the query returns each result, beginning with the first match, until it returns the number specified by the <end> value.

If you omit the <end> value, the query returns each result but skips the number of initial results specified by <start>.

Example

This example performs the following actions:

Calls the filter() method on the Movie model's manager to query the sample_mflix.movies collection
Queries documents that have a released value of datetime(2010, 7, 16) (July 16, 2010)
Returns the third and fourth results

Movie.objects.filter(released=timezone.make_aware(datetime(2010, 7, 16)))[2:4]

<QuerySet [<Movie: Inception>, <Movie: Winter's Bone>]>

Retrieve the First Result

To retrieve the first result from a query that might match multiple results, chain the first() method to the filter() method. Pass a query filter to the filter() method that specifies your query criteria.

The following example calls the filter() and first() methods to query the sample_mflix.movies collection for the first document in which the genres value is ["Crime", "Comedy"]:

Movie.objects.filter(genres=["Crime", "Comedy"]).first()

<Movie: The Crew>

Advanced Field Queries

This section describes how to run queries on the following field types:

EmbeddedModelField
ArrayField
JSONField
Primary Key

Query an EmbeddedModelField

You can run operations on your model that query fields of embedded models. To query these fields, specify your model field and each embedded field name separated by double underscores (__) until you reach the field you want to query, as shown in the following code:

Model.objects.filter(<model field>__<embedded model field>=<value>)

You can also use field lookups to refine your embedded model query. Add your lookup type after the embedded model field you're querying, prefixed by double underscores.

Example

This example uses a lookup to query the Award model, which is embedded in the Movie model. This embedded model represents the awards field in the sample_mflix.movies collection and its nested wins, nominations, and text fields. The following code queries for documents in which the awards.wins nested field value is greater than 150:

Movie.objects.filter(awards__wins__gt=150)

<QuerySet [<Movie: The Lord of the Rings: The Return of the King>,
<Movie: No Country for Old Men>, <Movie: Slumdog Millionaire>,
<Movie: Boyhood>, <Movie: The Social Network>, <Movie: Inception>,
<Movie: Gravity>, <Movie: Gravity>, <Movie: The Artist>,
<Movie: 12 Years a Slave>, <Movie: Birdman: Or (The Unexpected Virtue of Ignorance)>]>

Query an ArrayField

You can query data stored in an ArrayField value by using the standard query syntax. Django MongoDB Backend provides additional field lookup types for querying ArrayField values, which are described in the following table:

Lookup Type	Description
`contains`	Matches fields that store the provided value as a subset of their data. This `ArrayField` lookup overrides the `contains` lookup described in the Use Text Match Lookups section of this guide.
`contained_by`	Matches fields that store a subset of the provided values. This lookup type is the inverse of `contains`.
`overlap`	Matches field that store any of the provided values.
`len`	Matches fields that store the number of values provided.

Example

The following example uses the overlap lookup to query for documents whose genres field contains any values in the ["Adventure", "Family"] array:

Movie.objects.filter(genres__overlap=["Adventure", "Family"])

<QuerySet [<Movie: The Poor Little Rich Girl>, <Movie: Robin Hood>,
<Movie: Peter Pan>, <Movie: The Thief of Bagdad>, <Movie: Clash of the Wolves>,
<Movie: Beau Geste>, <Movie: The Black Pirate>, <Movie: The Son of the Sheik>,
<Movie: Steamboat Willie>, <Movie: The Big Trail>, <Movie: The Champ>,
'...(remaining elements truncated)...']>

Query a JSONField

You can query data stored in a JSONField value by using the same syntax as show in the Query an EmbeddedModelField section. Chain each field and nested field name together, separated by double underscores (__), until you reach the field you want to query.

The following example queries the JSONField-valued imdb field for values of its nested votes field that exceed 900000:

Movie.objects.filter(imdb__votes__gt=900000)

<QuerySet [<Movie: La nao capitana>, <Movie: The Godfather>,
<Movie: This Is Spinal Tap>, <Movie: Forrest Gump>, <Movie: Pulp Fiction>,
<Movie: The Shawshank Redemption>, <Movie: Se7en>,
<Movie: The Lord of the Rings: The Fellowship of the Ring>,
<Movie: The Matrix>, <Movie: Fight Club>,
<Movie: The Lord of the Rings: The Return of the King>,
<Movie: The Lord of the Rings: The Two Towers>, <Movie: The Shawshank Redemption>,
<Movie: Landet som icke èr>, <Movie: The Dark Knight>,
<Movie: The Danish Girl>, <Movie: The Dark Knight Rises>, <Movie: Inception>,
<Movie: Catching the Sun>, <Movie: Scouts Guide to the Zombie Apocalypse>,
'...(remaining elements truncated)...']>

Annotate and Filter JSON Data

You can use KT() expressions to annotate and filter data stored in a JSONField value. KT() expressions allow you to work with the text value of keys, indexes, or path transforms within a JSONField. Pass your KT() expression to the annotate() method, which annotates each object in the QuerySet with the provided KT() expressions.

Tip

To learn more about KT() expressions and the annotate() method, see the following resources in the Django documentation:

The following example uses annotate() and KT() to create a new score key, which stores imdb.rating nested field values. Then, the code sorts each document in the sample_mflix.movies collection by their descending score values:

from django.db.models.fields.json import KT
Movie.objects.annotate(score=KT("imdb__rating")).all().order_by("-score")

<QuerySet [<Movie: No Tomorrow>, <Movie: The Deposit>, <Movie: Man Down>,
<Movie: Convenience>, <Movie: Scouts Guide to the Zombie Apocalypse>,
<Movie: Another World>, <Movie: The Danish Girl>, <Movie: Ad Inexplorata>,
<Movie: Landet som icke èr>, <Movie: The Ghost and the Whale>,
<Movie: Coming to Terms>, <Movie: La nao capitana>, <Movie: All Eyes and Ears>,
<Movie: Catching the Sun>, <Movie: Manhattan Romance>, <Movie: Anomalisa>,
<Movie: Outliving Emily>, <Movie: Mary Loss of Soul>,
<Movie: The Childhood of a Leader>, <Movie: Krot na more>,
'...(remaining elements truncated)...']>

Query a Primary Key Field

You can use the pk lookup shortcut to query primary key values, which MongoDB stores as ObjectId values.

The following example queries the sample_mflix.movies collection for a document whose primary key is ObjectId("573a1394f29313caabce0d37"):

from bson import ObjectId
Movie.objects.get(pk=ObjectId("573a1394f29313caabce0d37"))

// Your ObjectId values might differ
<Movie: Vertigo>

The Movie model, which represents the sample_mflix.movies collection, uses the id field as its primary key. The following example constructs the same query as the preceding code by using the id field:

from bson import ObjectId
Movie.objects.get(id=ObjectId("573a1394f29313caabce0d37"))

Additional Information

To learn how to run raw database queries by using MongoDB's aggregation pipeline syntax, see the Perform Raw Database Queries guide.

To learn how to perform other QuerySet operations, see the Perform CRUD Operations guide.

To learn more about Django queries, see Making queries in the Django documentation.

Back

CRUD Operations

Perform Raw Queries