建立物件¶

要建立模型的新實例，請像其他 Python 類別一樣實例化它。

class Model(**kwargs)[原始碼]¶

關鍵字引數是您在模型上定義的欄位名稱。請注意，實例化模型不會觸及您的資料庫；為此，您需要使用 save()。

from django.db.models import DEFERRED


@classmethod
def from_db(cls, db, field_names, values):
    # Default implementation of from_db() (subject to change and could
    # be replaced with super()).
    if len(values) != len(cls._meta.concrete_fields):
        values = list(values)
        values.reverse()
        values = [
            values.pop() if f.attname in field_names else DEFERRED
            for f in cls._meta.concrete_fields
        ]
    instance = cls(*values)
    instance._state.adding = False
    instance._state.db = db
    # customization to store the original field values on the instance
    instance._loaded_values = dict(
        zip(field_names, (value for value in values if value is not DEFERRED))
    )
    return instance


def save(self, **kwargs):
    # Check how the current values differ from ._loaded_values. For example,
    # prevent changing the creator_id of the model. (This example doesn't
    # support cases where 'creator_id' is deferred).
    if not self._state.adding and (
        self.creator_id != self._loaded_values["creator_id"]
    ):
        raise ValueError("Updating the value of creator isn't allowed")
    super().save(**kwargs)

從資料庫重新整理物件¶

如果您從模型實例中刪除一個欄位，再次存取它會從資料庫重新載入該值。

>>> obj = MyModel.objects.first()
>>> del obj.field
>>> obj.field  # Loads the field from the database

Model.refresh_from_db(using=None, fields=None, from_queryset=None)[原始碼]¶

Model.arefresh_from_db(using=None, fields=None, from_queryset=None)¶

非同步版本：arefresh_from_db()

如果您需要從資料庫重新載入模型的值，可以使用 refresh_from_db() 方法。當呼叫此方法時不帶引數時，會執行以下操作：

1. 模型的所有非延遲欄位都會更新為目前資料庫中的值。

2. 所有快取的關聯都會從重新載入的實例中清除。

只有模型的欄位會從資料庫重新載入。其他與資料庫相關的值 (例如註釋) 不會重新載入。任何 @cached_property 屬性也不會清除。

重新載入發生在載入實例的資料庫，如果實例不是從資料庫載入，則從預設資料庫重新載入。可以使用 using 引數來強制用於重新載入的資料庫。

可以使用 fields 引數來強制載入的欄位集。

例如，若要測試 update() 呼叫是否產生預期的更新，您可以撰寫類似於以下的測試：

def test_update_result(self):
    obj = MyModel.objects.create(val=1)
    MyModel.objects.filter(pk=obj.pk).update(val=F("val") + 1)
    # At this point obj.val is still 1, but the value in the database
    # was updated to 2. The object's updated value needs to be reloaded
    # from the database.
    obj.refresh_from_db()
    self.assertEqual(obj.val, 2)

請注意，當存取延遲欄位時，延遲欄位的值的載入會透過此方法進行。因此，可以自訂延遲載入的方式。以下範例說明當重新載入延遲欄位時，如何重新載入實例的所有欄位。

class ExampleModel(models.Model):
    def refresh_from_db(self, using=None, fields=None, **kwargs):
        # fields contains the name of the deferred field to be
        # loaded.
        if fields is not None:
            fields = set(fields)
            deferred_fields = self.get_deferred_fields()
            # If any deferred field is going to be loaded
            if fields.intersection(deferred_fields):
                # then load all of them
                fields = fields.union(deferred_fields)
        super().refresh_from_db(using, fields, **kwargs)

from_queryset 引數允許使用與從 _base_manager 建立的查詢集不同的查詢集。它讓您可以更精確地控制模型的重新載入方式。例如，當您的模型使用軟刪除時，您可以讓 refresh_from_db() 考慮到這一點。

obj.refresh_from_db(from_queryset=MyModel.active_objects.all())

您可以快取相關的物件，否則這些物件會從重新載入的實例中清除。

