---
title: "モデルインスタンスリファレンス"
version: 6.1
locale: ja
source: https://docs.djangoproject.com/ja/6.1/ref/models/instances/
canonical: https://djangodocs.dev/ja/6.1/ref/models/instances/
---
# モデルインスタンスリファレンス

このドキュメントでは、`Model` API の詳細を説明しています。[モデル](/ja/6.1/topics/db/models/) と [データベースクエリ](/ja/6.1/topics/db/queries/) ガイドにある説明を前提としていますので、このドキュメントを読む前にこの 2 つを読んでおいた方がよいでしょう。

このリファレンスでは、 [データベースクエリガイド](/ja/6.1/topics/db/queries/) で提供された [Blogモデルの例](/ja/6.1/topics/db/queries/#queryset-model-example) を使用します。

## オブジェクトを作成する

モデルの新しいインスタンスを作成するには、他の Python クラスと同様にインスタンス化してください:

#### `class Model(**kwargs)`

The keyword arguments are the names of the fields you've defined on your model.
Note that instantiating a model in no way touches your database; for that, you
need to [`save()`](#django.db.models.Model.save).

> **Note**
>
> You may be tempted to customize the model by overriding the `__init__`
> method. If you do so, however, take care not to change the calling
> signature as any change may prevent the model instance from being saved.
> Additionally, referring to model fields within `__init__` may potentially
> result in infinite recursion errors in some circumstances. Rather than
> overriding `__init__`, try using one of these approaches:
>
> 1. モデルクラスにクラスメソッドを追加する:
>
>    ```
>    from django.db import models
>
>
>    class Book(models.Model):
>        title = models.CharField(max_length=100)
>
>        @classmethod
>        def create(cls, title):
>            book = cls(title=title)
>            # do something with the book
>            return book
>
>
>    book = Book.create("Pride and Prejudice")
>    ```
> 2. 独自のマネジャーにメソッドを追加する (通常推奨される方法です):
>
>    ```
>    class BookManager(models.Manager):
>        def create_book(self, title):
>            book = self.create(title=title)
>            # do something with the book
>            return book
>
>
>    class Book(models.Model):
>        title = models.CharField(max_length=100)
>
>        objects = BookManager()
>
>
>    book = Book.objects.create_book("Pride and Prejudice")
>    ```

> **Setting attributes does not convert types**
>
> Setting a model attribute does not convert the value to the field's Python
> type. That conversion happens when the model is [validated](#validating-objects). Although a field assigned a value of a different
> type (for example, a string assigned to a
> [`UUIDField`](/ja/6.1/ref/models/fields/#django.db.models.UUIDField)) may be converted when
> [`save()`](#django.db.models.Model.save) executes a query, the in-memory instance will keep the
> original value until it is [reloaded](#refreshing-objects).

### モデルの読み込みをカスタマイズする

#### `classmethod Model.from_db(db, field_names, values)`

`from_db()` メソッドを使うと、データベースから読み込むときのモデルインスタンス作成をカスタマイズできます。

引数 `db` はモデルを読み込む対象となるデータベースへのエイリアスになります。 `field_names` は読み込まれるすべてのフィールドの名前を持ち、そして `values` は `field_names` 内各フィールドに対応した値を持ちます。 `field_names` は `values` と同じ並び順になります。モデルのフィールドが全て存在する場合、 `values` はその順番が `__init__()` が期待する順番である事が保障されます。つまり、そのインスタンスは `cls(*values)` によって生成されます。いずれかのフィールドが遅延評価されている場合、そのフィールドは `field_names` 内には現れません。その場合、存在しない各フィールドには `django.db.models.DEFERRED` の値が設定されています。

新しいモデルを作成するだけでなく、`from_db()` メソッドは新しいインスタンスの [`_state`](#django.db.models.Model._state) 属性に `adding` と `db` のフラグを設定する必要があります。

以下はデータベースから読み出されたフィールドの初期値をどのように保存しているのかについてを示した例です:

```
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)
```

上の例ではその機能を明らかにするため `from_db()` の実装を全て行いました。この実装を行う場合では `from_db()` メソッドから `super()` を呼び出してもかまいません。

## データベースからオブジェクトを再読み込みする

モデルのインスタンスからあるフィールドを削除した場合、再度アクセスする事でその値をデータベースから再読み込みします:

```pycon
>>> 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`](/ja/6.1/ref/utils/#django.utils.functional.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)
```

When a deferred field is loaded on-demand for a single model instance, the
loading happens through this method. Thus it is possible to customize the way
this loading happens. The example below shows how one can reload all of the
instance's fields when a deferred field is loaded on-demand:

```
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`](/ja/6.1/topics/db/managers/#django.db.models.Model._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()`

対象となるモデルにおいて現在評価を遅延している全てのフィールドの属性名を持った集合を返すヘルパーメソッドです。

## オブジェクトを検証 (バリデーション) する

モデルのバリデーションには 4 つのステップがあります:

1. Validate the model fields - [`Model.clean_fields()`](#django.db.models.Model.clean_fields)
2. Validate the model as a whole - [`Model.clean()`](#django.db.models.Model.clean)
3. Validate the field uniqueness - [`Model.validate_unique()`](#django.db.models.Model.validate_unique)
4. 制約を検証する - [`Model.validate_constraints()`](#django.db.models.Model.validate_constraints)

モデルの [`full_clean()`](#django.db.models.Model.full_clean) メソッドを使うと、4 つ全てのステップが実行されます。

When you use a [`ModelForm`](/ja/6.1/topics/forms/modelforms/#django.forms.ModelForm), the call to
[`is_valid()`](/ja/6.1/ref/forms/api/#django.forms.Form.is_valid) will perform these validation steps for
all the fields that are included on the form. See the [ModelForm
documentation](/ja/6.1/topics/forms/modelforms/) for more information. You should only
need to call a model's [`full_clean()`](#django.db.models.Model.full_clean) method if you plan to handle
validation errors yourself, or if you have excluded fields from the
[`ModelForm`](/ja/6.1/topics/forms/modelforms/#django.forms.ModelForm) that require validation.

#### `Model.full_clean(exclude=None, validate_unique=True, validate_constraints=True)`

This method calls [`Model.clean_fields()`](#django.db.models.Model.clean_fields), [`Model.clean()`](#django.db.models.Model.clean),
[`Model.validate_unique()`](#django.db.models.Model.validate_unique) (if `validate_unique` is `True`),  and
[`Model.validate_constraints()`](#django.db.models.Model.validate_constraints) (if `validate_constraints` is `True`)
in that order and raises a [`ValidationError`](/ja/6.1/ref/exceptions/#django.core.exceptions.ValidationError) that
has a `message_dict` attribute containing errors from all four stages.

オプションの `exclude` 引数を指定することで、検証とクリーニングから除外するフィールド名の `set` を指定できます。[`ModelForm`](/ja/6.1/topics/forms/modelforms/#django.forms.ModelForm) は、この引数をフォーム上に存在しないフィールドを検証対象から除外するために使います。これは、エラーが発生してもユーザーによって修正できないからです。

Note that `full_clean()` will *not* be called automatically when you call
your model's [`save()`](#django.db.models.Model.save) method. You'll need to call it manually
when you want to run one-step model validation for your own manually created
models. For example:

```
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`](/ja/6.1/ref/exceptions/#django.core.exceptions.ValidationError) が送出されます。

The second step `full_clean()` performs is to call [`Model.clean()`](#django.db.models.Model.clean).
This method should be overridden to perform custom validation on your model.

#### `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()
```

Note, however, that like [`Model.full_clean()`](#django.db.models.Model.full_clean), a model's `clean()`
method is not invoked when you call your model's [`save()`](#django.db.models.Model.save) method.

上の例では、`Model.clean()` により発生した [`ValidationError`](/ja/6.1/ref/exceptions/#django.core.exceptions.ValidationError) 例外は文字列によりインスタンス化されていたので、特別なエラーディクショナリのキー  [`NON_FIELD_ERRORS`](/ja/6.1/ref/exceptions/#django.core.exceptions.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`](/ja/6.1/ref/exceptions/#django.core.exceptions.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()` でモデル上のユニーク制約をチェックします。

> **ModelForm 内に表示されないフィールドに対してフィールド特有のバリデーションエラーを発生させる方法**
>
> (`Meta.fields` や `Meta.exclude` で制限されて) モデルフォームに表示されないフィールドに対して `Model.clean()` 内でバリデーションエラーを発生させることはできません。やろうとしても、`ValueError` が発生します。これは、バリデーションエラーが除外されたフィールドと関連付けることができないからです。
>
> このジレンマに対応するには、[`Model.clean_fields()`](#django.db.models.Model.clean_fields) をオーバーライドすることです。これはバリデーションから除外されたフィールドのリストを受け取ります。次に例を示します。
>
> ```
> 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()`](#django.db.models.Model.clean_fields) と似ていますが、個別のフィールドの値ではなく [`Field.unique`](/ja/6.1/ref/models/fields/#django.db.models.Field.unique), [`Field.unique_for_date`](/ja/6.1/ref/models/fields/#django.db.models.Field.unique_for_date), [`Field.unique_for_month`](/ja/6.1/ref/models/fields/#django.db.models.Field.unique_for_month), [`Field.unique_for_year`](/ja/6.1/ref/models/fields/#django.db.models.Field.unique_for_year), [`Meta.unique_together`](/ja/6.1/ref/models/options/#django.db.models.Options.unique_together) によって定義されたユニーク制約を検証します。オプションの `exclude` 引数により、バリデーションから除外するフィールド名の `set` を指定できます。いずれかのフィールドがバリデーションに失敗した場合、[`ValidationError`](/ja/6.1/ref/exceptions/#django.core.exceptions.ValidationError) を発生させます。

[`Meta.constraints`](/ja/6.1/ref/models/options/#django.db.models.Options.constraints) で定義された [`UniqueConstraint`](/ja/6.1/ref/models/constraints/#django.db.models.UniqueConstraint) は [`Model.validate_constraints()`](#django.db.models.Model.validate_constraints) によって検証されます。

`validate_unique()` で `exclude` 引数を指定した場合、そのうちの 1 つでも含む [`unique_together`](/ja/6.1/ref/models/options/#django.db.models.Options.unique_together) 制限はチェックされません。

最後に、`full_clean()` でモデル上の他の制約をチェックします。

#### `Model.validate_constraints(exclude=None)`

このメソッドは [`Meta.constraints`](/ja/6.1/ref/models/options/#django.db.models.Options.constraints) で定義された全ての制約を検証します。オプションの `exclude` 引数で、検証から除外するフィールド名の `set` を指定できます。制約の検証に失敗した場合、 [`ValidationError`](/ja/6.1/ref/exceptions/#django.core.exceptions.ValidationError) を発生させます。

## オブジェクトを保存する

データベースにオブジェクトを保存し直すには、`save()` を呼び出します:

#### `Model.save(* (Keyword-only parameters separator (PEP 3102)), force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)`

#### `Model.asave(* (Keyword-only parameters separator (PEP 3102)), force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)`

*非同期バージョン*: `asave()`

`force_insert` と `force_update` 引数の詳細については [INSERT や UPDATE を強制する](#ref-models-force-insert) を参照してください。引数 `update_fields` の詳細については [どのフィールドを保存するか指定する](#ref-models-update-fields) セクションを参照してください。

保存の動作をカスタマイズしたい場合は、`save()` メソッドをオーバーライドできます。詳しくは [定義済みのモデルメソッドをオーバーライドする](/ja/6.1/topics/db/models/#overriding-model-methods) を参照してください。

モデル保存のプロセスには、いくつかの細かな注意点もあります; 以下の各セクションを参照してください。

### 自動インクリメントのプライマリキー

モデルに [`AutoField`](/ja/6.1/ref/models/fields/#django.db.models.AutoField) (自動インクリメントの主キー) がある場合、最初に `save()` を呼び出すと、自動インクリメントの値が計算され、オブジェクトの属性として保存されます:

```pycon
>>> 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.
```

`save()` を呼び出す前に、ID の値がどうなるかを知る方法はありません。 なぜなら、その値は Django ではなくデータベースが計算するからです。

利便性のために、各モデルには `id` という [`AutoField`](/ja/6.1/ref/models/fields/#django.db.models.AutoField) がデフォルトで用意されていますが、モデル内のフィールドに `primary_key=True` を明示的に指定しない限り、 `id` という名前のフィールドは用意されません。詳しくは [`AutoField`](/ja/6.1/ref/models/fields/#django.db.models.AutoField) のドキュメントを参照してください。

#### `pk` プロパティ

#### `Model.pk`

自分で主キーのフィールドを定義するか、 Django に用意させるかにかかわらず、各モデルには `pk` というプロパティがあります。これはモデル上の通常の属性のように振る舞いますが、実際にはそのモデルの主キーを構成するフィールドへのエイリアスです。ほかの属性と同様にこの値を読み書きでき、設定すればモデル内の該当フィールドが正しく更新されます。

#### 自動主キー値の明示的な指定

モデルが [`AutoField`](/ja/6.1/ref/models/fields/#django.db.models.AutoField) を持っていて、保存時に新しいオブジェクトの ID を明示的に定義したい場合は、ID の自動割り当てに頼るのではなく、保存前に明示的に定義してください:

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

自動主キー値を手動で割り当てる場合は、既に存在する主キー 値を使わないようにしてください！すでにデータベースに存在する明示的な主キー値を使って新しいオブジェクトを作成すると、 Django は新しいレコードを作成するのではなく、既存のレコードを変更するものとみなし ます。

上記の `'Cheddar Talk'` ブログの例を考えると、この例はデータベースの以前のレコードを上書きします:

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

このようなことが起こる理由については、後述の [How Django knows to UPDATE vs. INSERT](#how-django-knows-to-update-vs-insert) を参照してください。

自動主キーの値を明示的に指定することは、主キーの衝突が起きないと確信が持てる場合に、オブジェクトを一括保存するときに便利です。

PostgreSQLを使用している場合、主キーに関連付けられたシーケンスを更新する必要があるかもしれません。 [自動インクリメントの主キーの値を手動で指定する](/ja/6.1/ref/databases/#manually-specified-autoincrement-pk) を参照してください。

### save すると何が起きるか？

オブジェクトを保存するとき、Django は以下のステップを実行します:

1. **pre-save シグナルを発信します。** [`pre_save`](/ja/6.1/ref/signals/#django.db.models.signals.pre_save) シグナルが送られ、そのシグナルを待ち受ける関数が何かできるようになります。
2. **データの前処理。** 各フィールドの [`pre_save()`](/ja/6.1/ref/models/fields/#django.db.models.Field.pre_save) メソッドが呼び出され、必要な自動データ修正を行います。たとえば、日付/時刻フィールドは `pre_save()` をオーバーライドして [`auto_now_add`](/ja/6.1/ref/models/fields/#django.db.models.DateField.auto_now_add) と [`auto_now`](/ja/6.1/ref/models/fields/#django.db.models.DateField.auto_now) を実装しています。
3. **データベース用のデータを準備します。** 各フィールドの [`get_db_prep_save()`](/ja/6.1/ref/models/fields/#django.db.models.Field.get_db_prep_save) メソッドは、データベースに書き込めるデータ型で現在の値を提供するように要求されます。

   ほとんどのフィールドではデータの準備は不要です。整数や文字列のような単純なデータ型は Python オブジェクトとして 'すぐに書けます' 。しかし、より複雑なデータ型はしばしば何らかの変更を必要とします。

   たとえば、 [`DateField`](/ja/6.1/ref/models/fields/#django.db.models.DateField) フィールドは Python の `datetime` オブジェクトを使ってデータを格納します。データベースは `datetime` オブジェクトを保存しないので、フィールドの値を ISO 準拠の日付文字列に変換してデータベースに挿入する必要があります。
4. **データベースにデータを挿入します。** 前処理され準備されたデータは、データベースに挿入するためのSQL文に構成されます。
5. **post-save シグナルを発信します。** [`post_save`](/ja/6.1/ref/signals/#django.db.models.signals.post_save) シグナルが送られ、 そのシグナルを待ち受ける関数が何かできるようになります。

### Django が UPDATE と INSERT を見分ける方法

Django データベースオブジェクトが、オブジェクトの作成と変更に同じ `save()` メソッドを使うことにお気づきかもしれません。Django は `INSERT` や `UPDATE` といった SQL ステートメントを抽象化しています。具体的には、 `save()` を呼び出し、オブジェクトの主キー属性に [`default`](/ja/6.1/ref/models/fields/#django.db.models.Field.default) や [`db_default`](/ja/6.1/ref/models/fields/#django.db.models.Field.db_default) が **定義されていない場合** 、Django はこのアルゴリズムに従います：

- オブジェクトの主キー属性が `None` 以外に設定された場合、 Django は `UPDATE` を実行します。
- オブジェクトの主キー属性がセット *されていない*、もしくは `UPDATE` が何もアップデートしなかった場合 (主キーがデータベースに存在しない値に指定されている場合など) 、Django は `INSERT` を実行します。

オブジェクトの主キー属性に [`default`](/ja/6.1/ref/models/fields/#django.db.models.Field.default) や [`db_default`](/ja/6.1/ref/models/fields/#django.db.models.Field.db_default) が定義されている場合は既存のモデルインスタンスで、主キーにデータベースに存在する値が指定されていれば、Django は `UPDATE` を実行します。そうでない場合、 Django は `INSERT` を実行します。

ここで重要なのは、そのプライマリキーが使われていないことが保証できない場合、新しいオブジェクトを保存するときに明示的にプライマリキーの値を指定しないように気をつけることです。このニュアンスについては、上述の [自動プライマリキーの値を明示的に指定する](#explicitly-specifying-auto-primary-key-values) と下記の [INSERT や UPDATE を強制する](#forcing-an-insert-or-update) を参照してください。

Django 1.5 以前のバージョンでは、Django は主キー属性が指定されると `SELECT` を行いました。 `SELECT` で行が見つかれば `UPDATE` を行い、見つからなければ `INSERT` を行いました。古いアルゴリズムでは、 `UPDATE` の場合にクエリが 1 つ増えます。まれに、データベースにオブジェクトの主キー値の行があっても、その行が更新されたことを報告しない場合があります。たとえば、PostgreSQLの `ON UPDATE` トリガは `NULL` を返します。このような場合、 [`select_on_save`](/ja/6.1/ref/models/options/#django.db.models.Options.select_on_save) オプションを `True` に設定することで、古いアルゴリズムに戻すことができます。

#### INSERT や UPDATE を強制する

In some rare circumstances, it's necessary to be able to force the
[`save()`](#django.db.models.Model.save) method to perform an SQL `INSERT` and not fall back to
doing an `UPDATE`. Or vice-versa: update, if possible, but not insert a new
row. In these cases you can pass the `force_insert=True` or
`force_update=True` parameters to the [`save()`](#django.db.models.Model.save) method.
Passing both parameters is an error: you cannot both insert *and* update at the
same time!

[マルチテーブル継承](/ja/6.1/topics/db/models/#multi-table-inheritance) を使用する場合、`force_insert` に親クラスのタプルを渡すことで、各ベースに対して `INSERT` ステートメントを強制的に挿入できます。たとえば次のようになります:

```
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))
```

`force_insert=(models.Model,)` を渡すことで、すべての親モデルに対して `INSERT` ステートメントを強制的に挿入できます。デフォルトでは、 `force_insert=True` は現在のモデルに対してのみ新しい行の挿入を強制します。

> **Changed in Django 6.0**
>
> When a forced update does not affect any rows a
> [`NotUpdated`](/ja/6.1/ref/models/class/#django.db.models.Model.NotUpdated) exception is raised. On previous
> versions a generic [`django.db.DatabaseError`](/ja/6.1/ref/exceptions/#django.db.DatabaseError) was raised.

これらのパラメータを必要とするのは、まれであるべきです。Django は、ほとんどの場合で正しく処理を行い、オーバーライドしようとすると追跡が難しいエラーの原因となります。この機能は応用的な場合のみに使用してください。

`update_fields` を使うと `force_update` と同じように更新を強制します。

### 既存のフィールドに基づいて属性を更新する

フィールドに対して、現在の値をインクリメントしたりデクリメントしたりするような単純な計算が必要になることがあります。これを実現する1つの方法は、Pythonで次のように計算を行うことです:

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

データベースから取得した古い `number_sold` の値は 10 でした。そして、11 という値がデータベースに書き直されます。

The process can be made robust, [avoiding a race condition](/ja/6.1/ref/models/expressions/#avoiding-race-conditions-using-f), as well as slightly faster by expressing
the update relative to the original field value, rather than as an explicit
assignment of a new value. Django provides [F() 式](/ja/6.1/ref/models/expressions/#f-expressions) for performing
this kind of relative update. Using [F() 式](/ja/6.1/ref/models/expressions/#f-expressions), the previous example
is expressed as:

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

For more details, see the documentation on [F() 式](/ja/6.1/ref/models/expressions/#f-expressions) and their
[use in update queries](/ja/6.1/topics/db/queries/#topics-db-queries-update).

### どのフィールドを保存するか指定する

`save()` にキーワード引数 `update_fields` 内でフィールドリストの名前が渡された場合、このリスト内で指定されたフィールドだけが更新されます。これは、オブジェクトの 1 つないし少数のフィールドだけを更新したい場合に望ましいでしょう。データベースで全てのモデルフィールドを更新しないようにすると、実行速度が少し向上します。例えば:

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

`update_fields` 引数は文字列を含む任意のイテラブルです。空の `update_fields` イテラブルは保存をスキップします。 `None` という値は全てのフィールドを更新します。

`update_fields` を指定すると更新を強制します。

When saving a model fetched through deferred model loading
([`only()`](/ja/6.1/ref/models/querysets/#django.db.models.query.QuerySet.only) or
[`defer()`](/ja/6.1/ref/models/querysets/#django.db.models.query.QuerySet.defer)) only the fields loaded
from the DB will get updated. In effect there is an automatic
`update_fields` in this case. If you assign or change any deferred field
value, the field will be added to the updated fields.

> **Field.pre_save() と update_fields**
>
> `update_fields` が渡された場合、 `update_fields` の [`pre_save()`](/ja/6.1/ref/models/fields/#django.db.models.Field.pre_save) メソッドのみが呼び出されます。たとえば、これは `auto_now=True` の日付/時刻フィールドが `update_fields` に含まれない限り更新されないことを意味します。

## オブジェクトを削除する

#### `Model.delete(using=DEFAULT_DB_ALIAS, keep_parents=False)`

#### `Model.adelete(using=DEFAULT_DB_ALIAS, keep_parents=False)`

*非同期バージョン*: `adelete()`

Issues an SQL `DELETE` for the object. This only deletes the object in the
database; the Python instance will still exist and will still have data in
its fields, except for the primary key set to `None`. This method returns the
number of objects deleted and a dictionary with the number of deletions per
object type. The return value will count instances from related models if
Django is emulating cascade behavior via Python [`on_delete`](/ja/6.1/ref/models/fields/#django.db.models.ForeignKey.on_delete)
variants. Otherwise, for database variants such as
[`DB_CASCADE`](/ja/6.1/ref/models/fields/#django.db.models.DB_CASCADE), the return value will report only
instances of the [`QuerySet`](/ja/6.1/ref/models/querysets/#django.db.models.query.QuerySet)'s model.

より詳しく (まとめてオブジェクトを削除する方法を含む) については、[オブジェクトを削除する](/ja/6.1/topics/db/queries/#topics-db-queries-delete) を参照してください。

独自の削除動作がほしいときは、`delete()` メソッドをオーバーライドできます。詳しくは [定義済みのモデルメソッドをオーバーライドする](/ja/6.1/topics/db/models/#overriding-model-methods) を参照してください。

[マルチテーブル継承](/ja/6.1/topics/db/models/#multi-table-inheritance) では、子モデルのデータだけを削除したい場合があります。`keep_parents=True` を指定すると、親モデルのデータを保持します。

> **Changed in Django 6.1**
>
> Support for the `DB_*` variants of `on_delete` attribute was added.

## オブジェクトの Pickle 化

モデルを [`pickle`](https://docs.python.org/3/library/pickle.html#module-pickle) 化した時、現在の状態はpickle化された状態です。pickle化を解除すると、現在データベースにあるデータではなく、pickle化した時点のモデルインスタンスが格納されます。

> **バージョン間でpickle化されたデータを共有することはできません**
>
> モデルの pickle は、生成に使われた Django のバージョンでのみ有効です。Django バージョン N を使って pickle を生成した場合、その pickle が Django バージョン N+1 で読める保証はありません。pickle を長期的なアーカイブ戦略の一部として使うべきではありません。
>
> pickle の互換性エラーは、静的に衝突したオブジェクトのように判定が難しいことがあるので、モデルをpickle化したデータを別のバージョンで復元しようとすると `RuntimeWarning` が送出されます。

## その他のモデルインスタンスメソッド

いくつかのオブジェクトメソッドには特別な目的があります。

### `__str__()`

#### `Model.__str__()`

オブジェクトに対して `str()` を呼び出すと、 `__str__()` メソッドが呼び出されます。Django は多くの場所で `str(obj)` を使います。特に、 Django の管理サイトでオブジェクトを表示するときや、テンプレートでオブジェクトを表示するときに挿入される値として使われます。したがって、 `__str__()` メソッドからは、常に人間が読めるようなモデルの表現を返さなければなりません。

例:

```
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}"
```

### `__eq__()`

#### `Model.__eq__()`

等式メソッドは次のように定義されています: 同じ主キー値と具体的なクラスを持つインスタンスは等しいと見なされますが、主キー値が `None` のインスタンスはそれ自身以外のものと等しくありません。プロキシモデルの場合、具体的なクラスはモデルの最初の非プロキシ親として定義されます。他のモデルについては、単純にモデルのクラス自体です。

例:

```
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)
```

### `__hash__()`

#### `Model.__hash__()`

The `__hash__()` method is based on the instance's primary key value. It
is effectively `hash(obj.pk)`. If the instance doesn't have a primary key
value then a `TypeError` will be raised (otherwise the `__hash__()`
method would return different values before and after the instance is
saved), but changing the [`__hash__()`](https://docs.python.org/3/reference/datamodel.html#object.__hash__) value of an instance is
forbidden in Python.

### `get_absolute_url()`

#### `Model.get_absolute_url()`

オブジェクトに対する正式な URL を計算する方法は、`get_absolute_url()` で定義します。呼び出し元に対して、このメソッドは文字列を返します。この文字列は HTTP を通じてオブジェクトを参照するために使えるものです。

例:

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

While this code is correct and simple, it may not be the most portable way
to write this kind of method. The [`reverse()`](/ja/6.1/ref/urlresolvers/#django.urls.reverse) function is
usually the best approach.

例:

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

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

Django が `get_absolute_url()` を使う場所の一つが、admin アプリです。オブジェクトにこのメソッドが定義されている場合、オブジェクト編集のページは "View on site" リンクを持つようになり、`get_absolute_url()` で定義された通りオブジェクトの公開用ビューに直接飛べるようになります。

同様に、Django の他にもいくつか、`get_absolute_url()` が定義されている場合に使用するものがあります ([配信フィードフレームワーク](/ja/6.1/ref/contrib/syndication/) など)。 各モデルインスタンスがユニークな URL を持つことが適切な場合、`get_absolute_url()` を定義すべきです。

> **Warning**
>
> リダイレクトポイズニングの可能性を減らすため、検証されていないユーザーの入力を利用した URL の生成は避けてください。
>
> ```
> def get_absolute_url(self):
>     return "/%s/" % self.name
> ```
>
> `self.name` が `'/example.com'` の場合、上記は `'//example.com/'` を返します。これは有効な schema relative URL ですが、期待されていた `'/%2Fexample.com/'` ではありません。

It's good practice to use `get_absolute_url()` in templates, instead of
hardcoding your objects' URLs. For example, this template code is bad:

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

以下のテンプレートコードは改善例です:

```html+django
<a href="{{ object.get_absolute_url }}">{{ object.name }}</a>
```

このロジックのポイントは、オブジェクトのURL構造を変更する場合、スペルミス修正のような些細な変更であっても、URLが生成される場所すべてを修正する必要がないようにすることです。 `get_absolute_url()` メソッドでURLを一度定義しておけば、コード全体でそのメソッドを呼び出すだけで済みます。

> **Note**
>
> `get_absolute_url()` メソッドから返される文字列は、**必ず** ASCII 文字のみを含み (URI 仕様 [**RFC 3986 Section 2**](https://datatracker.ietf.org/doc/html/rfc3986.html#section-2) で必須)、必要に応じてURLエンコードする必要があります。
>
> `get_absolute_url()` メソッドを呼び出すコードやテンプレートは、結果をそのまま使用でき、 **さらに処理する必要はありません** 。ASCII 文字以外の文字を含む文字列を使用している場合は、`django.utils.encoding.iri_to_uri()` 関数を使用して変換すると便利です。

## 追加のインスタンスメソッド

In addition to [`save()`](#django.db.models.Model.save), [`delete()`](#django.db.models.Model.delete), a model object
might have some of the following methods:

#### `Model.get_FOO_display()`

[`choices`](/ja/6.1/ref/models/fields/#django.db.models.Field.choices) が設定されている全てのフィールドに対して、オブジェクトは `get_FOO_display()` メソッドを持ちます。このメソッドはフィールドの "人間が読める" 値を返します。

例:

```
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)
```

```pycon
>>> 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`](/ja/6.1/ref/models/fields/#django.db.models.Field.null) を持たない [`DateField`](/ja/6.1/ref/models/fields/#django.db.models.DateField) と [`DateTimeField`](/ja/6.1/ref/models/fields/#django.db.models.DateTimeField) に対して、オブジェクトは `get_next_by_FOO()` と `get_previous_by_FOO()` メソッドを持ちます。このメソッドは日付フィールドに関する次のオブジェクトと前のオブジェクトを返し、適切な場合には [`DoesNotExist`](/ja/6.1/ref/models/class/#django.db.models.Model.DoesNotExist) 例外を発生させます。

これらのメソッドはどちらもモデルのデフォルトマネージャを使用してクエリを実行します。カスタムマネージャによるフィルタリングをエミュレートする必要がある場合、あるいは単発のカスタムフィルタリングを実行したい場合、どちらのメソッドもオプションのキーワード引数を受け付けます。キーワード引数は [フィールドルックアップ](/ja/6.1/ref/models/querysets/#field-lookups) で説明されている形式でなければなりません。

同じ日付の値の場合、これらのメソッドはプライマリ・キーを同値の判定に使用することに注意してください。これにより、レコードがスキップされたり重複したりしないことが保証されます。つまり、これらのメソッドを未保存のオブジェクトで使用することはできないということです。

> **追加のインスタンスメソッドのオーバーライド**
>
> ほとんどの場合、 `get_FOO_display()`, `get_next_by_FOO()`, `get_previous_by_FOO()` をオーバーライドまたは継承すると、期待通りに動作するはずです。しかし、これらはメタクラスによって追加されるので、すべての継承構造を考慮することは現実的ではありません。より複雑なケースでは、 `Field.contribute_to_class()` をオーバーライドして、必要なメソッドを設定する必要があります。

## その他の属性

### `_state`

#### `Model._state`

`_state` 属性はモデルインスタンスのライフサイクルを追跡する `ModelState` オブジェクトを参照します。

The `ModelState` object has three attributes: `adding`, a flag which is
`True` if the model has not been saved to the database yet, `db`, a
string referring to the database alias the instance was loaded from or
saved to, and `fetch_mode`, the [fetch mode](/ja/6.1/topics/db/fetch-modes/) to be used in subsequent field fetches.

Newly instantiated instances have `adding=True` and `db=None`,
since they are yet to be saved, and `fetch_mode=models.FETCH_ONE`.
Instances fetched from a `QuerySet` will have `adding=False`, `db`
set to the alias of the associated database, and `fetch_mode` copied
from the queryset's fetch mode.

> **Changed in Django 6.1**
>
> The `fetch_mode` attribute was added.

### `_is_pk_set()`

#### `Model._is_pk_set()`

The `_is_pk_set()` method returns whether the model instance's `pk` is
set. It abstracts the model's primary key definition, ensuring consistent
behavior regardless of the specific `pk` configuration. A
`DatabaseDefault` on an unsaved instance is considered unset.

> **Changed in Django 6.1**
>
> In earlier versions, `True` was returned for `DatabaseDefault`
> values.