DOCSP-46329 Add Limitations page #12

jordan-smith721 · 2025-01-23T16:32:40Z

Pull Request Info

PR Reviewing Guidelines

JIRA - https://jira.mongodb.org/browse/DOCSP-46329

Staging Links

https://deploy-preview-12--docs-django.netlify.app/limitations/

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

netlify · 2025-01-23T16:33:00Z

✅ Deploy Preview for docs-django ready!

Name	Link
🔨 Latest commit	`8819421`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-django/deploys/679cd88421489c00080d4bf9
😎 Deploy Preview	https://deploy-preview-12--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.

Jibola

Looks great! Added in minor corrections.

Jibola · 2025-01-24T23:26:11Z

source/limitations.txt

+
+- ``EmbeddedModelField``
+
+  - You cannot change embedded models after creation.


Suggested change

- You cannot change embedded models after creation.

- EmbeddedModel schema changes do not register after creation.

Jibola · 2025-01-24T23:26:32Z

source/limitations.txt

+  - You cannot change embedded models after creation.
+  - Embedded documents cannot take Django foreign keys.
+  - {+django-odm+} does not support arbitrary or untyped embedded model
+    fields. You must derive all fields from a ``Model`` class.


Suggested change

fields. You must derive all fields from a ``Model`` class.

fields. You must derive all fields from a ``EmbeddedModel`` class.

Jibola · 2025-01-24T23:29:05Z

source/limitations.txt

+  - The ``DurationField`` stores milliseconds rather than microseconds.
+
+The following field types are unavailable in {+django-odm+}:
+
+- ``GeneratedField``
+- ``ImageField``
+
+- ``ForeignKey``
+
+  - When possible, you should use an ``EmbeddedModelField`` instead of a
+    ``ForeignKey`` field to avoid using ``$lookup`` operations. An
+    ``EmbeddedModelField`` emulates a MongoDB embedded document, and performs
+    better than a ``ForeignKey`` field. To learn more about how to reduce
+    ``$lookup`` operations, see the :atlas:`Reduce $lookup Operations
+    </schema-suggestions/reduce-lookup-operations/>` guide in the Atlas
+    documentation.
+  - The performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#foreignkey>`__ 
+    on a ``ForeignKey`` field is not as performant as using an
+    ``EmbeddedModelField``.


Suggested change

- The ``DurationField`` stores milliseconds rather than microseconds.

The following field types are unavailable in {+django-odm+}:

- ``GeneratedField``

- ``ImageField``

- ``ForeignKey``

- When possible, you should use an ``EmbeddedModelField`` instead of a

``ForeignKey`` field to avoid using ``$lookup`` operations. An

``EmbeddedModelField`` emulates a MongoDB embedded document, and performs

better than a ``ForeignKey`` field. To learn more about how to reduce

``$lookup`` operations, see the :atlas:`Reduce $lookup Operations

</schema-suggestions/reduce-lookup-operations/>` guide in the Atlas

documentation.

- The performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#foreignkey>`__

on a ``ForeignKey`` field is not as performant as using an

``EmbeddedModelField``.

- The ``DurationField`` stores milliseconds rather than microseconds.

- ``ForeignKey``

- When possible, you should use an ``EmbeddedModelField`` instead of a

``ForeignKey`` field to avoid using ``$lookup`` operations. An

``EmbeddedModelField`` emulates a MongoDB embedded document, and performs

better than a ``ForeignKey`` field. To learn more about how to reduce

``$lookup`` operations, see the :atlas:`Reduce $lookup Operations

</schema-suggestions/reduce-lookup-operations/>` guide in the Atlas

documentation.

- The performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#foreignkey>`__

on a ``ForeignKey`` field is not as performant as using an

``EmbeddedModelField``.

The following field types are unavailable in {+django-odm+}:

- ``GeneratedField``

- ``ImageField``

This needs to be moved to above the "The following field types are unavailable..." - JSONField has its own section.

@Jibola do we want to add a line around lack of support for Embeddedfield in Array. If their data is of this type they should use Join for now until we release the support for embeddedfield in array?

Jibola · 2025-01-24T23:29:48Z

source/limitations.txt

+~~~~~~~~~~~~~~~~~~
+
+- {+django-odm+} does not support ``GeoDjango``.
+- {+django-odm+} does not have any ``$lookup`` operators for MongoDB-specific


Suggested change

- {+django-odm+} does not have any ``$lookup`` operators for MongoDB-specific

- {+django-odm+} does not have any Django lookup operators for MongoDB-specific

R-shubham · 2025-01-28T14:47:24Z

source/limitations.txt