obj.refresh_from_db(from_queryset=MyModel.objects.select_related("related_field"))

您可以在重新載入模型的值之前，鎖定列直到交易結束。

obj.refresh_from_db(from_queryset=MyModel.objects.select_for_update())

Model.get_deferred_fields()[原始碼]¶

一個輔助方法，傳回一個集合，其中包含此模型目前延遲的所有欄位的屬性名稱。

驗證物件¶

驗證模型涉及四個步驟

1. 驗證模型欄位 - Model.clean_fields()

2. 將整個模型做驗證 - Model.clean()

3. 驗證欄位的唯一性 - Model.validate_unique()

4. 驗證約束 - Model.validate_constraints()

當您呼叫模型的 full_clean() 方法時，會執行所有這四個步驟。

當您使用 ModelForm 時，呼叫 is_valid() 將會對表單中包含的所有欄位執行這些驗證步驟。請參閱 ModelForm 文件 以取得更多資訊。如果您計劃自行處理驗證錯誤，或您已從 ModelForm 中排除需要驗證的欄位，則您只需要呼叫模型的 full_clean() 方法。

Model.full_clean(exclude=None, validate_unique=True, validate_constraints=True)[原始碼]¶

此方法會依序呼叫 Model.clean_fields()、Model.clean()、Model.validate_unique() (如果 validate_unique 為 True) 和 Model.validate_constraints() (如果 validate_constraints 為 True)，並引發一個 ValidationError，其中具有一個 message_dict 屬性，其中包含來自所有四個階段的錯誤。

可選的 exclude 引數可用於提供一組 set 欄位名稱，這些欄位名稱可以排除在驗證和清理之外。ModelForm 使用此引數來排除表單上不存在的欄位，以免驗證，因為任何引發的錯誤都無法由使用者更正。

請注意，當您呼叫模型的 save() 方法時，不會自動呼叫 full_clean()。當您想要為自己手動建立的模型執行一步模型驗證時，您需要手動呼叫它。例如：

from django.core.exceptions import ValidationError

try:
    article.full_clean()
except ValidationError as e:
    # Do something based on the errors contained in e.message_dict.
    # Display them to a user, or handle them programmatically.
    pass

full_clean() 執行的第一個步驟是清理每個個別欄位。

Model.clean_fields(exclude=None)[原始碼]¶

此方法會驗證模型上的所有欄位。可選的 exclude 引數可讓您提供一組 set 欄位名稱，以排除在驗證之外。如果任何欄位未通過驗證，它將引發 ValidationError。

full_clean() 執行的第二個步驟是呼叫 Model.clean()。應該覆寫此方法，以對模型執行自訂驗證。

Model.clean()[原始碼]¶

此方法應使用於提供自訂模型驗證，並在需要時修改模型上的屬性。例如，您可以使用它來自動為欄位提供值，或執行需要存取多個欄位的驗證。

import datetime
from django.core.exceptions import ValidationError
from django.db import models
from django.utils.translation import gettext_lazy as _


class Article(models.Model):
    ...

    def clean(self):
        # Don't allow draft entries to have a pub_date.
        if self.status == "draft" and self.pub_date is not None:
            raise ValidationError(_("Draft entries may not have a publication date."))
        # Set the pub_date for published items if it hasn't been set already.
        if self.status == "published" and self.pub_date is None:
            self.pub_date = datetime.date.today()

但是，請注意，與 Model.full_clean() 類似，當您呼叫模型的 save() 方法時，不會呼叫模型的 clean() 方法。

在上面的範例中，由 Model.clean() 引發的 ValidationError 例外是用字串實例化的，因此它將儲存在一個特殊的錯誤字典索引鍵 NON_FIELD_ERRORS 中。此索引鍵用於繫結到整個模型而不是特定欄位的錯誤。

from django.core.exceptions import NON_FIELD_ERRORS, ValidationError

try:
    article.full_clean()
except ValidationError as e:
    non_field_errors = e.message_dict[NON_FIELD_ERRORS]

