/ /

创建模型来表示集合

Overview

在本指南中，您可以学习；了解如何创建表示MongoDB集合的 Django 模型。模型是定义数据结构的Python类。使用 Django MongoDB后端时，可以将每个模型映射到MongoDB集合，并使用模型对象与集合的文档交互。

提示

要学习；了解有关 Django 模型的更多信息，请参阅 Django 文档中的 Model。

支持的字段

本节介绍 Django MongoDB后端对以下字段的支持，您可以将这些字段包含在模型中：

Django 字段
MongoDB BSON字段

Django 字段

下表描述了 Django MongoDB后端支持的 Django 模型字段：

字段类型	说明
`BinaryField`	存储原始二进制数据。
`BooleanField`	存储布尔值（`True` 或 `False`）。
`CharField`	存储字符串值。要存储更长的文本值，请使用 `TextField`。
`DateField`	将日期值存储在Python `datetime.date` 实例中。
`DateTimeField`	将日期和时间值存储在Python `datetime.datetime` 实例中。
`DecimalField`	存储十进制值。
`DurationField`	将表示时间段的值存储在Python `timedelta` 实例中。
`EmailField`	存储 `CharField` 值并使用 `EmailValidator` 来验证该值是否为电子邮件地址。
`FileField`	Stores file values.
`FilePathField`	存储表示文件系统上的文件名的 `CharField` 值。
`FloatField`	Stores float values.
`GenericIPAddressField`	以字符串格式存储 IPv4 或 IPv6解决。
`ImageField`	存储 `FileField` 值并验证上传的对象是否为有效图像。
`IntegerField` 和 `BigIntegerField`	存储大小最多为 64 位的整数值。
`JSONField`	Stores JSON data. To learn more about this field, see the Store JSON Data section in this guide.
`PositiveIntegerField` 和 `PositiveBigIntegerField`	存储大小最多为 64 位的正整数值。
`PositiveSmallIntegerField`	存储大小最多为 32 位的正整数值。
`SlugField`	存储短文本标签，通常用于URL值。
`SmallIntegerField`	存储大小最多为 32 位的整数值。
`TextField`	存储较大的文本值。
`URLField`	存储表示URL 的`CharField` 值。
`UUIDField`	存储 Python 的 `UUID` 类的实例。

MongoDB BSON字段

MongoDB以称为BSON的二进制表示形式组织和存储文档，从而支持灵活数据处理。

提示

To learn more about how MongoDB stores BSON data, see BSON Types in the MongoDB Server manual.

下表描述了支持的BSON字段类型以及您可以在 Django 模型中使用的 MongoDB MongoDB后端等效项：

BSON字段类型	Django MongoDB后端字段类型	BSON描述
`Array`	`ArrayField`	Stores array values. To learn more about using this field with Django MongoDB Backend, see the Store Array Data section in this guide.
`Object`	`EmbeddedModelField` or `EmbeddedModelArrayField`	Stores one or multiple embedded documents. To learn more about using these fields with Django MongoDB Backend, see the Store Embedded Model Data and Store Embedded Model Array Data sections.
`ObjectId`	`ObjectIdField`	存储MongoDB用主节点 (primary node in the replica set)键的唯一 12 字节标识符。
`Binary`	`BinaryField`	存储二进制数据。
`Boolean`	`BooleanField`	存储 `true` 或 `false` 值。
`Date`	`DatetimeField`	存储自 Unix 纪元或 1 月 1, 1970 以来的日期和时间（以毫秒为单位）。
`Decimal128`	`DecimalField`	存储 28 位十进制值。
`Double`	`FloatField`	存储浮点值。
`Int32`	`SmallIntegerField`	存储 32 位有符号整数。
`Int64`	`IntegerField` or `BigIntegerField`	存储 64 位有符号整数。
`String`	`CharField` or `TextField`	存储 UTF-8 编码的字符串值。

定义模型

要创建表示MongoDB集合的模型，请将模型类定义添加到应用程序的 models.py文件中。在模型类中，指定要存储的字段，并在内部 Meta 类中包含任何模型元数据。您还可以使用 __str__() 方法定义模型的字符串表示形式。使用以下语法定义模型：

 class <Model name>(models.Model):
     <field name> = <data type>
     # Include additional fields here
     class Meta:
         # Include metadata here
     def __str__(self):
         # Include logic for displaying your model as a string here

提示

要详细学习；了解可在Meta 类中指定的元数据选项，请参阅 Django 文档中的模型元选项。

要使用模型，必须将它们添加到项目的 settings.py文件中。编辑 INSTALLED_APPS 值以包含存储 models.py文件的模块的名称，如以下代码所示：

 INSTALLED_APPS = [
     '<application module>',
     # Include other app modules here
 ]

最后，从项目的根目录运行以下数据库迁移命令，为模型创建MongoDB集合或使用现有集合存储模型数据：

python manage.py makemigrations <application name>
python manage.py migrate

例子

此示例models.py文件定义了一个 Movie 模型类，其中包含以下信息：

