Skip to content

Commit 2a91d96

Browse files
norareidynorareidy
committed
more info
1 parent cb862c5 commit 2a91d96

File tree

2 files changed

+179
-90
lines changed

2 files changed

+179
-90
lines changed

‎source/includes/model-data/models.py‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,24 @@ def __str__(self):
1515
return self.title
1616
# end-models
1717

18+
# start-json-field
19+
from django.db import models
20+
21+
class Movie(models.Model):
22+
title = models.CharField(max_length=200)
23+
plot = models.TextField(blank=True)
24+
runtime = models.IntegerField(default=0)
25+
released = models.DateTimeField("release date", null=True, blank=True)
26+
imdb = models.JSONField(null=True, blank=True)
27+
28+
class Meta:
29+
db_table = "movies"
30+
managed = False
31+
32+
def __str__(self):
33+
return self.title
34+
# end-json-field
35+
1836
# start-array-field
1937
from django.db import models
2038
from django_mongodb_backend.fields import ArrayField

‎source/model-data/models.txt‎

Lines changed: 161 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -32,85 +32,6 @@ documents by using model objects.
3232
<{+django-docs+}/topics/db/models/>`__ in the {+framework+}
3333
documentation.
3434

35-
.. _django-models-define:
36-
37-
Define a Model
38-
--------------
39-
40-
To create an model that represents a MongoDB collection, add your model
41-
class definitions to your application's ``models.py`` file. In your model
42-
class, specify the fields you want to store and include any model metadata
43-
in an inner ``Meta`` class. You can also use the ``__str__()`` method to
44-
define a string representation of your model. Use the following syntax to
45-
define a model:
46-
47-
.. code-block:: python
48-
49-
class <Model name>(models.Model):
50-
<field name> = <data type>
51-
# Include additional fields here
52-
53-
class Meta:
54-
# Include metadata here
55-
56-
def __str__(self):
57-
# Include logic for displaying your model as a string here
58-
59-
To use your models, you must add them to your project's
60-
``settings.py`` file. Edit the ``INSTALLED_APPS`` value to include
61-
the name of the module that stores your ``models.py`` file, as shown
62-
in the following code:
63-
64-
.. code-block:: python
65-
66-
INSTALLED_APPS = [
67-
'<application module>',
68-
# Include other app modules here
69-
]
70-
71-
Finally, run the following database migration commands from your
72-
project's root directory to create MongoDB collections for your
73-
models or use existing collections to store model data:
74-
75-
.. code-block:: bash
76-
77-
python manage.py makemigrations <application name>
78-
python manage.py migrate
79-
80-
.. _django-models-define-ex:
81-
82-
Example
83-
```````
84-
85-
This sample ``models.py`` file defines a ``Movie`` model
86-
class that includes the following information:
87-
88-
- List of fields that represent movie data.
89-
90-
- ``Meta`` class that sets the ``db_table`` option
91-
to ``movies``. This instructs {+django-odm+} to use this model
92-
to represent the ``sample_mflix.movies`` collection from the
93-
:atlas:`Atlas sample datasets </sample-data>`.
94-
95-
The ``Meta`` class also sets the ``managed`` option to ``False``,
96-
instructing {+django-odm+} not to create a new collection
97-
for the model.
98-
99-
- ``__str__()`` method that defines the model's string
100-
representation as its ``title`` field value.
101-
102-
.. literalinclude:: /includes/model-data/models.py
103-
:start-after: start-models
104-
:end-before: end-models
105-
:language: python
106-
:copyable:
107-
108-
.. tip::
109-
110-
To learn more about the field types used in the model
111-
class definition, see the following :ref:`django-models-fields`
112-
section of this guide.
113-
11435
.. _django-models-fields:
11536

11637
Supported Field Types
@@ -220,11 +141,6 @@ that {+django-odm+} supports:
220141
* - ``UUIDField``
221142
- | Stores instances of Python's ``UUID`` class.
222143