若要將例外指派給特定欄位，請使用字典實例化 ValidationError，其中索引鍵為欄位名稱。我們可以更新先前的範例，以將錯誤指派給 pub_date 欄位。

class Article(models.Model):
    ...

    def clean(self):
        # Don't allow draft entries to have a pub_date.
        if self.status == "draft" and self.pub_date is not None:
            raise ValidationError(
                {"pub_date": _("Draft entries may not have a publication date.")}
            )
        ...

如果您在 Model.clean() 期間偵測到多個欄位中的錯誤，您也可以傳遞一個將欄位名稱對應到錯誤的字典。

raise ValidationError(
    {
        "title": ValidationError(_("Missing title."), code="required"),
        "pub_date": ValidationError(_("Invalid date."), code="invalid"),
    }
)

然後，full_clean() 將檢查模型上的唯一約束。

class Article(models.Model):
    ...

    def clean_fields(self, exclude=None):
        super().clean_fields(exclude=exclude)
        if self.status == "draft" and self.pub_date is not None:
            if exclude and "status" in exclude:
                raise ValidationError(
                    _("Draft entries may not have a publication date.")
                )
            else:
                raise ValidationError(
                    {
                        "status": _(
                            "Set status to draft if there is not a publication date."
                        ),
                    }
                )

Model.validate_unique(exclude=None)[原始碼]¶

此方法與 clean_fields() 類似，但會驗證透過 Field.unique、Field.unique_for_date、Field.unique_for_month、Field.unique_for_year 或模型上的 Meta.unique_together 定義的唯一性約束，而不是個別欄位值。可選的 exclude 引數可讓您提供一組 set 欄位名稱，以排除在驗證之外。如果任何欄位未通過驗證，它將引發 ValidationError。

在 UniqueConstraint 中定義的 Meta.constraints 會由 Model.validate_constraints() 進行驗證。

請注意，如果您向 validate_unique() 提供 exclude 參數，則任何涉及您提供的欄位的 unique_together 約束條件將不會被檢查。

最後，full_clean() 將檢查模型上的任何其他約束條件。

Model.validate_constraints(exclude=None)[原始碼]¶

此方法會驗證在 Meta.constraints 中定義的所有約束條件。可選的 exclude 參數允許您提供一個欄位名稱的 set，將其排除在驗證之外。如果任何約束條件驗證失敗，它將引發 ValidationError。

儲存物件¶

要將物件儲存回資料庫，請呼叫 save()

Model.save(*, force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)[原始碼]¶

Model.asave(*, force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)¶

非同步版本： asave()

有關使用 force_insert 和 force_update 參數的詳細資訊，請參閱 強制執行 INSERT 或 UPDATE。有關 update_fields 參數的詳細資訊，請參閱 指定要儲存的欄位 章節。

如果您想要自訂儲存行為，您可以覆寫此 save() 方法。有關更多詳細資訊，請參閱 覆寫預定義的模型方法。

模型儲存過程也有一些微妙之處；請參閱下面的章節。

>>> b2 = Blog(name="Cheddar Talk", tagline="Thoughts on cheese.")
>>> b2.id  # Returns None, because b2 doesn't have an ID yet.
>>> b2.save()
>>> b2.id  # Returns the ID of your new object.

>>> b3 = Blog(id=3, name="Cheddar Talk", tagline="Thoughts on cheese.")
>>> b3.id  # Returns 3.
>>> b3.save()
>>> b3.id  # Returns 3.

b4 = Blog(id=3, name="Not Cheddar", tagline="Anything but cheese.")
b4.save()  # Overrides the previous blog with ID=3!

Restaurant(pk=1, name="Bob's Cafe").save(force_insert=(Place,))

Restaurant(pk=1, name="Bob's Cafe", rating=4).save(force_insert=(Place, Rating))

>>> product = Product.objects.get(name="Venezuelan Beaver Cheese")
>>> product.number_sold += 1
>>> product.save()

>>> from django.db.models import F
>>> product = Product.objects.get(name="Venezuelan Beaver Cheese")
>>> product.number_sold = F("number_sold") + 1
>>> product.save()

