Forem: Abigail Afi Gbadago

Build a Task Manager with Django MongoDB Backend

Abigail Afi Gbadago — Fri, 10 Apr 2026 01:24:45 +0000

Whilst life can work out beautifully when things are spontaneous, sometimes, a little planning and management help put things into perspective. Today, we are going to build a task manager using the MongoDB Atlas Free Tier and Django MongoDB Backend to help plan out tasks and activities. This task manager, which we will call “Get Going,” features a drag-and-drop Kanban board (To Do, In Progress, Done sections) built with HTMX.

Create a MongoDB Atlas cluster & get connection string

To kick off things, we will create a MongoDB Atlas cluster by creating an account; if you don’t already have one (link to register.

If you already have an account, go ahead and sign in. In the left pane, click Project Overview to display a page with Clusters, Application Development, and a Toolbar.

Next, click on Create cluster.

Select the MongoDB Atlas Free Tier and enter your preferred cluster name. Then select your preferred provider and other settings.
Click create to deploy your new cluster.

After your cluster has been created, click Connect and add a database username and password.

After successfully adding credentials, click on Connect to Cluster, select Drivers, select Python, and install the Python driver via your command line interface.

Copy the Connection URI to use as the HOST setting in settings.py.

Next, we’ll create a virtual env and install dependencies.

Prerequisites

Platform used: MacOS Tahoe 26.3
Python 3.12+
MongoDB Atlas account (free tier)

Project setup

Create a project directory, set up a virtual environment, and install dependencies:
Create a requirements.txt file with the following:

#requirements.txt

Django>=6.0
django-mongodb-backend
python-dotenv

After, run pip install -r requirements.txt

Next, create a Django project using the MongoDB starter template, then create the tasks app:

django-admin startproject taskmanager --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip
cd taskmanager
python manage.py startapp tasks
Add the task app to settings.py by adding it to INSTALLED_APPS.

#settings.py

INSTALLED_APPS = [
    ...
    'tasks',
]

Environment Variables

Store sensitive credentials in a .env file at the project root (next to manage.py) to keep them out of source control. Then replace , , and with your MongoDB Atlas credentials.

#.env

SECRET_KEY=your-secret-key
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
MONGODB_HOST=mongodb+srv://<username>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority&appName=devrel-tutorial-django-taskmanager-devto
MONGODB_NAME=taskmanager

Task Model

To define the Task model, we'll include fields for title, description, status, priority, owner, an optional due date, and auto-managed timestamps. Status choices map to three columns on the Kanban board: To Do, In Progress, and Done.

#models.py

from django.conf import settings
from django.db import models

class Task(models.Model):
    class Status(models.TextChoices):
        TODO = 'todo', 'To Do'
        IN_PROGRESS = 'in_progress', 'In Progress'
        DONE = 'done', 'Done'

    class Priority(models.TextChoices):
        LOW = 'low', 'Low'
        MEDIUM = 'medium', 'Medium'
        HIGH = 'high', 'High'

    title = models.CharField(max_length=255)
    description = models.TextField(blank=True, default='')
    status = models.CharField(
        max_length=20,
        choices=Status.choices,
        default=Status.TODO,
    )
    priority = models.CharField(
        max_length=10,
        choices=Priority.choices,
        default=Priority.MEDIUM,
    )
    owner = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name='tasks',
    )
    due_date = models.DateTimeField(null=True, blank=True)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        ordering = ['-created_at']

    def __str__(self):
        return self.title

After creating our models, we will create and run migrations:
python manage.py makemigrations tasks
python manage.py migrate

Forms

Before we create views, create a TaskForm using Django's ModelForm, which will handle validation and rendering the creation and editing tasks, with fields for title, description, status, priority, and due date.

#forms.py 

from django import forms
from .models import Task

class TaskForm(forms.ModelForm):
    class Meta:
        model = Task
        fields = ['title', 'description', 'status', 'priority', 'due_date']
        widgets = {
            'due_date': forms.DateTimeInput(
                attrs={'type': 'date'},
                format='%Y-%m-%d',
            ),
        }

Authentication

For this project, we will use Django’s built-in authentication system, which provides user accounts, login, logout, and password handling out of the box.

Login/Logout Views

Regarding authentication when logging in and out, Django provides a LoginView and LogoutView right out of the box. After this, we will register the views in urls.py and point LOGIN_URL and LOGIN_REDIRECT_URL in settings.py so unauthenticated users are sent to the login page, and successful logins land on the task manager board.

To protect the view, we use the @login_required decorator on every view to ensure only authenticated users can access the board, create tasks, or modify them. Each task is also scoped to its owner — users can only see and manage their own tasks.

We will also add a login page at templates/registration/login.html, which is a form that requires username and password fields.

Next, to get into the system and access the task manager, we need to create a superuser.

Run python manage.py createsuperuser

Follow the prompts and type out your name, email, and password, as we will use them to access the task manager board.

Add urls.py at the project and app level

Finally, we wire everything up in taskmanager/urls.py, which maps the root URL to the board view, /login/ and /logout/ to Django's built-in auth views, and task operations to their respective views. Each task URL uses the task's ID in the path for edit, delete, and move actions.

#taskmanager/urls.py

from django.contrib import admin
from django.contrib.auth import views as auth_views
from django.urls import include, path


urlpatterns = [
    path('', include('tasks.urls')),
    path('login/', auth_views.LoginView.as_view(), name='login'),
    path('logout/', auth_views.LogoutView.as_view(), name='logout'),
    path('admin/', admin.site.urls),
]

#tasks/urls.py

from django.urls import path

from . import views

urlpatterns = [
    path('', views.board_view, name='board'),
    path('tasks/new/', views.task_create_view, name='task-create'),
    path(
        'tasks/<str:pk>/edit/',
        views.task_edit_view,
        name='task-edit',
    ),
    path(
        'tasks/<str:pk>/delete/',
        views.task_delete_view,
        name='task-delete',
    ),
    path(
        'tasks/<str:pk>/move/',
        views.task_move_view,
        name='task-move',
    ),
]

Building the Task Manager Board (Kanban Board)

To build the task manager board, we will need:
Logic for the board view — a view that queries the current user's tasks and groups them into three columns by status (To Do, In Progress, Done)
Templates — a base layout, the board page with its three-column grid, a reusable card partial for each task, and a form modal for creating and editing tasks
HTMX for interactivity — create, edit, and delete tasks without full page reloads using hx-get, hx-post, and hx-delete attributes

Next, let’s create the views.py, which has a board_view function that filters tasks belonging to the logged-in user and splits them into columns. We also add a COLUMNS constant that defines the three statuses(TO-DO, IN PROGRESS, and DONE) so we can loop through them.

Also, we will add a @login_required decorator that redirects unauthenticated users to /login/. Each column dict holds the status value, a display label, a CSS dot class for the colored indicator, and the filtered queryset of tasks for that status.

Create views

Now, we can go ahead and create views for our taskapp. The board_view queries the user's tasks, groups them by status into three columns, and displays the task manager board. In addition, we will create views for creating, editing, deleting, and moving tasks between columns — each protected with @login_required and scoped to the current user.

#views.py 

import json

from django.contrib.auth.decorators import login_required
from django.http import HttpResponse, JsonResponse
from django.shortcuts import get_object_or_404, render
from django.views.decorators.http import require_POST

from .forms import TaskForm
from .models import Task

COLUMNS = [
    {'status': 'todo', 'label': 'To Do', 'dot': 'todo'},
    {'status': 'in_progress', 'label': 'In Progress', 'dot': 'progress'},
   {'status': 'done', 'label': 'Done', 'dot': 'done'},
]

@login_required
def board_view(request):
    tasks = Task.objects.filter(owner=request.user)
    columns = []
    for col in COLUMNS:
        columns.append({
            **col,
            'tasks': tasks.filter(status=col['status']),
        })
    return render(request, 'tasks/board.html', {'columns': columns})


@login_required
def task_create_view(request):
    if request.method == 'POST':
        form = TaskForm(request.POST)
        if form.is_valid():
            task = form.save(commit=False)
            task.owner = request.user
            task.save()
            return HttpResponse(headers={'HX-Redirect': '/'})
    else:
        form = TaskForm()
    return render(request, 'tasks/_form_modal.html', {
        'form': form,
        'form_title': 'New Task',
        'form_action': request.path,
        'submit_label': 'Create',
    })
@login_required
def task_edit_view(request, pk):
    task = get_object_or_404(Task, pk=pk, owner=request.user)
    if request.method == 'POST':
        form = TaskForm(request.POST, instance=task)
        if form.is_valid():
            form.save()
            return HttpResponse(headers={'HX-Redirect': '/'})
    else:
        form = TaskForm(instance=task)
    return render(request, 'tasks/_form_modal.html', {
        'form': form,
        'form_title': 'Edit Task',
        'form_action': request.path,
        'submit_label': 'Save',
    })
@login_required
def task_delete_view(request, pk):
    task = get_object_or_404(Task, pk=pk, owner=request.user)
    task.delete()
    return HttpResponse(headers={'HX-Redirect': '/'})


@login_required
@require_POST
def task_move_view(request, pk):
    """Update a task's status when dragged to a new column."""
    task = get_object_or_404(Task, pk=pk, owner=request.user)
    data = json.loads(request.body)
    new_status = data.get('status')
    valid_statuses = [c['status'] for c in COLUMNS]
    if new_status not in valid_statuses:
        return JsonResponse({'error': 'Invalid status'}, status=400)
    task.status = new_status
    task.save()
    return JsonResponse({'ok': True})

Templates

Now, we move on to templates, which form how our UI is going to look.

tasks/base.html — this loads the stylesheet, the HTMX and SortableJS CDN scripts, and sets a global CSRF token on the tag so every HTMX request is authenticated.

{% load static %}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{% block title %}Get Going{% endblock %}</title>
  <link rel="stylesheet" href="{% static 'css/style.css' %}">
  <script src="https://unpkg.com/htmx.org@2.0.4"></script>
  <script src="https://cdn.jsdelivr.net/npm/sortablejs@1.15.6/Sortable.min.js"></script>
</head>
<body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}'>
  {% block body %}{% endblock %}
</body>
</html>

registration/login.html - for signing into the task manager board

{% extends "base.html" %}
{% block title %}Login — Get Going{% endblock %}

{% block body %}
<div class="login-page">
  <div class="login-card">
    <h1>Get <span style="color:var(--green)">Going</span></h1>
    <p class="subtitle">Sign in to manage your tasks</p>

    {% if form.errors %}
    <div class="error-msg">Invalid username or password.</div>
    {% endif %}

    <form method="post">
      {% csrf_token %}
      <div class="form-group">
        <label for="id_username">Username</label>
        <input type="text" name="username" id="id_username" autofocus required>
      </div>
      <div class="form-group">
        <label for="id_password">Password</label>
        <input type="password" name="password" id="id_password" required>
      </div>
      <button type="submit" class="btn btn-primary">Sign In</button>
    </form>
  </div>
  <footer class="app-footer" style="color:var(--sidebar-muted)">Get Going 2026 &trade;</footer>
</div>
{% endblock %}

tasks/board.html — extends base.html and contains the sidebar with navigation and the "+ New Task" button, a three-column grid that loops over columns, and an empty #modal-container div where modals get injected. Each column renders its header (colored dot, label, task count badge) and loops through its tasks using the card partial.

{% extends "base.html" %}
{% block title %}Board — Get Going{% endblock %}

{% block body %}
<div class="app-layout">

  <!-- Sidebar -->
  <aside class="sidebar">
    <div class="logo">Get <span>Going</span></div>

    <button class="new-task-btn"
            hx-get="{% url 'task-create' %}"
            hx-target="#modal-container"
            hx-swap="innerHTML">
      + New Task
    </button>

    <div class="sidebar-section">Menu</div>
    <nav class="sidebar-nav">
      <a href="{% url 'board' %}" class="active">📋 My Tasks</a>
    </nav>
 <div class="sidebar-bottom">
      <div class="user-info">
        <span>{{ request.user.username }}</span>
        <a href="{% url 'logout' %}" class="btn btn-ghost btn-small">Sign Out</a>
      </div>
    </div>
  </aside>

  <!-- Main -->
  <main class="main-content">
    <div class="main-header">
      <h2>My Tasks</h2>
    </div>

    <div class="board">
      {% for col in columns %}
      <div class="column">
        <div class="column-header">
          <span class="column-title">
            <span class="dot dot-{{ col.dot }}"></span>
            {{ col.label }}
          </span>
          <span class="column-count">{{ col.tasks|length }}</span>
        </div>
        <div class="card-list" id="col-{{ col.status }}" data-status="{{ col.status }}">
          {% for task in col.tasks %}
            {% include "tasks/_card.html" %}
          {% endfor %}
        </div>
      </div>
      {% endfor %}
    </div>

    <footer class="app-footer">Get Going 2026 &trade;</footer>
  </main>

</div>
<div id="modal-container"></div>

<script>
document.addEventListener('DOMContentLoaded', function() {
  const csrfToken = document.querySelector('[name=csrfmiddlewaretoken]')?.value
    || document.querySelector('body').getAttribute('hx-headers')
    && JSON.parse(document.querySelector('body').getAttribute('hx-headers'))['X-CSRFToken'];

  document.querySelectorAll('.card-list').forEach(function(list) {
    new Sortable(list, {
      group: 'board',
      animation: 150,
      ghostClass: 'drag-ghost',
      dragClass: 'drag-active',
      onEnd: function(evt) {
        const taskId = evt.item.dataset.id;
        const newStatus = evt.to.dataset.status;
        // Update column counts
        updateCounts();
        // Persist to server
        fetch('/tasks/' + taskId + '/move/', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'X-CSRFToken': csrfToken,
          },
          body: JSON.stringify({ status: newStatus }),
        }).then(function(res) {
          if (!res.ok) {
            evt.from.insertBefore(evt.item, evt.from.children[evt.oldIndex]);
            updateCounts();
          }
        });
      }
    });
  });

  function updateCounts() {
    document.querySelectorAll('.column').forEach(function(col) {
      const count = col.querySelector('.card-list').children.length;
      col.querySelector('.column-count').textContent = count;
    });
  }
});
</script>
{% endblock %}