223-
.. _django-models-json:
224-
225-
Use a JSONField
226-
```````````````
227-
228144
.. _django-models-mongodb-fields:
229145

230146
MongoDB BSON Fields
@@ -298,10 +214,149 @@ The following table describes supported BSON field types and their
298214
- ``CharField`` or ``TextField``
299215
- | Stores UTF-8 encoded string values.
300216

217+
.. _django-models-define:
218+
219+
Define a Model
220+
--------------
221+
222+
To create an model that represents a MongoDB collection, add your model
223+
class definitions to your application's ``models.py`` file. In your model
224+
class, specify the fields you want to store and include any model metadata
225+
in an inner ``Meta`` class. You can also use the ``__str__()`` method to
226+
define a string representation of your model. Use the following syntax to
227+
define a model:
228+
229+
.. code-block:: python
230+
231+
class <Model name>(models.Model):
232+
<field name> = <data type>
233+
# Include additional fields here
234+
235+
class Meta:
236+
# Include metadata here
237+
238+
def __str__(self):
239+
# Include logic for displaying your model as a string here
240+
241+
To use your models, you must add them to your project's
242+
``settings.py`` file. Edit the ``INSTALLED_APPS`` value to include
243+
the name of the module that stores your ``models.py`` file, as shown
244+
in the following code:
245+
246+
.. code-block:: python
247+
248+
INSTALLED_APPS = [
249+
'<application module>',
250+
# Include other app modules here
251+
]
252+
253+
Finally, run the following database migration commands from your
254+
project's root directory to create MongoDB collections for your
255+
models or use existing collections to store model data:
256+
257+
.. code-block:: bash
258+
259+
python manage.py makemigrations <application name>
260+
python manage.py migrate
261+
262+
.. _django-models-define-ex:
263+
264+
Example
265+
```````
266+
267+
This sample ``models.py`` file defines a ``Movie`` model
268+
class that includes the following information:
269+
270+
- List of fields that represent movie data.
271+
272+
- ``Meta`` class that sets the ``db_table`` option
273+
to ``movies``. This instructs {+django-odm+} to use this model
274+
to represent the ``sample_mflix.movies`` collection from the
275+
:atlas:`Atlas sample datasets </sample-data>`.
276+
277+
The ``Meta`` class also sets the ``managed`` option to ``False``,
278+
instructing {+django-odm+} not to create a new collection
279+
for the model.
280+
281+
- ``__str__()`` method that defines the model's string
282+
representation as its ``title`` field value.
283+
284+
.. literalinclude:: /includes/model-data/models.py
285+
:start-after: start-models
286+
:end-before: end-models
287+
:language: python
288+
:copyable:
289+
290+
.. tip::
291+
292+
To learn more about the field types used in the model
293+
class definition, see the :ref:`django-models-fields`
294+
section of this guide.
295+
296+
Use Advanced Fields
297+
-------------------
298+
299+
This section how to use the following field types
300+
in your Django models:
301+
302+
- :ref:`JSONField <django-models-json>`
303+
- :ref:`ArrayField <django-models-array>`
304+
- :ref:`EmbeddedModelField <django-models-embedded>`
305+
306+
.. _django-models-json:
307+
308+
Use a JSONField
309+
~~~~~~~~~~~~~~~
310+
311+
You can use a ``JSONField`` in your model to store JSON objects.
312+
JSON is a human-readable format for data exchange, and JSON objects
313+
are data containers that map string keys to values. MongoDB provides
314+
the ``Object`` field type to store JSON data in documents and internally
315+
stores this data in BSON, or Binary JSON, format.
316+
317+
.. note::
318+
319+
You can also use an ``EmbeddedModelField`` to represent a
320+
MongoDB ``Object``. To learn more about this field, see the
321+
:ref:`django-models-embedded` section of this guide.
322+
323+
{+django-odm+}'s support for ``JSONField`` has the following limitations:
324+
325+
- If you set the field's value to ``None``, {+django-odm+} stores its value as
326+
a SQL ``NULL`` value. Alternatively, you can set the ``JSONField`` value
327+
to ``Value(None, JSONField())``, which represents the JSON scalar ``null``.
328+
However, there is no way to distinguish between the SQL ``NULL`` and the JSON
329+
``null`` when querying.
330+
331+
- Some queries that use ``Q`` objects might not return the expected results.
332+
333+
- When querying for field that have a ``None`` value, {+django-odm+} incorrectly
334+
returns documents in which the field doesn't exist.
335+
336+
Example
337+
```````
338+
339+
The following example adds a ``JSONField`` value to the model created in
340+
the :ref:`Define a Model example <django-models-define-ex>` in this
341+
guide. The new field, called ``imdb``, stores JSON data that represents
342+
user ratings for each ``Movie`` object:
343+
344+
.. literalinclude:: /includes/model-data/models.py
345+
:start-after: start-json-field
346+
:end-before: end-json-field
347+
:language: python
348+
:copyable:
349+
:emphasize-lines: 8
350+
351+
.. tip::
352+
353+
To learn how to query data stored in a ``JSONField``, see
354+
:ref:`django-query-jsonfield` in the Specify a Query guide.
355+
301356
.. _django-models-array:
302357

303358
Use an ArrayField
304-
`````````````````
359+
~~~~~~~~~~~~~~~~~
305360