表示电影数据的字段列表。
Meta class that sets the db_table option to movies. This instructs Django MongoDB Backend to use this model to represent the sample_mflix.movies collection from the Atlas sample datasets.

Meta 类还将 managed 选项设置为 False，指示 Django MongoDB后端不要为模型创建新集合。
__str__() 方法，将模型的字符串表示形式定义为其 title字段值。

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)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

提示

要学习；了解有关模型类定义中使用的字段的更多信息，请参阅本指南的支持的字段部分。

使用高级字段

本节介绍如何在 Django 模型中使用以下字段：

JSONField
ArrayField
EmbeddedModelField
EmbeddedModelArrayField
PolymorphicEmbeddedModelField
PolymorphicEmbeddedModelArrayField

Store JSON Data

您可以在模型中使用 JSONField 来存储JSON对象。 JSON是一种人类可读的数据交换格式，而JSON对象是将字符串键映射到值的数据容器。 MongoDB提供 Object字段类型来在文档中存储JSON数据，并在内部以BSON（二进制JSON）格式存储此数据。

注意

您还可以使用嵌入式模型和多态嵌入式模型来表示MongoDB Object。

例子

The following example adds a JSONField value to the model created in the Define a Model example in this guide. The new field, called imdb, stores JSON data that represents user ratings for each Movie object:

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

提示

要学习；了解如何查询存储在 JSONField 中的数据，请参阅指定查询指南中的查询JSON值。

限制

Django MongoDB后端对 JSONField 的支持有以下限制：

如果将该字段的值设立为 None，则 Django MongoDB后端会将其值存储为SQL NULL 值。或者，您可以将 JSONField 值设立为 Value(None, JSONField())，它表示JSON标量 null。但是，在查询时无法区分SQL NULL 和JSON null。
某些使用 Q 对象的查询可能不会返回预期结果，尤其是在使用 QuerySet.exclude() 方法时。
查询具有 None 值的字段时，Django MongoDB后端会错误地返回不存在该字段的文档。

存储数组数据

您可以在模型中使用 ArrayField 来存储数据列表。要创建 ArrayField，请使用 ArrayField() 类构造函数并传递以下参数：

base_field：指定大量中存储的每个值的根本的数据类型。不能将 EmbeddedModelField 或 FileField 指定为基本字段类型。
size：（可选）指定大量的最大大小。
options : （可选）指定 Django字段选项。要查看可用选项列表，请参阅 Django 文档中的字段选项。

提示

您可以使用以下语法将大量值的大量存储在 ArrayField 中：

my_array = ArrayField(
      ArrayField(
          base_field,
          # ... Additional arguments
      ),
)

例子

The following example adds an ArrayField value to the model created in the 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:

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

提示

要学习了解如何查询存储在 ArrayField 中的数据，请参阅指定查询指南中的查询数组值。

存储嵌入式模型数据

您可以使用 EmbeddedModelField 来表示MongoDB Object，用于存储嵌套文档值。此类型允许一个模型在其字段之一中存储单独的模型。要创建 EmbeddedModelField，请将嵌入式模型类定义为 EmbeddedModel 抽象模型的子类。然后，使用 EmbeddedModelField() 构造函数在模型基类中创建一个字段并传递以下参数：

embedded_model：指定要存储的模型类。
options : （可选）指定 Django字段选项。要查看可用选项列表，请参阅 Django 文档中的字段选项。

重要

makemigrations Django 命令不会检测对嵌入式模型的更改。如果您对嵌入式模型的类进行更改，则存储在 EmbeddedModelField 中的模型不会反映这些更改。

例子

This example adds an EmbeddedModelField value to the model created in the 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:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import EmbeddedModelField
class Award(EmbeddedModel):
    wins = models.IntegerField(default=0)
    nominations = models.IntegerField(default=0)
    text = models.CharField(max_length=100)
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, null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

提示

要学习；了解如何查询存储在 EmbeddedModelField 中的数据，请参阅指定查询指南中的查询嵌入式模型值。

存储嵌入式模型数组数据

您可以使用 EmbeddedModelArrayField 表示以一对多关系存储文档大量的MongoDB文档字段。大量中的每个文档都对应一个 Django MongoDB后端 EmbeddedModelField 值。要创建 EmbeddedModelArrayField，请使用 EmbeddedModelArrayField() 类构造函数并传递以下参数：

embedded_model：指定每个大量项中存储的模型。
max_size：（可选）指定大量的最大大小。

例子

