DOCSP-46425: Specify a Query #2

norareidy · 2025-01-14T22:53:28Z

JIRA - https://jira.mongodb.org/browse/DOCSP-46425
Staging - https://deploy-preview-2--docs-django.netlify.app/interact-data/specify-a-query/

netlify · 2025-01-14T22:53:45Z

✅ Deploy Preview for docs-django ready!

Name	Link
🔨 Latest commit	`75a555a`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-django/deploys/6797b5ea5465260008d21d88
😎 Deploy Preview	https://deploy-preview-2--docs-django.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

aclark4life · 2025-01-15T23:17:30Z

source/interact-data/specify-a-query.txt

+In this guide, you can learn how to use {+django-odm+} to specify
+a database query.
+
+The Django ``QuerySet`` API provides functions that allow you to retrieve


s/functions/methods/

aclark4life · 2025-01-15T23:17:44Z

source/interact-data/specify-a-query.txt

+a database query.
+
+The Django ``QuerySet`` API provides functions that allow you to retrieve
+model objects. To run a MongoDB database query, call ``QuerySet`` functions


s/functions/methods/

aclark4life · 2025-01-15T23:19:45Z

source/interact-data/specify-a-query.txt

+to every model class. 
+
+When you assign a ``QuerySet`` to a variable, {+django-odm+} does not
+perform the operation until you evaluate the variable, usually by printing. After


s/,usually by printing//.

I would leave this out, more here about how you can evaluate: https://docs.djangoproject.com/en/5.1/ref/models/querysets/#when-querysets-are-evaluated

aclark4life · 2025-01-15T23:20:42Z

source/interact-data/specify-a-query.txt

+Run a Query
+-----------
+
+To query your MongoDB data, call a ``QuerySet`` function on your 


s/function/method/

aclark4life · 2025-01-15T23:20:55Z

source/interact-data/specify-a-query.txt

+model's ``Manager`` class and specify your matching criteria in a
+query filter.
+
+This section describes how to use the following functions from


s/functions/methods/

aclark4life · 2025-01-15T23:21:11Z

source/interact-data/specify-a-query.txt

+~~~~~~~~~~~~~~~~~~~~~~
+
+To retrieve all documents from a collection, call the ``all()``
+function on your model's ``Manager`` class.


s/function/method/

aclark4life · 2025-01-15T23:21:30Z

source/interact-data/specify-a-query.txt

+To retrieve all documents from a collection, call the ``all()``
+function on your model's ``Manager`` class.
+
+The following example calls the ``all()`` function to retrieve


s/function/method/

aclark4life · 2025-01-15T23:21:48Z

source/interact-data/specify-a-query.txt

+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To query a collection for documents that match a set of criteria,
+call the ``filter()`` function on your model's ``Manager`` class.


s/function/method/

aclark4life · 2025-01-15T23:21:55Z

source/interact-data/specify-a-query.txt

+
+To query a collection for documents that match a set of criteria,
+call the ``filter()`` function on your model's ``Manager`` class.
+Pass a query filter to the ``filter()`` function that specifies your


s/function/method/

aclark4life · 2025-01-15T23:22:01Z

source/interact-data/specify-a-query.txt

+Pass a query filter to the ``filter()`` function that specifies your
+query criteria.
+
+The following example calls the ``filter()`` function


s/function/method/

aclark4life · 2025-01-15T23:22:16Z

source/interact-data/specify-a-query.txt

+~~~~~~~~~~~~~~~~~~~~~
+
+To retrieve one document from a collection, call the ``get()``
+function on your model's ``Manager`` class. Pass 


s/function/method/

aclark4life · 2025-01-15T23:22:25Z

source/interact-data/specify-a-query.txt

+
+To retrieve one document from a collection, call the ``get()``
+function on your model's ``Manager`` class. Pass 
+a query filter to the ``get()`` function that specifies your


s/function/method/

aclark4life · 2025-01-15T23:22:32Z

source/interact-data/specify-a-query.txt

+.. important::
+
+   If your query matches no documents or multiple documents, the ``get()``
+   function generates an error. To retrieve one document from a query


s/function/method/

aclark4life · 2025-01-15T23:22:40Z

