-
Notifications
You must be signed in to change notification settings - Fork 20
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
Changes from all commits
4230372
924788d
6123720
84bc486
b81892b
158ff3d
da3ac8c
15fee18
ce6bcc4
1283d40
073c29c
3861026
9c34109
13fbf87
b3bfeb8
5ba56dc
9636386
6b99b50
64f1e0b
8999776
df740e8
73fe484
60cc381
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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/>`__ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Looks like there is some precedent for that. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Looking into this! There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
rustagir marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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: There was a problem hiding this comment. Choose a reason for hiding this commentThe 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? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Same here. Another helpful tooltip: There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. same comment as above There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. To insert a document into a collection, call the |
||
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>]> | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Here's our intersphinx config: https://github.com/mongodb-labs/django-mongodb-backend/blob/main/docs/source/conf.py#L39-L45 There was a problem hiding this comment. Choose a reason for hiding this commentThe 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` |
Uh oh!
There was an error while loading. Please reload this page.