+On this page, you can find a list of features that
+{+django-odm+} does not support. Because {+django-odm+} is in active
+development, some features listed on this page might be considered for future
+releases based on customer demand.


I would replace customer with "user" or any similar word to indicate it's not just paying customer.

R-shubham · 2025-01-28T14:50:58Z

source/limitations.txt

+- Creation of ``$vectorSearch`` and ``$search`` indexes through the Django
+  Indexes API
+- Creating geospatial indexes through the Django Indexes API
+- Updating indexes in ``EmbeddedModelFields`` after model creation


Can we link to the page where we cover exposing mongoclient so that people know the workaround? @Jibola

Yeah, that's in the "Raw Queries" section

R-shubham · 2025-01-28T14:51:49Z

source/limitations.txt

+
+The following model limitations apply to {+django-odm+}:
+
+- {+django-odm+} does not support multiple models within a collection.


@Jibola @jordan-smith721 How about something like this?

Currently, the integration enforces a one-to-one mapping between a Django model and a MongoDB collection, meaning multiple models cannot share the same collection.

R-shubham · 2025-01-28T14:58:09Z

source/limitations.txt

+  - The ``DurationField`` stores milliseconds rather than microseconds.
+
+The following field types are unavailable in {+django-odm+}:
+
+- ``GeneratedField``
+- ``ImageField``
+
+- ``ForeignKey``
+
+  - When possible, you should use an ``EmbeddedModelField`` instead of a
+    ``ForeignKey`` field to avoid using ``$lookup`` operations. An
+    ``EmbeddedModelField`` emulates a MongoDB embedded document, and performs
+    better than a ``ForeignKey`` field. To learn more about how to reduce
+    ``$lookup`` operations, see the :atlas:`Reduce $lookup Operations
+    </schema-suggestions/reduce-lookup-operations/>` guide in the Atlas
+    documentation.
+  - The performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#foreignkey>`__ 
+    on a ``ForeignKey`` field is not as performant as using an
+    ``EmbeddedModelField``.


@Jibola do we want to add a line around lack of support for Embeddedfield in Array. If their data is of this type they should use Join for now until we release the support for embeddedfield in array?

R-shubham · 2025-01-28T15:02:36Z

source/limitations.txt

+============
+Limitations
+============
+


@jordan-smith721 we should probably add a link here that if you a user wants us to support any specific feature listed here. They should let us know through our feedback portal: https://feedback.mongodb.com/forums/924286-drivers?category_id=370732 They can also vote on existing requested feature if it is relevant to them.

R-shubham · 2025-01-28T15:04:05Z

source/limitations.txt

+Performance
+-----------
+
+The engineering team is prioritizing performance improvements prior to the


@Jibola @jordan-smith721 How does this sound?

Since this release is a Public Preview, our primary focus has been on feature development rather than performance optimizations. You may or may not notice performance limitations with certain workloads. If you encounter any performance issues, please file a ticket or share your feedback https://feedback.mongodb.com/forums/924286-drivers?category_id=370732.

@Jibola @jordan-smith721 Are we not covering MongoDB feature limitations here?

jordan-smith721 · 2025-01-28T17:51:55Z

source/limitations.txt

+To learn how to run unsupported database operations by operating directly on
+your ``MongoClient`` instance, see the :ref:`django-client-operations` guide.


Note: This link will work once the PR is merged in

norareidy

Looks great, thank you for picking this up! left a few suggestions / questions

norareidy · 2025-01-30T14:59:02Z

source/limitations.txt

+
+{+django-odm+} does not support the following index functionalities:
+
+- Creation of ``$vectorSearch`` and ``$search`` indexes through the Django


S: to match the verb tense of the other list items:

Suggested change

- Creation of ``$vectorSearch`` and ``$search`` indexes through the Django

- Creating ``$vectorSearch`` and ``$search`` indexes through the Django

norareidy · 2025-01-30T15:00:11Z

source/limitations.txt

+- Updating indexes in ``EmbeddedModelFields`` after model creation
+
+To learn how to run unsupported database operations by operating directly on
+your ``MongoClient`` instance, see the :ref:`django-client-operations` guide.


S: since this is a section in the Raw Queries guide

Suggested change

your ``MongoClient`` instance, see the :ref:`django-client-operations` guide.

your ``MongoClient`` instance, see :ref:`django-client-operations` in the Perform Raw Database Queries guide.

norareidy · 2025-01-30T15:00:50Z

source/limitations.txt

+
+Indexes
+~~~~~~~
+


Q: should we also mention that expression indexes aren't supported? @Jibola

norareidy · 2025-01-30T15:01:28Z

source/limitations.txt