This example adds an EmbeddedModelArrayField value to the model created in the Define a Model example in this guide. This cast field stores an array of embedded Actor models. The following code defines the Actor model and modifies the Movie model to include the EmbeddedModelArrayField:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import EmbeddedModelArrayField
class Actor(EmbeddedModel):
    first_name = models.CharField(max_length=100)
    last_name = models.CharField(max_length=100)
    role = models.CharField(max_length=100)
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)
    cast = EmbeddedModelArrayField(Actor, null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

存储多态嵌入式模型数据

您可以使用 PolymorphicEmbeddedModelField 表示可以存储多种类型的嵌入式文档的MongoDB文档字段。每个嵌入式文档都由一个 Django MongoDB后端模型类表示。

要创建 PolymorphicEmbeddedModelField，请将 embedded_models 参数传递给 PolymorphicEmbeddedModelField() 类构造函数。该参数指定字段可以存储的模型类的列表。

例子

This example adds a PolymorphicEmbeddedModelField value to the model created in the Define a Model example in this guide. This awards field can store an embedded model of type Oscars or GoldenGlobes. Each embedded model contains information about all the Oscar or Golden Globe awards a movie has won.

以下代码定义了 Oscars 和 GoldenGlobes 嵌入式模型，然后修改 Movie 模型以包含 PolymorphicEmbeddedModelField：

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import PolymorphicEmbeddedModelField
class Oscars(EmbeddedModel):
    wins = models.IntegerField(default=0)
    nominations = models.IntegerField(default=0)
    best_picture = models.BooleanField(default=False)
class GoldenGlobes(EmbeddedModel):
    wins = models.IntegerField(default=0)
    nominations = models.IntegerField(default=0)
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 = PolymorphicEmbeddedModelField(["Oscars", "GoldenGlobes"], null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

提示

要学习了解如何查询存储在 PolymorphicEmbeddedModelField 中的数据，请参阅指定查询指南中的查询多态嵌入式模型值。

存储多态嵌入式模型数组数据

您可以使用 PolymorphicEmbeddedModelArrayField 表示可以存储多种类型的嵌入式文档的MongoDB文档字段。该字段与 PolymorphicEmbeddedModelField 类似，但它存储的是嵌入式文档的大量，而不是单个文档。大量中的每个嵌入式文档都由 Django MongoDB后端模型类表示。

要创建 PolymorphicEmbeddedModelArrayField，请将以下参数传递给 PolymorphicEmbeddedModelArrayField() 类构造函数：

embedded_models：指定字段可以存储的模型类
max_size：（可选）指定大量的最大大小

例子

This example adds a PolymorphicEmbeddedModelArrayField value to the model created in the Define a Model example in this guide. This awards field can store a list of embedded models of type Oscar or GoldenGlobe. Each embedded model contains information about one Oscar or Golden Globe award that a movie has won.

以下代码定义了 Oscar 和 GoldenGlobe 嵌入式模型，然后修改 Movie 模型以包含 PolymorphicEmbeddedModelArrayField：

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import PolymorphicEmbeddedModelArrayField
class Oscar(EmbeddedModel):
    category = models.CharField(max_length=200)
    year = models.IntegerField(default=0)
class GoldenGlobe(EmbeddedModel):
    category = models.CharField(max_length=200)
    year = models.IntegerField(default=0)
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 = PolymorphicEmbeddedModelArrayField(["Oscar", "GoldenGlobe"], null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

提示

要学习；了解如何查询存储在 PolymorphicEmbeddedModelArrayField 中的数据，请参阅指定查询指南中的查询多态嵌入式模型数组值。

指定唯一约束

为确保某个字段不会在多个文档中存储相同的值，请指定唯一性约束。

要创建唯一性约束，请将模型的 Meta 类中的 constraints 选项分配给 UniqueConstraint对象。按任意顺序将以下参数传递给 UniqueConstraint() 构造函数：

name：约束的名称。
fields：必须存储唯一值的一个或多个字段。
nulls_distinct：（可选） 一个布尔值，指定 Django 是否将具有 NULL 值的字段视为彼此不同。要仅支持一个 NULL 值，请将此选项设立为 False。

重要

支持 nulls_distinct

nulls_distinct 选项仅在 Django MongoDB 后端 v6.0.2 及更高版本中可用。

The following example sets a unique constraint on the Movie model's plot field, defined in the Define a Model example, by modifying the model's Meta class:

class Meta:
    db_table = "movies"
    managed = False
    constraints = [
        models.UniqueConstraint(name="unique_plot", fields=["plot"])
    ]

嵌入式字段约束

重要

支持嵌入式字段约束

您只能在 Django MongoDB 后端 v6.0.2 及更高版本中为 EmbeddedModelField 和 EmbeddedModelArrayField 子字段指定唯一约束。

Django MongoDB后端 v6.0.3添加了对 PolymorphicEmbeddedModelField 和 PolymorphicEmbeddedModelArrayField 子字段的唯一约束的支持。

要对嵌入式模型字段的子字段设立唯一性约束，请将 Meta.constraints 选项分配给 EmbeddedFieldUniqueConstraint对象。按任意顺序将以下参数传递给 EmbeddedFieldUniqueConstraint() 构造函数：

name：约束的名称。
fields：必须存储唯一值的一个或多个子字段。使用点表示法引用子字段名称。

The following example sets a unique constraint on the embedded Award model's text field, defined in the Store Embedded Model Data example, by modifying the Movie model's Meta class:

class Meta:
    db_table = "movies"
    managed = False
    constraints = [
        EmbeddedFieldUniqueConstraint(
           name="unique_award_details",
           fields=["awards.text"],
        )
    ]