From 84a87578a7235a3960e575087576286165883d80 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 17 Jan 2025 18:46:45 -0500 Subject: [PATCH 01/12] DOCSP-46325: Models --- snooty.toml | 1 + source/includes/model-data/models.py | 28 +++ source/model-data.txt | 25 +++ source/model-data/models.txt | 258 +++++++++++++++++++++++++++ 4 files changed, 312 insertions(+) create mode 100644 source/includes/model-data/models.py create mode 100644 source/model-data.txt create mode 100644 source/model-data/models.txt diff --git a/snooty.toml b/snooty.toml index 25222d6..fdf69ab 100644 --- a/snooty.toml +++ b/snooty.toml @@ -13,3 +13,4 @@ api = "https://django-mongodb.readthedocs.io/en/latest/" mdb-server = "MongoDB Server" django-version = "5.0" django-docs = "https://docs.djangoproject.com/en/{+django-version+}" +framework = "Django" diff --git a/source/includes/model-data/models.py b/source/includes/model-data/models.py new file mode 100644 index 0000000..7913bcc --- /dev/null +++ b/source/includes/model-data/models.py @@ -0,0 +1,28 @@ +# start-models +from django.db import models +from django_mongodb_backend.fields import EmbeddedModelField, ArrayField + +class Award(models.Model): + wins = models.IntegerField(default=0) + nominations = models.IntegerField(default=0) + text = models.CharField(max_length=100) + + class Meta: + managed = False + +class Movie(models.Model): + title = models.CharField(max_length=200) + plot = models.TextField(blank=True) + runtime = models.IntegerField(default=0) + released = models.DateTimeField("release date", null=True, blank=True) + awards = EmbeddedModelField(Award) + genres = ArrayField(models.CharField(max_length=100), null=True, blank=True) + imdb = models.JSONField(null=True) + + class Meta: + db_table = "movies" + managed = False + + def __str__(self): + return self.title +# end-models \ No newline at end of file diff --git a/source/model-data.txt b/source/model-data.txt new file mode 100644 index 0000000..cdd9221 --- /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 Models \ No newline at end of file diff --git a/source/model-data/models.txt b/source/model-data/models.txt new file mode 100644 index 0000000..8560a20 --- /dev/null +++ b/source/model-data/models.txt @@ -0,0 +1,258 @@ +.. _django-models: + +============= +Create Models +============= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: class, field, code example + +Overview +-------- + +In this guide, you can learn how to create {+framework+} **models** that +represent MongoDB collections. Models are Python classes that define +the structure of your data. When using {+django-odm+}, you can +map each model to a MongoDB collection and interact with the collection's +documents by using model objects. + +.. tip:: + + To learn more about {+framework+} models, see `Models + <{+django-docs+}/topics/db/models/>`__ in the {+framework+} + documentation. + +.. _django-models-define: + +Define a Model +-------------- + +To create an model that represents a MongoDB collection, add your model +class definitions to your application's ``models.py`` file. In your model +class, specify the fields you want to store and include any model metadata +in an inner ``Meta`` class. You can also use the ``__str__()`` method to +define a string representation of your model. Use the following syntax to +define a model: + +.. code-block:: python + + class (models.Model): + = + # Include additional fields here + + class Meta: + # Include metadata here + + def __str__(self): + # Include logic for displaying your model as a string here + +To use your models, you must add them to your project's +``settings.py`` file. Edit the ``INSTALLED_APPS`` value to include +the name of the module that stores your ``models.py`` file, as shown +in the following code: + +.. code-block:: python + + INSTALLED_APPS = [ + '', + # Include other app modules here + ] + +Finally, run the following database migration commands from your +project's root directory to create MongoDB collections for your +models or use existing collections to store model data: + +.. code-block:: bash + + python manage.py makemigrations + python manage.py migrate + +Example +``````` + +This sample ``models.py`` file defines ``Movie`` and ``Award`` +models. The ``Movie`` class includes the following information: + +- List of fields that represent movie data, including + an ``awards`` field that stores an embedded ``Award`` model. + +- ``Meta`` class that sets the ``db_table`` option + to ``movies``. This instructs {+django-odm+} to use this model + to represent the ``sample_mflix.movies`` collection from the + :atlas:`Atlas sample datasets `. + + The ``Meta`` class also sets the ``managed`` option to ``False``, + instructing {+django-odm+} not to create a new collection + for the model. + +- ``__str__()`` method that defines the model's string + representation as its ``title`` field value. + +The ``Award`` model stores data for the ``Movie`` model's +``awards`` field. Its class includes the following information: + +- List of fields that represent movie award data. + +- ``Meta`` class that sets the ``managed`` option to ``False``. + This instructs {+django-odm+} not to create a new collection + for the model. + +.. literalinclude:: /includes/model-data/models.py + :start-after: start-models + :end-before: end-models + :language: python + :copyable: + +.. tip:: + + To learn more about the field types used in the model + class definitions, see the following :ref:`django-models-fields` + section of this guide. + +.. _django-models-fields: + +Supported Field Types +--------------------- + +This section describes {+django-odm+}'s support for +the following field types: + +- :ref:`django-models-django-fields` +- :ref:`django-models-mongodb-fields` + +.. _django-models-django-fields: + +{+framework+} Fields +~~~~~~~~~~~~~~~~~~~~ + +The following table describes the {+framework+} model fields +that {+django-odm+} supports: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Field Type + - Description + + * - ``AutoField`` + - | Stores ``IntegerField`` values that automatically increment according to + available ID values. If you don't explicitly specify this field, + MongoDB automatically assigns an ``ObjectId`` primary key value. + + * - ``BigAutoField`` + - | Stores ``AutoField`` values up to 64 bits in size. + + * - ``BigIntegerField`` + - | Stores ``IntegerField`` values up to 64 bits in size. + + * - ``BinaryField`` + - | Stores raw binary data. + + * - ``BooleanField`` + - | Stores boolean (``True`` or ``False``) values. + + * - ``CharField`` + - | Stores string values. To store longer text values, use + ``TextField``. + + * - ``DateField`` + - | Stores date values in Python ``datetime.date`` instances. + + * - ``DateTimeField`` + - | Stores date and time values in Python ``datetime.datetime`` + instances. + + * - ``DecimalField`` + - | Stores decimal values. + + * - ``DurationField`` + - | Stores values representing periods of time in + Python ``timedelta`` instances. + + * - ``EmailField`` + - | Stores ``CharField`` values and uses an `EmailValidator + <{+django-docs+}/ref/validators/#django.core.validators.EmailValidator>`__ + to verify that the value is an email address. + + * - ``FileField`` + - | Stores file values. + + * - ``FilePathField`` + - | Stores ``CharField`` values that represent filenames on your filesystem. + + * - ``FloatField`` + - | Stores float values. + + * - ``GenericIPAddressField`` + - | Stores an Pv4 or IPv6 address in string format. + + * - ``IntegerField`` + - | Stores integer values. + + * - ``JSONField`` + - | Stores JSON data. To learn more about this field, see the + :ref:`django-models-json` section in this guide. + + * - ``PositiveBigIntegerField`` + - | Stores positive integer values up to 64 bits in size. + + * - ``PositiveIntegerField`` + - | Stores positive integer values up to 32 bits in size. + + * - ``PositiveSmallIntegerField`` + - | Stores positive integer values up to 16 bits in size. + + * - ``SlugField`` + - | Stores a short text label, often for URL values. + + * - ``SmallIntegerField`` + - | Stores integer values up to 16 bits in size. + + * - ``TextField`` + - | Stores large text values. + + * - ``URLField`` + - | Stores a ``CharField`` value representing a URL. + + * - ``UUIDField`` + - | Stores instances of Python's ``UUID`` class. + +.. _django-models-json: + +Use a JSONField +``````````````` + +.. _django-models-mongodb-fields: + +MongoDB Fields +~~~~~~~~~~~~~~ + +The following table describes field types specific to +{+django-odm+} that you can use in your models: + +Use an ArrayField +````````````````` + +Use an EmbeddedModelField +````````````````````````` + +Additional Information +---------------------- + +To learn how to use your models to run database operations, +see the :ref:`interact-data` guides. + +To learn more about {+framework+} field types, see `Model index reference +<{+django-docs+}/ref/models/fields/>`__ in the {+framework+} +documentation. \ No newline at end of file From cb862c5b30d7fb01e9728699df348ef4f68c0cd2 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 21 Jan 2025 15:30:23 -0500 Subject: [PATCH 02/12] edits --- source/includes/model-data/models.py | 48 +++++++- source/model-data/models.txt | 161 ++++++++++++++++++++++++--- 2 files changed, 186 insertions(+), 23 deletions(-) diff --git a/source/includes/model-data/models.py b/source/includes/model-data/models.py index 7913bcc..3976b90 100644 --- a/source/includes/model-data/models.py +++ b/source/includes/model-data/models.py @@ -1,6 +1,46 @@ # start-models from django.db import models -from django_mongodb_backend.fields import EmbeddedModelField, ArrayField + +class Movie(models.Model): + title = models.CharField(max_length=200) + plot = models.TextField(blank=True) + runtime = models.IntegerField(default=0) + released = models.DateTimeField("release date", null=True, blank=True) + + class Meta: + db_table = "movies" + managed = False + + def __str__(self): + return self.title +# end-models + +# start-array-field +from django.db import models +from django_mongodb_backend.fields import ArrayField + +class Movie(models.Model): + title = models.CharField(max_length=200) + plot = models.TextField(blank=True) + runtime = models.IntegerField(default=0) + released = models.DateTimeField("release date", null=True, blank=True) + genres = ArrayField( + models.CharField(max_length=100), + size=5, + null=True, + blank=True) + + class Meta: + db_table = "movies" + managed = False + + def __str__(self): + return self.title +# end-array-field + +# start-embedded-field +from django.db import models +from django_mongodb_backend.fields import EmbeddedModelField class Award(models.Model): wins = models.IntegerField(default=0) @@ -15,9 +55,7 @@ class Movie(models.Model): plot = models.TextField(blank=True) runtime = models.IntegerField(default=0) released = models.DateTimeField("release date", null=True, blank=True) - awards = EmbeddedModelField(Award) - genres = ArrayField(models.CharField(max_length=100), null=True, blank=True) - imdb = models.JSONField(null=True) + awards = EmbeddedModelField(Award, null=True, blank=True) class Meta: db_table = "movies" @@ -25,4 +63,4 @@ class Meta: def __str__(self): return self.title -# end-models \ No newline at end of file +# end-embedded-field \ No newline at end of file diff --git a/source/model-data/models.txt b/source/model-data/models.txt index 8560a20..0515855 100644 --- a/source/model-data/models.txt +++ b/source/model-data/models.txt @@ -77,14 +77,15 @@ models or use existing collections to store model data: python manage.py makemigrations python manage.py migrate +.. _django-models-define-ex: + Example ``````` -This sample ``models.py`` file defines ``Movie`` and ``Award`` -models. The ``Movie`` class includes the following information: +This sample ``models.py`` file defines a ``Movie`` model +class that includes the following information: -- List of fields that represent movie data, including - an ``awards`` field that stores an embedded ``Award`` model. +- List of fields that represent movie data. - ``Meta`` class that sets the ``db_table`` option to ``movies``. This instructs {+django-odm+} to use this model @@ -98,15 +99,6 @@ models. The ``Movie`` class includes the following information: - ``__str__()`` method that defines the model's string representation as its ``title`` field value. -The ``Award`` model stores data for the ``Movie`` model's -``awards`` field. Its class includes the following information: - -- List of fields that represent movie award data. - -- ``Meta`` class that sets the ``managed`` option to ``False``. - This instructs {+django-odm+} not to create a new collection - for the model. - .. literalinclude:: /includes/model-data/models.py :start-after: start-models :end-before: end-models @@ -116,7 +108,7 @@ The ``Award`` model stores data for the ``Movie`` model's .. tip:: To learn more about the field types used in the model - class definitions, see the following :ref:`django-models-fields` + class definition, see the following :ref:`django-models-fields` section of this guide. .. _django-models-fields: @@ -235,18 +227,151 @@ Use a JSONField .. _django-models-mongodb-fields: -MongoDB Fields -~~~~~~~~~~~~~~ +MongoDB BSON Fields +~~~~~~~~~~~~~~~~~~~ + +MongoDB organizes and stores documents in a binary representation +called ``BSON`` that allows for flexible data processing. + +.. tip:: + + To learn more about how MongoDB stores BSON data, see + :manual:`BSON Types ` in the {+mdb-server+} + manual. + +The following table describes supported BSON field types and their +{+django-odm+} equivalents that you can use in your Django models: + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - BSON Field Type + - Django Field Type + - BSON Description + + * - ``Array`` + - ``ArrayField`` + - | Stores array values. To learn more about using this field + with {+django-odm+}, see the :ref:`django-models-array` section + in this guide. + + * - ``Object`` + - ``EmbeddedModelField`` + - | Stores embedded documents. To learn more about using this field + with {+django-odm+}, see the :ref:`django-models-embedded` section in this guide. + + * - ``ObjectId`` + - ``AutoField`` + - | Stores unique 12-byte identifiers that MongoDB uses as primary keys. + + * - ``Binary`` + - ``BinaryField`` + - | Stores binary data. + + * - ``Boolean`` + - ``BooleanField`` + - | Stores ``true`` or ``false`` values. + + * - ``Date`` + - ``DatetimeField`` + - | Stores dates and times in milliseconds since the Unix + epoch, or January 1, 1970. + + * - ``Decimal128`` + - ``DecimalField`` + - | Stores 28-bit decimal values. + + * - ``Double`` + - ``FloatField`` + - | Stores floating-point values. + + * - ``Int32`` + - ``IntegerField`` + - | Stores 32-bit signed integers. + + * - ``Int64`` + - ``IntegerField`` or ``BigIntegerField`` + - | Stores 64-bit signed integers. -The following table describes field types specific to -{+django-odm+} that you can use in your models: + * - ``String`` + - ``CharField`` or ``TextField`` + - | Stores UTF-8 encoded string values. + +.. _django-models-array: Use an ArrayField ````````````````` +You can use an ``ArrayField`` in your model to store a list of data. +To create an ``ArrayField``, use the ``ArrayField()`` class constructor +and pass the following arguments: + +- ``base_field``: Specifies the underlying data type of each value + stored in the array. You cannot specify ``EmbeddedModelField`` or + ``FileField`` as the base field type. + +- ``size``: Specifies the maximum size of the array. This field is + optional. + +- ``options``: Specifies Django field options. To view a list of + available options, see `Field options <{+django-docs+}/ref/models/fields/#field-options>`__ + in the {+framework+} documentation. + +The following example adds an ``ArrayField`` value to the model created in +the :ref:`Define a Model example ` in this +guide. The new field, called ``genres``, stores a list of ``CharField`` values +that represent movie genres and can store a maximum of ``5`` values: + +.. literalinclude:: /includes/model-data/models.py + :start-after: start-array-field + :end-before: end-array-field + :language: python + :copyable: + :emphasize-lines: 9-13 + +.. tip:: + + You can also store an array of array values in an ``ArrayField``. + To view an example of a multi-dimensional array, see `ArrayField + <{+django-docs+}/ref/contrib/postgres/fields/#arrayfield>`__ in the {+framework+} + PostgreSQL documentation. + +.. _django-models-embedded: + Use an EmbeddedModelField ````````````````````````` +You can use an ``EmbeddedModelField`` to represent a MongoDB ``Object``, +which stores a nested document value. This type allows one model to +store a separate model in one of its fields. To create an ``EmbeddedModelField``, use +the ``EmbeddedModelField()`` class constructor and pass the following arguments: + +- ``embedded_model``: Specifies the model class to store. + +- ``options``: Specifies Django field options. To view a list of + available options, see `Field options <{+django-docs+}/ref/models/fields/#field-options>`__ + in the {+framework+} documentation. + +.. important:: + + The ``makemigrations`` Django command does not detect changes to embedded + models. If you make changes to the embedded model's class, the model + stored in the ``EmbeddedModelField`` does not reflect the changes. + +This example adds an ``EmbeddedModelField`` value to the model created in +the :ref:`Define a Model example ` in this +guide. The new field, called ``awards``, stores an embedded ``Award`` model +as its value. The following code defines the ``Award`` model +and modifies the ``Movie`` model to include the ``EmbeddedModelField``: + +.. literalinclude:: /includes/model-data/models.py + :start-after: start-embedded-field + :end-before: end-embedded-field + :language: python + :copyable: + :emphasize-lines: 17 + Additional Information ---------------------- From 2a91d9620798223b41c8ec3e09bb20b177d69cbf Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 21 Jan 2025 16:45:56 -0500 Subject: [PATCH 03/12] more info --- source/includes/model-data/models.py | 18 ++ source/model-data/models.txt | 251 +++++++++++++++++---------- 2 files changed, 179 insertions(+), 90 deletions(-) diff --git a/source/includes/model-data/models.py b/source/includes/model-data/models.py index 3976b90..1e68ef6 100644 --- a/source/includes/model-data/models.py +++ b/source/includes/model-data/models.py @@ -15,6 +15,24 @@ def __str__(self): return self.title # end-models +# start-json-field +from django.db import models + +class Movie(models.Model): + title = models.CharField(max_length=200) + plot = models.TextField(blank=True) + runtime = models.IntegerField(default=0) + released = models.DateTimeField("release date", null=True, blank=True) + imdb = models.JSONField(null=True, blank=True) + + class Meta: + db_table = "movies" + managed = False + + def __str__(self): + return self.title +# end-json-field + # start-array-field from django.db import models from django_mongodb_backend.fields import ArrayField diff --git a/source/model-data/models.txt b/source/model-data/models.txt index 0515855..17f11a0 100644 --- a/source/model-data/models.txt +++ b/source/model-data/models.txt @@ -32,85 +32,6 @@ documents by using model objects. <{+django-docs+}/topics/db/models/>`__ in the {+framework+} documentation. -.. _django-models-define: - -Define a Model --------------- - -To create an model that represents a MongoDB collection, add your model -class definitions to your application's ``models.py`` file. In your model -class, specify the fields you want to store and include any model metadata -in an inner ``Meta`` class. You can also use the ``__str__()`` method to -define a string representation of your model. Use the following syntax to -define a model: - -.. code-block:: python - - class (models.Model): - = - # Include additional fields here - - class Meta: - # Include metadata here - - def __str__(self): - # Include logic for displaying your model as a string here - -To use your models, you must add them to your project's -``settings.py`` file. Edit the ``INSTALLED_APPS`` value to include -the name of the module that stores your ``models.py`` file, as shown -in the following code: - -.. code-block:: python - - INSTALLED_APPS = [ - '', - # Include other app modules here - ] - -Finally, run the following database migration commands from your -project's root directory to create MongoDB collections for your -models or use existing collections to store model data: - -.. code-block:: bash - - python manage.py makemigrations - python manage.py migrate - -.. _django-models-define-ex: - -Example -``````` - -This sample ``models.py`` file defines a ``Movie`` model -class that includes the following information: - -- List of fields that represent movie data. - -- ``Meta`` class that sets the ``db_table`` option - to ``movies``. This instructs {+django-odm+} to use this model - to represent the ``sample_mflix.movies`` collection from the - :atlas:`Atlas sample datasets `. - - The ``Meta`` class also sets the ``managed`` option to ``False``, - instructing {+django-odm+} not to create a new collection - for the model. - -- ``__str__()`` method that defines the model's string - representation as its ``title`` field value. - -.. literalinclude:: /includes/model-data/models.py - :start-after: start-models - :end-before: end-models - :language: python - :copyable: - -.. tip:: - - To learn more about the field types used in the model - class definition, see the following :ref:`django-models-fields` - section of this guide. - .. _django-models-fields: Supported Field Types @@ -220,11 +141,6 @@ that {+django-odm+} supports: * - ``UUIDField`` - | Stores instances of Python's ``UUID`` class. -.. _django-models-json: - -Use a JSONField -``````````````` - .. _django-models-mongodb-fields: MongoDB BSON Fields @@ -298,10 +214,149 @@ The following table describes supported BSON field types and their - ``CharField`` or ``TextField`` - | Stores UTF-8 encoded string values. +.. _django-models-define: + +Define a Model +-------------- + +To create an model that represents a MongoDB collection, add your model +class definitions to your application's ``models.py`` file. In your model +class, specify the fields you want to store and include any model metadata +in an inner ``Meta`` class. You can also use the ``__str__()`` method to +define a string representation of your model. Use the following syntax to +define a model: + +.. code-block:: python + + class (models.Model): + = + # Include additional fields here + + class Meta: + # Include metadata here + + def __str__(self): + # Include logic for displaying your model as a string here + +To use your models, you must add them to your project's +``settings.py`` file. Edit the ``INSTALLED_APPS`` value to include +the name of the module that stores your ``models.py`` file, as shown +in the following code: + +.. code-block:: python + + INSTALLED_APPS = [ + '', + # Include other app modules here + ] + +Finally, run the following database migration commands from your +project's root directory to create MongoDB collections for your +models or use existing collections to store model data: + +.. code-block:: bash + + python manage.py makemigrations + python manage.py migrate + +.. _django-models-define-ex: + +Example +``````` + +This sample ``models.py`` file defines a ``Movie`` model +class that includes the following information: + +- List of fields that represent movie data. + +- ``Meta`` class that sets the ``db_table`` option + to ``movies``. This instructs {+django-odm+} to use this model + to represent the ``sample_mflix.movies`` collection from the + :atlas:`Atlas sample datasets `. + + The ``Meta`` class also sets the ``managed`` option to ``False``, + instructing {+django-odm+} not to create a new collection + for the model. + +- ``__str__()`` method that defines the model's string + representation as its ``title`` field value. + +.. literalinclude:: /includes/model-data/models.py + :start-after: start-models + :end-before: end-models + :language: python + :copyable: + +.. tip:: + + To learn more about the field types used in the model + class definition, see the :ref:`django-models-fields` + section of this guide. + +Use Advanced Fields +------------------- + +This section how to use the following field types +in your Django models: + +- :ref:`JSONField ` +- :ref:`ArrayField ` +- :ref:`EmbeddedModelField ` + +.. _django-models-json: + +Use a JSONField +~~~~~~~~~~~~~~~ + +You can use a ``JSONField`` in your model to store JSON objects. +JSON is a human-readable format for data exchange, and JSON objects +are data containers that map string keys to values. MongoDB provides +the ``Object`` field type to store JSON data in documents and internally +stores this data in BSON, or Binary JSON, format. + +.. note:: + + You can also use an ``EmbeddedModelField`` to represent a + MongoDB ``Object``. To learn more about this field, see the + :ref:`django-models-embedded` section of this guide. + +{+django-odm+}'s support for ``JSONField`` has the following limitations: + +- If you set the field's value to ``None``, {+django-odm+} stores its value as + a SQL ``NULL`` value. Alternatively, you can set the ``JSONField`` value + to ``Value(None, JSONField())``, which represents the JSON scalar ``null``. + However, there is no way to distinguish between the SQL ``NULL`` and the JSON + ``null`` when querying. + +- Some queries that use ``Q`` objects might not return the expected results. + +- When querying for field that have a ``None`` value, {+django-odm+} incorrectly + returns documents in which the field doesn't exist. + +Example +``````` + +The following example adds a ``JSONField`` value to the model created in +the :ref:`Define a Model example ` in this +guide. The new field, called ``imdb``, stores JSON data that represents +user ratings for each ``Movie`` object: + +.. literalinclude:: /includes/model-data/models.py + :start-after: start-json-field + :end-before: end-json-field + :language: python + :copyable: + :emphasize-lines: 8 + +.. tip:: + + To learn how to query data stored in a ``JSONField``, see + :ref:`django-query-jsonfield` in the Specify a Query guide. + .. _django-models-array: Use an ArrayField -````````````````` +~~~~~~~~~~~~~~~~~ You can use an ``ArrayField`` in your model to store a list of data. To create an ``ArrayField``, use the ``ArrayField()`` class constructor @@ -318,6 +373,16 @@ and pass the following arguments: available options, see `Field options <{+django-docs+}/ref/models/fields/#field-options>`__ in the {+framework+} documentation. +.. tip:: + + You can store an array of array values in an ``ArrayField``. + To view an example of a multi-dimensional array, see `ArrayField + <{+django-docs+}/ref/contrib/postgres/fields/#arrayfield>`__ in the {+framework+} + PostgreSQL documentation. + +Example +``````` + The following example adds an ``ArrayField`` value to the model created in the :ref:`Define a Model example ` in this guide. The new field, called ``genres``, stores a list of ``CharField`` values @@ -332,15 +397,13 @@ that represent movie genres and can store a maximum of ``5`` values: .. tip:: - You can also store an array of array values in an ``ArrayField``. - To view an example of a multi-dimensional array, see `ArrayField - <{+django-docs+}/ref/contrib/postgres/fields/#arrayfield>`__ in the {+framework+} - PostgreSQL documentation. + To learn how to query data stored in an ``ArrayField``, see + :ref:`django-query-arrayfield` in the Specify a Query guide. .. _django-models-embedded: Use an EmbeddedModelField -````````````````````````` +~~~~~~~~~~~~~~~~~~~~~~~~~ You can use an ``EmbeddedModelField`` to represent a MongoDB ``Object``, which stores a nested document value. This type allows one model to @@ -359,6 +422,9 @@ the ``EmbeddedModelField()`` class constructor and pass the following arguments: models. If you make changes to the embedded model's class, the model stored in the ``EmbeddedModelField`` does not reflect the changes. +Example +``````` + This example adds an ``EmbeddedModelField`` value to the model created in the :ref:`Define a Model example ` in this guide. The new field, called ``awards``, stores an embedded ``Award`` model @@ -372,6 +438,11 @@ and modifies the ``Movie`` model to include the ``EmbeddedModelField``: :copyable: :emphasize-lines: 17 +.. tip:: + + To learn how to query data stored in an ``EmbeddedModelField``, see + :ref:`django-query-embedded` in the Specify a Query guide. + Additional Information ---------------------- From 22b96f1f9b4dee3f33ccdaac9f38e74a7eb4cb04 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 21 Jan 2025 16:48:07 -0500 Subject: [PATCH 04/12] edit --- source/model-data/models.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/model-data/models.txt b/source/model-data/models.txt index 17f11a0..d68ec91 100644 --- a/source/model-data/models.txt +++ b/source/model-data/models.txt @@ -45,8 +45,8 @@ the following field types: .. _django-models-django-fields: -{+framework+} Fields -~~~~~~~~~~~~~~~~~~~~ +Django Fields +~~~~~~~~~~~~~ The following table describes the {+framework+} model fields that {+django-odm+} supports: From db2ed44b1886f877fcf3f49d0419f3572d687c22 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 21 Jan 2025 16:57:42 -0500 Subject: [PATCH 05/12] fixes --- source/model-data/models.txt | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/source/model-data/models.txt b/source/model-data/models.txt index d68ec91..cbe3ab2 100644 --- a/source/model-data/models.txt +++ b/source/model-data/models.txt @@ -38,7 +38,8 @@ Supported Field Types --------------------- This section describes {+django-odm+}'s support for -the following field types: +the following field types, which you can include in +your models: - :ref:`django-models-django-fields` - :ref:`django-models-mongodb-fields` @@ -61,7 +62,7 @@ that {+django-odm+} supports: * - ``AutoField`` - | Stores ``IntegerField`` values that automatically increment according to available ID values. If you don't explicitly specify this field, - MongoDB automatically assigns an ``ObjectId`` primary key value. + {+django-odm+} automatically assigns an ``ObjectId`` primary key value. * - ``BigAutoField`` - | Stores ``AutoField`` values up to 64 bits in size. @@ -108,7 +109,7 @@ that {+django-odm+} supports: - | Stores float values. * - ``GenericIPAddressField`` - - | Stores an Pv4 or IPv6 address in string format. + - | Stores an IPv4 or IPv6 address in string format. * - ``IntegerField`` - | Stores integer values. @@ -147,7 +148,7 @@ MongoDB BSON Fields ~~~~~~~~~~~~~~~~~~~ MongoDB organizes and stores documents in a binary representation -called ``BSON`` that allows for flexible data processing. +called BSON that allows for flexible data processing. .. tip:: @@ -163,7 +164,7 @@ The following table describes supported BSON field types and their :widths: 20 20 60 * - BSON Field Type - - Django Field Type + - {+django-odm+} Field Type - BSON Description * - ``Array`` @@ -262,7 +263,7 @@ models or use existing collections to store model data: .. _django-models-define-ex: Example -``````` +~~~~~~~ This sample ``models.py`` file defines a ``Movie`` model class that includes the following information: @@ -330,7 +331,7 @@ stores this data in BSON, or Binary JSON, format. - Some queries that use ``Q`` objects might not return the expected results. -- When querying for field that have a ``None`` value, {+django-odm+} incorrectly +- When querying for fields that have a ``None`` value, {+django-odm+} incorrectly returns documents in which the field doesn't exist. Example From 3be1492963b5ec086a5e1d1f60d26b38c98911cd Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 21 Jan 2025 16:59:04 -0500 Subject: [PATCH 06/12] toc --- snooty.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index fdf69ab..398f22c 100644 --- a/snooty.toml +++ b/snooty.toml @@ -5,7 +5,7 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv", "https://www.mongodb.com/docs/atlas/objects.inv" ] -# toc_landing_pages = ["/paths/to/pages/that/have/nested/content"] +toc_landing_pages = ["/paths/to/pages/that/have/nested/content"] [constants] django-odm = "Django MongoDB Backend" From 188ace2b099f8539c4f28e230c72108de51d4ccc Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 21 Jan 2025 17:19:46 -0500 Subject: [PATCH 07/12] snooty --- snooty.toml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index 398f22c..48656fc 100644 --- a/snooty.toml +++ b/snooty.toml @@ -5,7 +5,9 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv", "https://www.mongodb.com/docs/atlas/objects.inv" ] -toc_landing_pages = ["/paths/to/pages/that/have/nested/content"] +toc_landing_pages = [ + "/model-data" +] [constants] django-odm = "Django MongoDB Backend" From 4fbefe4e421ecc868637ad973e34cbe63b709813 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 22 Jan 2025 12:55:39 -0500 Subject: [PATCH 08/12] remove unsupported fields --- source/index.txt | 10 +++++----- source/model-data/models.txt | 12 +++--------- 2 files changed, 8 insertions(+), 14 deletions(-) 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/models.txt b/source/model-data/models.txt index cbe3ab2..6b24af8 100644 --- a/source/model-data/models.txt +++ b/source/model-data/models.txt @@ -59,14 +59,6 @@ that {+django-odm+} supports: * - Field Type - Description - * - ``AutoField`` - - | Stores ``IntegerField`` values that automatically increment according to - available ID values. If you don't explicitly specify this field, - {+django-odm+} automatically assigns an ``ObjectId`` primary key value. - - * - ``BigAutoField`` - - | Stores ``AutoField`` values up to 64 bits in size. - * - ``BigIntegerField`` - | Stores ``IntegerField`` values up to 64 bits in size. @@ -179,7 +171,7 @@ The following table describes supported BSON field types and their with {+django-odm+}, see the :ref:`django-models-embedded` section in this guide. * - ``ObjectId`` - - ``AutoField`` + - ``ObjectIdAutoField`` - | Stores unique 12-byte identifiers that MongoDB uses as primary keys. * - ``Binary`` @@ -228,6 +220,7 @@ define a string representation of your model. Use the following syntax to define a model: .. code-block:: python + :copyable: false class (models.Model): = @@ -245,6 +238,7 @@ the name of the module that stores your ``models.py`` file, as shown in the following code: .. code-block:: python + :copyable: false INSTALLED_APPS = [ '', From 412abb60f072d4b80b5d849e411d76d2b8bc9588 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 23 Jan 2025 09:56:20 -0500 Subject: [PATCH 09/12] jib feedback --- source/includes/model-data/models.py | 3 ++- source/model-data/models.txt | 12 ++++++------ 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/source/includes/model-data/models.py b/source/includes/model-data/models.py index 1e68ef6..f9fb7c7 100644 --- a/source/includes/model-data/models.py +++ b/source/includes/model-data/models.py @@ -58,9 +58,10 @@ def __str__(self): # start-embedded-field from django.db import models +from django_mongodb_backend.models import EmbeddedModel from django_mongodb_backend.fields import EmbeddedModelField -class Award(models.Model): +class Award(EmbeddedModel): wins = models.IntegerField(default=0) nominations = models.IntegerField(default=0) text = models.CharField(max_length=100) diff --git a/source/model-data/models.txt b/source/model-data/models.txt index 6b24af8..f1dce8f 100644 --- a/source/model-data/models.txt +++ b/source/model-data/models.txt @@ -171,7 +171,7 @@ The following table describes supported BSON field types and their with {+django-odm+}, see the :ref:`django-models-embedded` section in this guide. * - ``ObjectId`` - - ``ObjectIdAutoField`` + - ``ObjectIdField`` - | Stores unique 12-byte identifiers that MongoDB uses as primary keys. * - ``Binary`` @@ -216,7 +216,7 @@ To create an model that represents a MongoDB collection, add your model class definitions to your application's ``models.py`` file. In your model class, specify the fields you want to store and include any model metadata in an inner ``Meta`` class. You can also use the ``__str__()`` method to -define a string representation of your model. Use the following syntax to +define the string representation of your model. Use the following syntax to define a model: .. code-block:: python @@ -226,11 +226,11 @@ define a model: = # Include additional fields here - class Meta: - # Include metadata here + class Meta: + # Include metadata here - def __str__(self): - # Include logic for displaying your model as a string here + def __str__(self): + # Include logic for displaying your model as a string here To use your models, you must add them to your project's ``settings.py`` file. Edit the ``INSTALLED_APPS`` value to include From bdaff83d68cdf10e17b1c95a280ae6964a1c48b9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 23 Jan 2025 10:30:29 -0500 Subject: [PATCH 10/12] meta options --- source/model-data/models.txt | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/source/model-data/models.txt b/source/model-data/models.txt index f1dce8f..d1c283c 100644 --- a/source/model-data/models.txt +++ b/source/model-data/models.txt @@ -232,6 +232,12 @@ define a model: def __str__(self): # Include logic for displaying your model as a string here +.. tip:: + + To learn more about the metadata options you can specify + in the ``Meta`` class, see `Model Meta options <{+django-docs+}/ref/models/options/>`__ + in the {+framework+} documentation. + To use your models, you must add them to your project's ``settings.py`` file. Edit the ``INSTALLED_APPS`` value to include the name of the module that stores your ``models.py`` file, as shown @@ -431,7 +437,7 @@ and modifies the ``Movie`` model to include the ``EmbeddedModelField``: :end-before: end-embedded-field :language: python :copyable: - :emphasize-lines: 17 + :emphasize-lines: 18 .. tip:: From 7fd38fd41066964a1944d9bd5e939edf773ab048 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 23 Jan 2025 16:16:40 -0500 Subject: [PATCH 11/12] RM feedback --- source/model-data/models.txt | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/source/model-data/models.txt b/source/model-data/models.txt index d1c283c..2093654 100644 --- a/source/model-data/models.txt +++ b/source/model-data/models.txt @@ -104,7 +104,7 @@ that {+django-odm+} supports: - | Stores an IPv4 or IPv6 address in string format. * - ``IntegerField`` - - | Stores integer values. + - | Stores integer values up to 32 bits in size. * - ``JSONField`` - | Stores JSON data. To learn more about this field, see the @@ -297,7 +297,7 @@ class that includes the following information: Use Advanced Fields ------------------- -This section how to use the following field types +This section shows how to use the following field types in your Django models: - :ref:`JSONField ` @@ -321,19 +321,6 @@ stores this data in BSON, or Binary JSON, format. MongoDB ``Object``. To learn more about this field, see the :ref:`django-models-embedded` section of this guide. -{+django-odm+}'s support for ``JSONField`` has the following limitations: - -- If you set the field's value to ``None``, {+django-odm+} stores its value as - a SQL ``NULL`` value. Alternatively, you can set the ``JSONField`` value - to ``Value(None, JSONField())``, which represents the JSON scalar ``null``. - However, there is no way to distinguish between the SQL ``NULL`` and the JSON - ``null`` when querying. - -- Some queries that use ``Q`` objects might not return the expected results. - -- When querying for fields that have a ``None`` value, {+django-odm+} incorrectly - returns documents in which the field doesn't exist. - Example ``````` @@ -354,6 +341,23 @@ user ratings for each ``Movie`` object: To learn how to query data stored in a ``JSONField``, see :ref:`django-query-jsonfield` in the Specify a Query guide. +Limitations +``````````` + +{+django-odm+}'s support for ``JSONField`` has the following limitations: + +- If you set the field's value to ``None``, {+django-odm+} stores its value as + a SQL ``NULL`` value. Alternatively, you can set the ``JSONField`` value + to ``Value(None, JSONField())``, which represents the JSON scalar ``null``. + However, there is no way to distinguish between the SQL ``NULL`` and the JSON + ``null`` when querying. + +- Some queries that use ``Q`` objects might not return the expected results, + particularly when using the ``QuerySet.exclude()`` method. + +- When querying for fields that have a ``None`` value, {+django-odm+} incorrectly + returns documents in which the field doesn't exist. + .. _django-models-array: Use an ArrayField From f1910681f837acbd55364f753fc3cb5d2f9b933f Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 28 Jan 2025 10:29:17 -0500 Subject: [PATCH 12/12] SR feedback --- source/model-data/models.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/model-data/models.txt b/source/model-data/models.txt index 2093654..61729a1 100644 --- a/source/model-data/models.txt +++ b/source/model-data/models.txt @@ -212,7 +212,7 @@ The following table describes supported BSON field types and their Define a Model -------------- -To create an model that represents a MongoDB collection, add your model +To create a model that represents a MongoDB collection, add your model class definitions to your application's ``models.py`` file. In your model class, specify the fields you want to store and include any model metadata in an inner ``Meta`` class. You can also use the ``__str__()`` method to