+- ``ArrayField``
+
+  - {+django-odm+} does not support ``ArrayField`` polymorphism.
+  - {+django-odm+} does not support ``EmbeddedModelField`` within an ``ArrayField``.


S: a little clearer

Suggested change

- {+django-odm+} does not support ``EmbeddedModelField`` within an ``ArrayField``.

- {+django-odm+} does not support nesting an ``EmbeddedModelField`` within an ``ArrayField``.

norareidy · 2025-01-30T15:05:23Z

source/limitations.txt

+  - Filtering with a ``None`` key incorrectly returns objects in which a key
+    does not exist.


S: I think using field/value mongodb terminology makes more sense, since you use "value" in the first bullet

Suggested change

- Filtering with a ``None`` key incorrectly returns objects in which a key

does not exist.

- Filtering for ``None`` values incorrectly returns objects in which a field

does not exist.

norareidy · 2025-01-30T15:08:22Z

source/limitations.txt

+
+  - When possible, you should use an ``EmbeddedModelField`` instead of a
+    ``ForeignKey`` field to avoid using ``$lookup`` operations. An
+    ``EmbeddedModelField`` emulates a MongoDB embedded document, and performs


S: remove comma before dependent clause

Suggested change

``EmbeddedModelField`` emulates a MongoDB embedded document, and performs

``EmbeddedModelField`` emulates a MongoDB embedded document and performs

norareidy · 2025-01-30T15:09:45Z

source/limitations.txt

+    ``$lookup`` operations, see the :atlas:`Reduce $lookup Operations
+    </schema-suggestions/reduce-lookup-operations/>` guide in the Atlas
+    documentation.
+  - The performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#foreignkey>`__ 


S: might be better to link to the specific cascade section; also article

Suggested change

- The performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#foreignkey>`__

- Performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#django.db.models.CASCADE>`__

norareidy · 2025-01-30T15:10:32Z

source/limitations.txt

+- {+django-odm+} does not have any Django lookup operators for MongoDB-specific
+  geospatial queries.
+
+Aggregation operators


S:

Suggested change

Aggregation operators

Aggregation Operators

norareidy · 2025-01-30T15:10:54Z

source/limitations.txt

+Aggregation operators
+~~~~~~~~~~~~~~~~~~~~~
+
+{+django-odm+} does not contain any custom Django Field lookups for the MongoDB


S: lowercase field (I think)

Suggested change

{+django-odm+} does not contain any custom Django Field lookups for the MongoDB

{+django-odm+} does not contain any custom Django field lookups for the MongoDB

norareidy · 2025-01-30T15:11:40Z

source/limitations.txt

+aggregation framework. Instead, use the ``raw_aggregate`` method. For more
+information on the ``raw_aggregate`` method. 


S: you can link to the raw query guide; also, I'd add () after method names

Suggested change

aggregation framework. Instead, use the ``raw_aggregate`` method. For more

information on the ``raw_aggregate`` method.

aggregation framework. Instead, use the ``raw_aggregate()`` method. For more

information on the ``raw_aggregate()`` method, see

the :ref:`django-raw-queries` guide.

Jibola · 2025-01-30T16:04:38Z

source/limitations.txt

+The following field types are unavailable in {+django-odm+}:
+
+- ``GeneratedField``
+- ``ImageField``


Suggested change

- ``ImageField``

- ``AutoField``

- ``BigAutoField``

- ``SmallAutoField``

Looks like we support ImageField. I'll place

I can add to the fields in the Create Models guide

Jibola · 2025-01-30T16:05:37Z

source/limitations.txt

+- Creation of ``$vectorSearch`` and ``$search`` indexes through the Django
+  Indexes API
+- Creating geospatial indexes through the Django Indexes API
+- Updating indexes in ``EmbeddedModelFields`` after model creation


Yeah, that's in the "Raw Queries" section

norareidy

LGTM with final small comments!

norareidy · 2025-01-30T16:40:12Z

source/limitations.txt

+
+To learn how to run unsupported database operations by operating directly on
+your ``MongoClient`` instance, see :ref:`django-client-operations`  in the
+Perform Raw Database Queries.


S:

Suggested change

Perform Raw Database Queries.

Perform Raw Database Queries guide.

norareidy · 2025-01-30T16:43:56Z

source/limitations.txt

+The engineering team is prioritizing feature development for the Public Preview
+release of {+django-odm+}. Because of this, you might notice performance
+limitations with certain workloads. If you encounter any performance issues,
+please report it as shown in the :ref:`Issues & Help <django-issues-and-help>`


S: [nit]

Suggested change

please report it as shown in the :ref:`Issues & Help <django-issues-and-help>`

please report them as shown in the :ref:`Issues & Help <django-issues-and-help>`

