DOCSP-46322: Raw queries (#1)

* DOCSP-46322: Raw queries

* landing

* code edits

* jib feedback

* managers

* fix

* mongoclient operations

* more mongoclient

* fix code

* use include

* query api section

* fix

* sample data include edit

* fix str

Author: norareidy

snooty.toml

@@ -6,11 +6,14 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
                 "http://docs.djangoproject.com/en/5.0/_objects/"
               ]
 
-# toc_landing_pages = ["/paths/to/pages/that/have/nested/content"]
+toc_landing_pages = [
+    "/interact-data"
+]
 
 [constants]
 django-odm = "Django MongoDB Backend"
 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+}"
+pymongo-docs = "https://www.mongodb.com/docs/languages/python/pymongo-driver/current"

source/includes/interact-data/raw-queries.py

@@ -0,0 +1,104 @@
+# start-models
+from django.db import models
+from django_mongodb_backend.fields import ArrayField
+from django_mongodb_backend.managers import MongoManager
+
+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)
+    objects = MongoManager()
+
+    class Meta:
+        db_table = "movies"
+        managed = False
+
+    def __str__(self):
+        return self.title
+
+class Theater(models.Model):
+    theaterId = models.IntegerField(default=0)
+    objects = MongoManager()
+
+    class Meta:
+        db_table = "theaters"
+        managed = False
+    
+    def __str__(self):
+        return self.theaterId
+# end-models
+
+# start-filter-project
+movies = Movie.objects.raw_aggregate([
+    {"$match": {"title": "The Parent Trap"}},
+    {"$project": {
+        "title": 1,
+        "released": 1
+    }
+}])
+
+for m in movies:
+    print(f"Plot of {m.title}, released on {m.released}: {m.plot}\n")
+# end-filter-project
+
+# start-atlas-search
+movies = Movie.objects.raw_aggregate([
+    {
+        "$search": {
+            "index": "<search-index-name>",
+            "phrase": {
+                "path": "plot",
+                "query": "whirlwind romance",
+                "slop": 3
+            },
+            "highlight": {
+                "path": "plot"
+            }
+        }
+    },
+    {
+        "$project": {
+            "title": 1,
+            "highlight": {"$meta": "searchHighlights"}
+        }
+    }
+])
+
+for m in movies:
+    print(f"Title: {m.title}, text match details: {m.highlight}\n")
+# end-atlas-search
+
+# start-geo
+chicago_bounds = {
+    "type": "Polygon",
+    "coordinates": [[
+        [-87.851, 41.976],
+        [-87.851, 41.653],
+        [-87.651, 41.653],
+        [-87.651, 41.976],
+        [-87.851, 41.976] 
+    ]]
+}
+
+theaters = Theater.objects.raw_aggregate([
+    {
+        "$match": {
+            "location.geo": {
+                "$geoWithin": {
+                    "$geometry": chicago_bounds
+                }
+            }
+        }
+    },
+    {
+        "$project": {
+            "theaterId": 1
+        }
+    }
+])
+
+for t in theaters:
+    print(f"Theater ID: {t.theaterId}")
+# end-geo

source/includes/use-sample-data.rst

@@ -0,0 +1,25 @@
+The |model-classes| an inner ``Meta`` class, which specifies
+model metadata, and a ``__str__()`` method, which defines the 
+model's string representation. 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:
+
+|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,
+visit the :ref:`django-get-started` tutorial.

source/index.txt

@@ -11,14 +11,14 @@ Django MongoDB Backend
 
 .. toctree::
 
+    Interact with Data </interact-data>
     Issues & Help </issues-and-help>
     Compatibility </compatibility>
 
 
 .. TODO:
    Get Started </get-started>
    Connection Configuration </connect>
-   Interact with Data </interact-data>
    Model Your Data </model-data>
    Django Feature Limitations </feature-limitations>
    API Documentation <{+api+}>
@@ -29,6 +29,12 @@ Introduction
 Welcome to the documentation site for the official {+django-odm+},
 a Django database backend that uses PyMongo to connect to MongoDB. 
 
+Interact with Data
+------------------
+
+Learn how to use {+django-odm+} to perform operations on MongoDB data
+in the :ref:`django-interact-data` section.
+
 .. TODO:
 
 .. Get Started
@@ -43,12 +49,6 @@ 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
-.. ------------------
-
-.. Learn how to use {+django-odm+} to perform operations on MongoDB data
-   in the :ref:`django-interact-data` section.
-
 .. Model Your Data
 .. ---------------
 

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
+
+   Perform Raw Queries </interact-data/raw-queries>