Skip to content

DOCSP-46321: CRUD operations #144

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions snooty.toml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
driver-short = "PyMongo"
driver-long = "PyMongo, the MongoDB synchronous Python driver,"
driver-async = "PyMongo Async"
django-odm = "Django MongoDB Backend"
django-docs = "https://docs.djangoproject.com/en/5.1/"
framework = "Django"
language = "Python"
mdb-server = "MongoDB Server"
mongo-community = "MongoDB Community Edition"
Expand Down
310 changes: 310 additions & 0 deletions source/interact-data/crud.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,310 @@
.. _django-crud:

=======================
Perform CRUD Operations
=======================

.. contents:: On this page
:local:
:backlinks: none
:depth: 2
:class: singlecol

.. facet::
:name: genre
:values: reference

.. meta::
:keywords: insert, modify, read, write, code example

Overview
---------

In this guide, you can learn how to use {+django-odm+} to run
create, read, update, and delete (CRUD) operations on your MongoDB
collection.

You can use methods provided by the {+framework+} ``QuerySet`` API to run
CRUD operations. To run these operations, you can call ``QuerySet`` methods
on your model's manager. The ``Manager`` class handles database
operations and allows you to interact with your MongoDB data by referencing
Django models. By default, {+framework+} adds a ``Manager`` named ``objects``
to every model class.

This guide shows how to use the following ``QuerySet`` methods:

- :ref:`create() <django-crud-insert>`: Inserts documents into the collection
- :ref:`filter() and get() <django-crud-read>`: Retrieves one or multiple collection documents
- :ref:`update() <django-crud-modify>`: Modifies collection documents
- :ref:`delete() <django-crud-delete>`: Deletes collection documents

.. tip::

To learn more about {+framework+}'s ``QuerySet`` API, see the
`QuerySet API reference <https://docs.djangoproject.com/en/5.1/ref/models/querysets/>`__

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about using intersphinx for linking to Django docs? The objects file: http://docs.djangoproject.com/en/5.0/_objects/ I think this would be especially helpful for making sure links stay updated when switching from one Django version to the next.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like there is some precedent for that.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking into this!

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@norareidy were we able to get resolve the issue with sphinx?

in the {+framework+} documentation.

You can also use the {+framework+} admin site to edit your models
and their corresponding collections on a web interface. For
more information, see the `Django Admin Site <https://docs.djangoproject.com/en/5.1/ref/contrib/admin/>`__
entry in the {+framework+} documentation.

Sample Data
~~~~~~~~~~~

The examples in this guide use the ``Movie`` model, which represents
the ``sample_mflix.movies`` collection from the :atlas:`Atlas sample datasets </sample-data>`.
The ``Movie`` model class has the following definition:

.. code-block:: python

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

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

class Meta:
db_table = "movies"
managed = False
Comment on lines +71 to +73
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add a helpful tooltip or note to explain the purpose of these two meta configurations. A blurb along the lines of:
"""
In Django, defining a Meta class within a Model allows you to configure the Meta options for the model. In this example, we use db_table = "movies" to change the collection referenced in the database to look for movies, and we set managed = False to stop database creation, modification, or deletion during migration commands. To read more, check out Django's Meta Options documentation.
"""

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since I use this sample data on almost every page, what do you think of linking to the Models guide (which explains Meta and str()) instead of repeating the explanation every time?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good to me


def __str__(self):
return self.title
Comment on lines +75 to +76
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here. Another helpful tooltip:
"""
In Django, you can override the str method of a model to define how its instances are represented as strings.
"""

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same comment as above

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep. Works for me


The ``Movie`` model class includes an inner ``Meta`` class and a ``__str__()`` method.
To learn about these model features, see :ref:`django-models-define` in the
Create Models guide.

Run Code Examples
`````````````````

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

.. code-block:: bash

python manage.py shell

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

.. code-block:: python

from <your application name>.models import Movie
from {+framework+}.utils import timezone
from datetime import datetime

To learn how to create a {+framework+} application that uses the ``Movie``
model and the Python interactive shell to interact with MongoDB documents,
visit the :ref:`django-get-started` tutorial.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: link broken until #132 is merged


.. _django-crud-insert:

Insert Documents
----------------

To insert a document into a collection, call the ``create()`` method on your
model's manager. Pass the new document's field names and field values
as arguments to the ``create()`` method.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To insert a document into a collection, call the create() method on your model's Manager class. Pass the new document's field names and field values as arguments to the create() method.

Example
~~~~~~~

The following example calls the ``create()`` method to insert a document
into the ``sample_mflix.movies`` collection. The new document has
a ``title`` value of ``"Poor Things"`` and a ``runtime`` value
of ``141``:

.. code-block:: python

movie = Movie.objects.create(title="Poor Things", runtime=141)

The ``create()`` method allows you to create a new ``Movie`` object
and save the object to MongoDB in one method call. Alternatively, you
can create a ``Movie`` object and call ``save()``, as shown in the following
code:

.. code-block:: python

movie = Movie(title="Poor Things", runtime=141)
movie.save()

.. tip::

To learn more about the ``create()`` method, see `create()
<{+django-docs+}/ref/models/querysets/#create>`__ in the {+framework+}
documentation.