source/interact-data/specify-a-query.txt

+   If your query matches no documents or multiple documents, the ``get()``
+   function generates an error. To retrieve one document from a query
+   that might match multiple, use the :ref:`first() <django-query-first>`
+   function.


s/function/method/

aclark4life · 2025-01-15T23:22:47Z

source/interact-data/specify-a-query.txt

+   function.
+
+
+The following example calls the ``get()`` function


s/function/method/

aclark4life · 2025-01-15T23:22:58Z

source/interact-data/specify-a-query.txt

+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To query a collection for documents that do not meet your
+search criteria, call the ``exclude()`` function on your model's


s/function/method/

aclark4life · 2025-01-15T23:23:05Z

source/interact-data/specify-a-query.txt

+To query a collection for documents that do not meet your
+search criteria, call the ``exclude()`` function on your model's
+``Manager`` class. Pass the exclusion criteria as an 
+argument to the ``exclude()`` function.


s/function/method/

aclark4life

LGTM pending s/\b(functions?)\b/methods?/g

Also FWIW, methods are functions that belong to a class.

Jibola

I loved reading this! provided some additional guidance.

Jibola · 2025-01-16T06:36:20Z

source/interact-data/specify-a-query.txt

+You can combine field lookups to further specify your
+query criteria. To combine lookups, chain each lookup
+type together and separate them with a double underscore
+(``__``).


This section is misleading. The example below is actually demonstrating both navigating relationships (Movie --> Award --> Text) and then doing a lookup (istartswith).

Additionally, there's a bit of confusion because Award is still a nested document, so while it does have a relationship, it's not the same way "relationships" are communicated in Django.

I.e.

Using a nested document shouldn't be treated as a relationship, but as a way to query embedded models

Using a ForeignKey that references a model, however, is different. That is a relationship spanning multiple collections (tables).

Alright I made some changes - described Q objects in this section instead as a way to combine query filters, and moved the embedded model field section to the "Advanced Field Queries" section

source/interact-data/specify-a-query.txt

Jibola · 2025-01-16T06:49:44Z

source/interact-data/specify-a-query.txt

+transform of a ``JSONField``. For example, the following code uses
+the ``annotate()`` and ``KT()`` functions to create a new ``score`` key, which
+stores ``imdb.rating`` nested field values. Then, the code sorts 
+each document in the ``sample_mflix.movies`` collection by 
+their descending ``score`` values:


Adding two tips:

One for a short explanation of KT -- used to work with the text value of keys, indexes, or path transforms within a JSONField. With a link to the KT documentation in Django

One for annotate (very powerful method!) -- Annotates each object in the QuerySet with the provided list of query expressions.

aclark4life

👍

Jibola

Great improvements!

Added a couple more new suggestions. Let me know what you think.

source/interact-data/specify-a-query.txt

Jibola · 2025-01-17T16:42:53Z

source/interact-data/specify-a-query.txt

+To learn how to run raw database queries by using MongoDB's aggregation 
+pipeline syntax, see the :ref:`django-raw-queries` guide.


Two things:

I think this blurb should get moved to the "Advanced Field Queries" section.

We should still point to the django-raw-queries guide, but I think we should adopt something more like the language in Django's documentation.

The blurb could go something like this...

To leverage the power of querying in Django using the MongoDB Aggregation Pipeline directly, you can fall back on doing saw through our raw querying. Check out our section on raw querying; see the :ref:`django-raw-queries` guide.

Okay added - but added a section to "Run a Query", since raw_aggregate() doesn't query a specific field type.

rustagir

mostly small fixes + questions but great job!

rustagir · 2025-01-22T16:26:01Z

source/interact-data/specify-a-query.txt

+When you assign a ``QuerySet`` to a variable, {+django-odm+} does not
+perform the operation until you evaluate the variable. After
+evaluating the ``QuerySet``, Django saves the query results in the ``QuerySet``
+cache. Future evaluations of the ``QuerySet`` reuse the cached results.


Suggested change

cache. Future evaluations of the ``QuerySet`` reuse the cached results.

cache. Future evaluations of the ``QuerySet`` use the cached results.

rustagir · 2025-01-22T16:26:10Z