product.name = "Name changed again"
product.save(update_fields=["name"])

刪除物件¶

Model.delete(using=DEFAULT_DB_ALIAS, keep_parents=False)[原始碼]¶

Model.adelete(using=DEFAULT_DB_ALIAS, keep_parents=False)¶

非同步版本： adelete()

對物件發出 SQL DELETE 指令。這只會刪除資料庫中的物件；Python 實例仍然存在，並且其欄位中仍會保留資料，除了主鍵會被設定為 None。此方法會回傳刪除的物件數量以及一個字典，其中包含每個物件類型刪除的數量。

如需更多詳細資訊，包括如何批量刪除物件，請參閱 刪除物件。

如果您想要自訂刪除行為，可以覆寫 delete() 方法。請參閱 覆寫預定義的模型方法 以了解更多詳細資訊。

有時使用 多表格繼承 時，您可能只想刪除子模型的資料。指定 keep_parents=True 將會保留父模型的資料。

封存物件¶

當您 pickle 模型時，其目前的狀態會被封存。當您解封存它時，它會包含封存時的模型實例，而不是資料庫中當前的資料。

其他模型實例方法¶

一些物件方法有特殊用途。

from django.db import models


class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)

    def __str__(self):
        return f"{self.first_name} {self.last_name}"

from django.db import models


class MyModel(models.Model):
    id = models.AutoField(primary_key=True)


class MyProxyModel(MyModel):
    class Meta:
        proxy = True


class MultitableInherited(MyModel):
    pass


# Primary keys compared
MyModel(id=1) == MyModel(id=1)
MyModel(id=1) != MyModel(id=2)
# Primary keys are None
MyModel(id=None) != MyModel(id=None)
# Same instance
instance = MyModel(id=None)
instance == instance
# Proxy model
MyModel(id=1) == MyProxyModel(id=1)
# Multi-table inheritance
MyModel(id=1) != MultitableInherited(id=1)

def get_absolute_url(self):
    return "/people/%i/" % self.id

def get_absolute_url(self):
    from django.urls import reverse

    return reverse("people-detail", kwargs={"pk": self.pk})

def get_absolute_url(self):
    return "/%s/" % self.name

<!-- BAD template code. Avoid! -->
<a href="/people/{{ object.id }}/">{{ object.name }}</a>

<a href="{{ object.get_absolute_url }}">{{ object.name }}</a>

額外的實例方法¶

除了 save()、delete() 之外，模型物件可能還具有以下一些方法

Model.get_FOO_display()¶

對於每個設定了 choices 的欄位，物件將會擁有一個 get_FOO_display() 方法，其中 FOO 是欄位的名稱。此方法會回傳欄位的「人類可讀」值。

例如

from django.db import models


class Person(models.Model):
    SHIRT_SIZES = {
        "S": "Small",
        "M": "Medium",
        "L": "Large",
    }
    name = models.CharField(max_length=60)
    shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES)

>>> p = Person(name="Fred Flintstone", shirt_size="L")
>>> p.save()
>>> p.shirt_size
'L'
>>> p.get_shirt_size_display()
'Large'

Model.get_next_by_FOO(**kwargs)¶

Model.get_previous_by_FOO(**kwargs)¶

對於每個沒有設定 null=True 的 DateField 和 DateTimeField，物件將會有 get_next_by_FOO() 和 get_previous_by_FOO() 方法，其中 FOO 是欄位的名稱。這會返回相對於日期欄位的下一個和上一個物件，並在適當的時候引發 DoesNotExist 例外。

這兩個方法都會使用模型的預設管理器執行查詢。如果您需要模擬自訂管理器使用的篩選，或是想要執行一次性的自訂篩選，這兩個方法也接受選用的關鍵字參數，這些參數應該採用 欄位查找 中描述的格式。

請注意，在日期值相同的情況下，這些方法會使用主鍵作為平手打破器。這保證不會跳過或重複任何記錄。這也意味著您不能在未儲存的物件上使用這些方法。

其他屬性¶