From 2c92609cf8597d127c564474c252970bee065fc7 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Thu, 23 Jan 2025 08:32:07 -0800 Subject: [PATCH 1/6] add limitations --- source/index.txt | 1 + source/limitations.txt | 197 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 198 insertions(+) create mode 100644 source/limitations.txt diff --git a/source/index.txt b/source/index.txt index ea41052..796036b 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,6 +11,7 @@ Django MongoDB Backend .. toctree:: + Limitations Issues & Help Compatibility diff --git a/source/limitations.txt b/source/limitations.txt new file mode 100644 index 0000000..dec8744 --- /dev/null +++ b/source/limitations.txt @@ -0,0 +1,197 @@ +.. _django-limitations: + +============ +Limitations +============ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: support, features, django + +Overview +-------- + +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. + +Unsupported Database Variables +------------------------------ + +The following database variables are not supported by {+django-odm+}: + +- ``ATOMIC_REQUESTS`` +- ``AUTOCOMMIT`` +- ``CONN_HEALTH_CHECKS`` +- ``TIME_ZONE`` + +Model Limitations +----------------- + +The following model limitations apply to {+django-odm+}: + +- {+django-odm+} does not support multiple models within a collection. + +Indexes +~~~~~~~ + +{+django-odm+} does not support the following index functionalities: + +- 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 + +Fields +~~~~~~ + +{+django-odm+} has the following limitations on the specified field types: + +- ``ArrayField`` + + - {+django-odm+} does not support ``ArrayField`` polymorphism. + - {+django-odm+} does not support ``EmbeddedModelField`` within an ``ArrayField``. + +- ``EmbeddedModelField`` + + - 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. + +- ``JSONField`` + + - {+django-odm+} cannot distinguish between a JSON and a SQL ``null`` value. + Queries that use ``Value(None, JSONField())`` or the ``isnull`` lookup + return both JSON and SQL ``null`` values. + - Some queries with ``Q`` objects, such as ``Q(value__foo="bar")``, might + not work as expected. + - Filtering with a ``None`` key incorrectly returns objects in which a key + does not exist. + +- ``DateTimeField`` + + - {+django-odm+} does not support microsecond granularity for + ``DateTimeField``. + +- ``DurationField`` + + - 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 + ` 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``. + +Querying Limitations +-------------------- + +{+django-odm+} does not support the following ``QuerySet`` API methods: + +- ``distinct()`` +- ``dates()`` +- ``datetimes()`` +- ``prefetch_related()`` +- ``extra()`` + +{+django-odm+} does not support ``QuerySet.delete()`` and ``update()`` queries +that span multiple collections. + +Geospatial Queries +~~~~~~~~~~~~~~~~~~ + +- {+django-odm+} does not support ``GeoDjango``. +- {+django-odm+} does not have any ``$lookup`` operators for MongoDB-specific + geospatial queries. + +Aggregation operators +~~~~~~~~~~~~~~~~~~~~~ + +{+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. + +.. TODO: Link to aggregation + +Database Functions +~~~~~~~~~~~~~~~~~~ + +{+django-odm+} does not support the following database functions: + +- ``Chr`` +- ``ExtractQuarter`` +- ``MD5`` +- ``Now`` +- ``Ord`` +- ``Pad`` +- ``Repeat`` +- ``Reverse`` +- ``Right`` +- ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, ``SHA512`` +- ``Sign`` + +The ``tzinfo`` parameter of the ``Trunc`` database functions doesn't work +properly because MongoDB converts the result back to UTC. + +Django Management Command Limitations +------------------------------------- + +{+django-odm+} does not support the following Django management commands: + +- ``createcachetable`` +- ``inspectdb`` +- ``optimizemigration`` +- ``sqlflush`` +- ``sqlsequencereset`` + +Migration Limitations +--------------------- + +- {+django-odm+} does not support enforced schema validation. To learn how to + enforce schema validation in your application, see the :manual:`Specify JSON + Schema Validation ` guide in the + {+mdb-server+} manual. +- {+django-odm+} does not support `DDL Transactions + <{+django-docs+}/topics/migrations/#transactions>`__. +- {+django-odm+} does not support the ``migrate --fake-initial`` command. + +Asynchronous Support +-------------------- + +{+django-odm+} has not been tested for support of the asynchronous functionality of +the Django API. + +Data Types +---------- + +{+django-odm+} does not have a custom ``Field`` class for the ``BSONRegExp`` +data type. Instead, use the ``CharField`` class. + +Performance +----------- + +The engineering team is prioritizing performance improvements prior to the +General Availability release of {+django-odm+}. \ No newline at end of file From 4734d96210c238c45c079e46236e05bb98fcb48a Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Mon, 27 Jan 2025 09:06:12 -0800 Subject: [PATCH 2/6] tech review feedback --- source/limitations.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/limitations.txt b/source/limitations.txt index dec8744..faa3367 100644 --- a/source/limitations.txt +++ b/source/limitations.txt @@ -64,10 +64,10 @@ Fields - ``EmbeddedModelField`` - - You cannot change embedded models after creation. + - ``EmbeddedModel`` schema changes do not register 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. + fields. You must derive all fields from a ``EmbeddedModel`` class. - ``JSONField`` @@ -88,11 +88,6 @@ Fields - 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 @@ -106,6 +101,11 @@ The following field types are unavailable in {+django-odm+}: on a ``ForeignKey`` field is not as performant as using an ``EmbeddedModelField``. +The following field types are unavailable in {+django-odm+}: + +- ``GeneratedField`` +- ``ImageField`` + Querying Limitations -------------------- @@ -124,7 +124,7 @@ Geospatial Queries ~~~~~~~~~~~~~~~~~~ - {+django-odm+} does not support ``GeoDjango``. -- {+django-odm+} does not have any ``$lookup`` operators for MongoDB-specific +- {+django-odm+} does not have any Django lookup operators for MongoDB-specific geospatial queries. Aggregation operators From ff06bae7e3cefbf45b6ac5b71fc8a9c6a276f375 Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Tue, 28 Jan 2025 09:38:49 -0800 Subject: [PATCH 3/6] Shubham feedback --- source/limitations.txt | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/source/limitations.txt b/source/limitations.txt index faa3367..a43287f 100644 --- a/source/limitations.txt +++ b/source/limitations.txt @@ -23,7 +23,9 @@ Overview 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. +releases based on user demand. You can request support for a feature by leaving +a suggestion on the `Drivers Feedback Forum +`__. Unsupported Database Variables ------------------------------ @@ -38,9 +40,10 @@ The following database variables are not supported by {+django-odm+}: Model Limitations ----------------- -The following model limitations apply to {+django-odm+}: +The following limitations apply to models in {+django-odm+}: -- {+django-odm+} does not support multiple models within a collection. +- {+django-odm+} enforces a one-to-one mapping between a Django model and a + MongoDB collection. Because of this, multiple models cannot share the same collection. Indexes ~~~~~~~ @@ -52,6 +55,9 @@ Indexes - Creating geospatial indexes through the Django Indexes API - 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:`` guide. + Fields ~~~~~~ @@ -193,5 +199,9 @@ data type. Instead, use the ``CharField`` class. Performance ----------- -The engineering team is prioritizing performance improvements prior to the -General Availability release of {+django-odm+}. \ No newline at end of file +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 ` +guide. You can also share your feedback on the `Drivers Feedback Forum +`__. From e0e4b5f8d6213577455dc85258fc127f707e4b9d Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Tue, 28 Jan 2025 09:51:29 -0800 Subject: [PATCH 4/6] typo --- source/limitations.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/limitations.txt b/source/limitations.txt index a43287f..1428a8f 100644 --- a/source/limitations.txt +++ b/source/limitations.txt @@ -56,7 +56,7 @@ Indexes - 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:`` guide. +your ``MongoClient`` instance, see the :ref:`django-client-operations` guide. Fields ~~~~~~ From f5dc1d5ae92bc9889bace2d734f780c3cbc2e94d Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Thu, 30 Jan 2025 07:47:49 -0800 Subject: [PATCH 5/6] Nora feedback: --- source/limitations.txt | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/source/limitations.txt b/source/limitations.txt index 1428a8f..f979dbd 100644 --- a/source/limitations.txt +++ b/source/limitations.txt @@ -50,13 +50,14 @@ Indexes {+django-odm+} does not support the following index functionalities: -- Creation of ``$vectorSearch`` and ``$search`` indexes through the Django +- Creating ``$vectorSearch`` and ``$search`` indexes through the Django Indexes API - Creating geospatial indexes through the Django Indexes API - 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. +your ``MongoClient`` instance, see :ref:`django-client-operations` in the +Perform Raw Database Queries. Fields ~~~~~~ @@ -66,7 +67,7 @@ Fields - ``ArrayField`` - {+django-odm+} does not support ``ArrayField`` polymorphism. - - {+django-odm+} does not support ``EmbeddedModelField`` within an ``ArrayField``. + - {+django-odm+} does not support nesting an ``EmbeddedModelField`` within an ``ArrayField``. - ``EmbeddedModelField`` @@ -82,28 +83,28 @@ Fields return both JSON and SQL ``null`` values. - Some queries with ``Q`` objects, such as ``Q(value__foo="bar")``, might not work as expected. - - Filtering with a ``None`` key incorrectly returns objects in which a key + - Filtering for ``None`` values incorrectly returns objects in which a field does not exist. - ``DateTimeField`` - {+django-odm+} does not support microsecond granularity for - ``DateTimeField``. + ``DateTimeField``. - ``DurationField`` - - The ``DurationField`` stores milliseconds rather than microseconds. + - ``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 + ``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 ` guide in the Atlas documentation. - - The performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#foreignkey>`__ + - Performance of `CASCADE deletes <{+django-docs+}/ref/models/fields/#django.db.models.CASCADE>`__ on a ``ForeignKey`` field is not as performant as using an ``EmbeddedModelField``. @@ -133,12 +134,13 @@ Geospatial Queries - {+django-odm+} does not have any Django lookup operators for MongoDB-specific geospatial queries. -Aggregation operators +Aggregation Operators ~~~~~~~~~~~~~~~~~~~~~ -{+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. +{+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, see +the :ref:`django-raw-queries` guide. .. TODO: Link to aggregation From de3902fb808a4abef264d661b51e05cbc39db99e Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Thu, 30 Jan 2025 11:31:54 -0800 Subject: [PATCH 6/6] more feedback --- source/limitations.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/limitations.txt b/source/limitations.txt index f979dbd..e76b4eb 100644 --- a/source/limitations.txt +++ b/source/limitations.txt @@ -57,7 +57,7 @@ Indexes 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. +Perform Raw Database Queries guide. Fields ~~~~~~ @@ -111,7 +111,9 @@ Fields The following field types are unavailable in {+django-odm+}: - ``GeneratedField`` -- ``ImageField`` +- ``AutoField`` +- ``BigAutoField`` +- ``SmallAutoField`` Querying Limitations -------------------- @@ -204,6 +206,6 @@ Performance 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 ` +please report them as shown in the :ref:`Issues & Help ` guide. You can also share your feedback on the `Drivers Feedback Forum `__.