source/interact-data/specify-a-query.txt

+    To learn more about the Django ``QuerySet`` API, see `QuerySet API reference
+    <{+django-docs+}/ref/models/querysets/>`__ in the Django documentation.


S: indentation is off

rustagir · 2025-01-22T16:27:00Z

source/interact-data/specify-a-query.txt

+You can refine the set of documents that a query returns by creating a
+**query filter**. A query filter is an expression that specifies the search
+criteria MongoDB uses to match documents in a read or write operation.
+In a query filter, you can prompt {+django-odm+} to search for documents with an
+exact match to your query, or you can compose query filters to express more
+complex matching criteria.


S: I think that this paragraph should be further up. Maybe you can move the specifics about the QuerySet API into a subheading called Querying API?

source/interact-data/specify-a-query.txt

rustagir · 2025-01-22T17:15:00Z

source/interact-data/specify-a-query.txt

+If you want to run complex queries that Django's query API
+cannot express, you can use the ``raw_aggregate()`` method. This
+method allows you to specify your query criteria in a MongoDB
+aggregation pipeline, which you pass as an argument to 
+``raw_aggregate()``. 


Suggested change

If you want to run complex queries that Django's query API

cannot express, you can use the ``raw_aggregate()`` method. This

method allows you to specify your query criteria in a MongoDB

aggregation pipeline, which you pass as an argument to

``raw_aggregate()``.

If you want to run complex queries that Django's query API

does not support, you can use the ``raw_aggregate()`` method. This

method allows you to specify your query criteria in a MongoDB

aggregation pipeline, which you pass as an argument to

``raw_aggregate()``.

rustagir · 2025-01-22T18:47:42Z

source/interact-data/specify-a-query.txt

+.. _django-query-arrayfield:
+
+Query an ArrayField
+~~~~~~~~~~~~~~~~~


S: extend underline

rustagir · 2025-01-22T18:47:54Z

source/interact-data/specify-a-query.txt

+additional field lookup types for querying ``ArrayField`` values,
+as described in the following table:


Suggested change

additional field lookup types for querying ``ArrayField`` values,

as described in the following table:

additional field lookup types for querying ``ArrayField`` values,

which are described in the following table:

rustagir · 2025-01-22T18:48:07Z

source/interact-data/specify-a-query.txt