306361
You can use an ``ArrayField`` in your model to store a list of data.
307362
To create an ``ArrayField``, use the ``ArrayField()`` class constructor
@@ -318,6 +373,16 @@ and pass the following arguments:
318373
available options, see `Field options <{+django-docs+}/ref/models/fields/#field-options>`__
319374
in the {+framework+} documentation.
320375

376+
.. tip::
377+
378+
You can store an array of array values in an ``ArrayField``.
379+
To view an example of a multi-dimensional array, see `ArrayField
380+
<{+django-docs+}/ref/contrib/postgres/fields/#arrayfield>`__ in the {+framework+}
381+
PostgreSQL documentation.
382+
383+
Example
384+
```````
385+
321386
The following example adds an ``ArrayField`` value to the model created in
322387
the :ref:`Define a Model example <django-models-define-ex>` in this
323388
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:
332397

333398
.. tip::
334399

335-
You can also store an array of array values in an ``ArrayField``.
336-
To view an example of a multi-dimensional array, see `ArrayField
337-
<{+django-docs+}/ref/contrib/postgres/fields/#arrayfield>`__ in the {+framework+}
338-
PostgreSQL documentation.
400+
To learn how to query data stored in an ``ArrayField``, see
401+
:ref:`django-query-arrayfield` in the Specify a Query guide.
339402

340403
.. _django-models-embedded:
341404

342405
Use an EmbeddedModelField
343-
`````````````````````````
406+
~~~~~~~~~~~~~~~~~~~~~~~~~
344407

345408
You can use an ``EmbeddedModelField`` to represent a MongoDB ``Object``,
346409
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:
359422
models. If you make changes to the embedded model's class, the model
360423
stored in the ``EmbeddedModelField`` does not reflect the changes.
361424

425+
Example
426+
```````
427+
362428
This example adds an ``EmbeddedModelField`` value to the model created in
363429
the :ref:`Define a Model example <django-models-define-ex>` in this
364430
guide. The new field, called ``awards``, stores an embedded ``Award`` model
@@ -372,6 +438,11 @@ and modifies the ``Movie`` model to include the ``EmbeddedModelField``:
372438
:copyable:
373439
:emphasize-lines: 17
374440

441+
.. tip::
442+
443+
To learn how to query data stored in an ``EmbeddedModelField``, see
444+
:ref:`django-query-embedded` in the Specify a Query guide.
445+
375446
Additional Information
376447
----------------------
377448

0 commit comments

Comments
 (0)