Get Started

Install

• Install the latest version of djongo from:

  pip install --extra-index-url https://pypi.djongomapper.com/latest-updates/ djongo

• Into settings.py file of your project, add:

  DATABASES = {
      'default': {
          'ENGINE': 'djongo',
          'NAME': 'your-db-name',
      }
  }

Prerequisites

• You have a DjongoCS account.
• Your access tokens have been successfully setup.
• Alternatively, you can install an older version directly from pypi:

  pip install djongo

• Or, from github:

pip install git+https://github.com/djongo/djongo.git

Models

A Model is the single, canonical source of information about the data your application stores. It is defined as a Python class that subclasses djongo.models.Model. Each attribute of the class represents a MongoDB document field.

Each model maps to one MongoDB collection and encapsulates the structure and behavior of that collection in one place. Because models are plain Python classes, you can add helper methods and properties to encapsulate domain logic close to the data they operate on.

Defining models in code makes your schema explicit, reviewable, and easy to test. More details on models can be found here

from djongo import models

class Article(models.Model):
    title = models.CharField(max_length=200)
    body = models.TextField()
    published_on = models.DateTimeField(null=True, blank=True)

Fields

Fields are the building blocks of models. Djongo supports all of Django field types, for example CharField, TextField, IntegerField, BooleanField, and DateTimeField. Each field accepts options such as max_length, blank, null, default, and choices to control validation and storage behavior.

Models also express relationships at the schema level using ForeignKey, OneToOneField, and ManyToManyField. The inner Meta class lets you provide model-wide configuration such as verbose_name, custom database table names, and ordering preferences.

Djongo adds extra fields for supporting MongoDB features like embedded documents.

from djongo import models

class Author(models.Model):
    name = models.CharField(max_length=100)

class Post(models.Model):
    author = models.ForeignKey(Author, on_delete=models.CASCADE)
    title = models.CharField(max_length=255)
    tags = models.ManyToManyField('Tag', blank=True)

    class Meta:
        verbose_name = "blog post"
        ordering = ['-id']

EmbeddedField

The EmbeddedField lets you embed a document inside a document. Use it for creating MongoDB embedded documents. Nest a dict inside a model with the EmbeddedField. The model_container is used to describe the structure of the data stored.

from djongo import models

class Blog(models.Model):
    name = models.CharField(max_length=100)

    class Meta:
        abstract = True

class Entry(models.Model):
    blog = models.EmbeddedField(
        model_container=Blog
    )    
    headline = models.CharField(max_length=255)    

e = Entry()
e.blog = {
    'name': 'Djongo'
}
e.headline = 'The Django MongoDB connector'
e.save()

Learn more about embedded fields here.

ArrayField

The ArrayField lets you store a list of embedded documents inside a document. Nest a list of dict inside a model for doing this.

from djongo import models

class Entry(models.Model):
    blog = models.ArrayField(
        model_container=Blog
    )    
    headline = models.CharField(max_length=255)    

e = Entry()
e.blog = [
    {'name': 'Djongo'}, {'name': 'Django'}, {'name': 'MongoDB'}
]
e.headline = 'Djongo is the best Django and MongoDB connector'
e.save()

More about array fields here.

Querying Data

Writing queries for selecting MongoDB data is easy. Querying in Djongo works exactly like in Django because Djongo translates Django’s ORM queries into MongoDB queries under the hood. You interact with your data using model managers and QuerySets, which are lazy, iterable representations of database queries.

A QuerySet is constructed when you call methods like .all() or .filter(), and only hits the database when you actually evaluate it. This design allows you to build queries incrementally without immediately hitting the database. QuerySets make it easy to reason about database access while writing clean Python code.

from blog.models import Post

# Builds a QuerySet but does not hit the database yet
qs = Post.objects.all()

Retrieving Objects

The most common methods to retrieve data are .all(), .get(), and .filter().

• .all() returns every record as a QuerySet.

• .get() returns a single object and raises an error if none or multiple match.

• .filter() returns a QuerySet matching given conditions.

Filters use field lookups expressed with double underscores (e.g. field__lookup=value) and are injection safe because Django escapes parameters.

# Basic retrieval examples
post = Post.objects.get(id=1)
recent_posts = Post.objects.filter(published_date__year=2024)
all_posts = Post.objects.all()

Chaining Filters and Field Lookups

You can chain filters to build complex queries. Each filter call returns a new QuerySet, allowing you to progressively narrow down results. Django supports lookups like exact, iexact, contains, icontains, gte, lte, in, and range.