norareidy · 2025-01-30T16:44:58Z

source/limitations.txt

+The following field types are unavailable in {+django-odm+}:
+
+- ``GeneratedField``
+- ``ImageField``


I can add to the fields in the Create Models guide

add limitations

2c92609

Jibola requested changes Jan 24, 2025

View reviewed changes

tech review feedback

4734d96

jordan-smith721 requested a review from Jibola January 27, 2025 17:06

R-shubham reviewed Jan 28, 2025

View reviewed changes

jordan-smith721 added 2 commits January 28, 2025 09:38

Shubham feedback

ff06bae

typo

e0e4b5f

jordan-smith721 commented Jan 28, 2025

View reviewed changes

jordan-smith721 requested a review from R-shubham January 28, 2025 18:14

norareidy requested changes Jan 30, 2025

View reviewed changes

Nora feedback:

f5dc1d5

jordan-smith721 requested a review from norareidy January 30, 2025 16:03

Jibola requested changes Jan 30, 2025

View reviewed changes

norareidy approved these changes Jan 30, 2025

View reviewed changes

more feedback

de3902f

jordan-smith721 requested a review from Jibola January 30, 2025 19:32

Jibola approved these changes Jan 30, 2025

View reviewed changes

Merge branch 'master' into DOCSP-46329-limitations

8819421

jordan-smith721 merged commit 2b67495 into mongodb:master Jan 31, 2025
1 check passed

jordan-smith721 deleted the DOCSP-46329-limitations branch January 31, 2025 14:05


		- ``EmbeddedModelField``

		- You cannot change embedded models after creation.

	- You cannot change embedded models after creation.
	- EmbeddedModel schema changes do not register after creation.

	fields. You must derive all fields from a ``Model`` class.
	fields. You must derive all fields from a ``EmbeddedModel`` class.

	- {+django-odm+} does not have any ``$lookup`` operators for MongoDB-specific
	- {+django-odm+} does not have any Django lookup operators for MongoDB-specific


		The following model limitations apply to {+django-odm+}:

		- {+django-odm+} does not support multiple models within a collection.

		To learn how to run unsupported database operations by operating directly on
		your ``MongoClient`` instance, see the :ref:`django-client-operations` guide.


		{+django-odm+} does not support the following index functionalities:

		- Creation of ``$vectorSearch`` and ``$search`` indexes through the Django

	- Creation of ``$vectorSearch`` and ``$search`` indexes through the Django
	- Creating ``$vectorSearch`` and ``$search`` indexes through the Django

	your ``MongoClient`` instance, see the :ref:`django-client-operations` guide.
	your ``MongoClient`` instance, see :ref:`django-client-operations` in the Perform Raw Database Queries guide.

	- {+django-odm+} does not support ``EmbeddedModelField`` within an ``ArrayField``.
	- {+django-odm+} does not support nesting an ``EmbeddedModelField`` within an ``ArrayField``.


		Indexes
		~~~~~~~

		- Filtering with a ``None`` key incorrectly returns objects in which a key
		does not exist.

	``EmbeddedModelField`` emulates a MongoDB embedded document, and performs
	``EmbeddedModelField`` emulates a MongoDB embedded document and performs

	- The performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#foreignkey>`__
	- Performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#django.db.models.CASCADE>`__

	{+django-odm+} does not contain any custom Django Field lookups for the MongoDB
	{+django-odm+} does not contain any custom Django field lookups for the MongoDB

		aggregation framework. Instead, use the ``raw_aggregate`` method. For more
		information on the ``raw_aggregate`` method.

-aggregation framework. Instead, use the ``raw_aggregate`` method. For more
-information on the ``raw_aggregate`` method.
+aggregation framework. Instead, use the ``raw_aggregate()`` method. For more
+information on the ``raw_aggregate()`` method, see
+the :ref:`django-raw-queries` guide.

-- ``ImageField``
+- ``AutoField``
+- ``BigAutoField``
+- ``SmallAutoField``

	Perform Raw Database Queries.
	Perform Raw Database Queries guide.

	please report it as shown in the :ref:`Issues & Help <django-issues-and-help>`
	please report them as shown in the :ref:`Issues & Help <django-issues-and-help>`

DOCSP-46329 Add Limitations page #12

DOCSP-46329 Add Limitations page #12

Uh oh!

Conversation

jordan-smith721 commented Jan 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info

Staging Links

Self-Review Checklist

Uh oh!

netlify bot commented Jan 23, 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!

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!

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!

norareidy 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!

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!

norareidy 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

jordan-smith721 commented Jan 23, 2025 •

edited

Loading

netlify bot commented Jan 23, 2025 •

edited

Loading