DOCSP-46321: CRUD operations

snooty.toml

@@ -25,6 +25,7 @@ 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"
 language = "Python"
 mdb-server = "MongoDB Server"
 mongo-community = "MongoDB Community Edition"

source/interact-data/crud.txt

@@ -0,0 +1,280 @@
+.. _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 Django ``QuerySet`` API to run
+CRUD operations. To run these operations, call ``QuerySet`` methods
+your model's ``Manager``. The ``Manager`` class handles database
+operations and allows you to interact with your MongoDB data by referencing
+Django models. By default, Django adds a ``Manager`` named ``objects``
+to every model class. 
+
+This guide shows how to use the following ``QuerySet`` methods:
+
+- :ref:`create() <django-crud-insert>`
+- :ref:`filter() and get() <django-crud-read>`
+- :ref:`update() <django-crud-modify>`
+- :ref:`delete() <django-crud-delete>`
+
+.. tip::
+
+    To learn more about Django's ``QuerySet`` API, see
+    `QuerySet API reference <https://docs.djangoproject.com/en/5.1/ref/models/querysets/>`__
+    in the Django documentation.
+
+You can also use the Django 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/>`__
+in the Django documentation.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``Movie`` model, which represents
+the ``sample_mflix.movies`` collection from the :atlas:`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 EmbeddedModelField, 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)
+       awards = EmbeddedModelField(Award)
+       genres = ArrayField(models.CharField(max_length=100), null=True, blank=True)
+
+       class Meta:
+           db_table = "movies"
+           managed = False
+
+       def __str__(self):
+           return self.title
+
+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 django.utils import timezone
+   from datetime import datetime
+
+To learn how to create a Django application that uses the ``Movie``
+model and the Python interactive shell to interact with MongoDB documents,
+visit the :ref:`django-get-started` tutorial.
+
+.. _django-crud-insert:
+
+Insert Documents
+----------------
+
+To insert a document into a collection, call the ``create()`` method
+on an instance of your model's ``Manager`` class. Pass the new document's
+fields and 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
+
+   from sample_mflix.models import Movie
+
+   movie = Movie.objects.create(title="Poor Things", runtime=141)
+
+.. note::
+
+   The ``create()`` method allows you to create a new ``Movie`` object
+   and save the object as a collection document in one method call.
+   To view an example that creates an object then saves it to the
+   database by calling ``save()``, see `create() <https://docs.djangoproject.com/en/5.1/ref/models/querysets/#create>`__
+   in the Django documentation.
+
+.. _django-crud-read:
+
+Read Documents
+--------------
+
+To retrieve documents from your collection, call the ``filter()`` method on an
+instance of your model's ``Manager`` class. 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
+
+       from sample_mflix.models import Movie
+       from django.utils import timezone
+       from datetime import datetime
+
+       Movie.objects.filter(released=timezone.make_aware(datetime(2000, 1, 1)))
+
+    .. output::
+       :language: none
+       :visible: false
+
+       <MongoQuerySet [<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>]>
+
+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
+
+       from sample_mflix.models import Movie
+
+       Movie.objects.get(title="Boyhood")
+
+    .. output::
+       :language: none
+       :visible: false
+
+       <Movie: Boyhood>
+
+.. note::
+
+   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()``.
+
+.. _django-crud-modify:
+
+Modify Documents
+----------------
+
+To modify documents in a collection, call the ``filter()`` and ``update()``
+methods on an instance of your model's ``Manager`` class. 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
+
+       from sample_mflix.models import Movie
+
+       Movie.objects.filter(title="High Fidelity").update(plot=
+       "Rob, a record store owner and compulsive list maker, recounts his top five breakups, including the one in progress.")
+
+    .. output::
+       :language: none
+       :visible: false
+
+       // Outputs the number of modified documents
+       1
+
+.. _django-crud-delete:
+
+Delete Documents
+----------------
+
+To delete documents in a collection, call the ``filter()`` and ``delete()``
+methods on an instance of 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
+
+       from sample_mflix.models import Movie
+
+       Movie.objects.filter(runtime=5).delete()
+
+    .. output::
+       :language: none
+       :visible: false
+
+       // Outputs the number of deleted documents and objects
+       (16, {'sample_mflix.Movie': 16})
+
+
+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`