QuerySets remain lazy until evaluated, so chaining does not hit the database immediately. This pattern allows for clean, readable, composable queries.

qs = Post.objects.filter(published_date__year=2024)\
                 .filter(title__icontains="django")\
                 .order_by('-published_date')

Ordering, Slicing, and Limiting

You can order results using .order_by() and limit them using Python slicing syntax. Ordering accepts one or more field names, with a - prefix for descending order. Slicing translates to SQL/MongoDB LIMIT and OFFSET.

You can also use .first() and .last() to get a single record or None if none exist. These tools let you fetch only the portion of data you need efficiently.

latest_five = Post.objects.order_by('-published_date')[:5]
first_post = Post.objects.order_by('published_date').first()

Aggregations and Related Lookups

Django ORM (and therefore Djongo) supports aggregations with functions like Count, Sum, Avg, Min, and Max. Use .aggregate() to return a single summary value, or .annotate() to add computed values to each result row.

You can traverse related fields using double underscores (following ForeignKey, OneToOneField, or ManyToManyField). This lets you perform joins and calculations without writing raw database queries.

from djongo.models import Count

authors = Author.objects.annotate(num_posts=Count('post'))
for a in authors:
    print(a.name, a.num_posts)

Evaluating QuerySets

A QuerySet executes when it’s evaluated — when you iterate over it, convert it to a list, access a slice, or call .count(), .exists(), .first(), or .last().

The results are cached after the first evaluation, so repeated iterations don’t hit the database again unless you call .all() to refresh. This lazy and cached behavior helps minimize database traffic and improve performance.

You can learn more about making queries here.

qs = Post.objects.filter(published_date__year=2024)
print(list(qs))  # Executes the query
print(list(qs))  # Uses the cached results, no new query

Database Configuration

The settings.py supports (but is not limited to) the following options:

All options except ENGINE and ENFORCE_SCHEMA are the same those listed in the pymongo documentation.

    DATABASES = {
        'default': {
            'ENGINE': 'djongo',
            'NAME': 'your-db-name',
            'ENFORCE_SCHEMA': False,
            'CLIENT': {
                'host': 'host-name or ip address',
                'port': port_number,
                'username': 'db-username',
                'password': 'password',
                'authSource': 'db-name',
                'authMechanism': 'SCRAM-SHA-1'
            },
            'LOGGING': {
                'version': 1,
                'loggers': {
                    'djongo': {
                        'level': 'DEBUG',
                        'propagate': False,                        
                    }
                },
             },
        }
    }

Security and Integrity Checks

Djongo allows for checks on data fields before they are saved to the database. Running the correct integrity checks and field value validators before writing data into the database is important.

Enforce schema

MongoDB is schemaless, which means no schema rules are enforced by the database. You can add and exclude fields per entry and MongoDB will not complain. This can make life easier, especially when there are frequent changes to the data model. Take for example the Blog Model (version 1).

