diff --git a/snooty.toml b/snooty.toml index de16c44e..4eef4864 100644 --- a/snooty.toml +++ b/snooty.toml @@ -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" diff --git a/source/interact-data/crud.txt b/source/interact-data/crud.txt new file mode 100644 index 00000000..b424c3f2 --- /dev/null +++ b/source/interact-data/crud.txt @@ -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() `: Inserts documents into the collection +- :ref:`filter() and get() `: Retrieves one or multiple collection documents +- :ref:`update() `: Modifies collection documents +- :ref:`delete() `: Deletes collection documents + +.. tip:: + + To learn more about {+framework+}'s ``QuerySet`` API, see the + `QuerySet API reference `__ + 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 `__ +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 `. +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 + + def __str__(self): + return self.title + +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 .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. + +.. _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. + +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 + + , , + , , , + ]> + +.. 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 + + + +.. 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` \ No newline at end of file