From 509823b4dc001d21bb86b63395d9015d33849926 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 22 Jan 2025 17:57:03 -0500 Subject: [PATCH 1/6] DOCSP-46321: CRUD operations --- snooty.toml | 1 + source/includes/interact-data/crud.py | 45 ++++ source/index.txt | 14 +- source/interact-data.txt | 17 ++ source/interact-data/crud.txt | 295 ++++++++++++++++++++++++++ 5 files changed, 365 insertions(+), 7 deletions(-) create mode 100644 source/includes/interact-data/crud.py create mode 100644 source/interact-data.txt create mode 100644 source/interact-data/crud.txt diff --git a/snooty.toml b/snooty.toml index 1fe2cb2..f29ed88 100644 --- a/snooty.toml +++ b/snooty.toml @@ -14,3 +14,4 @@ api = "https://django-mongodb.readthedocs.io/en/latest/" mdb-server = "MongoDB Server" django-version = "5.0" django-docs = "https://docs.djangoproject.com/en/{+django-version+}" +framework = "Django" diff --git a/source/includes/interact-data/crud.py b/source/includes/interact-data/crud.py new file mode 100644 index 0000000..a9709de --- /dev/null +++ b/source/includes/interact-data/crud.py @@ -0,0 +1,45 @@ +# start-models +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 +# end-models + +# start-insert +Movie.objects.create(title="Poor Things", runtime=141) +# end-insert + +# start-save +movie = Movie(title="Poor Things", runtime=141) +movie.save() +# end-save + +# start-find-many +Movie.objects.filter(released=timezone.make_aware(datetime(2000, 1, 1))) +# end-find-many + +# start-find-one +Movie.objects.get(title="Boyhood") +# end-find-one + +# start-update +Movie.objects.filter( + title="High Fidelity").update( + plot="Rob, a record store owner, recounts his top five breakups,including the one in progress.") +# end-update + +# start-delete +Movie.objects.filter(runtime=5).delete() +# end-delete \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index ea41052..ca970d3 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,14 +11,14 @@ Django MongoDB Backend .. toctree:: - Issues & Help - Compatibility + Interact with Data + Issues & Help + Compatibility .. TODO: Get Started Connection Configuration - Interact with Data Model Your Data Django Feature Limitations API Documentation <{+api+}> @@ -43,11 +43,11 @@ a Django database backend that uses PyMongo to connect to MongoDB. .. Learn how to configure a connection to a MongoDB deployment in the :ref:`django-connection-configuration` section. -.. Interact with Data -.. ------------------ +Interact with Data +------------------ -.. Learn how to use {+django-odm+} to perform operations on MongoDB data - in the :ref:`django-interact-data` section. +Learn how to use {+django-odm+} to perform operations on MongoDB data +in the :ref:`django-interact-data` section. .. Model Your Data .. --------------- diff --git a/source/interact-data.txt b/source/interact-data.txt new file mode 100644 index 0000000..22a96d0 --- /dev/null +++ b/source/interact-data.txt @@ -0,0 +1,17 @@ +.. _django-interact-data: + +================== +Interact with Data +================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: odm, crud, query + +.. toctree:: + :caption: Interact with Data + + CRUD Operations \ No newline at end of file diff --git a/source/interact-data/crud.txt b/source/interact-data/crud.txt new file mode 100644 index 0000000..ec62f67 --- /dev/null +++ b/source/interact-data/crud.txt @@ -0,0 +1,295 @@ +.. _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: + +.. literalinclude:: /includes/interact-data/crud.py + :start-after: start-models + :end-before: end-models + :language: python + :copyable: + +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``: + +.. literalinclude:: /includes/interact-data/crud.py + :start-after: start-insert + :end-before: end-insert + :language: python + :copyable: + +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: + +.. literalinclude:: /includes/interact-data/crud.py + :start-after: start-save + :end-before: end-save + :language: python + :copyable: + +.. 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: + + .. input:: /includes/interact-data/crud.py + :start-after: start-find-many + :end-before: end-find-many + :language: python + + .. output:: + :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: + + .. input:: /includes/interact-data/crud.py + :start-after: start-find-one + :end-before: end-find-one + :language: python + + .. output:: + :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: + + .. input:: /includes/interact-data/crud.py + :start-after: start-update + :end-before: end-update + :language: python + + .. output:: + :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: + + .. input:: /includes/interact-data/crud.py + :start-after: start-delete + :end-before: end-delete + :language: python + + .. output:: + :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 From ed1799fda172fdce24b848556a2433f2337b5c31 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 22 Jan 2025 18:17:36 -0500 Subject: [PATCH 2/6] use include --- source/includes/use-sample-data.rst | 27 +++++++++++++++++++++++++++ source/interact-data/crud.txt | 28 +++++----------------------- 2 files changed, 32 insertions(+), 23 deletions(-) create mode 100644 source/includes/use-sample-data.rst diff --git a/source/includes/use-sample-data.rst b/source/includes/use-sample-data.rst new file mode 100644 index 0000000..a091c34 --- /dev/null +++ b/source/includes/use-sample-data.rst @@ -0,0 +1,27 @@ +The |model-classes| 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 + + |model-imports| + 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. \ No newline at end of file diff --git a/source/interact-data/crud.txt b/source/interact-data/crud.txt index ec62f67..0c17fd9 100644 --- a/source/interact-data/crud.txt +++ b/source/interact-data/crud.txt @@ -62,33 +62,15 @@ The ``Movie`` model class has the following definition: :language: python :copyable: -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. +.. include:: /includes/use-sample-data.rst -Run Code Examples -````````````````` + .. replacement:: model-classes -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: + ``Movie`` model includes -.. code-block:: bash + .. replacement:: model-imports - 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. + from .models import Movie .. _django-crud-insert: From 4eedc942b390346febb225b018152924219146e3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 22 Jan 2025 18:22:12 -0500 Subject: [PATCH 3/6] fix include --- source/includes/use-sample-data.rst | 6 +----- source/interact-data/crud.txt | 6 +++++- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/includes/use-sample-data.rst b/source/includes/use-sample-data.rst index a091c34..37407be 100644 --- a/source/includes/use-sample-data.rst +++ b/source/includes/use-sample-data.rst @@ -16,11 +16,7 @@ root directory: After entering the Python shell, ensure that you import the following models and modules: -.. code-block:: python - - |model-imports| - from {+framework+}.utils import timezone - from datetime import datetime +|model-imports| To learn how to create a {+framework+} application that uses the ``Movie`` model and the Python interactive shell to interact with MongoDB documents, diff --git a/source/interact-data/crud.txt b/source/interact-data/crud.txt index 0c17fd9..9596d62 100644 --- a/source/interact-data/crud.txt +++ b/source/interact-data/crud.txt @@ -70,7 +70,11 @@ The ``Movie`` model class has the following definition: .. replacement:: model-imports - from .models import Movie + .. code-block:: python + + from .models import Movie + from {+framework+}.utils import timezone + from datetime import datetime .. _django-crud-insert: From 19633524bbf707a8957969bb1683c5d7529098a4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 22 Jan 2025 19:15:25 -0500 Subject: [PATCH 4/6] query api section --- source/interact-data/crud.txt | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/source/interact-data/crud.txt b/source/interact-data/crud.txt index 9596d62..7856c9b 100644 --- a/source/interact-data/crud.txt +++ b/source/interact-data/crud.txt @@ -24,6 +24,14 @@ 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 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. + +Query API +~~~~~~~~~ + 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 @@ -31,23 +39,18 @@ 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. +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 Sample Data ~~~~~~~~~~~ From 9f3e667f1027e6420b1865b852a14f27276b3144 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 23 Jan 2025 09:59:17 -0500 Subject: [PATCH 5/6] capitalization --- source/interact-data/crud.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/interact-data/crud.txt b/source/interact-data/crud.txt index 7856c9b..d97d5de 100644 --- a/source/interact-data/crud.txt +++ b/source/interact-data/crud.txt @@ -76,7 +76,7 @@ The ``Movie`` model class has the following definition: .. code-block:: python from .models import Movie - from {+framework+}.utils import timezone + from django.utils import timezone from datetime import datetime .. _django-crud-insert: From 66ad4f955a74e3a4920b8b4a1b0e1f89940c69a0 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 23 Jan 2025 14:47:35 -0500 Subject: [PATCH 6/6] sample data include edit --- source/includes/use-sample-data.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/includes/use-sample-data.rst b/source/includes/use-sample-data.rst index 37407be..15433ac 100644 --- a/source/includes/use-sample-data.rst +++ b/source/includes/use-sample-data.rst @@ -1,5 +1,7 @@ -The |model-classes| an inner ``Meta`` class and a ``__str__()`` method. -To learn about these model features, see :ref:`django-models-define` in the +The |model-classes| an inner ``Meta`` class, which specifies +model metadata, and a ``__str__()`` method, which sets the +model's string representation to its ``title`` field. To learn about +these model features, see :ref:`django-models-define` in the Create Models guide. Run Code Examples