tasks/_card.html — a partial template for a single task card. It displays the title, description (clamped to two lines), due date, a color-coded priority badge, and edit/delete action buttons. Each card has a data-id="{{ task.id }}" attribute that SortableJS uses later for drag-and-drop.

<div class="task-card" id="task-{{ task.id }}" data-id="{{ task.id }}">
  <div class="task-card-title">{{ task.title }}</div>
  {% if task.description %}
  <div class="task-card-desc">{{ task.description }}</div>
  {% endif %}
  {% if task.due_date %}
  <div class="task-card-due">{{ task.due_date|date:'M d, Y' }}</div>
  {% endif %}
  <div class="task-card-footer">
    <span class="priority-badge priority-{{ task.priority }}">{{ task.get_priority_display }}</span>
    <div class="task-actions">
      <button title="Edit"
              hx-get="{% url 'task-edit' task.id %}"
              hx-target="#modal-container"
              hx-swap="innerHTML">✎</button>
      <button title="Delete" class="delete-btn"
              hx-delete="{% url 'task-delete' task.id %}"
              hx-target="#task-{{ task.id }}"
              hx-swap="outerHTML"
              hx-confirm="Delete this task?">✕</button>
    </div>
  </div>
</div>

tasks/_form_modal.html — a reusable modal for both creating and editing tasks. It receives form_title, form_action, and submit_label through the template context, so the same template can be rendered as "New Task" with a "Create" button or "Edit Task" with a "Save" button. Clicking the backdrop dismisses the modal.

<div class="modal-backdrop" onclick="if(event.target===this)this.remove()">
  <div class="modal">
    <h3>{{ form_title }}</h3>
    <form hx-post="{{ form_action }}"
          hx-target="body"
          hx-swap="innerHTML"
          hx-push-url="false">
      {% csrf_token %}
      <div class="form-group">
        <label for="id_title">Title</label>
        <input type="text" name="title" id="id_title"
               value="{{ form.title.value|default:'' }}" required>
      </div>
      <div class="form-group">
        <label for="id_description">Description</label>
        <textarea name="description" id="id_description">{{ form.description.value|default:'' }}</textarea>
      </div>
      <div class="form-group">
        <label for="id_status">Status</label>
        <select name="status" id="id_status">
          {% for value, label in form.fields.status.choices %}
          <option value="{{ value }}" {% if form.status.value == value %}selected{% endif %}>{{ label }}</option>
          {% endfor %}
        </select>
      </div>
      <div class="form-group">
        <label for="id_priority">Priority</label>
        <select name="priority" id="id_priority">
          {% for value, label in form.fields.priority.choices %}
          <option value="{{ value }}" {% if form.priority.value == value %}selected{% endif %}>{{ label }}</option>
          {% endfor %}
        </select>
      </div>
      <div class="form-group">
        <label for="id_due_date">Due Date</label>
        <input type="date" name="due_date" id="id_due_date"
               value="{{ form.due_date.value|date:'Y-m-d'|default:'' }}">
      </div>
      <div class="modal-actions">
        <button type="button" class="btn btn-ghost" onclick="this.closest('.modal-backdrop').remove()">Cancel</button>
        <button type="submit" class="btn btn-primary">{{ submit_label }}</button>
      </div>
    </form>
  </div>
</div>

NB: for the CRUD methods:

Create method — The "+ New Task" button in the sidebar uses hx-get to fetch the empty form modal from the server and inject it into #modal-container. When the form is submitted, hx-post sends the data to the create endpoint.
Edit method — The edit button on each card uses hx-get to fetch the form modal pre-filled with that task's data.
Delete method— The delete button (✕) uses hx-delete with hx-confirm="Delete this task?" for browser-native confirmation. It targets only the specific card element using hx-target="#task-{{ task.id }}" and hx-swap="outerHTML" to remove just that card from the DOM.

Drag & Drop

To bring some flexibility into the task manager, we will add drag and drop functionality. To achieve this, we will use SortableJS to handle the drag interaction in the browser and a dedicated endpoint to persist the status change to MongoDB.

SortableJS Setup

CDN load in base.html: SortableJS is loaded as a global script from the jsDelivr CDN, making the Sortable constructor available on every page that extends the base template (with this line <script src="https://cdn.jsdelivr.net/npm/sortablejs@1.15.6/Sortable.min.js"></script> )
Initialization + drag handler in board.html: On DOMContentLoaded, each .card-list element gets a Sortable instance with group: 'board' so cards can cross columns. The onEnd callback reads data-id and data-status to POST the new status to the move endpoint, with rollback on failure.
Drag feedback styles in style.css: .drag-ghost renders the drop placeholder with a dashed green border and reduced opacity, while .drag-active gives the card being dragged an elevated shadow and slight rotation for depth.

Styling

For styling, we keep it simple and use a MongoDB-inspired color palette defined as CSS custom properties; a dark sidebar layout, and a responsive breakpoint for mobile. Colors used for status indicator dots: gray for To Do, amber for In Progress, forest green for Done; priority badges: teal for Low, gold for Medium, red for High, and interactive elements like buttons and card hover states.

Responsiveness - CSS

To keep the board usable on smaller screens, we specify a single breakpoint at 768px to restructure the layout:

@media (max-width: 768px) {
    .sidebar {
        width: 100%;
        position: relative;
        flex-direction: row;
        padding: .75rem 1rem;
    }
    .sidebar-nav, .sidebar-section { display: none; }
    .main-content { margin-left: 0; }
    .board { grid-template-columns: 1fr; }
}

On mobile, the fixed sidebar collapses into a horizontal top bar with the logo and "+ New Task" button inline, hiding the nav links to save space. The main content drops its left margin, and the board switches from a three-column grid to a single stacked column.

Final Look at Task Manager

Adding tasks for display

We can create, read, update, and delete tasks via the website or Python Shell; however, we will add tasks via the Add Task button on the Task Manager board.

After adding sample tasks,

The same data is displayed under the task collection of the MongoDB cluster tier that was initially created. Example shown below.

This brings us to the end of this tutorial using Django MongoDB Backend to create a Task Manager with MongoDB Atlas Free Tier. To download the project, kindly access this link to project. If you liked this tutorial, kindly like this tutorial and share your thoughts and/or contributions in the comments section.

Thank you, and see you in the next one.

References

How to Set Up Queryable Encryption in a Django + MongoDB Application

Abigail Afi Gbadago — Thu, 19 Mar 2026 18:08:58 +0000

Build a Secure Risk Assessment API with MongoDB Queryable Encryption in Django

In this tutorial, we will build a Risk Assessment API with encrypted fields using the Django MongoDB Backend. This tutorial targets anyone working with sensitive data that needs to be protected. In this case, we will focus on assessing risk, which is fundamental in sectors such as finance or wealth asset management.

The Problem

Encryption plays a crucial role in mitigating potential threats to investments and ensuring regulatory compliance and long-term profitability of organizations. The major problem arises when sensitive data, such as Personal Identifiable Information (PII), financial, and health records, is stored in plain text in databases, which are vulnerable to exposure in the case of a database breach.

Under the EU’s Digital Operational Resilience Act (DORA), which became effective in January 2025, financial institutions are explicitly mandated to implement robust Information and Communications Technology (ICT) risk management frameworks, which include strict requirements for encryption of data—both at rest, in transit, and in use for operating in European markets, with similar requirements emerging globally.

Why MongoDB Queryable Encryption

MongoDB's Queryable Encryption solves this by encrypting data on the client side before it reaches the server, meaning the database can process queries on encrypted fields without ever seeing the plaintext. With Django MongoDB Backend's Queryable Encryption support, Django developers can protect their data. The fields are encrypted on write, decrypted on read, and the MongoDB server never has access to the raw data, even if compromised.

Queryable Encryption is supported on MongoDB versions as early as MongoDB 7.0 with new query operators for range, prefix, suffix, and substring queries that come with each versioned release. MongoDB 8.0 adds support for range queries on encrypted fields. More advanced text-style queries are being introduced in preview releases prior to general availability and are expected to become fully supported in a future release. To see the full range of supported operations, check here.

Design the Data Model

When deciding the data model for the risk assessment, let’s take a minute to think about the fields in our model.

Things we will encrypt: names, titles, descriptions that contain PII, and sensitive text.
Things we won’t encrypt: Scores, dates, Foreign keys, and anything you need to perform a sort or index on.

The relationship is visualized in the ERD below:

Overview of the Process

When a user makes a request, for example, a write request (POST /api/categories/) with "name": "Financial"} in the request body, Django receives the plaintext "Financial", the EncryptedCharField uses Queryable Encryption to encrypt sensitive data before storing or retrieving it as binary.

Prerequisites

Platform used: MacOS Tahoe 26.3
Python 3.13+
MongoDB Atlas account (free tier works)
Download mongo_crypt_shared library
- You can choose from MongoDB Enterprise Downloads or choose the current release:
- Select your OS; macOS ARM64 / Linux / Windows here
- Extract and note the path to mongo_crypt_v1.dylib (macOS) or mongo_crypt_v1.so (Linux)
- Reference the path in crypt_shared_lib_path in settings.py

Next, create a requirements.txt file with the following content:

Django>=6.0
djangorestframework==3.16.1

# For encryption(depends on corresponding Django version, >=6.0)
django-mongodb-backend[encryption]

# For the API Documentation(Swagger)
drf-spectacular

# For environment variables
Django-environ

Then run the following command in your terminal:
pip install -r requirements.txt

Project Setup

Create your Django project and app:

mkdir querysafe && cd querysafe
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
django-admin startproject querysafe --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/6.0.x.zip
python manage.py startapp riskapp

Add apps to settings.py

It is ideal to use [MONGODB_USERNAME], [PASSWORD] in an .env file

INSTALLED_APPS = [
    ...
    "rest_framework",
    "drf_spectacular",
    "riskapp",
]

Configure encrypted database

For the (encrypted) database, let's set up a few things first.

Download mongo_crypt_shared

Download from MongoDB Enterprise Downloads or choose the current release here
Extract and note the path to the library file
Reference the path in crypt_shared_lib_path in settings.py (usually looks like Crypt_shared_lib_path: /Users/path/mongo_crypt_shared_v1-macos-arm64-enterprise-8.2.5/lib/mongo_crypt_v1.dylib)
For more information, check here

Now add the encrypted database to your settings.py file under the default database:

# (default)
`
"default": {
    "ENGINE": "django_mongodb_backend",
    "HOST": "MONGO_URI", # "mongodb+srv://[username]:[password]@cluster0.hpljptt.mongodb.net/?appName=devrel-tutorial-python-qe-medium",
    "NAME": "querysafe",
}

# (encrypted)

"encrypted": {
        "ENGINE": "django_mongodb_backend",
        "HOST": "mongodb+srv://[username]:[password]@cluster0.hpljptt.mongodb.net/?appName=devrel-tutorial-python-qe-medium",
        "NAME": "encrypted_db",

        "OPTIONS": {
            "auto_encryption_opts": AutoEncryptionOpts(
                key_vault_namespace="encrypted_db.__keyVault",
                kms_providers={
                    "local": {
                        # Generated by os.urandom(96)
                        "key": (
                            b'-\xc3\x0c\xe3\x93\xc3\x8b\xc0\xf8\x12\xc5#b'
                            b'\x19\xf3\xbc\xccR\xc8\xedI\xda\\ \xfb\x9cB'
                            b'\x7f\xab5\xe7\xb5\xc9x\xb8\xd4d\xba\xdc\x9c'
                            b'\x9a\xdb9J]\xe6\xce\x104p\x079q.=\xeb\x9dK*'
                            b'\x97\xea\xf8\x1e\xc3\xd49K\x18\x81\xc3\x1a"'
                            b'\xdc\x00U\xc4u"X\xe7xy\xa5\xb2\x0e\xbc\xd6+-'
                            b'\x80\x03\xef\xc2\xc4\x9bU'
                        )
                    },
                },
                crypt_shared_lib_path="[PATH/TO/mongo_crypt_v1.dylib]", #for macOS
                crypt_shared_lib_required=True,
            )
        },
    },

}

Now, to visualize the encryption process for our risk data, we will first route operations to the encrypted database by creating a router, define our models, perform migrations, seed the db and then take a look at the encrypted fields in the db.

Create a router

# riskapp/routers.py

class EncryptedRouter:
    def allow_migrate(self, db, app_label, model_name=None, **hints):

        if app_label == "riskapp":
            return db == "encrypted"

        if db == "encrypted":
            return False
        return None

    def db_for_read(self, model, **hints):

        if model._meta.app_label == "riskapp":
            return "encrypted"
        return None

    db_for_write = db_for_read

Define models

from django.db import models
from django.conf import settings
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import (
    EncryptedCharField,
    EmbeddedModelField,
)

class RiskCategory(EmbeddedModel):
    name = EncryptedCharField(max_length=100)
    description = EncryptedCharField(max_length=500, blank=True)

    def __str__(self):
        return str(self.name)

class RiskOwner(EmbeddedModel):
    username = EncryptedCharField(max_length=150)
    email = EncryptedCharField(max_length=254, blank=True)
    role = EncryptedCharField(max_length=100, blank=True)

    def __str__(self):
        return f"{self.username} ({self.role})"


class Risk(EmbeddedModel):
    title = EncryptedCharField(max_length=200)
    description = EncryptedCharField(max_length=500, blank=True, default="")
    category = EmbeddedModelField(RiskCategory)

    def __str__(self):
        return str(self.title)


class RiskAssessment(models.Model):
    RISK_LEVEL_CHOICES = [
        ("Low", "Low"),
        ("Medium", "Medium"),
        ("High", "High"),
    ]

    risk = EmbeddedModelField(Risk)
    owner = EmbeddedModelField(RiskOwner, blank=True, null=True)
    likelihood = models.CharField(max_length=10, choices=RISK_LEVEL_CHOICES)
    impact = models.CharField(max_length=10, choices=RISK_LEVEL_CHOICES)
    score = models.PositiveSmallIntegerField()
    assessed_on = models.DateField(auto_now_add=True)

    class Meta:
        db_table = "risk_assessments"
        ordering = ["-assessed_on"]
        indexes = [
            models.Index(fields=["likelihood"]),
            models.Index(fields=["impact"]),
            models.Index(fields=["score"]),
        ]

    def __str__(self):
        return f"{self.risk.title} ({self.likelihood}/{self.impact})"

Run migrations

python manage.py makemigrations riskapp
python manage.py migrate --database encrypted

Create serializers for request and response

#serializers.py
from rest_framework import serializers

RISK_LEVEL_CHOICES = ["Low", "Medium", "High"]


class RiskCategorySerializer(serializers.Serializer):

    name = serializers.CharField(max_length=100)
    description = serializers.CharField(
        max_length=500, required=False, default=""
    )


class RiskSerializer(serializers.Serializer):

    title = serializers.CharField(max_length=200)
    description = serializers.CharField(
        max_length=500, required=False, default=""
    )
    category = RiskCategorySerializer()


class RiskOwnerSerializer(serializers.Serializer):

    username = serializers.CharField(max_length=150)
    email = serializers.CharField(max_length=254, required=False, default="")
    role = serializers.CharField(max_length=100, required=False, default="")


class AssessmentSerializer(serializers.Serializer):

    risk = RiskSerializer()
    owner = RiskOwnerSerializer(required=False)
    likelihood = serializers.ChoiceField(choices=RISK_LEVEL_CHOICES)
    impact = serializers.ChoiceField(choices=RISK_LEVEL_CHOICES)
    score = serializers.IntegerField(min_value=1, max_value=10)


class AssessmentResponseSerializer(serializers.Serializer):

    id = serializers.CharField(source='pk', read_only=True)
    risk = RiskSerializer()
    owner = RiskOwnerSerializer()
    likelihood = serializers.CharField()
    impact = serializers.CharField()
    score = serializers.IntegerField()
    assessed_on = serializers.DateField()

Create class-based views with APIView

We will use @extend_schema to provide detailed, accurate documentation for each endpoint.

#views.py

from rest_framework import status
from rest_framework.response import Response
from rest_framework.views import APIView
from drf_spectacular.utils import extend_schema

from riskapp.models import (
    RiskAssessment,
    Risk,
    RiskCategory,
    RiskOwner,
)
from riskapp.serializers import (
    AssessmentSerializer,
    AssessmentResponseSerializer,
)

DB = 'encrypted_db'


class AssessmentView(APIView):

    @extend_schema(
        responses=AssessmentResponseSerializer(many=True),
        summary="List all assessments",
        tags=["Assessments"],
    )
    def get(self, request):
        assessments = RiskAssessment.objects.using(DB).all()
        serializer = AssessmentResponseSerializer(assessments, many=True)
        return Response(serializer.data)

    @extend_schema(
        request=AssessmentSerializer,
        responses=AssessmentResponseSerializer,
        summary="Create an assessment",
        tags=["Assessments"],
    )
    def post(self, request):
        serializer = AssessmentSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        data = serializer.validated_data

        risk_data = data['risk']
        category_data = risk_data['category']

        assessment = RiskAssessment(
            risk=Risk(
                title=risk_data['title'],
                description=risk_data.get('description', ''),
                category=RiskCategory(
                    name=category_data['name'],
                    description=category_data.get('description', ''),
                ),
            ),
            likelihood=data['likelihood'],
            impact=data['impact'],
            score=data['score'],
        )

        if data.get('owner'):
            owner_data = data['owner']
            assessment.owner = RiskOwner(
                username=owner_data['username'],
                email=owner_data.get('email', ''),
                role=owner_data.get('role', ''),
            )

        assessment.save(using=DB)

        return Response(
            AssessmentResponseSerializer(assessment).data,
            status=status.HTTP_201_CREATED,
        )

Add urls.py at the project and app level.

#querysafe/urls.py

from django.contrib import admin
from django.urls import path, include
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('riskapp.urls')),
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'), #for swagger-ui
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'), #for swagger-ui
]

#riskapp/urls.py

from django.urls import path
from riskapp.views import AssessmentView

urlpatterns = [
    path('assessments/', AssessmentView.as_view(), name='assessments'),
]

Next, we will create a management command structure for custom management commands by:

Creating a folder called management in the riskapp and a folder called commands, which is where we will add a Python script to seed the data. This can be achieved either via the GUI or by running mkdir -p riskapp/management/commands.
Then creating init.py(empty) files in each directory to make them Python packages by touch riskapp/management/__init__.py and touch riskapp/management/commands/__init__.py or by creating them via GUI.

Seed data with the seed_data.py, which contains mock data below.

NB: Because encrypted fields can't be queried, the seed script uses create() with in-memory references and a --target flush flag to stay rerunnable.

#seed_data.py

from django.core.management.base import BaseCommand
from django.db import transaction

from riskapp.models import (
    RiskAssessment,
    Risk,
    RiskCategory,
    RiskOwner,
)
ASSESSMENTS = [
    {
        "risk_title": "NoSQL Injection",
        "risk_description": "Potential NoSQL injection via unsanitised operators",
        "category": "Security",
        "cat_desc": "Security and authentication data",
        "likelihood": "High",
        "impact": "High",
        "score": 9,
    },
    {
        "risk_title": "Data Exposure",
        "risk_description": "Sensitive data returned without field projection",
        "category": "Personal",
        "cat_desc": "Personal identifiable information (PII)",
        "likelihood": "Medium",
        "impact": "High",
        "score": 7,
    },
    {
        "risk_title": "Privilege Escalation",
        "risk_description": "Attempt to modify roles or permissions",
        "category": "Security",
        "cat_desc": "Security and authentication data",
        "likelihood": "Low",
        "impact": "High",
        "score": 6,
    },
    {
        "risk_title": "GDPR Violation",
        "risk_description": "Query accesses EU citizen data without consent check",
        "category": "Compliance",
        "cat_desc": "Regulatory and compliance data",
        "likelihood": "Medium",
        "impact": "Medium",
        "score": 5,
    },
    {
        "risk_title": "PHI Exposure",
        "risk_description": "Protected health information returned in query",
        "category": "Healthcare",
        "cat_desc": "Medical and health records (PHI)",
        "likelihood": "High",
        "impact": "High",
        "score": 9,
    },
    {
        "risk_title": "Credit Card Leak",
        "risk_description": "Payment card data queried without masking",
        "category": "Financial",
        "cat_desc": "Financial data and transactions",
        "likelihood": "Medium",
        "impact": "High",
        "score": 8,
    },
    {
        "risk_title": "Mass Data Export",
        "risk_description": "Query fetches excessive number of documents",
        "category": "Compliance",
        "cat_desc": "Regulatory and compliance data",
        "likelihood": "Low",
        "impact": "Medium",
        "score": 4,
    },
    {
        "risk_title": "Unindexed Scan",
        "risk_description": "Collection scan on sensitive collection",
        "category": "Financial",
        "cat_desc": "Financial data and transactions",
        "likelihood": "High",
        "impact": "Low",
        "score": 3,
    },
]

class Command(BaseCommand):
    """
    Seed the database with sample risk assessment data.
    Use --target flush to clear data before reseeding.
    """

    help = "Seed the database with sample risk assessment data"

    def add_arguments(self, parser):
        parser.add_argument(
            '--target',
            default='all',
            choices=['all', 'default', 'encrypted', 'flush'],
            help="'flush' to clear data, 'all' to seed both, or specify a database",
        )

    def handle(self, *args, **options):
        target = options['target']

        if target == 'flush':
            self._flush('default')
            self._flush('encrypted')
            return

        if target == 'all':
            databases = ['default', 'encrypted']
        else:
            databases = [target]

        try:
            for db in databases:
                self.db = db
                self.stdout.write(f"\nSeeding into: {self.db}")
                with transaction.atomic(using=self.db):
                    self._seed_assessments()
            self.stdout.write(self.style.SUCCESS("\nAll data seeded successfully!"))
        except Exception as e:
            self.stdout.write(self.style.ERROR(f"\nSeeding failed: {e}"))

    def _flush(self, db):
        RiskAssessment.objects.using(db).all().delete()
        self.stdout.write(self.style.WARNING(f"Flushed data from: {db}"))

    def _seed_assessments(self):
        self.stdout.write("\n--- Seeding Risk Assessments ---")

        owner = RiskOwner(
            username="assessor",
            email="assessor@querysafe.com",
            role="Analyst",
        )

        for item in ASSESSMENTS:
            assessment = RiskAssessment(
                risk=Risk(
                    title=item["risk_title"],
                    description=item["risk_description"],
                    category=RiskCategory(
                        name=item["category"],
                        description=item["cat_desc"],
                    ),
                ),
                owner=owner,
                likelihood=item["likelihood"],
                impact=item["impact"],
                score=item["score"],
            )
            assessment.save(using=self.db)
            self.stdout.write(
                f"  Created: {item['risk_title']} ({item['likelihood']}/{item['impact']})"
            )

Run the script file in the terminal
python manage.py seed_data

Swagger Documentation

Next, we add Swagger UI to create a presentation layer for our API.

Install drf-spectacular
pip install drf-spectacular

Next, add it to your INSTALLED_APPS and configure it in settings.py:

INSTALLED_APPS = [
    'querysafe.apps.MongoAdminConfig',
    'querysafe.apps.MongoAuthConfig',
    'querysafe.apps.MongoContentTypesConfig',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django_mongodb_backend',
    'drf_spectacular',
    'riskapp',
]

REST_FRAMEWORK = {
    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
}

SPECTACULAR_SETTINGS = {
    "TITLE": "QuerySafe API",
    "DESCRIPTION": "API for Risk Assessment using Queryable Encryption",
    "VERSION": "1.0.0",
    "SERVE_INCLUDE_SCHEMA": False,
}

Next, run the server to access the Swagger UI at http://localhost:8000/api/docs/

Results

Encrypted Data in MongoDB Atlas

The following screenshots show how sensitive data appears as encrypted binary data when viewed directly in MongoDB Atlas, while the Swagger interface displays the decrypted plaintext for authorized users.

Swagger UI (Auto-Decrypted)

The Swagger UI at http://127.0.0.1:8000/api/docs/ automatically decrypts and displays the data in plaintext for API consumers.

Terminal Query

When querying the database directly from the terminal using find_one(), the data appears as encrypted binary, demonstrating that the database server never has access to the plaintext.

Limitations

With Django MongoDB Backend’s encrypted model fields, you cannot use get_or_create() or filter() — each encryption produces a different ciphertext, so WHERE lookups never match.
Performance cost of client-side encryption/decryption - A read and write to an encrypted field requires client-side encryption/decryption on raw values directly. After fetching the data, your application server must individually decrypt each field for every record. This means that listing 1000 records requires 1000 decryption operations, which adds CPU overhead and slows down response times.
Why you can't encrypt everything:
- Dates — auto_now_add, ordering, and date filtering won't work on encrypted fields, else you can’t auto-populate timestamps (auto_now_add), order results (order_by('-created_at')) or filter by date ranges (filter(created_at__gte=last_week)).
- Scores/numbers — you can't sort or aggregate encrypted values / The database can't perform ORDER BY, SUM(), AVG(), MIN(), MAX(), or range queries (filter(risk_score__gte=80)) on encrypted values because it just sees random ciphertext.
- Indexed fields — CharField with choices like likelihood and impact need to remain queryable, so they can’t be encrypted.

Key Takeaways

Only encrypt fields that hold sensitive data and that you never need to search, sort, or filter by at the database level.
In the event of a database breach, the binary data won't be of any use to attackers, which keeps the integrity of your data safe (MongoDB never sees your plaintext data).

If you liked this tutorial, kindly comment and give me an emoji.

Thank you.

References

Build a RAG App With Django MongoDB Backend in 30 minutes

Abigail Afi Gbadago — Mon, 08 Dec 2025 17:02:51 +0000

The festive holidays are upon us. This is the time for deep reflections, catching up with family and friends, and enjoying life in general as the year comes to a close. This period is also a great time to rewatch old movie classics as we slide into the new year.

Today, we will build a retrieval-augmented generation (RAG) app to give us holiday movie recommendations. We will go through it step by step so that you fully understand how you can create one on your own.

What we will build

A RAG app in 30 minutes using:

Django MongoDB Backend.
Django MongoDB Backend is a Django database backend that uses PyMongo to connect to MongoDB.
Voyage AI.
Voyage AI (part of MongoDB) is a platform that provides the tools to build state-of-the-art AI models, semantic search, RAG, and agentic applications.
LangChain.
LangChain is an orchestration framework that simplifies and streamlines the development of agentic and RAG apps by providing pre-built tooling for defining your agentic or RAG application, an element of which includes data ingestion (in this case, from a JSON file), preprocessing, creation of embeddings, retrieval, and generation.

What you need

An IDE (this tutorial uses VSCode)
Python 3.10 or later
A MongoDB Atlas account (if you haven’t already, create an account)
A MongoDB Atlas cluster—the free tier is okay
A MongoDB connection string (with the username, password, and database included in the string)
A Voyage AI API key—create an account, and create and save an API key
Dataset—this is a JSON file with twenty(20) classic holiday movies; please download the file and add it to the root of your project directory; I created this by analyzing the structure of the sample_mflix dataset and creating a JSON document based on that

Dependencies

Create a requirements.txt to contain the:

python-dotenv package (version at the time of this tutorial is 1.1.1).
voyageai package (version at the time of this tutorial is 0.3.5).
langchain-voyageai package (version at the time of this tutorial is 0.1.7).
langchain-mongodb package (version at the time of this tutorial is 0.7.1).

Next, we will split the building process into the following steps:

Download the JSON file.
Follow the Django MongoDB Backend Quickstart.
Add dependencies and set environment variables.
Create models.
Embed with Voyage AI.
Insert data into the MongoDB Atlas cluster.
Integrate MongoDB Atlas Vector Search with LangChain.
Render data.

Download the JSON file

Based on the sample_mflix model, this is how we will model the objects in the JSON file.

The JSON file, holiday_movies.json, has twenty (20) classic holiday movie objects.

Example of object in document format:

{
      "_id": 1,
      "title": "It’s a Wonderful Life",
      "plot": "An angel is sent from Heaven to help a desperately frustrated businessman by showing him what life would have been like if he had never existed.",
      "runtime": 130,
      "released": "1946-12-20T00:00:00Z",
      "genres": ["Drama", "Family", "Fantasy"],
      "awards": {
        "wins": 0,
        "nominations": 5,
        "text": "Nominated for 5 Oscars"
      },
      "plot_embedding_voyage_3_large": null,
      "plot_embedding": null
}

Follow the Django MongoDB Backend Quickstart

This will lay the foundation and ensure you have all the necessary utilities bootstrapped to create a scaffold Django project. After that, you’ll be able to:
Create a Django project—in this case, I called it django_rag_app.
Ensure your database settings in your settings.py file are accurate. It should look like this:

DATABASES = {
    "default": {
          "ENGINE": "django_mongodb_backend",
          "HOST": "<connection string URI>",
          "NAME": "sample_mflix",
    },
}

After, test if everything is working well by running your server with the command
python manage.py runserver. Then, access this url: http://127.0.0.1:8000/.

You should see a page displaying a "Congratulations!" message and an image of a rocket.

Set Environment Variables

To set environment variables, create an .env file at the root of your directory to hold the MONGODB_URI and VOYAGE_API_KEY values.

This is how the MONGODB_URI looks like:

MONGODB_URI="mongodb+srv://[username]:[password]@[cluster_name].hpljptt.mongodb.net/?retryWrites=true&w=majority&appName=[cluster_name]"

Set dependencies

Run pip install requirements.txt to install the packages.

Create Django app

To create a new Django app (in this case, festive_flix), run

python manage.py startapp [festive_flix] --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.2.x.zip

Add the app festive_flix to INSTALLED APPS.

Create models

In our models.py file, we will add the fields we need as seen in the sample_mflix dataset.

from django.db import models
from django_mongodb_backend.fields import EmbeddedModelField, ArrayField
from django_mongodb_backend.models import EmbeddedModel

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, null=True, blank=True)
    genres = ArrayField(models.CharField(max_length=100), null=True, blank=True)

    def __str__(self):
        return self.title

Embed with Voyage AI

Create a new file called plot_embedding.py where we can put the script we will use to embed the reviews field of our holiday_movies.json file.

import json
from dotenv import load_dotenv
import voyageai
import os

load_dotenv()  

#using API key from environment variables in .env file
VOYAGE_API_KEY = os.environ.get("VOYAGE_API_KEY")

vo = voyageai.Client(VOYAGE_API_KEY)

with open("holiday_movies.json", "r") as f:
   data = json.load(f)
#focusing on "plot" field since that's what we are embedding
movies_list = [movie.get("plot", "") for movie in data.get("movies", [])]

#get embeddings for the plots using "voyage-3-lite"
result = vo.embed(movies_list, model="voyage-3-lite", input_type="document")

#new field to hold the embeddings
for movie, embedding in zip(data.get("movies", []), result.embeddings):
   movie["embedding"] = embedding

#write embeddings to a new file: embeddings_holiday_movies.json
with open("embeddings_holiday_movies.json", "w") as f:
   json.dump(data, f, indent=2)

From the plot_embedding.py script, we are:

Setting our key which is stored in the .env file at the root of the Django project.
Opening up our JSON file that’s already in our project.
Embedding the reviews field using Voyage AI’s “voyage-3-lite” embedding model.
Creating a new field (result) to hold the embedding (that has the same name as what we clarified when creating our models.py file).
Creating a new JSON file to hold the embeddings.

Next, run the script using python plot_embedding.py. Once it’s done, we see a new JSON file with our generated embeddings.

At this point, we can go ahead and insert our documents into our MongoDB cluster.

Insert data into the MongoDB cluster

Next, let’s create a new file at the root of the project named json_upload.py.

#json_upload.py
import json
import os
from pymongo import MongoClient
from dotenv import load_dotenv

load_dotenv()

#get the environment variable and connect
connection_string = os.getenv("MONGODB_URI")
client = MongoClient(connection_string)

#specify the database and collection
database = client["festive_flix_db"]
collection = database["holiday_movies_collection"]

#load json file with embeddings
with open("embeddings_holiday_movies.json", "r") as file:
   data = json.load(file)

if isinstance(data,dict) and "movies" in data:
   movies = data["movies"]

#clear existing collection and insert new data with embeddings
collection.delete_many({})

#use insert_many to insert multiple documents
result = collection.insert_many(movies)
print(f"Successfully inserted {len(result.inserted_ids)} documents")

After running the json_upload.py file, you will see a new collection of movies in your MongoDB Atlas cluster.

As we can see, our data is saved in our cluster with our Voyage AI embeddings.

Now that we have successfully stored our data in the MongoDB Atlas cluster, we will write a script using the langchain-mongodb package to do semantic search.

Integrate MongoDB Atlas Vector Search with LangChain

At this point, we need to integrate MongoDB Atlas Vector Search with LangChain, so we will create a vector search index, perform a semantic search based on the vector store, retrieve relevant documents based on embedding similarity, and finally, pass the output as a context to LangChain’s prompts to generate responses.

Create a vector search

To create the semantic search, we first need to create an Atlas Vector Search index.
To do this, click on the “Search & Vector Search” tab on the left sidebar. In the Atlas Search tab, click on the green “Create Search Index” button.

Next, click on the “Create Search Index” button as shown below.

Next, select “Vector Search,” fill in the details, and select the database and collection that the vector search will be based on.

After, choose the path that contains the array of vector embeddings—it should be embedding.

The number of dimensions is 512 because we used Voyage AI’s voyage-3-lite. If choosing a different model, please read up on Voyage AI’s text embeddings documentation to ensure you’re choosing the correct dimensions. For the similarity method, we are using cosine.

Click “Next,” review all the entered information, and click “Create Vector Search.”

Now, let’s create a new file in your project’s root and name it langchain_integration.py.
We are using an embeddings object from the Voyage AI documentation.

NB: VectorSearchIndex is now supported as a Django Index.

Query from the MongoDB vector store, retrieval, and answer generation to prompts

#langchain_integration.py
from langchain_voyageai import VoyageAIEmbeddings
from langchain_mongodb.vectorstores import MongoDBAtlasVectorSearch
from pymongo import MongoClient
from dotenv import load_dotenv
import os

load_dotenv()

voyage_api_key = os.getenv("VOYAGE_API_KEY")
connection_string = os.getenv("MONGO_URI")

#Check if environment variables are loaded
assert voyage_api_key, "ERROR: VOYAGE_API_KEY not found in .env file"
assert connection_string, "ERROR: MONGODB_URI not found in .env file"

#Connect to the Atlas cluster
try:
    client = MongoClient(os.getenv("MONGO_URI"))

    collection = client["festive_flix_db"]["holiday_movies_collection"]

except Exception as e:
    print(f"ERROR: Failed to connect to MongoDB: {e}")
    exit(1)

embedding = VoyageAIEmbeddings(
    voyage_api_key=os.getenv("VOYAGE_API_KEY"), 
    model="voyage-3-lite"
)

#Instantiate the vector store with LangChain configuration
vector_store = MongoDBAtlasVectorSearch(
    collection=collection,
    embedding=embedding,
    index_name="vector_index",
    text_key="plot",
    embedding_key="embedding"
)

#Similarity search
query = "Santa Claus"
print(f"\nSearching for: '{query}'")

try:
    # LangChain  handles embedding the query
    results = vector_store.similarity_search_with_score(query, k=3)
    print(f"Found {len(results)} results")

except Exception as e:
    print(f"Error occurred: {e}")
    results = []

#Display results
if results:
    print("\n=== Search Results for the query ===")
    for i, (doc, score) in enumerate(results, 1):
        # Extract metadata from the document
        title = doc.metadata.get("title", "Unknown")
        runtime = doc.metadata.get("runtime", "Unknown")
        genres = doc.metadata.get("genres", [])
        released = doc.metadata.get("released", "Unknown")
        awards = doc.metadata.get("awards", {})
        plot = doc.page_content

        print(f"\nResult {i} (Score: {score:.4f}):")
        print(f"Title: {title}")
        print(f"Plot: {plot}")
        print(f"Runtime: {runtime} minutes")
        print(f"Genres: {', '.join(genres) if isinstance(genres, list) else genres}")
        print(f"Released: {released[:4] if released != 'Unknown' else 'Unknown'}")

        if awards and awards.get("text"):
            print(f"Awards: {awards['text']}")
        print("-" * 50)
else:
    print("No results found.")

Now, when we run the script with the query = "Santa Claus", a similarity search is executed and we see the results in the terminal.

But we need to render it in our browser and make it prettier, so let’s do that.

Render data

#views.py 
from django.shortcuts import render

import os
from dotenv import load_dotenv
from langchain_voyageai.embeddings import VoyageAIEmbeddings
from langchain_mongodb.vectorstores import MongoDBAtlasVectorSearch

from langchain_voyageai import VoyageAIEmbeddings
from pymongo import MongoClient

load_dotenv()

def search_holiday_movies(request):

    query = request.GET.get("q", "")
    results = []

    if query:
        # use API keys
        voyage_api_key = os.getenv("VOYAGE_API_KEY")
        connection_string = os.getenv("MONGO_URI") 

        # Check if environment variables are loaded
        assert voyage_api_key, "ERROR: VOYAGE_API_KEY not found in .env file"
        assert connection_string, "ERROR: MONGO_URI not found in .env file"

        #This is the embedding object.
        embeddings = VoyageAIEmbeddings(
            voyage_api_key=voyage_api_key,
            model="voyage-3-lite"
        )

        #Specify our database and collection
        client = MongoClient(os.getenv("MONGO_URI"))
        database = client["festive_flix_db"]
        collection = database["holiday_movies_collection"]

        #Vector store with the embeddings model
        vector_store = MongoDBAtlasVectorSearch(
            collection=collection,
            embedding_key="embedding",
            index_name="vector_index",
            text_key="plot",
            embedding=embeddings
        )

        #Similarity search with the user's actual query
        print(f"\nSearching for: '{query}'")

        try:
            search_results = vector_store.similarity_search_with_score(query, k=3)
            print(f"Found {len(search_results)} results")

            #Format results for the template
            results = []
            for doc, score in search_results:
                result = {
                    'title': doc.metadata.get("title", "Unknown"),
                    'plot': doc.page_content,
                    'runtime': doc.metadata.get("runtime", "Unknown"),
                    'genres': doc.metadata.get("genres", []),
                    'released': doc.metadata.get("released", "Unknown"),
                    'awards': doc.metadata.get("awards", {}),
                    'score': score
                }
                results.append(result)

        except Exception as e:
            print(f"Error occurred: {e}")
            results = []

        #Print output to console
        if results:
            print(f"\n=== Search Results for '{query}' ===")
            for i, result in enumerate(results, 1):
                print(f"\nResult {i} (Score: {result['score']:.4f}):")
                print(f"Title: {result['title']}")
                print(f"Plot: {result['plot'][:100]}...")
                print("-" * 50)
        else:
            print(f"No results found for query: '{query}'")

    return render(request, "search_results.html", {"results": results, "query": query})

#festive_flix/templates/search_results.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Holiday Movie Search 🎄</title>
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }

        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: #f8f9fa;
            color: #333;
            line-height: 1.6;
        }

        .container {
            max-width: 800px;
            margin: 0 auto;
            padding: 40px 20px;
        }

        .header {
            text-align: center;
            margin-bottom: 40px;
        }

        .title {
            font-size: 2rem;
            color: #2c3e50;
            margin-bottom: 10px;
        }

        .subtitle {
            color: #6c757d;
            font-size: 1rem;
        }

        .search-form {
            background: white;
            padding: 30px;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(156, 151, 151, 0.1);
            margin-bottom: 30px;
        }

        .search-input {
            width: 100%;
            padding: 12px 16px;
            font-size: 16px;
            border: 2px solid #e9ecef;
            border-radius: 6px;
            margin-bottom: 15px;
            transition: border-color 0.3s;
        }

        .search-input:focus {
            outline: none;
            border-color: #66986d;
        }

        .search-button {
            background: #66986d;
            color: white;
            padding: 12px 24px;
            border: none;
            border-radius: 6px;
            font-size: 16px;
            cursor: pointer;
            transition: background-color 0.3s;
        }

        .search-button:hover {
            background: #9da29e;
        }

        .results-section {
            margin-top: 30px;
        }

        .results-info {
            margin-bottom: 20px;
            padding: 15px;
            background: #d4e6d4;
            border-radius: 6px;
            border-left: 4px solid #66986d;
        }

        .movie-card {
            background: white;
            border-radius: 8px;
            padding: 20px;
            margin-bottom: 20px;
            box-shadow: 0 2px 8px rgba(0,0,0,0.1);
            border: 1px solid #e9ecef;
        }

        .movie-title {
            font-size: 1.3rem;
            color: #2c3e50;
            margin-bottom: 10px;
            font-weight: 600;
        }

        .movie-plot {
            color: #555;
            margin-bottom: 15px;
            line-height: 1.6;
        }

        .movie-details {
            display: grid;
            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
            gap: 10px;
            padding-top: 15px;
            border-top: 1px solid #e9ecef;
            font-size: 0.9rem;
            color: #6c757d;
        }

        .detail-item {
            display: flex;
            align-items: center;
            gap: 5px;
        }

        .genres {
            grid-column: span 2;
            margin-top: 10px;
        }

        .genre-tag {
            display: inline-block;
            background: #f8f9fa;
            color: #495057;
            padding: 3px 8px;
            border-radius: 12px;
            font-size: 0.8rem;
            margin: 2px;
            border: 1px solid #dee2e6;
        }

        .similarity-score {
            background: #28a745;
            color: white;
            padding: 4px 8px;
            border-radius: 12px;
            font-size: 0.8rem;
            font-weight: 500;
            margin-left: auto;
        }

        .no-results {
            text-align: center;
            background: white;
            padding: 40px;
            border-radius: 8px;
            box-shadow: 0 2px 8px rgba(0,0,0,0.1);
        }

        .no-results-text {
            color: #6c757d;
            font-size: 1.1rem;
        }
    </style>
</head>
<body>
    <div class="container">
        <div class="header">
            <h1 class="title">Holiday Movie Search 🎄</h1>
            <p class="subtitle">Search for holiday movies by plot, themes, or keywords</p>
        </div>

        <div class="search-form">
            <form method="get" action="">
                <input 
                    type="text" 
                    name="q" 
                    class="search-input" 
                    placeholder="Enter keywords like 'elf', 'Santa Claus', 'Christmas magic'..." 
                    value="{{ query }}"
                >
                <button type="submit" class="search-button">Search Movies</button>
            </form>
        </div>

        {% if query %}
        <div class="results-section">
            {% if results %}
                <div class="results-info">
                    <strong>Search Query:</strong> "{{ query }}"<br>
                    <strong>Results Found:</strong> {{ results|length }} movie(s)
                </div>

                {% for result in results %}
                <div class="movie-card">
                    <div style="display: flex; align-items: center; justify-content: space-between;">
                        <h3 class="movie-title">{{ result.title }}</h3>
                        <span class="similarity-score">{{ result.score|floatformat:3 }}</span>
                    </div>

                    <p class="movie-plot">{{ result.plot }}</p>

                    <div class="movie-details">
                        <div class="detail-item">
                            <strong>Runtime:</strong> {{ result.runtime }} min
                        </div>
                        <div class="detail-item">
                            <strong>Released:</strong> {{ result.released|slice:":4" }}
                        </div>

                        {% if result.genres %}
                        <div class="genres">
                            <strong>Genres:</strong>
                            {% if result.genres|length > 0 %}
                                {% for genre in result.genres %}
                                    <span class="genre-tag">{{ genre }}</span>
                                {% endfor %}
                            {% else %}
                                <span class="genre-tag">{{ result.genres }}</span>
                            {% endif %}
                        </div>
                        {% endif %}
                    </div>
                </div>
                {% endfor %}
            {% else %}
                <div class="no-results">
                    <h3 class="no-results-text">No movies found for "{{ query }}"</h3>
                    <p>Try different keywords like "Santa", "Christmas", "holiday", or "winter"</p>
                </div>
            {% endif %}
        </div>
        {% endif %}
    </div>
</body>
</html>

Run python manage.py runserver.
Access the url http://127.0.0.1:8000/ and check for movies based on keywords.

Conclusion

Great job on following through this tutorial on building a RAG app that recommends holiday movies based on a similarity search with Django MongoDB Backend, Voyage API, and LangChain.

In this tutorial, we started off by getting our movies dataset (JSON file), creating a scaffold Django project and virtual environment, creating models based on our sample data, adding embeddings with Voyage AI, uploading data into the MongoDB Atlas cluster, adding our MongoDB Atlas Vector Search index with LangChain, and finally, we rendered and visualized query results with a simple template.

You can clone the GitHub repo for this project.

Check out another use case of Django MongoDB Backend, Voyage AI, and LangChain.

If you liked this tutorial or have questions or feedback, kindly leave a comment and give this tutorial a reaction at the top! Thank you and happy holidays in advance!

Building a REST API with the Django REST Framework and MongoDB

Abigail Afi Gbadago — Tue, 23 Sep 2025 15:47:11 +0000

REpresentational State Transfer (REST) APIs are fundamental in building software applications and services because they support efficient scaling and optimization of client-server interactions. REST is a software architectural style that retrieves and transmits user’s requests on the client side and information rendered on the server end in JavaScript Object Notation (JSON) or some other format.

Client requests are executed through Hypertext Transfer Protocol (HTTP) with HTTP verbs (methods):

GET: retrieve data sent by the server
POST: send and publish information to the server
PUT: update the server information
PATCH: partially modify an existing resource
DELETE: delete information from the server

REST APIs conform to:

Client-server architecture.
Statelessness.
Cacheable data.
Uniformity between systems.
A layered architecture that structures types of server.

REST APIs are heavily used in mobile and web app development since mobile applications can access them in the background and web apps can benefit from dynamic content that does not require a page reload. Also, third-party integrations such as payment gateways and microservices use REST APIs to interact with different services in larger systems.

Modern software applications using microservices rely on REST APIs that glue everything together. Instead of one application performing various concurrent tasks, which may not be optimal for high performance and scalability, REST APIs can be used with many smaller independent services like payment gateways, authentication, analytics, inventory and the like, with each service following the single-responsibility principle, executing tasks and communicating with each other.

This enables you to build, deploy, and scale each service separately without bringing the entire system down. Without REST APIs, services will be isolated with no means of interaction to execute tasks, and every application will exist in silos and system integrations may be difficult.

What is the Django REST framework?

Django developers have several options for building REST APIs, one of which is the Django REST framework (DRF)—a powerful and flexible toolkit for building web application programming interfaces (APIs). The Django REST framework OAuth package provides both OAuth1 and OAuth2 support, serialization support for both ORM and non-ORM data sources, extensive documentation, and other cool, customizable features.

In this tutorial, we will cover how to build a RESTful API using the official Django MongoDB Backend while highlighting the available features.

Prerequisites

MongoDB Atlas cluster which comes with the sample_geospatialdataset by default—learn how to create a deployment
Download Python 3.10 or later

Installation and setup

Set up a virtual environment

  python -m venv venv
  source venv/bin/activate

Install Django MongoDB Backend and DRF

pip install django-mongodb-backend djangorestframework

Configuration

Configure your MongoDB connection

Project structure

After creating your virtual environment (venv) in the previous step:

Create a Django project with the Django MongoDB Backend project template.

The django-mongodb-project template is similar to the default Django project template but it includes MongoDB-specific migrations and modifies the settings.py file to configure Django to use an ObjectId as each model's primary key.

After, the directory structure should look like this:

[Expected Django project directory structure in VS Code ]

Create the shipwrecks_api app by running this command:

python manage.py startapp shipwrecks_api --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.1.x.zip

The django-mongodb-app template ensures that your app.py file includes the line

"default_auto_field = 'django_mongodb_backend.fields.ObjectIdAutoField'"

Then, add the name of the app (shipwrecks_api) , rest framework, and django_filters to the settings.py under the INSTALLED APPS section.

It should look like this:

[Installed apps under settings.py]

The final directory structure should look like this:

[Directory structure showing Django project and app]

Django’s MVC pattern overview

Now, let’s take a step back to understand the architecture pattern of Django which will be useful in the creation of the shipwrecks_api.

The Django project architecture follows the Model View Controller architectural pattern but has a slight variation where you have Models, Templates, and Views (MTV). The MVC pattern in Django consist of:

A model: The model is the data layer which defines how data will be structured, enforces validation, and handles interactions with the MongoDB database.
A view: The view describes the data that gets presented to the user. It’s not necessarily how the data looks, but which data is presented. The view describes which data you see, not how you see it.
A template: The template is the presentation layer and consists of HTML files that define how data should appear to users.

Next, let’s define how our data will be structured based on the sample geospatial dataset. Kindly take a look at the fields within the sample document on that page as we will be data modeling using them in the next step when creating our Django model. This dataset contains fields which hold GeoJSON data.

Defining models

With Django MongoDB Backend, the MongoDB _id field is mapped to Django’s traditional id field—meaning you won’t have both _id and id simultaneously.

This is achieved by the DEFAULT_AUTO_FIELD =django_mongodb_backend.fields.ObjectIdAutoField line in the settings.py file in the django project.

Based on the sample document in the sample geospatial database, our model will look like:

#models.py

from django.db import models
from django_mongodb_backend.fields import ArrayField
from django_mongodb_backend.managers import MongoManager

class ShipwreckFeature(models.Model):
    recrd = models.CharField(max_length=200, blank=True)
    vesslterms = models.CharField(max_length=200, blank=True)
    feature_type = models.CharField(max_length=200, blank=True)
    chart = models.CharField(max_length=200, blank=True)
    latdec = models.FloatField(null=True, blank=True)
    londec = models.FloatField(null=True, blank=True)
    gp_quality = models.CharField(max_length=200, blank=True)
    depth = models.CharField(max_length=200, blank=True)
    sounding_type = models.CharField(max_length=200, blank=True)
    history = models.TextField(blank=True)
    quasou = models.CharField(max_length=200, blank=True)
    watlev = models.CharField(max_length=200, blank=True)
    coordinates = ArrayField(
        base_field=models.FloatField(), null=True, blank=True
    )
objects = MongoManager()

    class Meta:
        db_table = "shipwrecks_api" 
        managed = False

    def __str__(self):
        return f"{self.feature_type} at ({self.latdec}, {self.londec})"

Learn more about document modeling with Django MongoDB Backend.

Serializers

Introduction to DRF serializers

Serializers allow complex data, such as querysets and model instances, to be converted to native Python datatypes that can then be easily rendered into JSON, XML, or other content types. Serializers also provide deserialization, allowing parsed data to be converted back into complex types, after first validating the incoming data.

The serializers in the REST framework work similarly to Django's Form and ModelForm classes. The DRF provides a serializer class which gives you a powerful and generic way to control the output of your responses, as well as a ModelSerializer class which provides a useful shortcut for creating serializers that deal with model instances and querysets.

In the serializer class below, we use two serializer fields.

The SerializerMethodField is a read-only field which gets its value by calling a method on the serializer class it is attached to.
The HyperlinkedIdentityField can be applied as an identity relationship, such as the url field on a HyperlinkedModelSerializer (introduces the use of a hyperlinked style between entities). It can also be used for an attribute on the object.

Create serializers

#serializers.py

from rest_framework import serializers
from .models import ShipwreckFeature

class ShipwreckFeatureSerializer(serializers.ModelSerializer):
    id = serializers.SerializerMethodField(read_only=True)
    url = serializers.HyperlinkedIdentityField(
        view_name='shipwreck-detail'
    )

    def get_id(self, obj):
        """Convert ObjectId to string for API response"""
        return str(obj.pk) if obj.pk else None

    class Meta:
        model = ShipwreckFeature
        fields = [
           'id', 'url', 'recrd', 'vesslterms', 'feature_type',
            'chart', 'latdec', 'londec',
            'gp_quality', 'depth', 'sounding_type',
            'history', 'quasou', 'watlev',
            'coordinates'
        ]
        read_only_fields = ['id']

Views and URL configuration

Now, let’s create function-based views to display the shipwreck data.

#views.py

from rest_framework import viewsets, filters, permissions
from rest_framework.response import Response
from rest_framework import status
from django.shortcuts import get_object_or_404
from bson import ObjectId
from bson.errors import InvalidId
from .models import ShipwreckFeature
from .serializers import ShipwreckFeatureSerializer
from django_filters.rest_framework import DjangoFilterBackend

class ShipwreckFeatureViewSet(viewsets.ModelViewSet):
    queryset = ShipwreckFeature.objects.all()
    serializer_class = ShipwreckFeatureSerializer
    permission_classes = [permissions.AllowAny]
    filter_backends = [DjangoFilterBackend, filters.OrderingFilter]
    lookup_field = 'pk'  
    filterset_fields = ['recrd', 'vesslterms', 'feature_type', 'latdec', 'londec']
    ordering_fields = ['latdec', 'londec']
    ordering = ['latdec']
    http_method_names = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options']

    def get_object(self):
        """
        Override get_object to handle ObjectId validation
        """
        lookup_value = self.kwargs[self.lookup_field]

        # Validate ObjectId
        try:
            if not ObjectId.is_valid(lookup_value):
                raise InvalidId("Invalid ObjectId format")
            object_id = ObjectId(lookup_value)
        except (InvalidId, ValueError):
            from django.http import Http404
            raise Http404("Invalid ObjectId format")

        # Get the object
        queryset = self.filter_queryset(self.get_queryset())
        obj = get_object_or_404(queryset, pk=object_id)
        self.check_object_permissions(self.request, obj)
        return obj

    def destroy(self, request, *args, **kwargs):
        """
        Override destroy to add better error handling
        """
        try:
            instance = self.get_object()
            self.perform_destroy(instance)
            return Response(status=status.HTTP_204_NO_CONTENT)
        except Exception as e:
            return Response(
                {'error': f'Failed to delete shipwreck: {str(e)}'}, 
                status=status.HTTP_500_INTERNAL_SERVER_ERROR
            )

Url configuration to map views in the shipwrecks_api

#urls.py - shipwrecks_api

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import ShipwreckFeatureViewSet

router = DefaultRouter()
router.register(r'shipwrecks', ShipwreckFeatureViewSet, basename='shipwreck')

urlpatterns = [
    path('', include(router.urls)),
]

Url configuration to map views in the djangoproject

#urls.py - shipwrecks_api

from django.contrib import admin
from django.urls import path, include
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('shipwrecks_api.urls')),

    # Swagger Docs
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
]

Using the Python shell to create objects

#sw1 = ShipwreckFeature object for testing

sw1 = ShipwreckFeature.objects.create(
    recrd="R001",
    vesslterms="RMS Titanic",
    feature_type="Wrecks - Submerged, not dangerous",
    chart="US,U1,graph,DNC H140984",
    latdec=10.123456,
    londec=-80.654321,
    gp_quality="A",
    depth="3840 meters",
    sounding_type="approximate",
    history="The RMS Titanic sank on April 15, 1912, after hitting an iceberg, and its wreck lies in the North Atlantic Ocean about 400 nautical miles southeast of the coast of Newfoundland, Canada.",
    quasou="depth known",
    watlev="always under water/submerged",
    coordinates=[-80.654321, 10.123456]
)

#sw2 = ShipwreckFeature object for testing

sw2 = ShipwreckFeature.objects.create(
    recrd="R002",
    vesslterms="MV Explorer",
    feature_type="Wrecks - Submerged, navigational hazard",
    chart="US,U2,graph,DNC H1409880",
    latdec=-5.987654,
    londec=150.4321,
    gp_quality="B",
    depth="45 meters",
    sounding_type="sonar",
    history="Collided with reef in 1955",
    quasou="depth approximate",
    watlev="always under water/submerged",
    coordinates=[150.4321, -5.987654]
)

Using the Python shell python manage.py shell

[Creating a shipwreck object via the Python shell]

Using the Django REST framework web browsable API

Run python manage.py runserver and fill the fields of the object via the raw data tab or HTML form.

Examples of raw JSON data to create an object via the raw data option on the DRF web browsable API :

Example 1:

{
  "recrd": "R001",
  "vesslterms": "RMS Titanic",
  "feature_type": "Wrecks - Submerged, not dangerous",
  "chart": "US,U1,graph,DNC H140984",
  "latdec": 10.123456,
  "londec": -80.654321,
  "gp_quality": "A",
  "depth": "3840 meters",
  "sounding_type": "approximate",
  "history": "The RMS Titanic sank on April 15, 1912, after hitting an iceberg, and its wreck lies in the North Atlantic Ocean about 400 nautical miles southeast of the coast of Newfoundland, Canada.",
  "quasou": "depth known",
  "watlev": "always under water/submerged",
  "coordinates": "[-80.654321, 10.123456]"
}

Example 2:

{
"recrd": "R002",
  "vesslterms": "MV Explorer",
  "feature_type": "Wrecks - Submerged, navigational hazard",
  "chart": "US,U2,graph,DNC H1409880",
  "latdec": -5.987654,
  "Londec": 150.4321,
  "gp_quality": "B",
  "depth": "45 meters",
  "sounding_type": "sonar",
  "history": "Collided with reef in 1955",
  "quasou": "depth approximate",
  "watlev": "always under water/submerged",
  "coordinates": "[150.4321, -5.987654]"
}

CRUD operations:

The CRUD methods — CREATE, GET/RETRIEVE, UPDATE, and DELETE—can be executed via the DRF web browsable API, Postman, and via the Python shell. Since this tutorial covers the DRF, the examples shown will be done via the DRF web browsable API.

List all shipwrecks - http://127.0.0.1:8000/shipwrecks/

[DRF web browsable API page listing all shipwreck features]

GET via query parameter /api/shipwrecks/{id}/ - Example: http://127.0.0.1:8000/shipwrecks/?{id}/

[DRF web browsable API page listing a shipwreck feature by an id]

POST /api/shipwrecks/ - http://127.0.0.1:8000/shipwrecks/

[DRF web browsable API page after successfully creating a shipwreck]

PUT/PATCH: /api/shipwrecks/{id}/

http://127.0.0.1:8000/shipwrecks/

In this example, the gp_quality of changed from "A" to "C" and the latdec is changed to 20.83546.

[Updating a Shipwreck Feature via a PATCH method]

[Successfully updated the Shipwreck object via PATCH request]

DELETE /api/shipwrecks/{id}/

(Bulk delete is possible by adding it as a custom operation)

[Deleting a shipwreck feature via an id on the DRF web browsable API]

[Successfully deleted object via id on the DRF web browsable API]

Pagination

Pagination allows you to modify how large result sets are split into individual pages of data to improve readability and performance. To use the default pagination class, add the following lines of code to your settings.py, indicating that you want to display twenty(20) results per page.

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20
}

Django Admin

Create an admin user via the Django Admin interface.

Testing

from django.test import TestCase
from rest_framework.test import APITestCase
from rest_framework import status
from django.urls import reverse
from .models import ShipwreckFeature

class ShipwreckFeatureModelTest(TestCase):

    def setUp(self):
        self.shipwreck = ShipwreckFeature.objects.create(
            record="R001",
            vesslterms="test_vessel",
            feature_type="wreck",
            chart="test_chart",
            latdec=40.7128,
            londec=-74.0060,
            history="Test shipwreck for testing",
            coordinates=[-74.0060, 40.7128]
        )

    def test_shipwreck_creation(self):
        """Test that a shipwreck can be created"""
        self.assertEqual(self.shipwreck.recrd, "R001")
        self.assertEqual(self.shipwreck.vesslterms, "test_vessel")
        self.assertEqual(self.shipwreck.feature_type, "wreck")

    def test_shipwreck_str_method(self):
        """Test the string representation of shipwreck"""
        expected = "wreck at (40.7128, -74.006)"
        self.assertEqual(str(self.shipwreck), expected)


class ShipwreckFeatureAPITest(APITestCase):
    """Simple tests for the ShipwreckFeature API"""

    def setUp(self):
        self.shipwreck = ShipwreckFeature.objects.create(
            recrd="R002",
            vesslterms="api_test_vessel",
            feature_type="wreck",
            latdec=41.0,
            londec=-75.0,
            history="API test shipwreck"
        )
        self.list_url = reverse('shipwreck-list')

    def test_get_shipwreck_list(self):
        """Test retrieving list of shipwrecks"""
        response = self.client.get(self.list_url)
        self.assertEqual(response.status_code, status.HTTP_200_OK)
        self.assertEqual(len(response.data['results']), 1)

    def test_create_shipwreck(self):
        """Test creating a new shipwreck"""
        data = {
            'recrd': 'R003',
            'vesslterms': 'new_vessel',
            'feature_type': 'wreck',
            'latdec': 42.0,
            'londec': -76.0,
            'history': 'Newly created test shipwreck'
        }
        response = self.client.post(self.list_url, data, format='json')
        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
        self.assertEqual(ShipwreckFeature.objects.count(), 2)

    def test_get_single_shipwreck(self):
        """Test retrieving a single shipwreck"""
        detail_url = reverse('shipwreck-detail', kwargs={'pk': self.shipwreck.pk})
        response = self.client.get(detail_url)
        self.assertEqual(response.status_code, status.HTTP_200_OK)
        self.assertEqual(response.data['recrd'], 'R002')

Documentation

With REST APIs, we can document the endpoints with tools such as Swagger UI, Postman, OpenAPI Generator, and the like. With Django, a popular go-to is Swagger which describes the structure of your APIs so that machines can read them.

To implement documentation with Swagger UI:

Run pip install drf-spectacular in your terminal.
Add 'drf_spectacular' under INSTALLED_APPS in settings.py .

SPECTACULAR_SETTINGS = {
    'TITLE': 'Shipwrecks API',
    'DESCRIPTION': 'API for managing shipwreck data with MongoDB backend',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
    'COMPONENT_SPLIT_REQUEST': True,
    'SCHEMA_PATH_PREFIX': '/api/',
}

Add the following to urls.py:

from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView,

path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),

Now, we can access the Shipwreck API docs by running the following command http://127.0.0.1:8000/api/docs/. This gives a visualization of the CRUD endpoints which we can interact with just as with the DRF web browsable API.

[Swagger API page listing all CRUD methods for the Shipwreck API]

Example: Read method to retrieve all ShipwreckFeature objects.

[Swagger API page listing ShipwreckFeature objects]

Example
Creating a Shipwreck Feature object via Swagger.

[Swagger API page showing the created ShipwreckFeature object]

Wrap-up and further resources

In this tutorial, we looked at REST API architecture, HTTP methods/verbs, the Django REST framework (DRF), how to set up and install dependencies for the API, configuration, structuring the Django project, Django’s MTV pattern, creating the Django app, defining models, URLS, views, tests, CRUD examples with the Shipwreck feature database, and documenting the Shipwreck API using Swagger.

At this point, you have the essentials to create a REST API with the Django REST framework and Django MongoDB Backend. Give it a shot and comment on your experience—looking forward to it!

If you liked this tutorial or have questions or feedback, kindly leave a comment and give this tutorial a reaction up top!

References

Document Modeling With the Django MongoDB Backend

Abigail Afi Gbadago — Mon, 18 Aug 2025 17:53:54 +0000

In this tutorial, we will cover how the document model works using the Django MongoDB Backend with examples of data modeling, embedding and referencing, query designs, and design patterns.

A document database stores information in documents that are fast and easy for developers to work with. Document databases have flexible schema that allows the data model to evolve as the application changes and to horizontally scale out.

While Django was originally built for the RDMS structure, MongoDB provides a flexible solution of modeling data that suits applications that implement nested and/or dynamic data. It is a great option for applications that require quick read performance, fast iteration, and JSON-like handling. Thus, it’s a great fit for when your data model is dynamic, flexible, and nested.

Setting up the Django MongoDB Backend

Follow the steps outlined in the Getting Started section for the Django MongoDB Backend. This covers:

Installing the Django MongoDB Backend.
Configuring MongoDB as your database in settings.py.
Creating a sample project and app

Data modeling in Django

In Django, data is modeled in the form of objects, called models, which represent tables in a relational database or collections in MongoDB. A Django model is the single, definitive source of information about your data. It contains the essential fields and behaviors of the data you’re storing. Generally, each model maps to a single database table.

Example:

This example model defines a Human, which has a first_name and last_name:

from django.db import models

class Human(models.Model):
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)

Designing document models in MongoDB

In MongoDB, data modeling is organizing data (could consist of key-value pairs, relational, objects, graph, and geospatial data) flexibly within collections in a database and its related entities. Document modeling supports a flexible schema for data, making it easily adaptable to your application’s needs. Restructuring your schema can help you optimize your queries and can be done as many times as necessary.

A document stores data records that share a similar structure within collections.

Key differences to note when modeling data in RDMS and MongoDB

Tables and collections

A collection in MongoDB is a group of data stored in documents and a table. In RDMS, it’s a collection of related data and it consists of columns and rows.

Rows and documents

Documents in MongoDB group related data together in a collection, and rows store data in relational databases.

Predefined schema and schema-less but structured

With RDBMS, data is strictly stored according to a predefined schema, and as such, the data must be in the required structure. In MongoDB, data is stored in a schema-less but structured format. This means that there is no strict schema validation. However, schema validation rules can be created in order to ensure that all documents in a collection share a similar structure.

Due to the flexible nature of data models in MongoDB, there are various ways to map relationships between different entities in your schema.

Main options when modeling data:

Embedding data in the same collection
Referencing to connect related data that exists in separate collections

Relationships between documents in MongoDB

A one-to-one embedded relationship is modeled by embedding documents within a document, demonstrating documents embedded within the same document.
A one-to-many embedded document relationship is modeled by embedded documents, demonstrating one document linked to many documents.
A one-to-many relationship is modeled by referencing documents, demonstrating one document linked to many documents.
A many-to-many relationship is modeled by referencing documents, demonstrating many documents linked to other related documents.

MongoDB supports flexible data modeling by organizing data within documents with the links between related entities in a database.

The document design process

The document design process consists of the following steps:

Identify your workload: This helps determine the application that runs most frequently which aids in creating effective indexes and minimizes the number of calls the application makes to the database.
Map relationships: Mapping relationships is crucial because it determines the relationships of data stored in your documents which is instrumental for faster performance and querying using indexes.
Apply design patterns: Schema design patterns help to optimize your data model based on your application's access patterns. This improves application performance and reduces schema complexity.
Create indexes: An index is a data structure that stores the value of a field or specific sets of fields. It supports query patterns and covers a query when the index contains all of the fields scanned and improves query performance.

Define a model

To create a model in a MongoDB collection with the Django MongoDB Backend:
Add your model class definitions to your application's models.py file by specifying the fields you want to store and include any model metadata in an inner Meta class. You can also use the str() method to define the string representation of your model.

Syntax to define a model

class <Model name>(models.Model):
     <field name> = <data type>
     # Include additional fields here
     class Meta:
         # Include metadata here
     def __str__(self):

For example:

from django.db import models

class Human(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    age = models.PositiveIntegerField()

   class Meta:
db_table = "human"
managed = False

    def __str__(self):
        return f"{self.first_name} {self.last_name}"

Knowing when to embed vs reference

When designing your data models, it’s essential to know the relationships between them in order to determine whether to embed or reference while mapping relationships.

When related data needs to be retrieved in a single database operation, we generally embed sub-documents or arrays whilst we reference when relationships between data need to be stored using links, from one document to another.

When to embed documents

Embedded documents store related data in a single document structure. A document can contain arrays and sub-documents with related data. These denormalized data models allow applications to retrieve related data in a single database operation.

Why embed?

It helps in denormalization for read performance, thereby reducing duplicated data and the number of joins needed during read operations/$lookup operations.

Example: A product catalog where category is embedded into product and types are embedded as an array.

Using the Django MongoDB Backend, this translates to:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import EmbeddedModelField, EmbeddedModelArrayField

class Category(EmbeddedModel):
    name = models.CharField(max_length=100)

class TypeOption(EmbeddedModel):
    color = models.CharField(max_length=50)
    size = models.CharField(max_length=10)

class Product(models.Model):
    name = models.CharField(max_length=200)
    price = models.FloatField()
    category = EmbeddedModelField(Category)
    types = EmbeddedModelArrayField(TypeOption)

    def __str__(self):
        return self.name

An example of the product object in Django:

# Embedded models
category = Category(name="Clothing")
types = [
    TypeOption(color="Black", size="L"),
    TypeOption(color="White", size="XL")
]

#Creating the object
product = Product.objects.create(
    _id="p1",
    name="T‑Shirt",
    price=15.99,
    category=category,
    types=types
)

When to reference documents

References store relationships between data by including links, called references, from one document to another. For example, a customerId field in an orders collection indicates a reference to a document in the customers collection.

Applications can resolve these references to access the related data. Broadly, these are normalized data models.

Why reference?

Referencing allows you to reuse data and avoid overbloated documents and nested arrays.

Example (one-to-many):
Consider we have a customer collection with the following fields:

# Create embedded instances
customer = CustomerInfo(
    name="Alice", 
    email="alice@example.com", 
    address="123 Main St"
)

items = [
    OrderItem(product="T‑Shirt", quantity=2, price=19.99),
    OrderItem(product="Jeans", quantity=1, price=39.99)
]

# Create and save the order
order = Order.objects.create(
    _id="o1001",
    customer=customer,
    items=items,
    total=79.97,
    orderDate=timezone.make_aware(datetime(2025, 6, 11, 11, 0))
)

print(order)

Considering an instance when our data increases or needs to be updated, it will overbloat the document. Hence, we can reference the customerId in the orders collection, making it easier to update our collection as the data keeps increasing and changing, and reduce data duplication.

Example:

# Create Customer instance
customer = Customer.objects.create(
    _id="a123",
    name="Afi",
    email="afi@example.com",
    address="123 MongoDB Street"
)

# Create Order instance
order = Order.objects.create(
    _id="o1001",
    customerId="a123",
    items=[
        OrderItem(product="Tracksuit", quantity=1, price=29.99),
        OrderItem(product="MongoDB Beanie", quantity=1, price=9.99)
    ],
    total=39.99,
    orderDate=timezone.make_aware(datetime(2025, 8, 11, 10, 0))
)

Design patterns in the document model

Schema design patterns optimize reads and writes for the document model. We will discuss the:

Bucket Pattern.
Outlier Pattern.
Subset Pattern.

Bucket Pattern

The Bucket Pattern is used to bucket data (time-series or analytics) together. Data is organized into specific groups, increasing the ability to discover historical trends, provide future forecasting, and optimize our use of storage.

Example where a bank groups monthly transactions:

# Embedded transaction instances
transactions = [
    Transaction(date=date(2025, 8, 1), amount=-50.0, description="Grocery"),
    Transaction(date=date(2025, 8, 3), amount=-120.0, description="E Energy"),
    Transaction(date=date(2025, 8, 5), amount=1000.0, description="Paycheck"),
]

# MonthlyStatement document
bank_statement = MonthlyStatement.objects.create(
    _id="a123",
    userId="a123",
    month="2025-08",
    transactions=transactions
)

Outlier Pattern

The Outlier Pattern is useful for data that falls outside the "normal" pattern and needs to be tracked. The significant thing to note is that the outliers show a lot of difference in their data which isn’t considered "normal" and tweaking the application design to accommodate these edge cases can degrade performance for the more typical queries and documents.

Example:
Let’s say for a normal book entry, we have the following document:

book = Book.objects.create(
    _id="a123",
    title="Some Crime Novel",
    author="Jane Doe",
    copiesSold=1500
)

Then, consider this outlier example:

outlier_book = OutlierBook.objects.create(
    _id="b123",
    title="Goblet of Fire",
    author="John Doe",
    copiesSold=180000000,
    outlier=True
)

We see that the “copiesSold” is very high as compared to the previous entry and as such, the “outlier” field is added to track if it’s an outlier or not.

Subset Pattern

The Subset Pattern addresses the issues that arise when the working set (frequently accessed data) and indexes grow beyond the physical RAM allotted, which can result in information being removed from memory.

Example:
Let’s use the previous book example (from the Outlier Pattern) but let’s add an embedded array for reviews, where a book can have multiple reviews but a review can belong to only one book. In the case, where the copies sold is 180,000,000, the reviews will be exponentially high and will create a bloated document which affects querying and performance.

As such, we can only display the latest reviews per book and put the reviews in a separate collection, as seen below.

#imports
# Create review instances
reviews = [
    Review(reviewId=8212, author="Jess", text="Amazing read for a Potter Head!", date=date(2025, 8, 12)),
    Review(reviewId=8211, author="Alice", text="Same feeling as the movie!", date=date(2025, 8, 12))
]

# Create the book instance
book = Book.objects.create(
    _id="b123",
    title="Goblet of Fire",
    author="John Doe",
    copiesSold=180000000,
    outlier=True,
    recentReviews=reviews
)

Separate collection for reviews:

# Create review instances
reviews = [
    Review(reviewId=8212, author="Afi", text="Amazing read for a Potter Head!", date=date(2025, 8, 12)),
    Review(reviewId=8211, author="Jane", text="Same feeling as the movie!", date=date(2025, 8, 12))
]

# Create the product instance
product = Product.objects.create(
    _id="b123",
    title="Goblet of Fire",
    author="John Doe",
    copiesSold=180000000,
    outlier=True,
    recentReviews=reviews
)

Using Django ORM equivalents with the document model

The document model used with Django doesn’t have an ORM. Rather, it integrates directly with Django's model layer and ORM, so your Django models.Model classes map to MongoDB collections and documents, rather than SQL tables.

ORM operations—like filtering, lookups, and joins—are converted into MongoDB operations, such as lookups using optimized MongoDB aggregations, JOINs performed with $lookup, index definitions, and other schema-level operations.

In the next step, we will be looking at examples of ORM equivalent queries with sample data from the sample_guide dataset that contains documents that represent a planet in our solar system.

First, we have to model the data based on the document showed in the sample_samplies dataset to match what we want to use in our models.py file:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.managers import MongoManager
from django_mongodb_backend.fields import (
    ArrayField,
    EmbeddedModelArrayField,
    EmbeddedModelField
)

class Item(EmbeddedModel):
    name = models.CharField(max_length=100)
    tags = ArrayField(
        models.CharField(max_length=50),
        null=True,
        blank=True
    )
    price = models.DecimalField(max_digits=10, decimal_places=2)
    quantity = models.IntegerField()

class CustomerInfo(EmbeddedModel):
    gender = models.CharField(max_length=1)
    age = models.IntegerField()
    email = models.EmailField()
    satisfaction_score = models.IntegerField(null=True, blank=True)

class Sale(models.Model):
    sale_date = models.DateTimeField()
    items = EmbeddedModelArrayField(Item, null=True, blank=True)
    store_location = models.CharField(max_length=100)
    customer = EmbeddedModelField(CustomerInfo)
    coupon_used = models.BooleanField()
    purchase_method = models.CharField(max_length=50)
    objects = MongoManager()

    class Meta:
        db_table = "sales"
        managed = False

    def __str__(self):
        return f"Sale at {self.store_location} on {self.sale_date}"

After saving this in our models.py, run migrations and insert objects in order to query from the sample_supplies database.

#Imports
from sample_supplies.models import Sale, Item, CustomerInfo

from django.utils import timezone
from datetime import datetime
from django_mongodb_backend.managers import MongoManager
from django.db.models import Q

Example of an item object inserted:

items = [
    Item(name="notepad", tags=["office", "writing", "school"], price=35.29, quantity=2),
    Item(name="pens", tags=["writing", "office", "school", "stationary"], price=56.12, quantity=5),
    Item(name="envelopes", tags=["stationary", "office", "general"], price=19.95, quantity=8),
    Item(name="binder", tags=["school", "general", "organization"], price=14.16, quantity=3),
]

Example of a customer object inserted:

customer = CustomerInfo(gender="F", age=32, email="janedoe@fakemail.com", satisfaction_score=4)

Example of a sale object inserted:

sale = Sale.objects.create(
    _id=ObjectId(),
        sale_date=timezone.now(),
        items=items,
        store_location="Accra",
        customer=customer,
        coupon_used=True,
        purchase_method="Online"
)

Specifying A database query

To query the sample_guide database equivalent to Django ORM queries, we use the QuerySet methods (all(), filter(), get(), exclude(), and raw_aggregate()) on the Sale model manager in a query filter.

Examples:

all()

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

Sale.objects.all()

Output:

<QuerySet [<Sale: Sale at Accra on 2025-08-12 14:50:33.600000+00:00>, 
<Sale: Sale at London on 2025-08-12 14:51:01.244000+00:00>, <Sale: Sale at Paris on 2025-08-12 14:51:08.573000+00:00>]>

filter()

To query a collection for documents that match a set of criteria, user filter().

Sale.objects.filter(coupon_used=True)

Output:

<QuerySet [<Sale: Sale at Accra on 2025-08-12 14:50:33.600000+00:00>, 
<Sale: Sale at Paris on 2025-08-12 14:51:08.573000+00:00>]>

get()

To retrieve a document that matches a query, use the get() method.
You can also use the filter() method and first().

Sale.objects.filter(purchase_method="Online").first()

Output:

<Sale: Sale at Accra on 2025-08-12 14:50:33.600000+00:00>

Sale.objects.get(store_location="Accra")

Output:

<Sale: Sale at Accra on 2025-08-12 14:50:33.600000+00:00>

exclude()

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.

Sale.objects.exclude(coupon_used="True")

Output:

<QuerySet [<Sale: Sale at London on 2025-08-12 14:51:01.244000+00:00>]>

$Lookups within EmbeddedModelArray field

Sale.objects.filter(items__price__gt=30.00)

Output:

<QuerySet [<Sale: Sale at Accra on 2025-08-09 08:50:33.600000+00:00>, 
<Sale: Sale at London on 2025-08-10 14:51:01.244000+00:00>, 
<Sale: Sale at Paris on 2025-08-10 10:51:08.573000+00:00>, 
<Sale: Sale at Paris on 2025-08-10 17:47:13.089000+00:00>, 
<Sale: Sale at Lisbon on 2025-08-10 17:47:40.027000+00:00>]>

Query a primary key field

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

Sale.objects.get(pk=ObjectId("593a1394f29313caabce0d37"))

Output:

<Sale: Sale at Sao Tome on 2025-08-12 17:53:11.343000+00:00>

Q object

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.

Sale.objects.filter(
    (Q(store_location__startswith="Sao Tome") |   Q(store_location__startswith="Accra")) 
)

Output:

<QuerySet [<Sale: Sale at Accra on 2025-08-12 14:50:33.600000+00:00>, <Sale: Sale at Sao Tome on 2025-08-12 17:53:11.343000+00:00>, <Sale: Sale at Accra on 2025-08-12 17:58:41.477000+00:00>]>

Grouping and aggregations

An aggregation pipeline consists of one or more stages that process documents. Each stage performs an operation on the input documents. For example, a stage can filter documents, group documents, calculate values, and output documents from one stage to the next. For example, return the total, average, maximum, and minimum values.

Performing raw aggregate on a QuerySet

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().

Example:

sales= Sale.objects.raw_aggregate([
    {"$match": {"store_location": "Accra"}},
    {"$project": {
        "title": 1,
        "released": 1
    }
}])

for s in sales:
    print(f"Sales at the store location in {s.store_location} on the date: {s.sale_date}\n")

Output:

Sales at the store location in Accra on the date: 2025-08-12 14:50:33.600000+00:00
Sales at the store location in Accra on the date: 2025-08-12 17:58:41.477000+00:00
Sales at the store location in Accra on the date: 2025-08-12 20:00:50.157000+00:00

Best practices when modeling data in MongoDB

Avoid deeply nested documents—know when to embed or reference.
Understand your data and try to think ahead in terms of scaling so that your queries work efficiently using indexes.
Use pagination when working with large data to avoid unnecessary scrolling.

Conclusion

The document model provides an efficient way of flexibly structuring your data and helps improve query responses and efficiency when done correctly. Keep in mind that embedding isn’t always bad (it depends on the use case), and referencing isn’t always the bad guy just because you want to swerve JOINS or $lookups. They all serve a purpose to fit your application needs—that’s why you need to understand your data in order to model data efficiently. Have you tried the document model yet? If yes, how was the experience? If no, give it a try and let’s discuss. Check the resources below for more information.

Resources

Accessing Data With Django MongoDB Backend: Queries to Aggregation Pipelines

Abigail Afi Gbadago — Thu, 07 Aug 2025 13:44:30 +0000

Why use MongoDB with Django?

The MongoDB document model goes well with Django's mission to “encourage rapid development and clean, pragmatic design.” The concept of MongoDB’s document model reflects how developers think about and structure their data in code when it comes to a Django model and a MongoDB document. MongoDB allows Django developers to create their models in a whole different way, especially in modern applications, which include hierarchical, semi-structured, and rapidly evolving data structures. As such, developers won’t need to use too many JOINs in various use cases, as data that is accessed together should be stored together.

While Django was built for RDMS, using non-relational databases such as MongoDB provides advantages such as schema flexibility, aggregation pipelines, dynamic/nested data structures, high speed I/O operations, and easier scaling options since it’s designed to scale horizontally with shards with less overhead.

In this tutorial, we will be accessing and aggregating data using the Django MongoDB Backend.

Setting up Django with MongoDB

Connecting Django to MongoDB

There are different ways of using Python/Django with MongoDB, such as:

PyMongo—the native python driver for MongoDB (not an ORM).
MongoEngine—a community-backed Object Document Mapper (ODM) for MongoDB which leverages PyMongo.
Django MongoDB Backend.

Prerequisites

Python >= 3.10
Django
A virtual environment—(Example: python3.13 -m venv venv)
Django MongoDB Backend

Installation and setup

To set up and connect to a MongoDB instance using the Django MongoDB Backend, kindly visit the docs and follow through to create a Django project.

After creating your Django project, you should see the “Congratulations!” message and an image of a rocket when you access http://127.0.0.1:8000/ after starting your server.

You should see the quickstart directory, along with a venv folder, mongo_migrations, manage.py, and the README file.

Creating the application in the Django project

In this section, we will:

Create an application in our Django project using the sample_mflix database. Take a few minutes to analyze the data in the collection because that will be used to create documents in our Django MongoDB models.py file.
Look at a use-case of creating a movie model with embedded awards.
Perform CRUD operations: create, query, update nested documents on the model.

Creating the Django app with the custom MongoDB template

From the root directory in your Django project, run the following command to create a new Django app (in this case, called cine_flix) based on a custom Django MongoDB template:

python manage.py startapp cine_flix --template

The django-mongodb-app template ensures that your app.py file includes the line

default_auto_field = 'django_mongodb_backend.fields.ObjectIdAutoField'

because Django natively uses default integer, id whilst MongoDB natively uses ObjectId, _id. As such, if we skip that, we may end up with misaligned primary key types, which will affect the migrations applied or Django admin-related operations. If you did not use the template, make sure you’ve followed the steps in configuring a project to use Django MongoDB Backend.

After executing the command, you will see your cine_flix app nested in the root directory.

Look at a use-case using the Movie model which has an embedded array (Genres) as a MongoDB Django model example

We will model our data based on the sample_mflix data.

To do this, open the models.py file in the cine_flix directory and replace its contents with the following code:

from django.db import models
from django.conf import settings
from django_mongodb_backend.fields import EmbeddedModelField, ArrayField
from django_mongodb_backend.models import EmbeddedModel

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, null=True, blank=True)
    genres = ArrayField(models.CharField(max_length=100), null=True, blank=True)

    class Meta:
        db_table = "movies"
        managed = False

    def __str__(self):
        return self.title

class Viewer(models.Model):
    name = models.CharField(max_length=100)
    email = models.CharField(max_length=200)

    class Meta:
        db_table = "users"
        managed = False

    def __str__(self):
        return self.name

The model contains:

An embedded model field named awards, which stores an Award object.
An array field named genres, which stores a list of genres that describe the movie.
A Viewer model which stores account information for movie viewers.
The Award model represents embedded document values stored in the Movie model.

Now, save the models.py file and let’s go populate our views.py file.

Django views

A Django view is a Python function or class that takes an HTTP request and returns an HTTP response—typically rendering data (e.g., from our models.py file) via a template or returning other responses like JSON. Views enable us with data via endpoints that perform CRUD operations (create, read/query, update, and delete nested documents).

In the views.py file in the cine_flix directory, add the following lines of code to create views that display data:

from django.http import HttpResponse
from django.shortcuts import render

from .models import Movie, Viewer

def index(request):
    return HttpResponse("Hello, world.")

def recent_movies(request):
    movies = Movie.objects.order_by("-released")[:5]
    return render(request, "recent_movies.html", {"movies": movies})

def viewers_list(request):
    viewers = Viewer.objects.order_by("name")[:5]
    return render(request, "viewers_list.html", {"viewers": viewers})

These views display a landing page message and information about your Movie and Viewer models.

Configuring URLs for Django views

Create a new file called urls.py file in the root of your cine_flix directory. To connect the views we created in the previous step to URLs, paste the following code into urls.py.

from django.urls import path

from . import views

urlpatterns = [
    path("recent_movies/", views.recent_movies, name="recent_movies"),
    path("viewers_list/", views.viewers_list, name="viewers_list"),
    path("", views.index, name="index"),
]

After that, find the other urls.py file in the project folder—which, in this case, is quickstart, so the path will be the quickstart/urls.py file. Then, add this line of code and save the file:

path("", include("cine_flix.urls")),

And the final urls.py will look like this:

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", include("cine_flix.urls")),
]

Django templates

Templates act as a separation between your Django application logic and presentation of data. They render data in the form of UI for users to interact with.

In your cine_flix app directory, create a subdirectory called templates, which will store all data which will be rendered via HTML files.

Then, create a file called recent_movies.html, paste the following code, and save:

<!-- templates/recent_movies.html -->
<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Recent Movies</title>
</head>
<body>
   <h1>Five Most Recent Movies</h1>
   <ul>
      {% for movie in movies %}
            <li>
               <strong>{{ movie.title }}</strong> (Released: {{ movie.released }})
            </li>
      {% empty %}
            <li>No movies found.</li>
      {% endfor %}
   </ul>
</body>
</html>

This template formats the movie data requested by the recent_movies view.

After, create another file in the cine_flix/templates directory called viewers_list.html, paste the following code, and save:

<!-- templates/viewers_list.html -->
<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Viewers List</title>
</head>
<body>
   <h1>Alphabetical Viewers List</h1>
   <table>
      <thead>
            <tr>
               <th>Name</th>
               <th>Email</th>
            </tr>
      </thead>
      <tbody>
            {% for viewer in viewers %}
               <tr>
                  <td>{{ viewer.name }}</td>
                  <td>{{ viewer.email }}</td>
               </tr>
            {% empty %}
               <tr>
                  <td colspan="2">No viewer found.</td>
               </tr>
            {% endfor %}
      </tbody>
   </table>
</body>
</html>

This template formats the user data requested by the viewers_list view.

Register the cine_flix app

At this point, we need to tell Django to register the cine_flix app, from models and migrations to templates and admin. To do that, open the settings.py file in the quickstart project and add this line of code to the top of the INSTALLED_APPS setting to resemble the following code:

INSTALLED_APPS = [
    ''cine_flix.apps.CineFlixConfig',
    'quickstart.apps.MongoAdminConfig',
    'quickstart.apps.MongoAuthConfig',
    'quickstart.apps.MongoContentTypesConfig',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
]

Run migrations

From your project root (in your terminal, you should run these commands in the project directory), create migrations for the Movie, Award, and Viewer models and apply the changes to the database:

python manage.py makemigrations cine_flix
python manage.py migrate

After, you should see the migrations applied with OK statuses.

At this point, we have a basic Django MongoDB Backend app that can access the sample_mflix MongoDB Atlas database.

Now, let’s create and interact with data via CRUD operations.

Perform CRUD operations: create, read/query, update, delete nested documents

To perform CRUD operations, we need to use the Python interactive shell on our model objects.

To start the Python shell, run the following command in the terminal:

python manage.py shell

Then import the required classes and modules with the following lines of code from your Python shell:

from cine_flix.models import Movie, Award, Viewer
from django.utils import timezone
from datetime import datetime

Create a Movie object

Example:

movie_awards = Award(wins=9, nominations=11, text="Won 7 Oscars")
movie = Movie.objects.create(
title="Everything Everywhere All at Once",
plot="Evelyn Wang, a Chinese‑American laundromat owner, finds herself swept into a multiversal adventure to prevent the collapse of existence, exploring alternate lives she could’ve led—all while dealing with family dysfunction and mid‑life malaise",
runtime=132,
released=timezone.make_aware(datetime(2024, 6, 22)),
awards=movie_awards,
genres=["Adventure", "Comedy"]
)

movie_awards = Award(wins=14, nominations=6, text="Won 8 Oscars")
movie2 = Movie.objects.create(
title="Mad Max: Fury Road",
plot="In a brutal post‑apocalyptic wasteland, Imperator Furiosa helps five women escape from a tyrant; she joins forces with Max Rockatansky in a high-octane chase across the desert in the armored War Rig",
runtime=120,
released=timezone.make_aware(datetime(2015, 5, 15)),
awards=movie_awards,
genres=["Action", "Adventure"]
)

Insert a Viewer object into the database

You can also use your Viewer model to insert documents into the sample_mflix.users collection. Run the following code to create a Viewer object that stores data about a movie viewer named "Alex Carter":

viewer = Viewer.objects.create(
    name="Alex Carter",
    email="Alex Carter@fakegmail.com"
)

viewer = Viewer.objects.create(
    name="Solomon Cruz",
    email="solomoncruz@fakegmail.com"
)

Query (Read)

Viewer.objects.filter(email="alexcarter@fakegmail.com").first()

Update

movie.runtime = 117
movie.save()

We can verify the update by running:
>>> query = Movie.objects.filter(runtime=117)
>>> print(query)

This returns ]> as the result since the movie Everything Everywhere All at Once had its runtime updated from 132 to 117.

Delete

One movie viewer named "Solomon Cruz" no longer uses the movie streaming site. To remove this viewer's corresponding document from the database, run the following code:

old_viewer = Viewer.objects.filter(name="Solomon Cruz").first()
old_viewer.delete()

Exiting the Python Shell

exit()

Running your server

python manage.py runserver

Render your new objects

To ensure that you inserted a Movie object into the database, visit http://127.0.0.1:8000/recent_movies/. You can see the two movies we added via the shell.

Then, ensure that you inserted a Viewer object into the database by visiting http://127.0.0.1:8000/viewers_list/. You can see the one viewer name because we deleted one in the previous step.

Querying embedded models and arrays

Filter with the dot notation on an embedded model. Dot notation example:

>>> selected_movie = Movie.objects.filter(awards__wins__gt=7)
>>> print(selected_movie)
>>> <QuerySet [<Movie: Everything Everywhere All at Once>, <Movie: Mad Max: Fury Road>]>

The output is Mad Max: Fury Road since it has an award win of 14. The double underscores act just like dot notation internally with Django.

Find the specific genre within the Genres array.

>>> Movie.objects.filter(genres__contains=["Action"])
>>> <MongoQuerySet [<Movie: Mad Max: Fury Road>]>

The output is MongoQuerySet [<Movie: Mad Max: Fury Road>] since it matches the Movie object containing the value of Action in the Genres array.

Find more than one genre within a movie object.

>>> Movie.objects.filter(genres__contains=["Comedy", "Adventure"])
>>> <MongoQuerySet [<Movie: Everything Everywhere All at Once>]> 
The output is <MongoQuerySet [<Movie: Everything Everywhere All at Once>]>

Update the movie object with a specific genre.

>>> updated_genre = Movie.objects.filter(title="Everything Everywhere All at   Once").update(genres=["Thriller"])

To verify, run:

Movie.objects.filter(title="Everything Everywhere All at Once").values('title', 'genres').first()

The output is {'title': 'Everything Everywhere All at Once', 'genres': ['Thriller']}.

Challenges

As the data grows, there may be challenges in filtering, sorting, or aggregating data within large arrays. As such, try to restructure large arrays by separating or capping them, and specific subfields should be indexed to enable faster lookups to reduce slower queries.

Overview of MongoDB’s aggregation pipeline

MongoDB’s aggregation pipeline consists of one or more stages that process documents. Each stage performs an operation on the input documents. For example, a stage can filter documents, group documents, and calculate values. The documents that are output from a stage are passed to the next stage.

You may be familiar with the aggregation pipeline, however, that has been included on the Django MongoDB Backend now. This allows you to use our MongoDB specific operations outside of the constraints of typical Django lookup queries.

Examples of such cases are:

Performing lookups using the $near geospatial Operator in MongoDB, but it’s not available in Django.
Hybrid Search which couples the precision of text search with the semantic understanding of vector search to deliver the most relevant answers to end users.
Hyper-optimized queries which use MongoDB native operators to improve the efficiency of read operations by reducing the amount of data that query operations need to process.

Raw MongoDB Django aggregation example

Let’s run an aggregation pipeline to determine the average runtime of the movies in our collection.

from cine_flix.models import Movie

pipeline = [
  {"$match": {"genres": "Adventure"}},
  {"$group": {"_id": None, "avg_runtime": {"$avg": "$runtime"}}}
]

agg_query = Movie.objects.raw_aggregate(pipeline)

for result in agg_query:
    print("Average runtime:", result.avg_runtime)

Using the Django MongoDB Backend views, you can also implement the pipeline inside your views.py by adding these lines of code to your views.py:

def avg_runtime_view(request):
    pipeline = [
        {"$match": {"genres": "Adventure"}},
        {"$group": {"_id": None, "avg_runtime": {"$avg": "$runtime"}}}
    ]

    agg_query = Movie.objects.raw_aggregate(pipeline)
    avg = agg_query[0].avg_runtime if agg_query else None

   return render(request, "average_runtime.html", {"avg_runtime": avg})

After, create an average_runtime.html template in the Templates folder and add these lines of code:

<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Recent Movies</title>
</head>

<body>

    <h1>Average Runtime for Adventure Movies</h1>

    {% if avg_runtime is not None %}
      <p>The average runtime is <strong>{{ avg_runtime }}</strong> minutes.</p>
    {% else %}
      <p>No data found.</p>
    {% endif %}
</body>
</html>

Lastly, I added the URL to the app’s urls.py file.

   path("avg-runtime/", views.avg_runtime_view, name="avg_runtime"),

Then, run the server using Python manage.py runserver. We see the output displayed in the image below of the average runtime result from the pipeline.

Best practices when working with data

Endeavor to keep embedded arrays in a manageable size to avoid bloated documents.
Model your data properly to suit your query patterns so that aggregation or pipeline stages work efficiently.
Use caching and pagination for aggregated data to reduce server load and increase performance with large datasets.

Conclusion

In this tutorial, we looked at accessing data with the Django MongoDB Backend, setting up and installation of the Django MongoDB Backend, creating an application within a Django project, CRUD methods on the Movie object, challenges, raw aggregation and best practices when working with data.

Using the Django MongoDB Backend to access data is an efficient way to work with data—related data is stored together (even with varying document structures)—so try it out and let me know.

If you have any questions, feel free to reach out to our community: MongoDB Community Forum.