diff --git a/source/index.txt b/source/index.txt index df10007..1146dc4 100644 --- a/source/index.txt +++ b/source/index.txt @@ -15,9 +15,9 @@ Django MongoDB Backend Connection Configuration Model Your Data Interact with Data - Limitations & Upcoming Features + Feature Compatibility Issues & Help - Compatibility + Version Compatibility API Documentation <{+api+}> .. warning:: Public Preview @@ -56,12 +56,11 @@ Interact with Data Learn how to use {+django-odm+} to perform operations on MongoDB data in the :ref:`django-interact-data` section. -Limitations and Upcoming Features ---------------------------------- +Django and MongoDB Feature Compatibility +---------------------------------------- -Learn about the features that {+django-odm+} does not support -and features that we plan to support in upcoming releases -in the :ref:`django-limitations` section. +Learn about {+django-odm+}'s support for {+framework+} and +MongoDB features in the :ref:`django-limitations` section. Compatibility ------------- diff --git a/source/limitations-upcoming.txt b/source/limitations-upcoming.txt index 1707f70..186947d 100644 --- a/source/limitations-upcoming.txt +++ b/source/limitations-upcoming.txt @@ -1,301 +1,581 @@ .. _django-limitations: +.. _django-feature-compat: -================================= -Limitations and Upcoming Features -================================= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol +======================================== +Django and MongoDB Feature Compatibility +======================================== .. facet:: :name: genre :values: reference .. meta:: - :keywords: support, features, django + :keywords: upcoming, odm, support + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol Overview -------- -On this page, you can find a list of features that -{+django-odm+} does not support. You can also find features +On this page, you can find information about supported and unsupported +features in {+django-odm+}. You can also find features currently planned for the General Availability (GA) and post-GA releases. We will prioritize these upcoming features based on user demand, and you can request support for a feature by :ref:`creating a JIRA issue `. -Feature Limitations -------------------- - -In this section, you can learn about the following -types of unsupported {+framework+} and MongoDB features: - -- :ref:`django-limitations-transactions` -- :ref:`django-limitations-models` -- :ref:`django-limitations-query` -- :ref:`django-limitations-management` -- :ref:`django-limitations-migration` -- :ref:`django-limitations-performance` - -.. _django-limitations-transactions: - -Transaction management -~~~~~~~~~~~~~~~~~~~~~~ - -Query execution uses Django and MongoDB's default behavior of autocommit mode. -Each query is immediately committed to the database. - -Django's transaction management APIs are not supported. - -.. _django-limitations-models: - -Model Limitations -~~~~~~~~~~~~~~~~~ - -Django doesn't support MongoDB's `polymorphic pattern -`__ -where slightly different models share the same collection. - -Indexes -``````` - -{+django-odm+} does not support the following index functionalities: - -- 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 - -.. _django-limitations-models-fields: - -Fields -`````` - -{+django-odm+} has the following limitations on the specified field types: - -- ``ArrayField`` - - - ``ArrayField`` polymorphism is not supported. - - Nested ``EmbeddedModelField`` values within an ``ArrayField`` are not supported. - -- ``EmbeddedModelField`` - - - ``EmbeddedModel`` schema changes do not register after creation. - - Embedded documents cannot take Django foreign keys. - - Arbitrary or untyped embedded model fields are not supported. You must - derive all fields from a ``EmbeddedModel`` 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 for ``None`` values incorrectly returns objects in which a field - does not exist. - -- ``DateTimeField`` - - - Microsecond granularity for ``DateTimeField`` values is not supported. - -- ``DurationField`` - - - ``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 - ` guide in the Atlas - documentation. - - 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``. - -The following field types are unavailable in {+django-odm+}: +MongoDB Features +---------------- -- ``GeneratedField`` -- ``AutoField`` (including ``BigAutoField`` and ``SmallAutoField``) +This section indicates whether the {+django-odm+} supports various +MongoDB features and which features we plan to support in +the GA release. -.. _django-limitations-query: +.. important:: -Querying Limitations -~~~~~~~~~~~~~~~~~~~~ + Unsupported MongoDB features that have a checkmark (``✓``) symbol in the + **General Availability Support** column are planned for the GA + release. However, support is not guaranteed. -{+django-odm+} does not support the following ``QuerySet`` API methods: +Index Support +~~~~~~~~~~~~~ -- ``distinct()`` -- ``dates()`` -- ``datetimes()`` -- ``prefetch_related()`` -- ``extra()`` +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 30 40 -{+django-odm+} does not support ``QuerySet.delete()`` and ``update()`` queries -that span multiple collections. + * - MongoDB Feature + - Current Support + - General Availability Support -Geospatial Queries -`````````````````` + * - Atlas Search and Atlas Vector Search indexes + - *Unsupported*. You cannot use the Django + Indexes API to create these indexes, but you can use + the PyMongo Driver by :ref:`exposing your MongoClient `. + - ✓ -{+django-odm+} does not support the following geospatial query features: + * - Compound indexes + - ✓ + - ✓ -- ``GeoDjango`` -- Django lookup operators for MongoDB-specific geospatial queries + * - Embedded document indexes + - ✓ + - ✓ -Aggregation Operators -````````````````````` + * - Geospatial indexes + - *Unsupported*. You cannot use the Django + Indexes API to create these indexes, but you can use + the PyMongo Driver by :ref:`exposing your MongoClient `. + - ✓ -{+django-odm+} does not include any custom Django field lookups for the MongoDB -aggregation framework. Instead, use the ``raw_aggregate()`` method. See the -:ref:`django-raw-queries` guide. + * - Multikey indexes + - ✓ + - ✓ -Database Functions -`````````````````` + * - Partial indexes + - ✓ + - ✓ -{+django-odm+} does not support the following database functions: + * - Single field indexes + - ✓ + - ✓ -- ``Chr`` -- ``ExtractQuarter`` -- ``MD5`` -- ``Now`` -- ``Ord`` -- ``Pad`` -- ``Repeat`` -- ``Reverse`` -- ``Right`` -- ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, ``SHA512`` -- ``Sign`` + * - Unique indexes + - ✓ + - ✓ -The ``tzinfo`` parameter of the ``Trunc`` database functions doesn't work -properly because MongoDB converts the result back to UTC. + * - Updating ``EmbeddedModelFields`` indexes after model creation + - *Unsupported*. + - ✓ -.. _django-limitations-management: +Data Type Support +~~~~~~~~~~~~~~~~~ -Unsupported Management Commands +{+django-odm+} currently supports all MongoDB data types not included +in the following table. To view a full list of supported types, see the +:ref:`django-models-mongodb-fields` section of the Create Models guide. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 30 40 + + * - BSON Data Type + - Current Support + - General Availability Support + + * - ``Array`` + - *Partially Supported*. You can use the ``ArrayField`` field type with the + following limitations: + + - ``ArrayField`` polymorphism is not supported. + - Nested ``EmbeddedModelField`` values within an ``ArrayField`` are not supported. + + - ✓ + + * - ``Object`` + - *Partially Supported*. You can use the ``EmbeddedModelField`` field type with the + following limitations: + + - ``EmbeddedModel`` schema changes do not register after creation. + - Embedded documents cannot take Django foreign keys. + - Arbitrary or untyped embedded model fields are not supported. You must + derive all fields from a ``EmbeddedModel`` class. + + - *Partial Support Planned*. We plan to add support for registering + ``EmbeddedModel`` schema changes after creation. + + * - ``Regular Expression`` + - *Unsupported*. + - *Unsupported*. However, we plan to support this type + in a post-GA release. + +Query Support +~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 30 40 + + * - MongoDB Feature + - Current Support + - General Availability Support + + * - Aggregation operations + - *Partially Supported*. The {+django-odm+} does not include custom + Django field lookups for the MongoDB aggregation framework, but you + can use the :ref:`raw_aggregate() method `. + - *Full Support Not Planned*. However, we plan to add support for MongoDB + aggregation operators in a post-GA release. + + * - Atlas Search queries + - *Partially Supported*. You cannot use the Django + ``QuerySet`` API to run Atlas Search queries, but you can use + the :ref:`raw_aggregate() method `. + - ✓ + + * - Delete operations + - ✓ + - ✓ + + * - Geospatial queries + - *Partially Supported*. You cannot use the Django + ``QuerySet`` or ``GeoDjango`` API to run geospatial queries, but you can use + the :ref:`raw_aggregate() method `. + - ✓ + + * - Insert operations + - ✓ + - ✓ + + * - Read operations + - ✓ + - ✓ + + * - Update operations + - ✓ + - ✓ + + * - Vector Search queries + - *Partially Supported*. You cannot use the Django + ``QuerySet`` API to run Vector Search queries, but you can use + the :ref:`raw_aggregate() method `. + - ✓ + +Database and Collection Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following ``django-admin`` commands are unsupported: - -- ``createcachetable`` -- ``inspectdb`` - -.. _django-limitations-migration: +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 30 40 -Migration Limitations -~~~~~~~~~~~~~~~~~~~~~ + * - MongoDB Feature + - Current Support + - General Availability Support -{+django-odm+} does not support the following migration features: + * - Asynchronous 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. -- `DDL Transactions <{+django-docs+}/topics/migrations/#transactions>`__. -- The ``migrate --fake-initial`` option. + * - Authentication + - ✓ + - ✓ -.. _django-limitations-performance: + * - Cached data storage + - ✓ Use the ``django_mongodb_backend.cache.MongoDBCache`` backend rather + than {+framework+}'s built-in database cache backend, ``django.core.cache.backends.db.DatabaseCache``. + - ✓ -Performance -~~~~~~~~~~~ + * - Change Streams + - *Unsupported*. + - *Unsupported*. However, we plan to add support for this feature + in a post-GA release. + + * - Client-side Field Level Encryption and Queryable Encryption + - *Unsupported*. + - ✓ + + * - Collection interaction + - ✓ + - ✓ + + * - Database interaction + - ✓ + - ✓ + + * - GridFS + - *Unsupported*. + - *Unsupported*. However, we plan to add support for this feature + in a post-GA release. + + * - Multiple models for one collection + - *Unsupported*. + - ✓ + + * - Representing documents + - ✓ Use models to represent MongoDB documents. + - ✓ + + * - Schema validation + - *Unsupported*. + - *Unsupported*. However, we plan to add support for this feature + in a post-GA release. + + * - Timeseries data + - ✓ + - ✓ + + * - Transactions + - *Unsupported*. + - ✓ + +Django Features +--------------- + +This section indicates whether the {+django-odm+} supports various +{+framework+} features and which features we plan to support in +the GA release. + +.. important:: + + Unsupported {+framework+} features that have a checkmark (``✓``) symbol in the + **General Availability Support** column are planned for the GA + release. However, support is not guaranteed. + +Field Type Support +~~~~~~~~~~~~~~~~~~ + +{+django-odm+} currently supports all {+framework+} field types not included in +the following table. To view a full list of supported fields, see the :ref:`django-models-django-fields` +section of the Create Models guide. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 30 40 + + * - {+framework+} Field Type + - Current Support + - General Availability Support + + * - ``AutoField`` + - *Unsupported*. The ``BigAutoField`` and ``SmallAutoField`` types are also + not supported. Instead, use ``ObjectIdField``. + - *Unsupported*. + + * - ``DateTimeField`` + - *Partially Supported*. You can use this field type with the + following limitations: + + - Microsecond granularity for ``DateTimeField`` values is not supported. + + - *Full Support Not Planned*. + + * - ``DurationField`` + - *Partially Supported*. You can use this field type with the + following limitations: + + - ``DurationField`` stores milliseconds rather than microseconds + + - *Full Support Not Planned*. + + * - ``ForeignKey`` + - *Partially Supported*. You can use this field type with the + following limitations: + + - 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. + - 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``. + + - *Full Support Not Planned*. + + * - ``GeneratedField`` + - *Unsupported*. + - *Unsupported*. + + * - ``JSONField`` + - *Partially Supported*. You can use this field type with the + following limitations: + + - {+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 for ``None`` values incorrectly returns objects in which a field + does not exist. + + - *Full Support Not Planned*. However, we plan to address the + ``Q`` object and ``None`` key filtering limitations in a post-GA release. + +Query Support +~~~~~~~~~~~~~ + +{+django-odm+} currently supports all {+framework+} ``QuerySet`` methods not +included in the following table. To view the supported methods, see `QuerySet API +<{+django-docs+}/ref/models/querysets/#queryset-api>`__ in the {+framework+} +documentation. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 30 40 + + * - {+framework+} ``QuerySet`` Feature + - Current Support + - General Availability Support + + * - ``delete()`` + - *Partially Supported*. You cannot use this method to perform + queries that span multiple collections. + - *Full Support Not Planned*. + + * - ``extra()`` + - *Unsupported*. + - *Unsupported*. + + * - ``prefetch_related()`` + - *Unsupported*. + - *Unsupported*. + + * - ``raw()`` + - *Unsupported*. However, you can use the ``raw_aggregate()`` method + to run queries that use MongoDB's aggregation pipeline syntax. + - *Full Support Not Planned*. + + * - ``update()`` + - *Partially Supported*. You cannot use this method to perform + queries that span multiple collections. + - *Full Support Not Planned*. + +Database Function Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +{+django-odm+} currently supports all database functions not included in +the following table. To view a full list of functions, see `Database Functions +<{+django-docs+}/ref/models/database-functions/>`__ in the {+framework+} +documentation. + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 30 40 + + * - {+framework+} Function + - Current Support + - General Availability Support + + * - ``Chr`` + - *Unsupported*. + - *Unsupported*. + + * - ``ExtractQuarter`` + - *Unsupported*. + - *Unsupported*. + + * - ``MD5`` + - *Unsupported*. + - *Unsupported*. + + * - ``Now`` + - *Unsupported*. + - *Unsupported*. + + * - ``Ord`` + - *Unsupported*. + - *Unsupported*. + + * - ``Pad`` + - *Unsupported*. + - *Unsupported*. + + * - ``Repeat`` + - *Unsupported*. + - *Unsupported*. + + * - ``Reverse`` + - *Unsupported*. + - *Unsupported*. + + * - ``Right`` + - *Unsupported*. + - *Unsupported*. + + * - ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, ``SHA512`` + - *Unsupported*. + - *Unsupported*. + + * - ``Sign`` + - *Unsupported*. + - *Unsupported*. + + * - ``Trunc`` + - *Partially Supported*. The ``tzinfo`` parameter of the + :py:class:`~django.db.models.functions.TruncDate` and + :py:class:`~django.db.models.functions.TruncTime` database + functions is not supported. + - *Full Support Not Planned*. + +Management Support +~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 30 40 + + * - {+framework+} Feature + - Current Support + - General Availability Support + + * - {+framework+} Admin + - ✓ + - ✓ + + * - {+framework+} Forms + - ✓ + - ✓ + + * - {+framework+} Authentication + - ✓ + - ✓ + + * - Management commands + - *Partially Supported*. To view the unsupported + commands, see the :ref:`following section `. + - *Full Support Not Planned*. + +.. _django-management-commands: -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 them as shown in the :ref:`Issues & Help ` -guide. +Management Command Support +`````````````````````````` + +{+django-odm+} currently supports all management commands not included in +the following table. To view a full list of commands, see `Available commands +<{+django-docs+}/ref/django-admin/#available-commands>`__ in the {+framework+} +documentation. -General Availability Release Features -------------------------------------- +.. list-table:: + :header-rows: 1 + :widths: 30 30 40 -In this section, you can learn about the following -types of {+framework+} and MongoDB features that -GA and post-GA {+django-odm+} releases will likely introduce: + * - {+framework+} Command + - Current Support + - General Availability Support -- :ref:`django-upcoming-mongodb` -- :ref:`django-upcoming-models` -- :ref:`django-upcoming-management` -- :ref:`django-upcoming-third-party` + * - ``createcachetable`` + - *Unsupported*. Instead, use {+django-odm+}'s ``createcachecollection`` command. + - *Unsupported*. -.. _django-upcoming-mongodb: + * - ``dumpdata`` + - *Unsupported*. + - ✓ -MongoDB Features -~~~~~~~~~~~~~~~~ - -We plan to support the following MongoDB features in the GA release: - -- Programmatic management of Vector Search, Atlas Search, - and geospatial indexes by using the Django API -- Vector Search, Atlas Search, and geospatial queries - by using the Django API -- Queryable Encryption and Client-side Field Level Encryption -- Database transactions -- Storage of cached data in the database + * - ``inspectdb`` + - *Unsupported*. + - *Unsupported*. However, we plan to support this command + in a post-GA release. -We plan to support the following MongoDB features in future post-GA releases: + * - ``loaddata`` + - *Unsupported*. + - ✓ -- GridFS for large file storage -- Change streams for data monitoring -- Schema validation + * - ``sqlflush`` + - *Unsupported*. + - *Unsupported*. -.. tip:: + * - ``sqlsequencereset`` + - *Unsupported*. + - *Unsupported*. - To learn more about the MongoDB features mentioned in this section, see - the following resources: +Migration Support +~~~~~~~~~~~~~~~~~ - - :atlas:`Atlas Vector Search ` in the Atlas documentation - - :atlas:`Atlas Search ` in the Atlas documentation - - :manual:`Geospatial Queries ` in the {+mdb-server+} - manual - - :manual:`In-Use Encryption ` in the {+mdb-server+} - manual - - :manual:`Transactions ` in the {+mdb-server+} - manual - - :manual:`GridFS ` in the {+mdb-server+} - manual - - :manual:`Change Streams ` in the {+mdb-server+} - manual +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 30 40 -.. _django-upcoming-models: + * - {+framework+} Feature + - Current Support + - General Availability Support -Model Features -~~~~~~~~~~~~~~ + * - Creating, deleting, and updating indexes through migration + commands + - *Partially Supported*. You cannot update indexes on embedded model + or array fields. + - *Full Support Not Planned*. -We plan to support the following model features in the GA release: + * - `DDL Transactions <{+django-docs+}/topics/migrations/#transactions>`__ + - *Unsupported*. + - *Unsupported*. -- Arrays of embedded documents -- Polymorphic embedded documents and arrays -- Application of changes to the embedded model schema to - ``EmbeddedModelField`` values -- Multiple models within a collection -- Improved form representation in embedded models + * - ``migrate --fake-initial`` option + - *Unsupported*. + - *Unsupported*. -In a future post-GA release, we plan to add a custom model field for the -``BSONRegExp`` data type. +Third Party Library Support +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _django-upcoming-management: +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 30 30 40 -Management Command Features -~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * - Library + - Current Support + - General Availability Support -Serialization support for ``EmbeddedModelField`` (i.e. Django's ``dumpdata`` -and ``loaddata`` management commands) will be added by the GA release. + * - `Django-filter `__ + - *Partially Supported*. Most use cases are supported. + - *Partially Supported*. This release will outline use case limitations. -.. _django-upcoming-third-party: + * - `Django Rest Framework `__ + - *Partially Supported*. Most use cases are supported. + - *Partially Supported*. This release will outline use case limitations. -Third-Party Libraries -~~~~~~~~~~~~~~~~~~~~~ + * - `Django-allauth `__ + - *Partially Supported*. Most use cases are supported. + - *Partially Supported*. This release will outline use case limitations. -We plan to test compatibility with the following third-party libraries by the -GA release: + * - `Wagtail `__ + - *Unsupported*. + - *Partially Supported*. This release will outline use case limitations. -- `Django-filter `__ -- `Django Rest Framework `__ -- `Django-allauth `__ -- `Wagtail `__ -- `Django Debug Toolbar `__ + * - `Django Debug Toolbar `__ + - *Partially Supported*. Most use cases are supported. + - *Partially Supported*. This release will outline use case limitations.