.. _django-crud-read:

Read Documents
--------------

To retrieve documents from your collection, call the ``filter()`` method
on your model's manager. Pass a query filter, or criteria that specifies
which documents to retrieve, as an argument to the ``filter()`` method.

Alternatively, you can call the ``get()`` method to retrieve a single document
that matches your query.

Return Multiple Documents Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following example calls the ``filter()`` method to retrieve
documents from the ``sample_mflix.movies`` collection. The query
returns ``Movie`` objects that represent movies released on January 1, 2000:

.. io-code-block::
:copyable: true

.. input::
:language: python

Movie.objects.filter(released=timezone.make_aware(datetime(2000, 1, 1)))

.. output::
:language: none
:visible: false

<QuerySet [<Movie: The Bumblebee Flies Anyway>, <Movie: Angels of the Universe>,
<Movie: First Person Plural>, <Movie: Just, Melvin: Just Evil>, <Movie: Sound and Fury>,
<Movie: Peppermint Candy>]>

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm thinking we should add a tooltip to link to the lookup operations documentation in Django.

cc: @aclark4life @timgraham

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean add a link to the Django documentation for each method at the end of the sections? I can do that!

.. tip::

To learn more about the ``filter()`` method, see `filter()
<{+django-docs+}/ref/models/querysets/#filter>`__ in the {+framework+}
documentation.

Return One Document Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To retrieve only one document that matches your query criteria, call the
``get()`` method and pass a query filter as an argument. The following example
retrieves a document in which the ``title`` value is ``"Boyhood"``:

.. io-code-block::
:copyable: true

.. input::
:language: python

Movie.objects.get(title="Boyhood")

.. output::
:language: none
:visible: false

<Movie: Boyhood>

.. important::

If your query matches no documents or multiple documents, the ``get()``
method generates an error. To retrieve one document from a query
that might match multiple, chain the ``first()`` method to ``filter()``,
as shown in the following code:

.. code-block:: python

Movie.objects.filter(title="Boyhood").first()

.. tip::

To learn more about the ``get()`` method, see `get()
<{+django-docs+}/ref/models/querysets/#get>`__ in the {+framework+}
documentation.

.. _django-crud-modify:

Modify Documents
----------------

To modify documents in a collection, call the ``filter()`` and ``update()``
methods on your model's manager. Pass a query filter, or criteria that
specifies which documents to update, as an argument to the ``filter()``
method. Then, pass the fields and values you want to update as
arguments to the ``update()`` method.

Example
~~~~~~~

The following example calls the ``update()`` method to modify
documents in the ``sample_mflix.movies`` collection. The code matches
a document that has a ``title`` value of ``"High Fidelity"`` and adds a
``plot`` field:

.. io-code-block::
:copyable: true

.. input::
:language: python

Movie.objects.filter(
title="High Fidelity").update(
plot="Rob, a record store owner, recounts his top five breakups,including the one in progress.")
.. output::
:language: none
:visible: false

// Outputs the number of modified documents
1

.. tip::

To learn more about the ``update()`` method, see `update()
<{+django-docs+}/ref/models/querysets/#update>`__ in the {+framework+}
documentation.

.. _django-crud-delete:

Delete Documents
----------------

To delete documents in a collection, call the ``filter()`` and ``delete()``
methods on your model's ``Manager`` class. Pass a query filter,
or criteria that specifies which documents to delete, as an argument to the
``filter()`` method.

Example
~~~~~~~

The following example calls the ``delete()`` method to delete documents
in the ``sample_mflix.movies`` collection. The code matches
and deletes documents that have a ``runtime`` value of ``5``:

.. io-code-block::
:copyable: true

.. input::
:language: python

Movie.objects.filter(runtime=5).delete()

.. output::
:language: none
:visible: false

// Outputs the number of deleted documents and objects
(16, {'sample_mflix.Movie': 16})

.. tip::

To learn more about the ``delete()`` method, see `delete()
<{+django-docs+}/ref/models/querysets/#delete>`__ in the {+framework+}
documentation.

Additional Information
----------------------

.. TODO: To learn more about performing read operations, see the Specify a Query guide.

To view more create, read, update, and delete examples, see the following
steps of the :ref:`django-get-started` tutorial:

- :ref:`django-get-started-write`
- :ref:`django-get-started-query`