From a1c584a3af97886a03fb3e7af64ce08482ab2c9b Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 16 Jan 2025 19:30:36 -0500 Subject: [PATCH 1/8] DOCSP-46327: Create indexes --- source/includes/model-data/indexes.py | 94 ++++++++ source/index.txt | 10 +- source/model-data.txt | 25 ++ source/model-data/indexes.txt | 319 ++++++++++++++++++++++++++ 4 files changed, 443 insertions(+), 5 deletions(-) create mode 100644 source/includes/model-data/indexes.py create mode 100644 source/model-data.txt create mode 100644 source/model-data/indexes.txt diff --git a/source/includes/model-data/indexes.py b/source/includes/model-data/indexes.py new file mode 100644 index 0000000..bcac5ca --- /dev/null +++ b/source/includes/model-data/indexes.py @@ -0,0 +1,94 @@ +# start-models +from django.db import models +from django.db.models import Q, F +from django_mongodb_backend.fields import EmbeddedModelField, ArrayField + +class Nutrition(models.Model): + calories = models.IntegerField(default=0) + fat_grams = models.IntegerField(default=0) + carb_grams = models.IntegerField(default=0) + protein_grams = models.IntegerField(default=0) + +class Recipe(models.Model): + title = models.CharField(max_length=200) + cuisine = models.CharField(max_length=200) + cook_time = models.IntegerField(default=0) + prep_time = models.IntegerField(default=0) + allergens = ArrayField(models.CharField(max_length=100), null=True, blank=True) + nutrition = EmbeddedModelField(Nutrition, null=True, blank=True) + + class Meta: + db_table = "recipes" + + def __str__(self): + return self.title +# end-models + +# start-single-field-meta +class Meta: + db_table = "recipes" + indexes = [ + models.Index(fields=["title"], name="title_idx"), + ] +# end-single-field-meta + +# start-single-field-option +title = models.CharField(max_length=200, db_index=True) +# end-single-field-option + +# start-compound +class Meta: + db_table = "recipes" + indexes = [ + models.Index(fields=["title", "cook_time"]), + ] +# end-compound + +# start-multikey +class Meta: + db_table = "recipes" + indexes = [ + models.Index(fields=["allergens"], name="allergy_idx"), + ] +# end-multikey + +# start-embedded +class Meta: + db_table = "recipes" + indexes = [ + models.Index(fields=["nutrition"]), + ] +# end-embedded + +# start-partial +class Meta: + db_table = "recipes" + indexes = [ + models.Index(fields=["cuisine"], + condition=Q(cook_time__lt=30), + name="fast_cuisine_idx"), + ] +# end-partial + +# start-unique-single +title = models.CharField(max_length=200, unique=True) +# end-unique-single + +# start-unique-compound +class Meta: + db_table = "recipes" + indexes = [ + models.Index(fields=["title", "cuisine"]), + ] + constraints = [ + models.UniqueConstraint(fields=["title", "cuisine"], name="unique_regional_meal") + ] +# end-unique-compound + +# start-multikey +class Meta: + db_table = "recipes" + indexes = [ + models.Index(F("cook_time") + F("prep_time"), name="total_time_idx"), + ] +# end-multikey \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index ea41052..bc1c561 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,6 +11,7 @@ Django MongoDB Backend .. toctree:: + Model Your Data Issues & Help Compatibility @@ -19,7 +20,6 @@ Django MongoDB Backend Get Started Connection Configuration Interact with Data - Model Your Data Django Feature Limitations API Documentation <{+api+}> @@ -49,11 +49,11 @@ a Django database backend that uses PyMongo to connect to MongoDB. .. Learn how to use {+django-odm+} to perform operations on MongoDB data in the :ref:`django-interact-data` section. -.. Model Your Data -.. --------------- +Model Your Data +--------------- -.. Learn how to create Django models that represent MongoDB collections - in the :ref:`django-model-data` section. +Learn how to create Django models that represent MongoDB collections +in the :ref:`django-model-data` section. .. Django Feature Limitations .. -------------------------- diff --git a/source/model-data.txt b/source/model-data.txt new file mode 100644 index 0000000..bacd7a4 --- /dev/null +++ b/source/model-data.txt @@ -0,0 +1,25 @@ +.. _django-model-data: + +=============== +Model Your Data +=============== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use Django MongoDB Backend to model MongoDB data. + :keywords: field, query, collection, object + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Create Indexes \ No newline at end of file diff --git a/source/model-data/indexes.txt b/source/model-data/indexes.txt new file mode 100644 index 0000000..0877d76 --- /dev/null +++ b/source/model-data/indexes.txt @@ -0,0 +1,319 @@ +.. _django-indexes: + +============== +Create Indexes +============== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: query, optimization, efficiency + +Overview +-------- + +In this guide, you can learn how to create MongoDB **indexes** by using your +Django models. Indexes can improve the efficiency of queries and add +additional functionality to querying and storing documents. + +Without indexes, MongoDB must scan every document in a collection to find the +documents that match each query. These collection scans are +slow and can negatively affect the performance of your application. However, if an +appropriate index exists for a query, MongoDB can use the index to limit the +documents it must inspect. + +Django provides the ``Index`` class, which you can use to create an +index on your model. {+django-odm+} creates the same index on your +MongoDB collection that the model represents. + +.. tip:: + + To learn more about the ``Index`` class, see `Model index reference + <{+django-docs+}/ref/models/indexes/>`__ in the Django + documentation. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``Recipe`` model, which contains an +embedded ``Nutrition`` model as the value of its ``nutrition`` field. +These model classes have the following definitions: + +.. literalinclude:: /includes/interact-data/specify-a-query.py + :start-after: start-models + :end-before: end-models + :language: python + :copyable: + +The ``db_table = "recipes"`` option instructs {+django-odm+} to map the ``Recipe`` +model to a MongoDB collection called ``recipes``. To learn how to +create a Django application that uses models to interact with MongoDB +collections, visit the :ref:`django-get-started` tutorial. + +Create an Index +--------------- + +To create an index on your model, specify the ``indexes`` option +in your model's ``Meta`` class. Set the value of this ``indexes`` option +to a list of the indexes you want to create, as shown in the following +code: + +.. code-block:: python + :copyable: false + + class Meta: + indexes = [ + models.Index(), + models.Index(), + # add more indexes here + ] + +To define your index, pass the following arguments to the ``Index()`` method: + +- ``expressions``: Specifies a database expression to index. If you don't pass + the ``fields`` argument, this argument is required. To learn more about this + argument, see the :ref:`django-indexes-expressions` section of this guide. + +- ``fields``: Specifies a list of fields to index. If you don't pass the + ``expressions`` argument, this argument is required. + +- ``name``: Specifies the index name. This argument is optional, and Django + automatically creates an index name if you don't provide one. + +- ``condition``: Specifies a subset of documents to index. This argument is + optional. To learn more about the ``condition`` argument, see the :ref:`django-indexes-partial` + section of this guide. + +After you apply your database migrations, {+django-odm+} creates the +same indexes on the MongoDB collection. + +.. tip:: + + To learn how to create and apply database migrations, see `Migrations + <{+django-docs+}/topics/migrations/>`__ in the Django documentation. + +This section shows how to create the following index types: + +- :ref:`Single field ` +- :ref:`Compound ` +- :ref:`Multikey ` +- :ref:`Embedded document ` + +.. _django-indexes-single-field: + +Single Field Index +~~~~~~~~~~~~~~~~~~ + +Single field indexes store information from a single field in a collection. +By default, all MongoDB collections have an index on the ``_id`` field. + +The following example updates the ``Recipe`` model's ``Meta`` class to create +a single field index on the ``title`` field, which {+django-odm+} creates +on the ``recipes`` collection: + +.. literalinclude:: /includes/model-data/indexes.py + :start-after: start-single-field-meta + :end-before: end-single-field-meta + :language: python + :copyable: + :emphasize-lines: 3-5 + +Alternatively, you can set the ``db_index`` option on your model's ``title`` field +to create the index, as shown in the following code: + +.. literalinclude:: /includes/model-data/indexes.py + :start-after: start-single-field-option + :end-before: end-single-field-option + :language: python + :copyable: + +.. _django-indexes-compound: + +Compound Index +~~~~~~~~~~~~~~ + +Compound indexes collect and sort data from multiple fields in a collection. +MongoDB groups data by the first field specified in the index, and then by +each subsequent field. + +The following example updates the ``Recipe`` model's ``Meta`` class to create +a compound index on the ``title`` and ``cook_time`` fields, which {+django-odm+} creates +on the ``recipes`` collection: + +.. literalinclude:: /includes/model-data/indexes.py + :start-after: start-compound + :end-before: end-compound + :language: python + :copyable: + :emphasize-lines: 3-5 + +.. _django-indexes-multikey: + +Multikey Index +~~~~~~~~~~~~~~ + +Multikey indexes collect and sort data from array fields. When you create an index on an +array field, MongoDB automatically sets that index as a multikey index. + +The following example updates the ``Recipe`` model's ``Meta`` class to create +a compound index on the ``allergens`` array field, which {+django-odm+} creates +on the ``recipes`` collection: + +.. literalinclude:: /includes/model-data/indexes.py + :start-after: start-multikey + :end-before: end-multikey + :language: python + :copyable: + :emphasize-lines: 3-5 + +.. _django-indexes-embedded: + +Embedded Document Index +~~~~~~~~~~~~~~~~~~~~~~~ + +You can create indexes on fields that store embedded model values, +which MongoDB represents as embedded documents. These indexes are only +used in queries that specify the entire embedded document. Queries +on a specific field within the embedded document do not use the index. + +The following example updates the ``Recipe`` model's ``Meta`` class to create +an index on the ``nutrition`` embedded model field, which {+django-odm+} creates +on the ``recipes`` collection: + +.. literalinclude:: /includes/model-data/indexes.py + :start-after: start-multikey + :end-before: end-multikey + :language: python + :copyable: + :emphasize-lines: 3-5 + +Advanced Index Configuration +---------------------------- + +.. _django-indexes-partial: + +Partial Indexes +~~~~~~~~~~~~~~~ + +Partial indexes index only the documents in a collection that meet specified +filter condition, which reduces storage use and performance costs. + +To create a partial index, pass the ``condition`` argument to the ``models.Index()`` +method. Set the condition value to a ``Q`` object that includes the filter +criteria. When using the ``condition`` argument, you must also pass the ``name`` +argument to ``models.Index()``. + +.. tip:: + + To learn more about ``Q`` objects, see `Complex lookups with Q objects + <{+django-docs+}/topics/db/queries/#complex-lookups-with-q-objects>`__ + in the Django documentation. + +The following example updates the ``Recipe`` model's ``Meta`` class to create +a partial index on the ``cuisine`` field, instructing {+django-odm+} to +only index documents that have a ``cook_time`` value less than ``30``: + +.. literalinclude:: /includes/model-data/indexes.py + :start-after: start-partial + :end-before: end-partial + :language: python + :copyable: + :emphasize-lines: 3-5 + +.. _django-indexes-unique: + +Unique Indexes +~~~~~~~~~~~~~~ + +Unique indexes allow you to prevent indexed fields from storing duplicate values. +On a single field, unique indexes ensure that a value appears at most once for +the specified field. On multiple fields, unique indexes ensure that any given +combination of the index key values appears at most once. + +Single Field Example +```````````````````` + +The following example updates the ``Recipe`` model's ``cuisine`` field, +setting the ``unique`` option to ``True`` to create a unique single field index: + +.. literalinclude:: /includes/model-data/indexes.py + :start-after: start-unique-single + :end-before: end-unique-single + :language: python + :copyable: + +.. note:: + + Setting the ``unique`` option to ``True`` automatically creates + an index on the given field. + +Compound Example +```````````````` + +The following example updates the ``Recipe`` model's ``Meta`` class to create +a compound index on the ``title`` and ``cuisine`` fields. Then, the code +sets the ``constraints`` option to a ``UniqueConstraint`` instance, which +creates a unique compound index on these fields: + +.. literalinclude:: /includes/model-data/indexes.py + :start-after: start-unique-compound + :end-before: end-unique-compound + :language: python + :copyable: + +.. tip:: + + To learn more about the ``Meta`` class's ``constraint`` option, see `Constraints + <{+django-docs+}/ref/models/constraints/>`__ in the Django documentation. + +.. _django-indexes-expressions: + +Index Expressions +~~~~~~~~~~~~~~~~~ + +To create indexes on expressions and database functions, pass the +``expressions`` argument to the ``models.Index()`` method. When using +the ``expressions`` argument, you must also pass the ``name`` +argument to ``models.Index()``. + +The following example updates the ``Recipe`` model's ``Meta`` class to create +an index on the sum of the ``cook_time`` and ``prep_time`` values: + +.. literalinclude:: /includes/model-data/indexes.py + :start-after: start-partial + :end-before: end-partial + :language: python + :copyable: + :emphasize-lines: 3-5 + +.. tip:: + + The preceding example uses ``F`` objects to create a database + function. To learn more about ``F`` objects, see `F() expressions + <{+django-docs+}/ref/models/expressions/#f-expressions>`__ in the Django + documentation. + +Additional Information +---------------------- + +To learn more about the index types mentioned in this guide, +see the following {+mdb-server+} manual resources: + +- :manual:`Single Field Indexes ` +- :manual:`Compound Indexes ` +- :manual:`Multikey Indexes ` +- :manual:`Embedded Document Indexes ` +- :manual:`Partial Indexes ` +- :manual:`Unique Indexes ` + +To learn more about creating indexes on Django models, see +`Model index reference <{+django-docs+}/ref/models/indexes/>`__ in the Django +documentation. From 4e6ee50582052806de88101a590718bf0dc96913 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 16 Jan 2025 19:37:20 -0500 Subject: [PATCH 2/8] edits --- source/model-data/indexes.txt | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/source/model-data/indexes.txt b/source/model-data/indexes.txt index 0877d76..d183847 100644 --- a/source/model-data/indexes.txt +++ b/source/model-data/indexes.txt @@ -198,6 +198,13 @@ on the ``recipes`` collection: Advanced Index Configuration ---------------------------- +This section shows how to create the following advanced +index types: + +- :ref:`django-indexes-partial` +- :ref:`django-indexes-unique` +- :ref:`django-indexes-functions` + .. _django-indexes-partial: Partial Indexes @@ -274,10 +281,10 @@ creates a unique compound index on these fields: To learn more about the ``Meta`` class's ``constraint`` option, see `Constraints <{+django-docs+}/ref/models/constraints/>`__ in the Django documentation. -.. _django-indexes-expressions: +.. _django-indexes-functions: -Index Expressions -~~~~~~~~~~~~~~~~~ +Function Indexes +~~~~~~~~~~~~~~~~ To create indexes on expressions and database functions, pass the ``expressions`` argument to the ``models.Index()`` method. When using From ea6b1b3801ea90ede4d50a580f23b2a4d43dd8c7 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 16 Jan 2025 19:47:44 -0500 Subject: [PATCH 3/8] fixes --- source/includes/model-data/indexes.py | 13 +++++++------ source/model-data/indexes.txt | 27 ++++++++++++++------------- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/source/includes/model-data/indexes.py b/source/includes/model-data/indexes.py index bcac5ca..9291ac4 100644 --- a/source/includes/model-data/indexes.py +++ b/source/includes/model-data/indexes.py @@ -5,7 +5,6 @@ class Nutrition(models.Model): calories = models.IntegerField(default=0) - fat_grams = models.IntegerField(default=0) carb_grams = models.IntegerField(default=0) protein_grams = models.IntegerField(default=0) @@ -71,7 +70,7 @@ class Meta: # end-partial # start-unique-single -title = models.CharField(max_length=200, unique=True) +cuisine = models.CharField(max_length=200, unique=True) # end-unique-single # start-unique-compound @@ -81,14 +80,16 @@ class Meta: models.Index(fields=["title", "cuisine"]), ] constraints = [ - models.UniqueConstraint(fields=["title", "cuisine"], name="unique_regional_meal") + models.UniqueConstraint(fields=["title", "cuisine"], + name="unique_regional_meal"), ] # end-unique-compound -# start-multikey +# start-expression class Meta: db_table = "recipes" indexes = [ - models.Index(F("cook_time") + F("prep_time"), name="total_time_idx"), + models.Index(F("cook_time") + F("prep_time"), + name="total_time_idx"), ] -# end-multikey \ No newline at end of file +# end-expression \ No newline at end of file diff --git a/source/model-data/indexes.txt b/source/model-data/indexes.txt index d183847..bac83df 100644 --- a/source/model-data/indexes.txt +++ b/source/model-data/indexes.txt @@ -22,13 +22,13 @@ Overview In this guide, you can learn how to create MongoDB **indexes** by using your Django models. Indexes can improve the efficiency of queries and add -additional functionality to querying and storing documents. +additional query and document storage functionality. Without indexes, MongoDB must scan every document in a collection to find the documents that match each query. These collection scans are slow and can negatively affect the performance of your application. However, if an appropriate index exists for a query, MongoDB can use the index to limit the -documents it must inspect. +documents it inspects. Django provides the ``Index`` class, which you can use to create an index on your model. {+django-odm+} creates the same index on your @@ -47,7 +47,7 @@ The examples in this guide use the ``Recipe`` model, which contains an embedded ``Nutrition`` model as the value of its ``nutrition`` field. These model classes have the following definitions: -.. literalinclude:: /includes/interact-data/specify-a-query.py +.. literalinclude:: /includes/model-data/indexes.py :start-after: start-models :end-before: end-models :language: python @@ -76,11 +76,11 @@ code: # add more indexes here ] -To define your index, pass the following arguments to the ``Index()`` method: +To define your index, pass the following arguments to the ``models.Index()`` method: - ``expressions``: Specifies a database expression to index. If you don't pass the ``fields`` argument, this argument is required. To learn more about this - argument, see the :ref:`django-indexes-expressions` section of this guide. + argument, see the :ref:`django-indexes-functions` section of this guide. - ``fields``: Specifies a list of fields to index. If you don't pass the ``expressions`` argument, this argument is required. @@ -189,8 +189,8 @@ an index on the ``nutrition`` embedded model field, which {+django-odm+} creates on the ``recipes`` collection: .. literalinclude:: /includes/model-data/indexes.py - :start-after: start-multikey - :end-before: end-multikey + :start-after: start-embedded + :end-before: end-embedded :language: python :copyable: :emphasize-lines: 3-5 @@ -211,7 +211,7 @@ Partial Indexes ~~~~~~~~~~~~~~~ Partial indexes index only the documents in a collection that meet specified -filter condition, which reduces storage use and performance costs. +filter criteria, which reduces storage use and performance costs. To create a partial index, pass the ``condition`` argument to the ``models.Index()`` method. Set the condition value to a ``Q`` object that includes the filter @@ -233,7 +233,7 @@ only index documents that have a ``cook_time`` value less than ``30``: :end-before: end-partial :language: python :copyable: - :emphasize-lines: 3-5 + :emphasize-lines: 3-7 .. _django-indexes-unique: @@ -275,6 +275,7 @@ creates a unique compound index on these fields: :end-before: end-unique-compound :language: python :copyable: + :emphasize-lines: 6-8 .. tip:: @@ -295,11 +296,11 @@ The following example updates the ``Recipe`` model's ``Meta`` class to create an index on the sum of the ``cook_time`` and ``prep_time`` values: .. literalinclude:: /includes/model-data/indexes.py - :start-after: start-partial - :end-before: end-partial + :start-after: start-expression + :end-before: end-expression :language: python :copyable: - :emphasize-lines: 3-5 + :emphasize-lines: 3-7 .. tip:: @@ -315,7 +316,7 @@ To learn more about the index types mentioned in this guide, see the following {+mdb-server+} manual resources: - :manual:`Single Field Indexes ` -- :manual:`Compound Indexes ` +- :manual:`Compound Indexes ` - :manual:`Multikey Indexes ` - :manual:`Embedded Document Indexes ` - :manual:`Partial Indexes ` From d746448fc17b821dd28e5e6bc1538054c21432bd Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 17 Jan 2025 10:00:27 -0500 Subject: [PATCH 4/8] clarify --- source/includes/model-data/indexes.py | 5 +--- source/model-data/indexes.txt | 35 +++++++++++++++------------ 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/source/includes/model-data/indexes.py b/source/includes/model-data/indexes.py index 9291ac4..695bcc6 100644 --- a/source/includes/model-data/indexes.py +++ b/source/includes/model-data/indexes.py @@ -76,9 +76,6 @@ class Meta: # start-unique-compound class Meta: db_table = "recipes" - indexes = [ - models.Index(fields=["title", "cuisine"]), - ] constraints = [ models.UniqueConstraint(fields=["title", "cuisine"], name="unique_regional_meal"), @@ -89,7 +86,7 @@ class Meta: class Meta: db_table = "recipes" indexes = [ - models.Index(F("cook_time") + F("prep_time"), + models.Index(expressions=F("cook_time") + F("prep_time"), name="total_time_idx"), ] # end-expression \ No newline at end of file diff --git a/source/model-data/indexes.txt b/source/model-data/indexes.txt index bac83df..89face0 100644 --- a/source/model-data/indexes.txt +++ b/source/model-data/indexes.txt @@ -21,12 +21,12 @@ Overview -------- In this guide, you can learn how to create MongoDB **indexes** by using your -Django models. Indexes can improve the efficiency of queries and add +Django models. Indexes can improve the efficiency of queries and provide additional query and document storage functionality. Without indexes, MongoDB must scan every document in a collection to find the -documents that match each query. These collection scans are -slow and can negatively affect the performance of your application. However, if an +documents that match a query. These collection scans are slow and can +negatively affect the performance of your application. However, if an appropriate index exists for a query, MongoDB can use the index to limit the documents it inspects. @@ -53,10 +53,11 @@ These model classes have the following definitions: :language: python :copyable: -The ``db_table = "recipes"`` option instructs {+django-odm+} to map the ``Recipe`` -model to a MongoDB collection called ``recipes``. To learn how to -create a Django application that uses models to interact with MongoDB -collections, visit the :ref:`django-get-started` tutorial. +In the ``Recipe`` model's ``Meta`` class, the ``db_table = "recipes"`` option +instructs {+django-odm+} to map the ``Recipe`` model to a MongoDB collection +called ``recipes``. To learn how to create a Django application that +uses models to interact with MongoDB collections, visit the +:ref:`django-get-started` tutorial. Create an Index --------------- @@ -80,7 +81,7 @@ To define your index, pass the following arguments to the ``models.Index()`` met - ``expressions``: Specifies a database expression to index. If you don't pass the ``fields`` argument, this argument is required. To learn more about this - argument, see the :ref:`django-indexes-functions` section of this guide. + argument, see the :ref:`django-indexes-expressions` section of this guide. - ``fields``: Specifies a list of fields to index. If you don't pass the ``expressions`` argument, this argument is required. @@ -203,7 +204,7 @@ index types: - :ref:`django-indexes-partial` - :ref:`django-indexes-unique` -- :ref:`django-indexes-functions` +- :ref:`django-indexes-expressions` .. _django-indexes-partial: @@ -266,7 +267,7 @@ Compound Example ```````````````` The following example updates the ``Recipe`` model's ``Meta`` class to create -a compound index on the ``title`` and ``cuisine`` fields. Then, the code +a compound index on the ``title`` and ``cuisine`` fields. The code sets the ``constraints`` option to a ``UniqueConstraint`` instance, which creates a unique compound index on these fields: @@ -275,17 +276,19 @@ creates a unique compound index on these fields: :end-before: end-unique-compound :language: python :copyable: - :emphasize-lines: 6-8 + :emphasize-lines: 3-6 .. tip:: - To learn more about the ``Meta`` class's ``constraint`` option, see `Constraints - <{+django-docs+}/ref/models/constraints/>`__ in the Django documentation. + Setting the ``constraints`` option to a ``UniqueConstraint`` automatically + creates an index on the specified fields. To learn more about the ``Meta`` + class's ``constraint`` option, see `Constraints <{+django-docs+}/ref/models/constraints/>`__ + in the Django documentation. -.. _django-indexes-functions: +.. _django-indexes-expressions: -Function Indexes -~~~~~~~~~~~~~~~~ +Expression Indexes +~~~~~~~~~~~~~~~~~~ To create indexes on expressions and database functions, pass the ``expressions`` argument to the ``models.Index()`` method. When using From 6c8d010bda1216210ca7d88e750838f8133f4e48 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 22 Jan 2025 12:58:09 -0500 Subject: [PATCH 5/8] remove expression indexes --- source/model-data/indexes.txt | 35 +---------------------------------- 1 file changed, 1 insertion(+), 34 deletions(-) diff --git a/source/model-data/indexes.txt b/source/model-data/indexes.txt index 89face0..c154a69 100644 --- a/source/model-data/indexes.txt +++ b/source/model-data/indexes.txt @@ -79,12 +79,7 @@ code: To define your index, pass the following arguments to the ``models.Index()`` method: -- ``expressions``: Specifies a database expression to index. If you don't pass - the ``fields`` argument, this argument is required. To learn more about this - argument, see the :ref:`django-indexes-expressions` section of this guide. - -- ``fields``: Specifies a list of fields to index. If you don't pass the - ``expressions`` argument, this argument is required. +- ``fields``: Specifies a list of fields to index. This argument is required. - ``name``: Specifies the index name. This argument is optional, and Django automatically creates an index name if you don't provide one. @@ -204,7 +199,6 @@ index types: - :ref:`django-indexes-partial` - :ref:`django-indexes-unique` -- :ref:`django-indexes-expressions` .. _django-indexes-partial: @@ -285,33 +279,6 @@ creates a unique compound index on these fields: class's ``constraint`` option, see `Constraints <{+django-docs+}/ref/models/constraints/>`__ in the Django documentation. -.. _django-indexes-expressions: - -Expression Indexes -~~~~~~~~~~~~~~~~~~ - -To create indexes on expressions and database functions, pass the -``expressions`` argument to the ``models.Index()`` method. When using -the ``expressions`` argument, you must also pass the ``name`` -argument to ``models.Index()``. - -The following example updates the ``Recipe`` model's ``Meta`` class to create -an index on the sum of the ``cook_time`` and ``prep_time`` values: - -.. literalinclude:: /includes/model-data/indexes.py - :start-after: start-expression - :end-before: end-expression - :language: python - :copyable: - :emphasize-lines: 3-7 - -.. tip:: - - The preceding example uses ``F`` objects to create a database - function. To learn more about ``F`` objects, see `F() expressions - <{+django-docs+}/ref/models/expressions/#f-expressions>`__ in the Django - documentation. - Additional Information ---------------------- From e149273c128d9bc1f1bbf067ee17c4ecd6a76db2 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 23 Jan 2025 09:52:56 -0500 Subject: [PATCH 6/8] embeddedmodel --- source/includes/model-data/indexes.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/includes/model-data/indexes.py b/source/includes/model-data/indexes.py index 695bcc6..643bc63 100644 --- a/source/includes/model-data/indexes.py +++ b/source/includes/model-data/indexes.py @@ -1,9 +1,10 @@ # start-models from django.db import models from django.db.models import Q, F +from django_mongodb_backend.models import EmbeddedModel from django_mongodb_backend.fields import EmbeddedModelField, ArrayField -class Nutrition(models.Model): +class Nutrition(EmbeddedModel): calories = models.IntegerField(default=0) carb_grams = models.IntegerField(default=0) protein_grams = models.IntegerField(default=0) From 13bcdd1078b6c58e478be726473e6fdf508a0baf Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 23 Jan 2025 11:18:57 -0500 Subject: [PATCH 7/8] embedded doc note --- source/model-data/indexes.txt | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/source/model-data/indexes.txt b/source/model-data/indexes.txt index c154a69..2cb3752 100644 --- a/source/model-data/indexes.txt +++ b/source/model-data/indexes.txt @@ -176,9 +176,7 @@ Embedded Document Index ~~~~~~~~~~~~~~~~~~~~~~~ You can create indexes on fields that store embedded model values, -which MongoDB represents as embedded documents. These indexes are only -used in queries that specify the entire embedded document. Queries -on a specific field within the embedded document do not use the index. +which MongoDB represents as embedded documents. The following example updates the ``Recipe`` model's ``Meta`` class to create an index on the ``nutrition`` embedded model field, which {+django-odm+} creates @@ -191,6 +189,14 @@ on the ``recipes`` collection: :copyable: :emphasize-lines: 3-5 +.. important:: + + The index created in the preceding example is only used in queries that + specify the entire embedded document. Queries on a specific field within + the embedded document do not use the index. However, you can index + fields within the embedded document by adding an inner ``Meta`` class + to the ``Nutrition`` model and specifying the ``indexes`` option. + Advanced Index Configuration ---------------------------- From abf9be54711edb2343d51d5bea8ea75cc58253b5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 23 Jan 2025 14:00:19 -0500 Subject: [PATCH 8/8] MM feedback --- source/includes/model-data/indexes.py | 15 +++------------ source/model-data/indexes.txt | 2 +- 2 files changed, 4 insertions(+), 13 deletions(-) diff --git a/source/includes/model-data/indexes.py b/source/includes/model-data/indexes.py index 643bc63..70194b2 100644 --- a/source/includes/model-data/indexes.py +++ b/source/includes/model-data/indexes.py @@ -13,7 +13,6 @@ class Recipe(models.Model): title = models.CharField(max_length=200) cuisine = models.CharField(max_length=200) cook_time = models.IntegerField(default=0) - prep_time = models.IntegerField(default=0) allergens = ArrayField(models.CharField(max_length=100), null=True, blank=True) nutrition = EmbeddedModelField(Nutrition, null=True, blank=True) @@ -33,7 +32,8 @@ class Meta: # end-single-field-meta # start-single-field-option -title = models.CharField(max_length=200, db_index=True) +class Recipe(models.Model): + title = models.CharField(max_length=200, db_index=True) # end-single-field-option # start-compound @@ -81,13 +81,4 @@ class Meta: models.UniqueConstraint(fields=["title", "cuisine"], name="unique_regional_meal"), ] -# end-unique-compound - -# start-expression -class Meta: - db_table = "recipes" - indexes = [ - models.Index(expressions=F("cook_time") + F("prep_time"), - name="total_time_idx"), - ] -# end-expression \ No newline at end of file +# end-unique-compound \ No newline at end of file diff --git a/source/model-data/indexes.txt b/source/model-data/indexes.txt index 2cb3752..d4ea144 100644 --- a/source/model-data/indexes.txt +++ b/source/model-data/indexes.txt @@ -294,7 +294,7 @@ see the following {+mdb-server+} manual resources: - :manual:`Single Field Indexes ` - :manual:`Compound Indexes ` - :manual:`Multikey Indexes ` -- :manual:`Embedded Document Indexes ` +- :manual:`Embedded Document Indexes ` - :manual:`Partial Indexes ` - :manual:`Unique Indexes `