+```````
+
+The following example uses the ``__overlap`` lookup to query
+for documents whose  ``genres`` field stores any values in the


Suggested change

for documents whose ``genres`` field stores any values in the

for documents whose ``genres`` field contains any values in the

rustagir · 2025-01-22T18:48:48Z

source/interact-data/specify-a-query.txt

+The following example queries the ``imdb`` field, a ``JSONField``,
+for values of its nested ``votes`` field that exceed ``900000``:


Suggested change

The following example queries the ``imdb`` field, a ``JSONField``,

for values of its nested ``votes`` field that exceed ``900000``:

The following example queries the ``JSONField``-valued ``imdb`` field

for values of its nested ``votes`` field that exceed ``900000``:

rustagir · 2025-01-22T18:50:53Z

source/interact-data/specify-a-query.txt

+
+The ``Movie`` model, which represents the ``sample_mflix.movies`` collection,
+uses the ``id`` field as its primary key. The following example constructs
+the same query as the preceding code:


Suggested change

the same query as the preceding code:

the same query as the preceding code by using the ``id`` field:

rustagir

few small suggestions but everything looks really good!

rustagir · 2025-01-23T14:49:33Z

source/interact-data/specify-a-query.txt

+      <Movie: In the Land of the Head Hunters>, <Movie: The Perils of Pauline>,
+      <Movie: The Italian>, <Movie: Regeneration>, <Movie: Civilization>,
+      <Movie: Where Are My Children?>, <Movie: The Poor Little Rich Girl>,
+      <Movie: Wild and Woolly>, <Movie: The Blue Bird>, <Movie: From Hand to Mouth>,
+      <Movie: High and Dizzy>, <Movie: One Week>, <Movie: The Saphead>,
+      <Movie: The Ace of Hearts>, <Movie: The Four Horsemen of the Apocalypse>,
+      '...(remaining elements truncated)...']>


S: applies to multiple examples, but up to you to truncate this further as the number of results doesn't signify anything

rustagir · 2025-01-23T14:50:43Z

source/interact-data/specify-a-query.txt

+.. literalinclude:: /includes/interact-data/specify-a-query.py
+   :start-after: start-models
+   :end-before: end-models
+   :language: python
+   :copyable:


S: cant comment on the code example but it might be helpful to note either as a code comment or somewhere in this text that the str method means that the string representation of a model is just its title

R-shubham

LGTM

norareidy added 2 commits January 14, 2025 13:44

DOCSP-46425: Specify a query

aeeeae1

DOCSP-46425: Specify a Query

86257f0

norareidy added 4 commits January 15, 2025 10:24

more info

8e5ef5e

more

b5ceafc

rest of page

53bbe4c

edits

17b5505

norareidy requested review from aclark4life, Jibola and R-shubham January 15, 2025 20:38

norareidy added 3 commits January 15, 2025 15:41

link fix

a29716e

edits

d775baf

edits

1e7fe90

aclark4life reviewed Jan 15, 2025

View reviewed changes

aclark4life approved these changes Jan 15, 2025

View reviewed changes

Jibola requested changes Jan 16, 2025

View reviewed changes

norareidy added 3 commits January 16, 2025 15:19

feedback

24803b2

Merge remote-tracking branch 'upstream/master' into DOCSP-46425-query

c56dd83

fixes

9628ae2

norareidy requested a review from Jibola January 16, 2025 20:31

norareidy added 2 commits January 16, 2025 15:37

edits

eae953b

wording

0c4d8ed

aclark4life approved these changes Jan 17, 2025

View reviewed changes

Jibola requested changes Jan 17, 2025

View reviewed changes

feedback

a1f6613

norareidy requested a review from Jibola January 21, 2025 15:32

rustagir self-requested a review January 22, 2025 16:24

Jibola approved these changes Jan 22, 2025

View reviewed changes

rustagir suggested changes Jan 22, 2025

View reviewed changes

RR feedback

cde657c

norareidy requested a review from rustagir January 22, 2025 22:29

norareidy added 4 commits January 22, 2025 17:32

fixes

e1e80ea

date

a28644b

fix

c888551

use include

1f08717

rustagir approved these changes Jan 23, 2025

View reviewed changes

norareidy added 4 commits January 23, 2025 14:42

RR feedback 2

8967686

embeddedmodel

877335f

test link

8ac2b61

try again

67790cf

R-shubham approved these changes Jan 27, 2025

View reviewed changes

Merge remote-tracking branch 'upstream/master' into DOCSP-46425-query

75a555a

norareidy merged commit a7004fe into mongodb:master Jan 27, 2025
5 checks passed

norareidy deleted the DOCSP-46425-query branch January 27, 2025 16:39

		To learn how to run raw database queries by using MongoDB's aggregation
		pipeline syntax, see the :ref:`django-raw-queries` guide.

	cache. Future evaluations of the ``QuerySet`` reuse the cached results.
	cache. Future evaluations of the ``QuerySet`` use the cached results.

		To learn more about the Django ``QuerySet`` API, see `QuerySet API reference
		<{+django-docs+}/ref/models/querysets/>`__ in the Django documentation.

		additional field lookup types for querying ``ArrayField`` values,
		as described in the following table:

	for documents whose ``genres`` field stores any values in the
	for documents whose ``genres`` field contains any values in the

		The following example queries the ``imdb`` field, a ``JSONField``,
		for values of its nested ``votes`` field that exceed ``900000``:

	the same query as the preceding code:
	the same query as the preceding code by using the ``id`` field:

DOCSP-46425: Specify a Query #2

DOCSP-46425: Specify a Query #2

Uh oh!

Conversation

norareidy commented Jan 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jan 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-django ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aclark4life left a comment

Choose a reason for hiding this comment

Uh oh!

Jibola left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aclark4life left a comment

Choose a reason for hiding this comment

Uh oh!

Jibola left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

norareidy commented Jan 14, 2025 •

edited

Loading

netlify bot commented Jan 14, 2025 •

edited

Loading