class Blog(models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()

You can save several entries into the DB and later modify it to version 2:

class Blog(models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()
    description = models.TextField()

The modified Model can be saved without running any migrations.

This works fine if you know what you are doing. Consider a query that retrieves entries belonging to both the 'older' model (with just 2 fields) and the current model. What will the value of description now be? To handle such scenarios Djongo comes with the ENFORCE_SCHEMA option.

When connecting to Djongo you can set ENFORCE_SCHEMA: True. In this case, a MigrationError will be raised when field values are missing from the retrieved documents. You can then check what went wrong.

ENFORCE_SCHEMA: False works by silently setting the missing fields with the value None. If your app is programmed to expect this (which means it is not a bug) you can get away by not calling any migrations.

Validators

Apply validators to each field before they are saved.

from django.core.exceptions import ValidationError
from django.utils.translation import gettext_lazy as _
from djongo import models
from django.core.validators import URLValidator

def script_injection(value):
    if value.find('<script>') != -1:
        raise ValidationError(_('Script injection in %(value)s'),
                              params={'value': value})

class Address(models.Model)
    city = models.CharField(max_length=50)
    homepage = models.URLField(validators=[URLValidator, script_injection])
    class Meta:
        abstract=True

class Entry(models.Model):
    _id = models.ObjectIdField()
    address = models.EmbeddedField(model_container=Address)

Integrity checks

class Entry(models.Model):
    _id = models.ObjectIdField()
    address = models.EmbeddedField(model_container=Address,
                                   null=False,
                                   blank=False)

By setting null=False, blank=False in EmbeddedField, missing values are never stored.

Djongo Manager

Djongo Manager extends the functionality of the usual Django Manager. It gives direct access to the pymongo collection API. To use this manager define your manager as DjongoManager in the model.

class Entry(models.Model):
    blog = models.EmbeddedField(
        model_container=Blog,
    )
    headline = models.CharField(max_length=255)    
    objects = models.DjongoManager()

Use it like the usual Django manager:

post = Entry.objects.get(pk=p_key)

Will get a model object having primary key p_key.

Using PyMongo Commands

MongoDB has powerful query syntax and DjongoManager lets you exploit it fully. For the above Entry model define a custom query function:

class EntryView(DetailView):

    def get_object(self, queryset=None):
        index = [i for i in Entry.objects.mongo_aggregate([
            {
                '$match': {
                    'headline': self.kwargs['path']
                }
            },
        ])]

        return index

You can directly access any pymongo command by prefixing mongo_ to the command name.

For example, to perform aggregate on the BlogPage collection (BlogPage is stored as a table in SQL or a collection in MongoDB) the function name becomes mongo_aggregate. To directly insert a document (instead of .save() a model) use mongo_insert_one()

GridFS

To save files using GridFS you must create a file storage instance of GridFSStorage:

grid_fs_storage = GridFSStorage(collection='myfiles')

In your model define your field as FileField or ImageField as usual:

avatar = models.ImageField(storage=grid_fs_storage, upload_to='')

Refer to Using GridFSStorage for more details.

DjongoCS

Djongo Cloud Server is the fastest way to deploy to the cloud your djongo powered apps. The DjongoCS package and dependencies come preconfigured and installed on a Google Cloud Platform server.

1. Start by creating an account. You will be assigned a working webserver instance running Django and MongoDB.
2. (Optional) Test your instance by entering https://api.djongomapper.com/<username>/ in your browser. The username is what was used while creating the account.
3. Login to your dashboard and upload your Public SSH key. The command to open a shell to your instance will appear in the dashboard. You can upload your app specific Django scripts to the server.

Generate access token

Once logged into the dashboard click on generate token. This generates and installs a pass token needed for downloading the latest version of djongo for local development. Copy and add the generated token into the ~/.netrc file located in your home directory.

machine pypi.djongomapper.com
login <djongocs username>
password <generated token>

You can then install the latest version of djongo:

pip install --extra-index-url https://pypi.djongomapper.com/latest-updates/ djongo

Make sure to safely install and store the pass token inside the ~/.netrc file. The pass token is not saved on the DjongoCS server locally.

SSH

On account creation you install your public SSH key at the dashboard. This gives the SSH access to the VM instance for uploading a Django App. Once the key is installed, the dashboard displays the SSH port number over which you can connect to the VM instance.

Establish a secure shell connection using:

ssh <username>@api.djongomapper.com -p <port> 

The username is the same as the username used while creating the DjongoCS account.

When you create an account on DjongoCS you get a unique URL path assigned to you. The Django views that you create for servicing your API can be accessed and extended further starting from the base URL: https://api.djongomapper.com/<username>

Launching the App

Establishing an SSH connection to your server logs you into the /home/$USER directory. The typical home directory structure looks like:

~home
| -- .ssh/
| -- site/
|   -- api/
|     -- settings.py
|     -- urls.py
|   -- apps/
|     -- app1/
|       -- views.py
|       -- models.py
|     -- app2/
|       -- views.py
|       -- models.py

In your urls.py if you add an entry like path('hello/', app1.views.hello), the URL path becomes https://api.djongomapper.com/<username>/hello

DjongoCS Features

Features under development on DjongoCS are not a part of the standard Djongo package.

DjongoCS supports multiple features of MongoDB including:

Indexes

Support for indexes provided by MongoDB, for example 2dSphere Index, Text Index and Compound Indexes.

Model Query

Support for GeoSpatial Queries and Tailable Cursors.

Model Update

Unordered and Ordered Bulk Writes.

Database Transactions

Atomic multi document transactions with commit and rollback support.

Schema Validation and Model Creation

Automatic JSON Schema validation document generation and options to add Read and Write Concerns for the Models.

Aggregation Operators

Support for various aggregation operators provided by MongoDB.

Contribute

If you think djongo is useful, please share it with the world! Your endorsements and online reviews will help get more support for this project.

You can contribute to the source code or the documentation by creating a simple pull request! You may want to refer to the design documentation to get an idea on how Django MongoDB connector is implemented.