--- title: "モデルフィールドリファレンス" version: 6.1 locale: ja source: https://docs.djangoproject.com/ja/6.1/ref/models/fields/ canonical: https://djangodocs.dev/ja/6.1/ref/models/fields/ --- # モデルフィールドリファレンス このドキュメントには、Django が提供するフィールドオプション [field options](#field-options) とフィールド型 [field types](#field-types) を含む、[`Field`](#django.db.models.Field) のすべての API リファレンスが記載されています。 > **Note** > > フィールドは [`django.db.models.fields`](#module-django.db.models.fields) に定義されていますが、利便性のために [`django.db.models`](/ja/6.1/topics/db/models/#module-django.db.models) にインポートされています。標準的な慣例としては、`from django.db import models` を使用し、フィールドを `models.Field` として参照します。 ## フィールドオプション 以下の引数は全てのフィールドタイプで有効です。全て省略可能です。 ### `null` #### `Field.null` `True` の場合、Django はデータベース内に `NULL` として空の値を保持します。デフォルトは `False` です。 [`CharField`](#django.db.models.CharField) や [`TextField`](#django.db.models.TextField) などの文字列ベースのフィールドでは、 [`null`](#django.db.models.Field.null) の使用は避けてください。Django は習慣的に、文字列ベースのフィールドの「データなし」状態には `NULL` ではなく空文字列を用います。文字列ベースのフィールドが `null=False` の場合でも、「データなし」として空文字列は保存できます。 `null=True` の場合は、「データなし」を表す値が NULL と空文字列の 2 通りになります。多くの場合、「データなし」を表す値が 2 つあるのは冗長です。例外として、[`CharField`](#django.db.models.CharField) に `unique=True` と `blank=True` の両方を設定する場合があります。この状況では、空文字列のオブジェクトを複数保存する際に一意制約違反を避けるため、 `null=True` が必要になります。 文字列ベースのフィールドでもそれ以外でも、フォーム内で空の値を許可したいときは `blank=True` を指定する必要があります。 [`null`](#django.db.models.Field.null) パラメーターはデータベースストレージにだけ影響を与えるからです（詳細は [`blank`](#django.db.models.Field.blank) を参照）。 > **Note** > > Oracleのデータベースバックエンドを使っているときには、この属性にかかわらず、値 `NULL` が空の文字列を意味するために保持されます。 ### `blank` #### `Field.blank` `True` の場合、フィールドはブランクになることが許容されます。デフォルトは `False` です。 [`null`](#django.db.models.Field.null) とは異なる点に注意してください。[`null`](#django.db.models.Field.null) が純粋にデータベースに関連する一方で、[`blank`](#django.db.models.Field.blank) はバリデーションに関連します。フィールドが `blank=True` を持つ場合、フォームバリデーションは空の値のエントリーを許容します。`blank=False` を持つ場合、フィールドは必須となります。 > **欠損値の補完** > > `blank=True` は `null=False` のフィールドでも使用できますが、この場合、 [`clean()`](/ja/6.1/ref/models/instances/#django.db.models.Model.clean) を実装し、欠損値をプログラムで補完する必要があります。 ### `choices` #### `Field.choices` このフィールドの選択肢として使用するための、以下で説明する形式のマッピングまたはイテラブルです。choices が指定された場合、 [モデルのバリデーション](/ja/6.1/ref/models/instances/#validating-objects) によって強制的に、デフォルトのフォームウィジェットが通常のテキストフィールドの代わりにこれらの選択肢を持つセレクトボックスになります。 マッピングが指定された場合、キー要素はモデルに設定される実際の値で、2番目の要素は人間が読める名前です。例えば ``` YEAR_IN_SCHOOL_CHOICES = { "FR": "Freshman", "SO": "Sophomore", "JR": "Junior", "SR": "Senior", "GR": "Graduate", } ``` また、 [sequence](https://docs.python.org/3/glossary.html#term-sequence) として、ちょうど2つの項目からなるイテラブルを渡すこともできます (例 `[(A1, B1), (A2, B2), ...]`)。各タプルの最初の要素はモデルに設定される実際の値で、2番目の要素は人間が読める名前です。例えば ``` YEAR_IN_SCHOOL_CHOICES = [ ("FR", "Freshman"), ("SO", "Sophomore"), ("JR", "Junior"), ("SR", "Senior"), ("GR", "Graduate"), ] ``` また、`choices` は、上記のいずれかのフォーマットを返す引数なしの呼び出し可能オブジェクトとして定義することもできます。例えば ``` def get_currencies(): return {i: i for i in settings.CURRENCIES} class Expense(models.Model): amount = models.DecimalField(max_digits=10, decimal_places=2) currency = models.CharField(max_length=3, choices=get_currencies) ``` `choice` に呼び出し可能オブジェクトを渡すと、例えば選択肢が以下のような場合に特に便利です： - 同じデータベースや外部データベースのテーブルをクエリしたり、静的ファイルから選択肢にアクセスしたりするような、I/Oバウンド操作の結果（キャッシュされる可能性があります）。 - ほぼ安定しているが、場合によって、あるいはプロジェクトによって異なる可能性のあるリスト。このカテゴリの例は、通貨、国、言語、タイムゾーンなど、よく知られた値のインベントリを提供するサードパーティのアプリを使用する場合などです。 一般的に、モデルクラスの内部で選択肢を定義し、それぞれの値に適切に名前づけられた定数を定義するのがベストです: ``` from django.db import models class Student(models.Model): FRESHMAN = "FR" SOPHOMORE = "SO" JUNIOR = "JR" SENIOR = "SR" GRADUATE = "GR" YEAR_IN_SCHOOL_CHOICES = { FRESHMAN: "Freshman", SOPHOMORE: "Sophomore", JUNIOR: "Junior", SENIOR: "Senior", GRADUATE: "Graduate", } year_in_school = models.CharField( max_length=2, choices=YEAR_IN_SCHOOL_CHOICES, default=FRESHMAN, ) def is_upperclass(self): return self.year_in_school in {self.JUNIOR, self.SENIOR} ``` モデルクラスの外側で選択肢リストを定義し、それを参照することもできますが、モデルクラスの内側で選択肢と各選択肢の名前を定義することで、その情報を使用するクラスで保持し、選択肢を参照しやすくなります（例えば、`Student.SOPHOMORE` は `Student` モデルがインポートされていればどこでも動作します）。 利用可能な選択肢を、組織化のために名前付きグループにまとめることもできます。 ``` MEDIA_CHOICES = { "Audio": { "vinyl": "Vinyl", "cd": "CD", }, "Video": { "vhs": "VHS Tape", "dvd": "DVD", }, "unknown": "Unknown", } ``` マッピングのキーはグループに適用する名前であり、値はそのグループ内の選択肢で、フィールドの値とオプションの人間が読める名前からなります。グループ化されたオプションは、1つのマッピングの中でグループ化されていないオプションと組み合わせることができます（この例の `"unknown"` オプションのように）。 2値タプルのリストなど、シーケンスを使うこともできます： ``` MEDIA_CHOICES = [ ( "Audio", ( ("vinyl", "Vinyl"), ("cd", "CD"), ), ), ( "Video", ( ("vhs", "VHS Tape"), ("dvd", "DVD"), ), ), ("unknown", "Unknown"), ] ``` なお、choices はリストやタプルである必要はなく、任意のシーケンスオブジェクトでも構いません。これにより、選択肢を動的に構築できます。しかし、 [`choices`](#django.db.models.Field.choices) をハックして動的にするよりは、 [`ForeignKey`](#django.db.models.ForeignKey) を持つ適切なデータベーステーブルを使ったほうがいいでしょう。 [`choices`](#django.db.models.Field.choices) はあまり変更されない静的なデータのためのものです。 > **Note** > > `choices` の順番を変更すると、変更のたびに新しいマイグレーションが生成されます。 [`choices`](#django.db.models.Field.choices) が設定されている各モデルフィールドに対して、 Django は選択肢を2値タプルのリストに正規化し、フィールドの現在の値に対して、 人間が読める名前を取得するメソッドを追加します。データベース API ドキュメントの [`get_FOO_display()`](/ja/6.1/ref/models/instances/#django.db.models.Model.get_FOO_display) を参照してください。 Unless [`blank=False`](#django.db.models.Field.blank) is set on the field along with a [`default`](#django.db.models.Field.default) then a label containing `"- Select an option -"` will be rendered with the select box. To override this behavior, add a tuple to `choices` containing `None`; e.g. `(None, 'Your String For Display')`. Alternatively, you can use an empty string instead of `None` where this makes sense - such as on a [`CharField`](#django.db.models.CharField). > **Changed in Django 6.1** > > The default blank label was changed from `"---------"` to > `"- Select an option -"`. #### 列挙型 さらに Django には、選択肢を簡潔に定義するためにサブクラス化できる列挙型があります： ``` from django.utils.translation import gettext_lazy as _ class Student(models.Model): class YearInSchool(models.TextChoices): FRESHMAN = "FR", _("Freshman") SOPHOMORE = "SO", _("Sophomore") JUNIOR = "JR", _("Junior") SENIOR = "SR", _("Senior") GRADUATE = "GR", _("Graduate") year_in_school = models.CharField( max_length=2, choices=YearInSchool, default=YearInSchool.FRESHMAN, ) def is_upperclass(self): return self.year_in_school in { self.YearInSchool.JUNIOR, self.YearInSchool.SENIOR, } ``` これらはPythonの標準ライブラリの [`enum`](https://docs.python.org/3/library/enum.html#module-enum) と似たような動作をしますが、若干の変更が加えられています： - 列挙型のメンバ値は、具象データ型を構築するときに使う引数のタプルです。Django はこのタプルの末尾に、人間が読める名前、つまり `label` として使われる文字列値を追加することをサポートしています。この `label` は遅延 (Lazy な) 翻訳が可能な文字列です。したがって、ほとんどの場合、メンバの値は `(value, label)` の2値タプルになります。より複雑なデータ型を使用した [選択肢のサブクラスの例](#field-choices-enum-subclassing) については以下を参照してください。タプルが提供されない場合、あるいは最後の項目が（lazyな）文字列でない場合、 `label` はメンバー名から [自動的に生成](#field-choices-enum-auto-label) されます。 - 値には `.label` プロパティが追加され、人間が読める名前を返します。 - 列挙型クラスには、 `.choices`, `.labels`, `.values`, `.names` などのカスタムプロパティが追加されており、これらの列挙型の異なる部分のリストに簡単にアクセスできるようになっています。 > **Warning** > > これらのプロパティ名をメンバ名として使用することはできません。 - The use of [`enum.unique()`](https://docs.python.org/3/library/enum.html#enum.unique) is enforced to ensure that values cannot be defined multiple times. This is unlikely to be expected in choices for a field. なお、 `YearInSchool.SENIOR`, `YearInSchool['SENIOR']`, `YearInSchool('SR')` を使用して列挙型のメンバにアクセスしたり、メンバの `.name` と `.value` プロパティを参照したりすることは期待通りに動作します。 人が読める名前を翻訳する必要がない場合は、メンバ名から推測してそれらを自動設定させることができます（アンダースコアをスペースに置き換え、タイトルケースを使用します）： ```pycon >>> class Vehicle(models.TextChoices): ... CAR = "C" ... TRUCK = "T" ... JET_SKI = "J" ... >>> Vehicle.JET_SKI.label 'Jet Ski' ``` 列挙値が整数である必要があるケースは非常に多いので、Django は `IntegerChoices` クラスを用意しています。例えば ``` class Card(models.Model): class Suit(models.IntegerChoices): DIAMOND = 1 SPADE = 2 HEART = 3 CLUB = 4 suit = models.IntegerField(choices=Suit) ``` また、 [Enum Functional API](https://docs.python.org/3/howto/enum.html#functional-api) を利用することもできます。この場合、ラベルは上記のように自動的に生成されます： ```pycon >>> MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE") >>> MedalType.choices [('GOLD', 'Gold'), ('SILVER', 'Silver'), ('BRONZE', 'Bronze')] >>> Place = models.IntegerChoices("Place", "FIRST SECOND THIRD") >>> Place.choices [(1, 'First'), (2, 'Second'), (3, 'Third')] ``` もし `int` や `str` 以外の具象データ型のサポートが必要であれば、 `Choices` と必要な具象データ型、例えば [`date`](https://docs.python.org/3/library/datetime.html#datetime.date) を [`DateField`](#django.db.models.DateField) で使用するようにサブクラス化できます： ``` class MoonLandings(datetime.date, models.Choices): APOLLO_11 = 1969, 7, 20, "Apollo 11 (Eagle)" APOLLO_12 = 1969, 11, 19, "Apollo 12 (Intrepid)" APOLLO_14 = 1971, 2, 5, "Apollo 14 (Antares)" APOLLO_15 = 1971, 7, 30, "Apollo 15 (Falcon)" APOLLO_16 = 1972, 4, 21, "Apollo 16 (Orion)" APOLLO_17 = 1972, 12, 11, "Apollo 17 (Challenger)" ``` さらに注意すべき点がいくつかあります： - 列挙型は [名前付きグループ](#field-choices-named-groups) をサポートしていません。 - 具体的なデータ型を持つ列挙型では、すべての値がそのデータ型に一致する必要があるため、 [blank label](#field-choices-blank-label) をオーバーライドする際に、 `None` という値を持つメンバを作成することはできません。代わりに、クラスに `__empty__` 属性を設定します： ``` class Answer(models.IntegerChoices): NO = 0, _("No") YES = 1, _("Yes") __empty__ = _("(Unknown)") ``` ### `db_column` #### `Field.db_column` このフィールドを使用するためのデータベースのカラムの名前です。もし与えられなければ、Django はフィールド名を使用します。 データベースのカラム名が SQL の予約語だったり、Python の変数名として使用できない文字 (特に多いのがハイフン) が含まれていたとしても大丈夫です。Django はカラムとテーブルの名前を自動的にクオートして処理してくれます。 ### `db_comment` #### `Field.db_comment` このフィールドに使うデータベースカラムのコメントです。あなたの Django コードを見ていないような、データベースに直接アクセスできる人のために、フィールドをドキュメント化するのに便利です。例えば： ``` pub_date = models.DateTimeField( db_comment="Date and time when the article was published", ) ``` ### `db_default` #### `Field.db_default` データベースによって計算されるこのフィールドのデフォルト値。これはリテラル値でも、 [`Now`](/ja/6.1/ref/models/database-functions/#django.db.models.functions.Now) のようなデータベース関数でも構いません： ``` created = models.DateTimeField(db_default=Now()) ``` リテラルやデータベース関数から構成する限り、より複雑な式を使用できます： ``` month_due = models.DateField( db_default=TruncMonth( Now() + timedelta(days=90), output_field=models.DateField(), ) ) ``` データベースのデフォルトは、他のフィールドやモデルを参照することはできません。例えば、これは無効です： ``` end = models.IntegerField(db_default=F("start") + 50) ``` もし `db_default` と [`Field.default`](#django.db.models.Field.default) の両方が指定された場合、Python コードでインスタンスを作成する際には `default` が優先されます。データベースレベルでも `db_default` が設定され、ORM の外部で行を挿入するときや、マイグレーションで新しいフィールドを追加するときに使用されます。 フィールドに `db_default` は設定されているが `default` が設定されておらず、フィールドに値が割り当てられていない場合、保存されていないモデルインスタンスでは `DatabaseDefault` オブジェクトがフィールドの値として返されます。フィールドの実際の値は、モデルインスタンスが保存されたときにデータベースによって決定されます。 ### `db_index` #### `Field.db_index` `True` の場合、データベースインデックスがこのフィールドのために生成されます。 > **代わりに indexes オプションを使用してください。** > > 可能であれば、代わりに [`Meta.indexes`](/ja/6.1/ref/models/options/#django.db.models.Options.indexes) オプションを使用してください。ほとんどの場合、 [`indexes`](/ja/6.1/ref/models/options/#django.db.models.Options.indexes) は `db_index` よりも多くの機能を提供します。 `db_index` は将来廃止される可能性があります。 ### `db_tablespace` #### `Field.db_tablespace` このフィールドにインデックスが作成されている場合に、このフィールドのインデックスに使用する [データベース テーブル空間](/ja/6.1/topics/db/tablespaces/) の名前です。デフォルトはプロジェクトの [`DEFAULT_INDEX_TABLESPACE`](/ja/6.1/ref/settings/#std-setting-DEFAULT_INDEX_TABLESPACE) が設定されている場合はその設定値、またはモデルの [`db_tablespace`](/ja/6.1/ref/models/options/#django.db.models.Options.db_tablespace) が設定されている場合はその設定値です。バックエンドがインデックスのテーブル空間をサポートしていない場合、このオプションは無視されます。 ### `default` #### `Field.default` そのフィールドのデフォルト値です。このオプションには特定の値もしくは呼び出し可能オブジェクトを渡すことができます。もし渡した値が呼び出し可能であれば新しくオブジェクトが生成される度に呼び出されます。 デフォルト値はミュータブルなオブジェクト（モデルのインスタンス、 `list` 、 `set` など）にはできません。そのオブジェクトの同じインスタンスへの参照が、すべての新しいモデルインスタンスのデフォルト値として使用されてしまうからです。代わりに、必要なデフォルト値を呼び出し可能オブジェクトでラップします。例えば、 [`JSONField`](#django.db.models.JSONField) に対してデフォルトの `dict` を指定したい場合、下記のような関数を使用します： ``` def contact_default(): return {"email": "to1@example.com"} contact_info = JSONField("ContactInfo", default=contact_default) ``` `lambda` は [マイグレーションでシリアライズ](/ja/6.1/topics/migrations/#migration-serializing) できないので、`default` のようなフィールドオプションには使えません。その他の注意点についてはドキュメントを参照してください。 [`ForeignKey`](#django.db.models.ForeignKey) のようにモデルインスタンスにマッピングされるフィールドの場合、デフォルトはモデルインスタンスではなく、参照するフィールドの値 ([`to_field`](#django.db.models.ForeignKey.to_field) が設定されていない限り `pk`) になります。 デフォルト値は、新しいモデルインスタンスが作成され、フィールドに値が提供されていない場合に使用されます。フィールドが主キーの場合、フィールドが `None` に設定されているときにもデフォルト値が使われます。 デフォルト値は [`Field.db_default`](#django.db.models.Field.db_default) でデータベースレベルで設定することもできます。 ### `editable` #### `Field.editable` `False` の場合、フィールドは管理サイトやその他の [`ModelForm`](/ja/6.1/topics/forms/modelforms/#django.forms.ModelForm) において表示されません。このとき [model validation](/ja/6.1/ref/models/instances/#validating-objects) の過程でもスキップされます。デフォルトは `True` です。 ### `error_messages` #### `Field.error_messages` 引数 `error_messages` を指定すると、フィールドが表示するデフォルトのメッセージを上書きできます。オーバーライドしたいエラーメッセージにマッチするキーを持つ辞書を渡してください。 エラーメッセージのキーには `null`, `blank`, `invalid`, `invalid_choice`, `unique`, `unique_for_date` があります。以下の [Field types](#field-types) セクションで説明する各フィールドには、追加のエラーメッセージキーが指定されています。 これらのエラーメッセージはフォームに反映されないことがよくあります。詳細は [モデルの error\_messages についての注意](/ja/6.1/topics/forms/modelforms/#considerations-regarding-model-errormessages) を参照してください。 ### `help_text` #### `Field.help_text` フォームウィジェットと共に表示される "補助" テキストになります。この値はフィールドがフォームとして利用されない場合でもドキュメント化する際に有用です。 この値は自動生成のフォームではHTMLエスケープ *されません* 。そのため、 [`help_text`](#django.db.models.Field.help_text) にはHTMLが使えます。例： ``` help_text = "Please use the following format: YYYY-MM-DD." ``` あるいは、プレーンテキストを使い、 [`django.utils.html.escape()`](/ja/6.1/ref/utils/#django.utils.html.escape) で HTML の特殊文字をエスケープすることもできます。クロスサイトスクリプティング攻撃を避けるために、信頼できないユーザから来る可能性のあるヘルプテキストは必ずエスケープしてください。 ### `primary_key` #### `Field.primary_key` `True` の場合、設定したフィールドはそのモデルの主キーとなります。 モデル内のいずれのフィールドにも `primary_key=True` を指定せず、かつ複合主キーを定義していない場合、 Django は主キーを保持するためのフィールドを自動的に追加します。したがって、既定の主キー動作を上書きしたくなければ、どのフィールドにも `primary_key=True` を設定する必要はありません。自動作成される主キーの型は、アプリ単位では [`AppConfig.default_auto_field`](/ja/6.1/ref/applications/#django.apps.AppConfig.default_auto_field) 、グローバルには [`DEFAULT_AUTO_FIELD`](/ja/6.1/ref/settings/#std-setting-DEFAULT_AUTO_FIELD) 設定で指定できます。詳しくは [自動インクリメントの主キーフィールド](/ja/6.1/topics/db/models/#automatic-primary-key-fields) を参照してください。 `primary_key=True` は [`null=False`](#django.db.models.Field.null) および [`unique=True`](#django.db.models.Field.unique) を含意します。1 つのモデルで `primary_key=True` を設定できるフィールドは 1 つだけです。この不変条件を維持するため、複合主キーは、すべてのフィールドにこのフラグを `True` と設定するのではなく、[`CompositePrimaryKey`](#django.db.models.CompositePrimaryKey) を使用して定義しなければなりません。 主キーフィールドは読み取り専用です。既存のオブジェクトの主キーの値を変更して保存すると、古いオブジェクトはそのままで新しいオブジェクトが作成されます。 The primary key field is set to `None` when calling a model instance’s [`delete()`](/ja/6.1/ref/models/instances/#django.db.models.Model.delete) method. ### `unique` #### `Field.unique` `True` の場合、そのフィールドはテーブル上で一意となる制約を受けます。 これはデータベースレベルとモデルのバリデーションで強制されます。 [`unique`](#django.db.models.Field.unique) フィールドの値が重複しているモデルを保存しようとすると、モデルの [`save()`](/ja/6.1/ref/models/instances/#django.db.models.Model.save) メソッドによって [`django.db.IntegrityError`](/ja/6.1/ref/exceptions/#django.db.IntegrityError) が発生します。 このオプションは [`ManyToManyField`](#django.db.models.ManyToManyField) と [`OneToOneField`](#django.db.models.OneToOneField) 以外の全てのフィールドタイプで有効です。 `unique` が `True` の場合、[`db_index`](#django.db.models.Field.db_index) を指定する必要はないことに注意してください。なぜなら `unique` がインデックスの作成を意味するからです。 ### `unique_for_date` #### `Field.unique_for_date` これを [`DateField`](#django.db.models.DateField) または [`DateTimeField`](#django.db.models.DateTimeField) の名前に設定すると、このフィールドが日付フィールドの値に対して一意であることを要求します。 例えば、 `title` フィールドに `unique_for_date="pub_date"` を指定した場合、 Django は同じ `title` と `pub_date` を持つ 2 つのレコードの入力を許可しません。 [`DateTimeField`](#django.db.models.DateTimeField) を指すように設定した場合は、フィールドの日付部分のみが考慮されることに注意してください。また、 [`USE_TZ`](/ja/6.1/ref/settings/#std-setting-USE_TZ) が `True` の場合、オブジェクトの保存時に [カレントタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) でチェックが行われます。 This is enforced by [`Model.validate_unique()`](/ja/6.1/ref/models/instances/#django.db.models.Model.validate_unique) during model validation but not at the database level. If any [`unique_for_date`](#django.db.models.Field.unique_for_date) constraint involves fields that are not part of a [`ModelForm`](/ja/6.1/topics/forms/modelforms/#django.forms.ModelForm) (for example, if one of the fields is listed in `exclude` or has [`editable=False`](#django.db.models.Field.editable)), [`Model.validate_unique()`](/ja/6.1/ref/models/instances/#django.db.models.Model.validate_unique) will skip validation for that particular constraint. ### `unique_for_month` #### `Field.unique_for_month` [`unique_for_date`](#django.db.models.Field.unique_for_date) と似ていますが、フィールドが月に対して一意である必要があります。 ### `unique_for_year` #### `Field.unique_for_year` [`unique_for_date`](#django.db.models.Field.unique_for_date) や [`unique_for_month`](#django.db.models.Field.unique_for_month) と同様です。 ### `verbose_name` #### `Field.verbose_name` 人間が読めるフィールド名。verbose な名前が指定されていない場合、 Django はフィールドの属性名を使って自動的にフィールドを作成し、アンダースコアをスペースに変換します。詳しくは [verbose なフィールド名](/ja/6.1/topics/db/models/#verbose-field-names) を参照してください。 ### `validators` #### `Field.validators` このフィールドに対して実行するバリデータのリスト。詳細は [バリデータのドキュメント](/ja/6.1/ref/validators/) を参照してください。 ## フィールドの型 ### `AutoField` #### `class AutoField(**options)` 利用可能な ID に応じて、自動的にインクリメントする [`IntegerField`](#django.db.models.IntegerField) です。通常は直接使う必要はありません; 指定しない場合は、主キーのフィールドが自動的にモデルに追加されます。[自動インクリメントの主キーフィールド](/ja/6.1/topics/db/models/#automatic-primary-key-fields) も参照してください。 ### `BigAutoField` #### `class BigAutoField(**options)` 64 ビットの数値です。`1` から `9223372036854775807` までの数を扱える以外は、[`AutoField`](#django.db.models.AutoField) と同じです。 ### `BigIntegerField` #### `class BigIntegerField(**options)` 64 ビットの整数で、 [`IntegerField`](#django.db.models.IntegerField) とよく似ていますが、 `-9223372036854775808` から `9223372036854775807` までの数値が入ることが保証されています。このフィールドのデフォルトのフォームウィジェットは [`NumberInput`](/ja/6.1/ref/forms/widgets/#django.forms.NumberInput) です。 ### `BinaryField` #### `class BinaryField(max_length=None, **options)` 生のバイナリデータを格納するフィールドです。 [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes), [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray) または [`memoryview`](https://docs.python.org/3/library/stdtypes.html#memoryview) を指定できます。 デフォルトでは、 `BinaryField` は [`editable`](#django.db.models.Field.editable) を `False` に設定します。この場合、 [`ModelForm`](/ja/6.1/topics/forms/modelforms/#django.forms.ModelForm) に含めることはできません。 #### `BinaryField.max_length` オプション。フィールドの最大長 (バイト単位)。最大長は [`MaxLengthValidator`](/ja/6.1/ref/validators/#django.core.validators.MaxLengthValidator) を使ったDjango のバリデーションで強制されます。 > **BinaryField を誤用する** > > ファイルをデータベース内に格納したいと考えるかもしれませんが、99%のケースにおいてそれは悪い設計です。このフィールドは、適切な [静的ファイル](/ja/6.1/howto/static-files/) の取り扱いに対する代替手段では *ありません* 。 ### `BooleanField` #### `class BooleanField(**options)` true/false のフィールドです。 このフィールドのデフォルトのフォームウィジェットは [`CheckboxInput`](/ja/6.1/ref/forms/widgets/#django.forms.CheckboxInput) で、 [`null=True`](#django.db.models.Field.null) の場合は [`NullBooleanSelect`](/ja/6.1/ref/forms/widgets/#django.forms.NullBooleanSelect) です。 [`Field.default`](#django.db.models.Field.default) が定義されていないときの `BooleanField` のデフォルト値は `None` です。 ### `CompositePrimaryKey` #### `class CompositePrimaryKey(*field_names, **options)` 複合主キーを定義するために用いられる仮想的なフィールドです。 このフィールドはモデルの `pk` 属性として定義しなければなりません。これが存在する場合、 Django は基盤となるモデルテーブルを複合主キーで作成します。 `*field_names` 引数は主キーを構成する位置フィールド名のリストです。 詳細は [複合主キー](/ja/6.1/topics/composite-primary-key/) を参照してください。 ### `CharField` #### `class CharField(max_length=None, **options)` 小 - 大サイズの文字列のフィールドです。 多量のテキストを扱うときは [`TextField`](#django.db.models.TextField) を使ってください。 このフィールドのデフォルトのフォームウィジェットは [`TextInput`](/ja/6.1/ref/forms/widgets/#django.forms.TextInput) です。 [`CharField`](#django.db.models.CharField) には以下の追加引数があります： #### `CharField.max_length` フィールドの（文字数の）最大値。 `max_length` はデータベース層および class:~django.core.validators.MaxLengthValidator を使用した Django のバリデーションによる制約を受けます。無制限の `VARCHAR` 列をサポートする PostgreSQL と SQLite を除き、 Django でサポートされるすべてのデータベースバックエンドにおいて必須です。 > **Note** > > 複数のデータベースバックエンド間で使われるアプリケーションを作る場合は、いくつかのバックエンドで `max_length` に制限があることに注意しなければなりません。詳しくは [データベースバックエンドの注意事項](/ja/6.1/ref/databases/) を参照してください。 #### `CharField.db_collation` オプション。フィールドのデータベース照合順序名(collation name)です。 > **Note** > > 照合順序名は標準化されていません。そのため、これは複数のデータベースバックエンド間でポータブルではありません。 > **Oracle** > > Oracle が照合順序をサポートするのは、`MAX_STRING_SIZE` データベース初期化パラメータが `EXTENDED` に設定されている場合だけです。 ### `DateField` #### `class DateField(auto_now=False, auto_now_add=False, **options)` Python で `datetime.date` インスタンスによって表される日付です。多少の追加的な省略可能な引数を持ちます: #### `DateField.auto_now` オブジェクトが保存される度に自動的に現在の日付をセットします。"最後の変更" タイムスタンプに役立ちます。現在の日付が常に使われる点に注意してください; オーバーライドできる単なるデフォルト値ではありません。 [`Model.save()`](/ja/6.1/ref/models/instances/#django.db.models.Model.save) が呼ばれたとき、フィールドは自動的に更新されるだけです。[`QuerySet.update()`](/ja/6.1/ref/models/querysets/#django.db.models.query.QuerySet.update) のような別の方法で他のフィールドに更新を加えるとき、フィールドは更新されません。あのように更新の中でフィールドの独自の値を指定できるとしてもです。 #### `DateField.auto_now_add` オブジェクトが最初に作成されるとき、自動的にフィールドに現在の日付をセットします。タイムスタンプの作成に役立ちます。現在の日付が *常に* 使われる点に注意してください; オーバーライドできる単なるデフォルト値ではありません。たとえオブジェクトを作成するときに値をセットしたとしても無視されます。このフィールドを修正できるようにしておきたい場合は、`auto_now_add=True` の代わりに以下をセットしてください: - [`DateField`](#django.db.models.DateField) に対して: `default=date.today` \- [`datetime.date.today()`](https://docs.python.org/3/library/datetime.html#datetime.date.today) より - [`DateTimeField`](#django.db.models.DateTimeField) に対して: `default=timezone.now` \- [`django.utils.timezone.now()`](/ja/6.1/ref/utils/#django.utils.timezone.now) より このフィールドのデフォルトのフォームウィジェットは [`DateInput`](/ja/6.1/ref/forms/widgets/#django.forms.DateInput) です。admin は JavaScript カレンダーと "Today" のショートカットを追加します。追加の `invalid_date` エラーメッセージキーを含みます。 オプション `auto_now_add`、`auto_now`、`default` は相互に排他的です。これらのオプションを組み合わせるとエラーが発生します。 > **Note** > > 現在実装されているように、`auto_now` や `auto_now_add` を `True` にセットすると、フィールドは `editable=False` と `blank=True` にセットされます。 > **Note** > > `auto_now` と `auto_now_add` オプションは、常に作成時または更新時の [デフォルトのタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) の日付を使用します。もし別のものが必要であれば、`auto_now` や `auto_now_add` を使用する代わりに、独自の呼び出し可能オブジェクトをデフォルトとして使用するか、 `save()` をオーバーライドするか、あるいは `DateField` の代わりに `DateTimeField` を使用し、表示時に datetime から date への変換をどのように処理するかを検討するとよいでしょう。 > **Warning** > > [`DateField`](#django.db.models.DateField) には常に `datetime.date` インスタンスを使用してください。 > > `datetime.datetime` インスタンスを持っている場合は、まずそれを `datetime.date` に変換することをお勧めします。変換しない場合、[`DateField`](#django.db.models.DateField) は `datetime.datetime` を [デフォルトのタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) にローカライズし、`datetime.date` インスタンスに変換してその時間部分を削除します。これは、保存および比較の両方において当てはまります。 > **Warning** > > PostgreSQL と MySQL では、`DateField` に対して [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) を用いた算術演算を行うと、 `date` ではなく datetime が返されます。これは、Python の `timedelta` が SQL の ```INTERVAL ``に変換され、これらのデータベースでは ``date +/- interval``` という SQL 演算の結果が `timestamp` になるためです。 > > `date` 型の結果を得るには、次のいずれかの方法を使用してください。基本的には、結果を明示的に `date` 型へキャストすることになります。 > > ``` > import datetime > from django.db.models import DateField, F > from django.db.models.functions import Cast > > qs = MyModel.objects.annotate( > previous_day=Cast( > F("date_field") - datetime.timedelta(days=1), > output_field=DateField(), > ) > ) > ``` > > あるいは、 PostgreSQL だけですが、日数を整数演算として扱うこともできます。 > > ``` > from django.db.models import DateField, ExpressionWrapper, F > > qs = MyModel.objects.annotate( > previous_day=ExpressionWrapper( > F("date_field") - 1, # Subtract 1 day as integer > output_field=DateField(), > ) > ) > ``` ### `DateTimeField` #### `class DateTimeField(auto_now=False, auto_now_add=False, **options)` Python で `datetime.datetime` インスタンスによって表される日付と時刻です。[`DateField`](#django.db.models.DateField) と同じくいくつかの追加的な引数を持ちます: このフィールドのデフォルトのフォームウィジェットは [`DateTimeInput`](/ja/6.1/ref/forms/widgets/#django.forms.DateTimeInput) です。管理画面では、JavaScript のショートカットを使って [`TextInput`](/ja/6.1/ref/forms/widgets/#django.forms.TextInput) ウィジェットを 2 つに分けて使用します。 > **Warning** > > [`DateTimeField`](#django.db.models.DateTimeField) には常に `datetime.datetime` インスタンスを使用してください。 > > `datetime.date` インスタンスを持っている場合は、まずそれを `datetime.datetime` に変換することをお勧めします。変換しない場合、[`DateTimeField`](#django.db.models.DateTimeField) は時間部分に [デフォルトのタイムゾーン](/ja/6.1/topics/i18n/timezones/#default-current-time-zone) の午前0時を使用します。これは、保存および比較の両方において当てはまります。`datetime.date` インスタンスと [`DateTimeField`](#django.db.models.DateTimeField) の日付部分を比較するには、[`date`](/ja/6.1/ref/models/querysets/#std-fieldlookup-date) ルックアップを使用してください。 ### `DecimalField` #### `class DecimalField(max_digits=None, decimal_places=None, **options)` 固定精度の10進数で、Python では [`Decimal`](https://docs.python.org/3/library/decimal.html#decimal.Decimal) インスタンスで表されます。これは [`DecimalValidator`](/ja/6.1/ref/validators/#django.core.validators.DecimalValidator) を使用して入力を検証します。 Has the following arguments: #### `DecimalField.max_digits` The maximum number of digits allowed in the number. Note that this number must be greater than or equal to `decimal_places`. It's always required on MySQL because this database doesn't support numeric fields with no precision. It's also required for all database backends when [`decimal_places`](#django.db.models.DecimalField.decimal_places) is provided. #### `DecimalField.decimal_places` The number of decimal places to store with the number. It's always required on MySQL because this database doesn't support numeric fields with no precision. It's also required for all database backends when [`max_digits`](#django.db.models.DecimalField.max_digits) is provided. 例えば、小数点以下2桁の分解能で `999.99` までの数値を保存するには、次のようにします： ``` models.DecimalField(..., max_digits=5, decimal_places=2) ``` 小数点以下第10位の精度で約10億までを保持するには: ``` models.DecimalField(..., max_digits=19, decimal_places=10) ``` このフィールドのデフォルトのフォームウィジェットは、[`localize`](/ja/6.1/ref/forms/fields/#django.forms.Field.localize) が `False` のとき [`NumberInput`](/ja/6.1/ref/forms/widgets/#django.forms.NumberInput) で、そうでなければ [`TextInput`](/ja/6.1/ref/forms/widgets/#django.forms.TextInput) となります。 > **Note** > > [`FloatField`](#django.db.models.FloatField) クラスと [`DecimalField`](#django.db.models.DecimalField) クラスの違いについては [FloatField vs. DecimalField](#floatfield-vs-decimalfield) を参照してください。また、Decimal に関する [SQLite の制限](/ja/6.1/ref/databases/#sqlite-decimal-handling) についても注意してください。 > **Changed in Django 6.1** > > Support for `DecimalField` with no precision was added on Oracle, > PostgreSQL, and SQLite. ### `DurationField` #### `class DurationField(**options)` 時刻の期間を保持するフィールドで、 Python の [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) によってモデル化されます。PostgreSQL で使われるときに用いられるデータ型は `interval` で、Oracle でのデータ型は `INTERVAL DAY(9) TO SECOND(6)` です。 それ以外では、マイクロ秒の `bigint` が使われます。 > **Note** > > `DurationField` での演算はほとんどの場合で機能します。ただし、PostgreSQL 以外のデータベースでは、`DurationField` の値と `DateTimeField` インスタンス上の演算を比較することは期待通りに機能しません。 ### `EmailField` #### `class EmailField(max_length=254, **options)` [`EmailValidator`](/ja/6.1/ref/validators/#django.core.validators.EmailValidator) を使って、値が有効なメールアドレスであるかどうかをチェックする [`CharField`](#django.db.models.CharField) です。 ### `FileField` #### `class FileField(upload_to='', storage=None, max_length=100, **options)` ファイルアップロードのフィールドです。 > **Note** > > `primary_key` 引数はサポートされておらず、使用するとエラーになります。 以下のオプション引数があります： #### `FileField.upload_to` この属性は、アップロードディレクトリとファイル名を設定する方法を提供し、2 つの方法でセットできます。どちらの場合も、値は [`Storage.save()`](/ja/6.1/ref/files/storage/#django.core.files.storage.Storage.save) メソッドに渡されます。 文字列値または [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) を指定する場合、 [`strftime()`](https://docs.python.org/3/library/time.html#time.strftime) フォーマットを含むことができます。これはファイルアップロードの日時に置き換えられます（アップロードされたファイルで指定されたディレクトリが一杯にならないようにするためです）。例えば以下のようにします： ``` class MyModel(models.Model): # file will be uploaded to MEDIA_ROOT/uploads upload = models.FileField(upload_to="uploads/") # or... # file will be saved to MEDIA_ROOT/uploads/2015/01/30 upload = models.FileField(upload_to="uploads/%Y/%m/%d/") ``` デフォルトの [`FileSystemStorage`](/ja/6.1/ref/files/storage/#django.core.files.storage.FileSystemStorage) を使用している場合、この文字列の値が [`MEDIA_ROOT`](/ja/6.1/ref/settings/#std-setting-MEDIA_ROOT) パスに追加され、アップロードされたファイルが保存されるローカルファイルシステムの場所になります。別のストレージを使用している場合は、そのストレージのドキュメントで `upload_to` の扱い方を確認してください。 `upload_to` は関数のなどの呼び出し可能オブジェクトにすることもできます。これはファイル名を含むアップロードパスを取得するために呼び出されます。この呼び出し可能オブジェクトは2つの引数を受け取り、ストレージシステムに渡すUnixスタイルのパス（フォワードスラッシュ付き）を返さなければなりません。2つの引数は | 引数 | 説明 | | --- | --- | | `instance` | `FileField` が定義されているモデルのインスタンス。具体的には、そのファイルが格納されている特定のインスタンスです。

ほとんどの場合、このオブジェクトはまだデータベースに保存されていないため、デフォルトの `AutoField` を使用している場合、 *主キーフィールドの値をまだ持っていない可能性があります* 。 | | `filename` | ファイルに元々与えられていたファイル名。これは、最終的な宛先パスを決定するときに考慮されることもあれば、考慮されないこともあります。 | 例: ``` def user_directory_path(instance, filename): # file will be uploaded to MEDIA_ROOT/user_/ return "user_{0}/{1}".format(instance.user.id, filename) class MyModel(models.Model): upload = models.FileField(upload_to=user_directory_path) ``` #### `FileField.storage` ストレージオブジェクト、またはストレージオブジェクトを返す呼び出し可能オブジェクトです。これはファイルの保存と取得を行います。このオブジェクトの渡し方の詳細については [ファイルの管理](/ja/6.1/topics/files/) を参照してください。 このフィールドのデフォルトのフォームウィジェットは [`ClearableFileInput`](/ja/6.1/ref/forms/widgets/#django.forms.ClearableFileInput) です。 モデル内で a [`FileField`](#django.db.models.FileField) や [`ImageField`](#django.db.models.ImageField) (後述) 使うにはいくつかのステップを取ります: 1. 設定ファイルでは、 [`MEDIA_ROOT`](/ja/6.1/ref/settings/#std-setting-MEDIA_ROOT) を Django にアップロードされたファイルを保存するディレクトリへのフルパスを指定する必要があります（パフォーマンス上、これらのファイルはデータベースには保存されません）。 [`MEDIA_URL`](/ja/6.1/ref/settings/#std-setting-MEDIA_URL) をそのディレクトリの公開 URL にします。このディレクトリは Web サーバのユーザアカウントで書き込み可能である必要があります。 2. モデルに [`FileField`](#django.db.models.FileField) または [`ImageField`](#django.db.models.ImageField) を追加し、 [`upload_to`](#django.db.models.FileField.upload_to) オプションを定義して、ファイルをアップロードする [`MEDIA_ROOT`](/ja/6.1/ref/settings/#std-setting-MEDIA_ROOT) のサブディレクトリを指定します。 3. データベースに保存されるのは、ファイルへのパス ([`MEDIA_ROOT`](/ja/6.1/ref/settings/#std-setting-MEDIA_ROOT) からの相対パス) だけです。Django 組み込みの [`url`](#django.db.models.fields.files.FieldFile.url) 属性を使うと便利です。例えば、 [`ImageField`](#django.db.models.ImageField) が `mug_shot` という名前の場合、 `{{ object.mug_shot.url }}` でテンプレート内の画像の絶対パスを取得できます。 例えば、 [`MEDIA_ROOT`](/ja/6.1/ref/settings/#std-setting-MEDIA_ROOT) が `'/home/media'` に設定され、 [`upload_to`](#django.db.models.FileField.upload_to) が `'photos/%Y/%m/%d'` に設定されているとします。 [`upload_to`](#django.db.models.FileField.upload_to) の `'%Y/%m/%d'` の部分は [`strftime()`](https://docs.python.org/3/library/time.html#time.strftime) フォーマットです。`'%Y'` は4桁の年、`'%m'` は2桁の月、`'%d'` は2桁の日です。2007年1月15日にファイルをアップロードすると、 `/home/media/photos/2007/01/15` というディレクトリに保存されます。 アップロードされたファイルのディスク上のファイル名やファイルサイズを取得したい場合は、それぞれ [`name`](/ja/6.1/ref/files/file/#django.core.files.File.name) 属性と [`size`](/ja/6.1/ref/files/file/#django.core.files.File.size) 属性を使うことができます。利用可能な属性やメソッドの詳細については [`File`](/ja/6.1/ref/files/file/#django.core.files.File) クラスリファレンス と [ファイルの管理](/ja/6.1/topics/files/) トピックガイド を参照してください。 > **Note** > > このファイルは、モデルをデータベースに保存する際に一緒に保存されるため、ディスク上で実際に使用されるファイル名は、モデルが保存されるまで当てになりません。 アップロードされたファイルの相対URLは [`url`](#django.db.models.fields.files.FieldFile.url) 属性で取得できます。内部的には、 [`Storage`](/ja/6.1/ref/files/storage/#django.core.files.storage.Storage) クラスの [`url()`](/ja/6.1/ref/files/storage/#django.core.files.storage.Storage.url) メソッドを呼び出します。 アップロードされたファイルを扱うときは常に、セキュリティホールを避けるために、アップロードする場所とファイルの種類に細心の注意を払う必要があることに注意してください。 *アップロードされたすべてのファイルを検証し* 、そのファイルがあなたが考えているものであることを確認してください。例えば、誰かがあなたのウェブサーバーのドキュメントルートにあるディレクトリに、検証なしでファイルをアップロードするのをやみくもに許可すると、誰かがCGIやPHPスクリプトをアップロードし、あなたのサイトのそのURLにアクセスしてスクリプトを実行できます。それを許してはいけません。 また、アップロードされたHTMLファイルであっても、ブラウザが実行できるため（サーバは実行できませんが）、XSS攻撃やCSRF攻撃と同様のセキュリティ上の脅威をもたらす可能性があることに注意してください。 [`FileField`](#django.db.models.FileField) インスタンスは `varchar` カラムとしてデータベースに作成され、デフォルトの最大長は100文字です。他のフィールドと同様に、 [`max_length`](#django.db.models.CharField.max_length) 引数を使用して最大長を変更できます。 #### `FileField` と `FieldFile` #### `class FieldFile` モデル上の [`FileField`](#django.db.models.FileField) にアクセスするとき、元となるファイルにアアクセスするためのプロキシとして、[`FieldFile`](#django.db.models.fields.files.FieldFile) のインスタンスが与えられます。 [`FieldFile`](#django.db.models.fields.files.FieldFile) の API は [`File`](/ja/6.1/ref/files/file/#django.core.files.File) の API を反映していますが、主な違いが 1 つあります: *クラスによってラップされたオブジェクトは必ずしも Python のビルトインのファイルオブジェクトのラッパーであるとは限りません。* 代わりに、[`Storage.open()`](/ja/6.1/ref/files/storage/#django.core.files.storage.Storage.open) メソッドの結果を包むラッパーで、これは [`File`](/ja/6.1/ref/files/file/#django.core.files.File) オブジェクトもしくは [`File`](/ja/6.1/ref/files/file/#django.core.files.File) API の独自ストレージの実装となります。 `read()` や `write()` など、[`File`](/ja/6.1/ref/files/file/#django.core.files.File) から継承されたAPIに加えて、[`FieldFile`](#django.db.models.fields.files.FieldFile) には基になるファイルとやり取りするために使用できるいくつかのメソッドが含まれています： > **Warning** > > このクラスの 2 つのメソッド、[`save()`](#django.db.models.fields.files.FieldFile.save) と [`delete()`](#django.db.models.fields.files.FieldFile.delete) は、デフォルトで、関連する FieldFile のモデルオブジェクトをデータベースに保存します。 #### `FieldFile.name` 関連する [`FileField`](#django.db.models.FileField) の [`Storage`](/ja/6.1/ref/files/storage/#django.core.files.storage.Storage) のルートからの相対パスを含むファイル名です。 #### `FieldFile.path` ファイルのローカルファイルシステムパスにアクセスするための読み取り専用プロパティ。基になる [`Storage`](/ja/6.1/ref/files/storage/#django.core.files.storage.Storage) クラスの [`path()`](/ja/6.1/ref/files/storage/#django.core.files.storage.Storage.path) メソッドを呼び出します。 #### `FieldFile.size` 元となる [`Storage.size()`](/ja/6.1/ref/files/storage/#django.core.files.storage.Storage.size) メソッドの結果です。 #### `FieldFile.url` 元となる [`Storage`](/ja/6.1/ref/files/storage/#django.core.files.storage.Storage) クラス の [`url()`](/ja/6.1/ref/files/storage/#django.core.files.storage.Storage.url) メソッドを呼ぶことによって、ファイルの相対 URL にアクセスするための読み取り専用プロパティです。 #### `FieldFile.open(mode='rb')` このインスタンスに関連付けられたファイルを、指定された `モード` で開くか、開き直します。標準の Python の `open()` メソッドとは違い、ファイルのデスクリプタを返しません。 元となるファイルはアクセスするときに暗黙的に開かれるので、元となるファイルにポインタをリセットするためか `モード` を変更するため以外には、このメソッドを呼ぶ必要はないでしょう。 #### `FieldFile.close()` 標準の Python の `file.close()` メソッドのように動作し、このインスタンスに関連付けられたファイルを閉じます。 #### `FieldFile.save(name, content, save=True)` このメソッドは、ファイル名とファイルの内容を取り、それらをフィールドのストレージクラスに渡し、格納されたファイルをモデルフィールドに関連付けます。 手動でファイルデータをモデル上の [`FileField`](#django.db.models.FileField) インスタンスに関連付けるには、 `save()` メソッドを使用してそのファイルデータを保持します。 Takes two required arguments: `name` which is the name of the file, and `content` which is an object containing the file's contents. The optional `save` argument controls whether or not the model instance is saved after the file associated with this field has been altered. Defaults to `True`. `content` 引数は、Python のビルトインのファイルオブジェクトではなく、[`django.core.files.File`](/ja/6.1/ref/files/file/#django.core.files.File) のインスタンスでなければならないことに注意してください。 以下のように、既存の Python ファイルオブジェクトから [`File`](/ja/6.1/ref/files/file/#django.core.files.File) を構築できます: ``` from django.core.files import File # Open an existing file using Python's built-in open() f = open("/path/to/hello.world") myfile = File(f) ``` もしくは、以下のように Python の文字列から構築することもできます: ``` from django.core.files.base import ContentFile myfile = ContentFile("hello world") ``` より詳しくは [ファイルの管理](/ja/6.1/topics/files/) を参照してください。 #### `FieldFile.delete(save=True)` このインスタンスに関連付けられているファイルを削除し、フィールドのすべての属性をクリアします。 注: このメソッドは、`delete()` が呼び出されたときにファイルが開いた場合、ファイルを閉じます。 省略可能な `save` 引数は、このフィールドに関連付けられたファイルが削除された後にモデルインスタンスを保存するかどうかをコントロールします。 デフォルトは `True` です。 モデルを削除するとき、関連ファイルは削除されない点に注意してください。 孤立したファイルをクリーンアップする必要がある場合、自分で処理する必要があります (たとえば、手動で実行したり、cron などを通して定期的に実行される独自の管理コマンドです)。 ### `FilePathField` #### `class FilePathField(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options)` [`CharField`](#django.db.models.CharField) は選択肢をファイルシステム上の特定のディレクトリにあるファイル名に限定します。いくつかの特別な引数を持ちますが、最初の引数は **必須** です： #### `FilePathField.path` 必須です。[`FilePathField`](#django.db.models.FilePathField) が選択肢から取得するディレクトリへの、ファイルシステムの絶対パスです。例: `"/home/images"`。 `path` には呼び出し可能オブジェクトを指定することもでき、これは例えば実行時に動的にパスを設定する関数などです。例： ``` import os from django.conf import settings from django.db import models def images_path(): return os.path.join(settings.LOCAL_FILE_DIR, "images") class MyModel(models.Model): file = models.FilePathField(path=images_path) ``` #### `FilePathField.match` 省略可能です。正規表現で、文字列として、[`FilePathField`](#django.db.models.FilePathField) がファイル名をフィルタリングするために使用します。 正規表現は、フルパスではなくベースファイル名に適用される点に注意してください。 例: `"foo.*\.txt$"`。これは `foo23.txt` とは合致しますが、`bar.txt` や `foo23.png` とは合致しません。 #### `FilePathField.recursive` 省略可能です。`True` か `False` のどちらかを取り、デフォルトは `False` です。[`path`](#django.db.models.FilePathField.path) の全てのサブディレクトリを含むかどうかを指定します。 #### `FilePathField.allow_files` Optional. Either `True` or `False`. Default is `True`. Specifies whether files in the specified location should be included. Either this or [`allow_folders`](#django.db.models.FilePathField.allow_folders) must be `True`. #### `FilePathField.allow_folders` Optional. Either `True` or `False`. Default is `False`. Specifies whether folders in the specified location should be included. Either this or [`allow_files`](#django.db.models.FilePathField.allow_files) must be `True`. 1つの可能性は、フルパスではなく、ベースファイル名に [`match`](#django.db.models.FilePathField.match) が適用されることです。 したがって、この例: ``` FilePathField(path="/home/images", match="foo.*", recursive=True) ``` ...は、`/home/images/foo/bar.png` ではなく `/home/images/foo.png` とマッチします。これは、[`match`](#django.db.models.FilePathField.match) がベースのファイル名に適用されるからです (`foo.png` と `bar.png`)。 [`FilePathField`](#django.db.models.FilePathField) のインスタンスは、デフォルトが最大 100 文字の `varchar` カラムとして、データベース上に生成されます。他のフィールドと同様に、[`max_length`](#django.db.models.CharField.max_length) 引数を使って最大文字数を変更できます。 ### `FloatField` #### `class FloatField(**options)` `float` インスタンスによって表される Python の浮動小数点数です。 このフィールドのデフォルトのフォームウィジェットは、[`localize`](/ja/6.1/ref/forms/fields/#django.forms.Field.localize) が `False` のとき [`NumberInput`](/ja/6.1/ref/forms/widgets/#django.forms.NumberInput) で、そうでなければ [`TextInput`](/ja/6.1/ref/forms/widgets/#django.forms.TextInput) となります。 > **FloatField と DecimalField の比較** > > [`FloatField`](#django.db.models.FloatField) クラスは、[`DecimalField`](#django.db.models.DecimalField) クラスと混同されることがあります。両方とも実数を表しますが、異なる方法で表現しています。`FloatField` は内部的には Python の `float` 型を使い、`DecimalField` は Python の `Decimal` 型を使います。この 2 つの違いについては、 Python のドキュメント [`decimal`](https://docs.python.org/3/library/decimal.html#module-decimal) module を参照してください。 ### `GeneratedField` #### `class GeneratedField(* (Keyword-only parameters separator (PEP 3102)), expression, output_field, db_persist, **kwargs)` 常にモデル内の他のフィールドに基づいて計算されるフィールド。このフィールドはデータベース自身によって管理・更新されます。 `GENERATED ALWAYS` SQL 構文を使います。 生成カラムには、格納と仮想の2種類があります。格納生成カラムは書き込まれる (挿入もしくは更新される) ときに計算され、通常のカラムと同じようにストレージを占有します。仮想生成カラムはストレージを占有せず、読み込まれるときに計算されます。したがって、仮想生成カラムはビューに似ており、格納生成カラムはマテリアライズド・ビューに似ています。 #### `GeneratedField.expression` モデルが変更されるたびにフィールドの値を自動的に設定するためにデータベースによって使用される [`Expression`](/ja/6.1/ref/models/expressions/#django.db.models.Expression) 。 式は決定論的でなければならず、モデル内の（同じデータベース・テーブル内の）フィールドだけを参照しなければなりません。生成フィールドは他の生成フィールドを参照することはできません。データベースのバックエンドはさらなる制限を課すことができます。 #### `GeneratedField.output_field` フィールドのデータ型を定義するモデルフィールドインスタンス。 #### `GeneratedField.db_persist` データベースカラムが実際のカラムのようにストレージを占有するかどうかを決定します。 `False` の場合、カラムは仮想カラムとして動作し、データベースのストレージ領域を占有しません。 PostgreSQL \< 18 only supports persisted columns. Oracle \< 23ai/26ai (23.7) only supports virtual columns. > **Changed in Django 6.1** > > Support for virtual `GeneratedField`s was added on Postgres 18+ and > for stored ones on Oracle 23ai/26ai (23.7+). > **データベースの制約** > > 生成フィールドに関しては多くのデータベース固有の制限があり、Djangoはそれらを検証しないため、データベースがエラーを発生させる可能性があります。例えば、PostgreSQLでは、生成カラムで参照される関数や演算子は `IMMUTABLE` としてマークされている必要があります。 > > あなたのデータベースで `expression` がサポートされているかどうかを常に確認する必要があります。 [MariaDB](https://mariadb.com/kb/en/generated-columns/#expression-support), [MySQL](https://dev.mysql.com/doc/refman/en/create-table-generated-columns.html), [Oracle](https://docs.oracle.com/en/database/oracle/oracle-database/21/sqlrf/CREATE-TABLE.html#GUID-F9CE0CC3-13AE-4744-A43C-EAC7A71AAAB6__BABIIGBD), [PostgreSQL](https://www.postgresql.org/docs/current/ddl-generated-columns.html), [SQLite](https://www.sqlite.org/gencol.html#limitations) のドキュメントを確認してください。 > **Changed in Django 6.0** > > `GeneratedField`s are now automatically refreshed from the database on > backends that support it (SQLite, PostgreSQL, and Oracle) and marked as > deferred otherwise. [`null`](#django.db.models.Field.null) has no effect on `GeneratedField` since whether the column is nullable depends on the database and expression used. ### `GenericIPAddressField` #### `class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)` IPv4 か IPv6 のアドレスで、文字列フォーマットです (例: `192.0.2.30` ないし `2a02:42fe::4`)。このフィールドのデフォルトのフォームウィジェットは [`TextInput`](/ja/6.1/ref/forms/widgets/#django.forms.TextInput) です。 IPv6 アドレスは、 [**RFC 4291 Section 2.2**](https://datatracker.ietf.org/doc/html/rfc4291.html#section-2.2) section 2.2 (同セクションの paragraph 3 で提案された IPv4 のフォーマットの使用を含む) にしたがって、 `::ffff:192.0.2.0` のように正規化します。たとえば、 `2001:0::0:01` は `2001::1` と正規化され、 `::ffff:0a0a:0a0a` は `::ffff:10.10.10.10` と正規化されます。そして、すべての文字は小文字に変換されます。 #### `GenericIPAddressField.protocol` 有効なインプットを、指定したプロトコルに制限します。 使用可能な値は `'both'` (デフォルト)、`'IPv4'`、`'IPv6'` のどれかです。マッチングは大文字と小文字を区別しません。 #### `GenericIPAddressField.unpack_ipv4` IPv4 にマッピングされた `::ffff:192.0.2.1` のようなアドレスをアンパックします。このオプションを有効にすると、このアドレスは `192.0.2.1` とアンパックされます。デフォルトは無効です。`protocol` が `'both'` に設定されている場合にだけ使用できます。 ブランク値を要する場合、ブランク値は null として保持されるため、null 値を許容する必要があります。 ### `ImageField` #### `class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)` [`FileField`](#django.db.models.FileField) から全ての属性とメソッドを継承して、さらにアップロードされたオブジェクトが有効な画像であることを検証します。 [`FileField`](#django.db.models.FileField) で使える専用の属性に加えて、[`ImageField`](#django.db.models.ImageField) には `height` と `width` 属性があります。 これらの属性に対するクエリを容易にするために、[`ImageField`](#django.db.models.ImageField) は以下のオプション引数を持ちます： #### `ImageField.height_field` 画像オブジェクトがセットされるたびに自動的に画像の高さが入力されるモデルフィールドの名前。 #### `ImageField.width_field` 画像オブジェクトがセットされるたびに自動的に画像の幅が入力されるモデルフィールドの名前。 [pillow](https://pypi.org/project/pillow/) ライブラリを必要とします。 [`ImageField`](#django.db.models.ImageField) のインスタンスは、デフォルトが最大 100 文字の `varchar` カラムとして、データベース上に生成されます。他のフィールドと同様に、[`max_length`](#django.db.models.CharField.max_length) 引数を使って最大文字数を変更できます。 このフィールドのデフォルトのフォームウィジェットは [`ClearableFileInput`](/ja/6.1/ref/forms/widgets/#django.forms.ClearableFileInput) です。 ### `IntegerField` #### `class IntegerField(**options)` 整数値です。特定範囲の値のみ使用可能です (その範囲はデータベースに依存します)。 `-2147483648` から `2147483647` までの値は、Django がサポートするすべてのデータベースで安全に使用できます。 [`MinValueValidator`](/ja/6.1/ref/validators/#django.core.validators.MinValueValidator) と [`MaxValueValidator`](/ja/6.1/ref/validators/#django.core.validators.MaxValueValidator) を使って、デフォルトのデータベースがサポートする値に基づいて入力を検証します。 このフィールドのデフォルトのフォームウィジェットは、[`localize`](/ja/6.1/ref/forms/fields/#django.forms.Field.localize) が `False` のとき [`NumberInput`](/ja/6.1/ref/forms/widgets/#django.forms.NumberInput) で、そうでなければ [`TextInput`](/ja/6.1/ref/forms/widgets/#django.forms.TextInput) となります。 ### `JSONField` #### `class JSONField(encoder=None, decoder=None, **options)` JSON エンコードされたデータを格納するためのフィールドです。Python では、データは Python ネイティブフォーマットで表現されます。辞書、リスト、文字列、数値、真偽値、そして `None` です。 `JSONField` はMariaDB、MySQL、Oracle、PostgreSQL、([JSON1 エクステンションが有効な](/ja/6.1/ref/databases/#sqlite-json1)) SQLite でサポートされています。 #### `JSONField.encoder` An optional [`json.JSONEncoder`](https://docs.python.org/3/library/json.html#json.JSONEncoder) subclass to serialize data types not supported by the standard JSON serializer (e.g. `datetime.datetime` or [`UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID)). For example, you can use the [`DjangoJSONEncoder`](/ja/6.1/topics/serialization/#django.core.serializers.json.DjangoJSONEncoder) class. デフォルトは `json.JSONEncoder` です。 #### `JSONField.decoder` An optional [`json.JSONDecoder`](https://docs.python.org/3/library/json.html#json.JSONDecoder) subclass to deserialize the value retrieved from the database. The value will be in the format chosen by the custom encoder (most often a string). Your deserialization may need to account for the fact that you can't be certain of the input type. For example, you run the risk of returning a `datetime` that was actually a string that just happened to be in the same format chosen for `datetime`s. デフォルトは `json.JSONDecoder` です。 データベース内の `JSONField` をクエリするには、 [JSONField へのクエリ](/ja/6.1/topics/db/queries/#querying-jsonfield) を参照してください。 > **デフォルト値について** > > If you give the field a [`default`](#django.db.models.Field.default), ensure > it's a callable such as the [`dict`](https://docs.python.org/3/library/stdtypes.html#dict) class or a function that > returns a fresh object each time. Incorrectly using a mutable object like > `default={}` or `default=[]` creates a mutable default that is shared > between all instances. > **インデックスの作成** > > [`Index`](/ja/6.1/ref/models/indexes/#django.db.models.Index) と [`Field.db_index`](#django.db.models.Field.db_index) はどちらも B-tree インデックスを作成しますが、`JSONField` をクエリする際には特に役に立ちません。PostgreSQL でだけ、より適した [`GinIndex`](/ja/6.1/ref/contrib/postgres/indexes/#django.contrib.postgres.indexes.GinIndex) を使うことができます。 > **PostgreSQL ユーザーの場合** > > PostgreSQLには2つのJSONベースのデータ型があります。 `json` と `jsonb` です。これらの主な違いは、格納方法とクエリ方法です。PostgreSQLの `json` フィールドはJSONの元の文字列表現として格納され、キーに基づいてクエリを行うにはその場でデコードする必要があります。 `jsonb` フィールドはJSONの実際の構造に基づいて格納され、インデックスを作成できます。そのトレードオフとして、`jsonb` フィールドへの書き込みに若干の追加コストが発生します。 `JSONField` は `jsonb` を使用します。 > **Oracle のユーザーの場合** > > Oracle Database does not support storing JSON scalar values. Only JSON > objects and arrays (represented in Python using [`dict`](https://docs.python.org/3/library/stdtypes.html#dict) and > [`list`](https://docs.python.org/3/library/stdtypes.html#list)) are supported. ### `PositiveBigIntegerField` #### `class PositiveBigIntegerField(**options)` [`PositiveIntegerField`](#django.db.models.PositiveIntegerField) とほぼ同じですが、特定の数以下の値のみ使用可能です (その上限はデータベースに依存します)。 `0` から `9223372036854775807` までの値は、 Django がサポートする全てのデータベースで安全に使用できます。 ### `PositiveIntegerField` #### `class PositiveIntegerField(**options)` [`IntegerField`](#django.db.models.IntegerField) とほぼ同じですが、ゼロ( `0` )以上の整数で、特定の数以下の値のみ使用可能です (その上限はデータベースに依存します)。 `0` から `2147483647` までの値は、 Django がサポートするすべてのデータベースで安全に使用できます。値 `0` は後方互換性のために許容されています。 ### `PositiveSmallIntegerField` #### `class PositiveSmallIntegerField(**options)` class:PositiveIntegerField とほぼ同じですが、特定の数以下の値のみ使用可能です (その上限はデータベースに依存します)。 `0` から `32767` までの値は、 Django がサポートする全てのデータベースで安全に使用できます。 ### `SlugField` #### `class SlugField(max_length=50, **options)` [スラグ (slug)](/ja/6.1/glossary/#term-slug) は新聞用語です。スラグとは、アルファベット、数字、アンダースコア、またはハイフンのみを含む、何かの短いラベルです。一般的にURLで使われます。 CharField のように、[`max_length`](#django.db.models.CharField.max_length) を指定することもできます (データベースの可搬性についてのノートとそのセクションの [`max_length`](#django.db.models.CharField.max_length) も参照してください)。[`max_length`](#django.db.models.CharField.max_length) が指定されていないとき、Django はデフォルトの文字数 50 を使います。 暗黙的に [`Field.db_index`](#django.db.models.Field.db_index) を `True` にセットします。 It is often useful to automatically prepopulate a SlugField based on the value of some other value. You can do this automatically in the admin using [`prepopulated_fields`](/ja/6.1/ref/contrib/admin/#django.contrib.admin.ModelAdmin.prepopulated_fields). バリデーションには [`validate_slug`](/ja/6.1/ref/validators/#django.core.validators.validate_slug) または [`validate_unicode_slug`](/ja/6.1/ref/validators/#django.core.validators.validate_unicode_slug) を使用します。 #### `SlugField.allow_unicode` `True` なら、フィールドはASCII文字に加えてUnicode文字も受け付けます。デフォルトは `False` です。 ### `SmallAutoField` #### `class SmallAutoField(**options)` class:AutoField とほぼ同じですが、特定の数以下の値のみ使用可能です (その上限はデータベースに依存します)。 `1` から `32767` までの値は、 Django がサポートする全てのデータベースで安全に使用できます。 ### `SmallIntegerField` #### `class SmallIntegerField(**options)` class:IntegerField とほぼ同じですが、特定の数以下の値のみ使用可能です (その上限はデータベースに依存します)。 `-32768` から `32767` までの値は、 Django がサポートする全てのデータベースで安全に使用できます。 ### `TextField` #### `class TextField(**options)` 多量のテキストのフィールドです。このフィールドのデフォルトのフォームウィジェットは [`Textarea`](/ja/6.1/ref/forms/widgets/#django.forms.Textarea) です。 `max_length` 属性を指定した場合、自動生成されたフォームフィールドの [`Textarea`](/ja/6.1/ref/forms/widgets/#django.forms.Textarea) ウィジェット内で反映されます。ただし、モデルやデータベースのレベルでは施行されません。そのためには [`CharField`](#django.db.models.CharField) を使用してください。 #### `TextField.db_collation` オプション。フィールドのデータベース照合順序名(collation name)です。 > **Note** > > 照合順序名は標準化されていません。そのため、これは複数のデータベースバックエンド間でポータブルではありません。 > **Oracle** > > Oracle は `TextField` の照合順序 (collation) をサポートしていません。 ### `TimeField` #### `class TimeField(auto_now=False, auto_now_add=False, **options)` Python で `datetime.time` インスタンスによって表される時刻です。[`DateField`](#django.db.models.DateField) と同じ自動入力されるオプションを受け入れます。 このフィールドのデフォルトのフォームウィジェットは [`TimeInput`](/ja/6.1/ref/forms/widgets/#django.forms.TimeInput) です。admin はいくつかの JavaScript ショートカットを追加します。 ### `URLField` #### `class URLField(max_length=200, **options)` URLの [`CharField`](#django.db.models.CharField) で、 [`URLValidator`](/ja/6.1/ref/validators/#django.core.validators.URLValidator) によってバリデーションされます。 このフィールドのデフォルトのフォームウィジェットは [`URLInput`](/ja/6.1/ref/forms/widgets/#django.forms.URLInput) です。 全ての [`CharField`](#django.db.models.CharField) サブクラスと同じく、[`URLField`](#django.db.models.URLField) は省略可能な [`max_length`](#django.db.models.CharField.max_length) 引数を取ります。[`max_length`](#django.db.models.CharField.max_length) を指定しない場合、デフォルトの 200 が使われます。 ### `UUIDField` #### `class UUIDField(**options)` A field for storing universally unique identifiers. Uses Python's [`UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID) class. When used on PostgreSQL and MariaDB, this stores in a `uuid` datatype, otherwise in a `char(32)`. UUID は [`primary_key`](#django.db.models.Field.primary_key) に代わる [`AutoField`](#django.db.models.AutoField) への良い選択肢です。 データベースはあなたのための UUID を生成しないため、 [`default`](#django.db.models.Field.default) を使うことが推奨されます: ``` import uuid from django.db import models class MyUUIDModel(models.Model): id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False) # other fields ``` `UUID` のインスタンスではなく、呼び出し可能オブジェクト（カッコは書かない）を `default` に渡すことに注意してください。 > **Lookups on PostgreSQL and MariaDB** > > Using [`iexact`](/ja/6.1/ref/models/querysets/#std-fieldlookup-iexact), [`contains`](/ja/6.1/ref/models/querysets/#std-fieldlookup-contains), [`icontains`](/ja/6.1/ref/models/querysets/#std-fieldlookup-icontains), > [`startswith`](/ja/6.1/ref/models/querysets/#std-fieldlookup-startswith), [`istartswith`](/ja/6.1/ref/models/querysets/#std-fieldlookup-istartswith), [`endswith`](/ja/6.1/ref/models/querysets/#std-fieldlookup-endswith), or > [`iendswith`](/ja/6.1/ref/models/querysets/#std-fieldlookup-iendswith) lookups on PostgreSQL don't work for values without > hyphens, because PostgreSQL and MariaDB store them in a hyphenated uuid > datatype type. ## リレーションシップフィールド Djangoは、リレーションを表すフィールドのセットも定義しています。 ### `ForeignKey` #### `class ForeignKey(to, on_delete, **options)` 多対一のリレーションシップです。モデルが関連するクラスと、[`on_delete`](#django.db.models.ForeignKey.on_delete) オプションの2つの位置引数が必要です。 ``` from django.db import models class Manufacturer(models.Model): name = models.TextField() class Car(models.Model): manufacturer = models.ForeignKey(Manufacturer, on_delete=models.CASCADE) ``` 最初の位置引数には、具象モデルクラスまたはモデルクラスへの [遅延参照](#lazy-relationships) のいずれかを指定できます。モデルが自分自身とリレーションシップを持つ [再帰的リレーションシップ](#recursive-relationships) もサポートされています。 2番目の位置引数の詳細については、[`ForeignKey.on_delete`](#django.db.models.ForeignKey.on_delete) を参照してください。 A database index is automatically created on the `ForeignKey`. You can disable this by setting [`db_index`](#django.db.models.Field.db_index) to `False`. You may want to avoid the overhead of an index if you are creating a foreign key for consistency rather than joins, or if you will be creating an alternative index like a partial or multiple column index. #### データベース上の表現 内部的に、Django はフィールド名に `"_id"` を追加してデータベースのカラム名を作成します。上記の例では、`Car` モデルのデータベーステーブルには `manufacturer_id` カラムが作成されます。この名前は [`db_column`](#django.db.models.Field.db_column) を指定することで明示的に変更できますが、通常はデータベースのカラム名を直接操作する必要はありません（カスタムSQLを記述する場合を除く）。あなたのコードは常にモデルオブジェクトのフィールド名を操作します。 #### 引数 [`ForeignKey`](#django.db.models.ForeignKey) はリレーションシップの動作の詳細を定義する他の引数を取ることができます。 #### `ForeignKey.on_delete` When an object referenced by a [`ForeignKey`](#django.db.models.ForeignKey) is deleted, the referring objects need updating. The [`on_delete`](#django.db.models.ForeignKey.on_delete) argument specifies how this is done, and whether Django or your database makes the updates. For example, if you have a nullable [`ForeignKey`](#django.db.models.ForeignKey) and you want Django to set it to `None` when the referenced object is deleted: ``` user = models.ForeignKey( User, models.SET_NULL, blank=True, null=True, ) ``` The possible values for [`on_delete`](#django.db.models.ForeignKey.on_delete) are listed below. Import them from [`django.db.models`](/ja/6.1/topics/db/models/#module-django.db.models). The `DB_*` variants use the database to prevent deletions or update referring objects, whilst the other values make Django perform the relevant actions. The database variants are more efficient because they avoid fetching related objects, but `pre_delete` and `post_delete` signals won't be sent when `DB_CASCADE` is used. The database variants cannot be mixed with Python variants (other than [`DO_NOTHING`](#django.db.models.DO_NOTHING)) in the same model and in models related to each other. > **Changed in Django 6.1** > > Support for `DB_*` variants of the `on_delete` attribute was added. [`on_delete`](#django.db.models.ForeignKey.on_delete) に指定できる値は [`django.db.models`](/ja/6.1/topics/db/models/#module-django.db.models) にあります： - #### `CASCADE` カスケード削除。 Django は SQL 制約の `ON DELETE CASCADE` の動作をエミュレートし、 [`ForeignKey`](#django.db.models.ForeignKey) を含むオブジェクトも削除します。 [`Model.delete()`](/ja/6.1/ref/models/instances/#django.db.models.Model.delete) はリレーション先モデルでは呼び出されませんが、 [`pre_delete`](/ja/6.1/ref/signals/#django.db.models.signals.pre_delete) と [`post_delete`](/ja/6.1/ref/signals/#django.db.models.signals.post_delete) シグナルは削除された全てのオブジェクトに対して送られます。 - #### `DB_CASCADE` > **New in Django 6.1** Cascade deletes. Database-level version of [`CASCADE`](#django.db.models.CASCADE): the database deletes referred-to rows and the one containing the `ForeignKey`. - #### `PROTECT` [`django.db.IntegrityError`](/ja/6.1/ref/exceptions/#django.db.IntegrityError) のサブクラスである [`ProtectedError`](/ja/6.1/ref/exceptions/#django.db.models.ProtectedError) を発生させて、参照オブジェクトの削除を防ぎます。 - #### `RESTRICT` [`RestrictedError`](/ja/6.1/ref/exceptions/#django.db.models.RestrictedError) ([`django.db.IntegrityError`](/ja/6.1/ref/exceptions/#django.db.IntegrityError) のサブクラス) を発生させて、参照オブジェクトの削除を防ぎます。 [`PROTECT`](#django.db.models.PROTECT) とは異なり、同じ操作で削除されるオブジェクトが [`CASCADE`](#django.db.models.CASCADE) リレーションシップで参照されている場合、参照オブジェクトの削除は許可されます。 以下のような一連のモデルを考えてみましょう: ``` class Artist(models.Model): name = models.CharField(max_length=10) class Album(models.Model): artist = models.ForeignKey(Artist, on_delete=models.CASCADE) class Song(models.Model): artist = models.ForeignKey(Artist, on_delete=models.CASCADE) album = models.ForeignKey(Album, on_delete=models.RESTRICT) ``` `Song` によって参照されている `Album` を削除することになるとしても、 `Artist` を削除することは可能です。なぜなら `Song` も、カスケードリレーションシップを通して `Artist` 自身を参照しているからです。例えば以下のようになります： ```pycon >>> artist_one = Artist.objects.create(name="artist one") >>> artist_two = Artist.objects.create(name="artist two") >>> album_one = Album.objects.create(artist=artist_one) >>> album_two = Album.objects.create(artist=artist_two) >>> song_one = Song.objects.create(artist=artist_one, album=album_one) >>> song_two = Song.objects.create(artist=artist_one, album=album_two) >>> album_one.delete() # Raises RestrictedError. >>> artist_two.delete() # Raises RestrictedError. >>> artist_one.delete() (4, {'Song': 2, 'Album': 1, 'Artist': 1}) ``` - #### `SET_NULL` [`ForeignKey`](#django.db.models.ForeignKey) に null をセットします。これは [`null`](#django.db.models.Field.null) が `True` の場合のみ可能です。 - #### `DB_SET_NULL` > **New in Django 6.1** Set the [`ForeignKey`](#django.db.models.ForeignKey) value to `NULL`. This is only possible if [`null`](#django.db.models.Field.null) is `True`. Database-level version of [`SET_NULL`](#django.db.models.SET_NULL). - #### `SET_DEFAULT` [`ForeignKey`](#django.db.models.ForeignKey) にデフォルト値を設定します。 [`ForeignKey`](#django.db.models.ForeignKey) にデフォルト値が設定されている必要があります。 - #### `DB_SET_DEFAULT` > **New in Django 6.1** Set the [`ForeignKey`](#django.db.models.ForeignKey) value to its [`Field.db_default`](#django.db.models.Field.db_default) value, which must be set. If a row in the referenced table is deleted, the foreign key values in the referencing table will be updated to their [`Field.db_default`](#django.db.models.Field.db_default) values. `DB_SET_DEFAULT` is not supported on MySQL and MariaDB. - #### `SET()` Set the [`ForeignKey`](#django.db.models.ForeignKey) to the value passed to [`SET()`](#django.db.models.SET), or if a callable is passed in, the result of calling it. In most cases, passing a callable will be necessary to avoid executing queries at the time your `models.py` is imported: ``` from django.conf import settings from django.contrib.auth import get_user_model from django.db import models def get_sentinel_user(): return get_user_model().objects.get_or_create(username="deleted")[0] class MyModel(models.Model): user = models.ForeignKey( settings.AUTH_USER_MODEL, on_delete=models.SET(get_sentinel_user), ) ``` - #### `DO_NOTHING` 何もしません。データベースのバックエンドが参照整合性を強制している場合、手動で SQL の `ON DELETE` 制約をデータベースフィールドに追加しない限り、 [`IntegrityError`](/ja/6.1/ref/exceptions/#django.db.IntegrityError) が発生します。 #### `ForeignKey.limit_choices_to` このフィールドが `ModelForm` や管理画面でレンダリングされる際に、このフィールドで選択可能な選択肢に制限を設定します（デフォルトでは、クエリセット内のすべてのオブジェクトが選択可能です）。辞書、[`Q`](/ja/6.1/ref/models/querysets/#django.db.models.Q) オブジェクト、または辞書や [`Q`](/ja/6.1/ref/models/querysets/#django.db.models.Q) オブジェクトを返す呼び出し可能オブジェクトのいずれかを使用できます。 例: ``` staff_member = models.ForeignKey( User, on_delete=models.CASCADE, limit_choices_to={"is_staff": True}, ) ``` 上記を指定すると、 `ModelForm` の対応するフィールドに、 `is_staff=True` を持つ `User` インスタンスのみがリストされます。これは Django の管理画面で役に立つかもしれません。 呼び出し可能なオブジェクトは、例えば、Python の `datetime` モジュールと組み合わせて使用することで、日付の範囲で選択を制限するのに役立ちます。例えば下記のようにします： ``` def limit_pub_date_choices(): return {"pub_date__lte": datetime.date.today()} limit_choices_to = limit_pub_date_choices ``` もし `limit_choices_to` が [`Q オブジェクト`](/ja/6.1/ref/models/querysets/#django.db.models.Q) を返す場合、これは [複雑なクエリ](/ja/6.1/topics/db/queries/#complex-lookups-with-q) に便利です。これが管理画面で利用可能な選択肢に効果を及ぼすのは、そのフィールドがモデルの `ModelAdmin` の [`raw_id_fields`](/ja/6.1/ref/contrib/admin/#django.contrib.admin.ModelAdmin.raw_id_fields) にリストされていない場合だけです。 > **Note** > > `limit_choices_to` に呼び出し可能オブジェクトが指定されている場合、新しいフォームがインスタンス化されるたびに呼び出されます。また、管理コマンドや admin によってモデルが検証されるときにも呼び出されます。admin は様々なエッジケースでフォームの入力を検証するためにクエリセットを複数回構築するので、呼び出し可能オブジェクトが複数回呼び出される可能性があります。 #### `ForeignKey.related_name` リレーション先オブジェクトからこのオブジェクトへのリレーションに使用する名前です。これは [`related_query_name`](#django.db.models.ForeignKey.related_query_name) (ターゲットモデルからの逆フィルタに使用する名前) のデフォルト値でもあります。詳しい説明と例については [リレーション先オブジェクトのドキュメント](/ja/6.1/topics/db/queries/#backwards-related-objects) を参照してください。 [抽象モデル](/ja/6.1/topics/db/models/#abstract-base-classes) のリレーションを定義する際には、この値を設定する必要があることに注意してください。それにより、 [いくつかの特別な構文](/ja/6.1/topics/db/models/#abstract-related-name) が使えるようになります。 Django が逆方向のリレーションを作らないようにしたい場合は、 `related_name` を `'+'` に設定するか、 `'+'` で終わらせてください。例えば、 `User` モデルがこのモデルと逆方向のリレーションを持たないようにするには下記のようにします： ``` user = models.ForeignKey( User, on_delete=models.CASCADE, related_name="+", ) ``` #### `ForeignKey.related_query_name` ターゲットモデルからの逆フィルタに使用する名前です。デフォルトは [`related_name`](#django.db.models.ForeignKey.related_name) か、 [`default_related_name`](/ja/6.1/ref/models/options/#django.db.models.Options.default_related_name) が設定されていればその値、そうでなければモデルの名前になります： ``` # Declare the ForeignKey with related_query_name class Tag(models.Model): article = models.ForeignKey( Article, on_delete=models.CASCADE, related_name="tags", related_query_name="tag", ) name = models.CharField(max_length=255) # That's now the name of the reverse filter Article.objects.filter(tag__name="important") ``` [`related_name`](#django.db.models.ForeignKey.related_name) と同様に、`related_query_name` は [いくつかの特別な構文](/ja/6.1/topics/db/models/#abstract-related-name) によるアプリのラベルとクラスの補間をサポートします。 #### `ForeignKey.to_field` リレーション先オブジェクト上の、リレーション対象となるフィールドです。デフォルトでは、Djangoはリレーション先オブジェクトの主キーを使用します。別のフィールドを参照する場合、そのフィールドには `unique=True` が設定されている必要があります。 #### `ForeignKey.db_constraint` この外部キーに対してデータベースに制約を作成するかどうかを制御します。デフォルトは `True` で、ほとんどの場合それが望ましい設定です。これを `False` に設定すると、データの整合性に大きな悪影響を及ぼす可能性があります。それでも、以下のようなシナリオではこの設定を行いたくなるかもしれません： - 無効なレガシーデータを持っている場合。 - データベースをシャーディング（分割）している場合。 これが `False` にセットされている場合、存在しないリレーション先オブジェクトにアクセスすると `DoesNotExist` 例外が発生します。 #### `ForeignKey.swappable` この [`ForeignKey`](#django.db.models.ForeignKey) がスワップ可能なモデルを指している場合のマイグレーションフレームワークの対応を制御します。デフォルトの `True` の場合、[`ForeignKey`](#django.db.models.ForeignKey) が `settings.AUTH_USER_MODEL` (または他のスワップ可能なモデルの設定) の現在の値と一致するモデルを指している場合、リレーションシップはモデルに直接ではなく、設定への参照を使用してマイグレーションに保存されます。 この設定を `False` に上書きしてよいのは、モデルが常にスワップされたモデルを指すべきであると確信している場合のみです。例えば、カスタムユーザーモデル用に特別に設計されたプロフィールモデルの場合などが該当します。 `False` を設定しても、スワップ可能モデルがスワップアウトされた方のモデルを参照できるわけではありません。具体的には、この設定を `False` にすると、この [`ForeignKey`](#django.db.models.ForeignKey) を使用して作成されるマイグレーションは、指定されたモデルを常に直接参照します（そのため、例えば、対応していない `User` モデルを使用してマイグレーションを実行しようとした場合、明確なエラーが発生します）。 迷ったときは、デフォルトの `True` のままにしてください。 ### `ManyToManyField` #### `class ManyToManyField(to, **options)` 多対多のリレーションシップ。位置引数が必要で、モデルがリレーションを持つクラスを指定します。これは [`ForeignKey`](#django.db.models.ForeignKey) での使用と全く同じ方法で機能し、[再帰的なリレーションシップ](#recursive-relationships) や [遅延リレーションシップ](#lazy-relationships) を含みます。 リレーション先オブジェクトはフィールドの [`RelatedManager`](/ja/6.1/ref/models/relations/#django.db.models.fields.related.RelatedManager) で追加、削除、作成ができます。 #### データベース上の表現 裏では、Django は多対多のリレーションシップを表現するために、中間的な join テーブルを作成します。デフォルトでは、このテーブル名は多対多のフィールド名と、それを含むモデルのテーブル名を使って生成されます。データベースによっては一定以上の長さのテーブル名をサポートしていないため、これらのテーブル名は自動的に切り捨てられ、一意性のハッシュが使用されます (例: `author_books_9cdf`)。 [`db_table`](#django.db.models.ManyToManyField.db_table) オプションを使用すれば、手動でjoinテーブルの名前を指定できます。 #### 引数 [`ManyToManyField`](#django.db.models.ManyToManyField) はリレーションシップがどう機能するかをコントロールする複数のオプション引数を受け付けます。 #### `ManyToManyField.related_name` [`ForeignKey.related_name`](#django.db.models.ForeignKey.related_name) と同様です。 #### `ManyToManyField.related_query_name` [`ForeignKey.related_query_name`](#django.db.models.ForeignKey.related_query_name) と同様です。 #### `ManyToManyField.limit_choices_to` [`ForeignKey.limit_choices_to`](#django.db.models.ForeignKey.limit_choices_to) と同様です。 #### `ManyToManyField.symmetrical` self の ManyToManyFields の定義でのみ使用されます。次のモデルを考えてみましょう： ``` from django.db import models class Person(models.Model): friends = models.ManyToManyField("self") ``` Django はこのモデルを処理するとき、 [`ManyToManyField`](#django.db.models.ManyToManyField) を持つことを識別し、その結果 `Person` クラスに `person_set` 属性を追加しません。その代わりに、 [`ManyToManyField`](#django.db.models.ManyToManyField) は対称であると仮定されます。つまり、もし私があなたの友達なら、あなたは私の友達です。 もし `self` との多対多のリレーションシップに対称性を持たせたくない場合は、 [`symmetrical`](#django.db.models.ManyToManyField.symmetrical) を `False` に設定してください。これにより Django は逆リレーションシップの記述子を追加し、 [`ManyToManyField`](#django.db.models.ManyToManyField) リレーションシップが非対称になるようにします。 #### `ManyToManyField.through` Django は多対多のリレーションシップを管理するテーブルを自動生成します。しかし、中間テーブルを手動で指定したい場合は、 [`through`](#django.db.models.ManyToManyField.through) オプションを使って、使いたい中間テーブルを表す Django モデルを指定できます。 `through` モデルはモデルクラスを直接指定するか、モデルクラスへの [lazy reference](#lazy-relationships) を用いて指定できます。 このオプションの最も一般的な利用法は、 [多対多のリレーションシップに追加のデータを関連付けたい](/ja/6.1/topics/db/models/#intermediary-manytomany) 場合です。 > **Note** > > 中間モデルを使用した再帰的リレーションシップでは、逆アクセサ名 (reverse accessor name) を決定することはできません。同じ名前になってしまうからです。少なくともどちらかに [`related_name`](#django.db.models.ForeignKey.related_name) を設定する必要があります。もし Django が逆リレーションを作成しないことを望むなら、 `related_name` を `'+'` に設定してください。 > **中間モデルにおける外部キーの順序** > > :attr:through\_fields\` を使わずに中間モデルを用いて同一モデルへの非対称な多対多関係を定義する場合、中間モデル内の最初の外部キーが `ManyToManyField` のソース側を、2 番目の外部キーがターゲット側を表すものとして扱われます。以下がその例です。 > > ``` > from django.db import models > > > class Manufacturer(models.Model): > name = models.CharField(max_length=255) > clients = models.ManyToManyField( > "self", symmetrical=False, related_name="suppliers", through="Supply" > ) > > > class Supply(models.Model): > supplier = models.ForeignKey( > Manufacturer, models.CASCADE, related_name="supplies_given" > ) > client = models.ForeignKey( > Manufacturer, models.CASCADE, related_name="supplies_received" > ) > product = models.CharField(max_length=255) > ``` > > ここで、 `Manufacturer` モデルでは `supplier` としての役割で `clients` との多対多リレーションを定義しています。したがって、中間の `Supply` モデルでは、（ソースである） `supplier` 外部キーが、（ターゲットである） `client` 外部キーよりも先に配置されていなければなりません。 > > `ManyToManyField` において [`through_fields=("supplier", "client")`](#django.db.models.ManyToManyField.through_fields) と指定すると、 `through` モデルにおける外部キーの順序は無関係になります。 明示的な `through` モデルを指定しない場合でも、関連付けを保持するために作成されたテーブルへ直接アクセスするための暗黙的な `through` モデルクラスが存在します。このモデルクラスは、モデルを結びつけるために、主キーと2つの外部キー、あわせて3つのフィールドを持ち、2つの外部キーには一意制約が設定されます。 ソース・モデルとターゲット・モデルが異なる場合、以下のフィールドが生成されます： - `id`: リレーションの主キー。 - `_id`: `ManyToManyField` を宣言したモデルの `id` 。 - `_id`: `ManyToManyField` が指すモデルの `id` 。 もし `ManyToManyField` が同じモデルを指している場合、以下のフィールドが生成されます： - `id`: リレーションの主キー。 - `from__id`: モデルを指すインスタンス (つまりソースインスタンス) の `id` です。 - `to__id`: リレーションシップの対象となるインスタンス (つまり、ターゲットモデル・インスタンス) の `id` 。 このクラスは、通常のモデルのように、指定されたモデルのインスタンスに関連するレコードをクエリするために使用できます： ``` Model.m2mfield.through.objects.all() ``` #### `ManyToManyField.through_fields` カスタムの中間モデルが指定されている場合にだけ使われます。Django は通常、多対多のリレーションシップを確立するために、仲介モデルのどのフィールドを使うかを自動的に決定します。しかし、以下のモデルを考えてみてください： ``` from django.db import models class Person(models.Model): name = models.CharField(max_length=50) class Group(models.Model): name = models.CharField(max_length=128) members = models.ManyToManyField( Person, through="Membership", through_fields=("group", "person"), ) class Membership(models.Model): group = models.ForeignKey(Group, on_delete=models.CASCADE) person = models.ForeignKey(Person, on_delete=models.CASCADE) inviter = models.ForeignKey( Person, on_delete=models.CASCADE, related_name="membership_invites", ) invite_reason = models.CharField(max_length=64) ``` `Membership` は `Person` に対する外部キーを *2つ* 持っています (`person` と `inviter`) ので、リレーションシップが曖昧になり、Django はどちらを使うべきか分からなくなります。この場合、上の例のように `through_fields` を使って、 Django がどの外部キーを使うかを明示的に指定する必要があります。 `through_fields` は2値タプル `('field1', 'field2')` を受け付けます。ここで `field1` は [`ManyToManyField`](#django.db.models.ManyToManyField) が定義されているモデルの外部キーの名前 (この場合は `group`) で、 `field2` は対象のモデルの外部キーの名前 (この場合は `person`) です。 多対多のリレーションシップに参加するモデルのいずれか(あるいは両方)に対して、仲介モデルに複数の外部キーがある場合、 `through_fields` を指定する必要があります。これは [再帰的なリレーションシップ](#recursive-relationships) にも当てはまり、中間モデルが使われ、そのモデルへの外部キーが2つ以上ある場合、あるいは Django がどの2つを使うかを明示的に指定したい場合に適用されます。 #### `ManyToManyField.db_table` 多対多のデータを格納するために作成するテーブルの名前です。これが指定されない場合、 Django はリレーションシップを定義するモデルのテーブル名と、 フィールド名に基づいてデフォルトの名前を決めます。 #### `ManyToManyField.db_constraint` 中間テーブルの外部キーに対して制約を作成するかどうかを制御します。デフォルトは `True` で、ほとんどの場合それが望ましい設定です。これを `False` に設定すると、データの整合性に大きな悪影響を及ぼす可能性があります。それでも、以下のようなシナリオでこの設定を行いたくなるかもしれません： - 無効なレガシーデータを持っている場合。 - データベースをシャーディング（分割）している場合。 `db_constraint` と `through` の両方を渡すとエラーになります。 #### `ManyToManyField.swappable` この [`ManyToManyField`](#django.db.models.ManyToManyField) がスワップ可能なモデルを指している場合のマイグレーションフレームワークの対応を制御します。もし `True` (デフォルト) であれば、 [`ManyToManyField`](#django.db.models.ManyToManyField) が `settings.AUTH_USER_MODEL` (または他のスワップ可能なモデルの設定) の現在の値と一致するモデルを指している場合、リレーションシップはモデルに直接ではなく、設定への参照を使用してマイグレーションに保存されます。 この設定を `False` に上書きしてよいのは、モデルが常にスワップされたモデルを指すべきであると確信している場合のみです。例えば、カスタムユーザーモデル用に特別に設計されたプロフィールモデルの場合などが該当します。 迷ったときは、デフォルトの `True` のままにしてください。 [`ManyToManyField`](#django.db.models.ManyToManyField) は [`validators`](#django.db.models.Field.validators) をサポートしていません。 [`null`](#django.db.models.Field.null) は、データベースレベルでリレーションシップを要求する方法がないので、何の効果もありません。 ### `OneToOneField` #### `class OneToOneField(to, on_delete, parent_link=False, **options)` 一対一のリレーションシップです。概念的には [`ForeignKey`](#django.db.models.ForeignKey) に [`unique=True`](#django.db.models.Field.unique) を指定したものと似ていますが、リレーションの "反対側" が直接1つのオブジェクトを返します。 これは、何らかの方法で別のモデルを「拡張」するモデルの主キーとして最も有用です。例えば、[マルチテーブル継承](/ja/6.1/topics/db/models/#multi-table-inheritance) は、子モデルから親モデルへの暗黙の一対一リレーションシップを追加することによって実装されます。 位置引数が1つ必要で、モデルが関連付けられるクラスを指定します。これは [`ForeignKey`](#django.db.models.ForeignKey) と全く同じ方法で機能し、[再帰的なリレーションシップ](#recursive-relationships) や [遅延リレーションシップ](#lazy-relationships) に関するすべてのオプションが含まれます。 もし `OneToOneField` に [`related_name`](#django.db.models.ForeignKey.related_name) 引数を指定しなければ、 Django は現在のモデルの小文字の名前をデフォルト値として使用します。 次の例では、 ``` from django.conf import settings from django.db import models class MySpecialUser(models.Model): user = models.OneToOneField( settings.AUTH_USER_MODEL, on_delete=models.CASCADE, ) supervisor = models.OneToOneField( settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="supervisor_of", ) ``` 出来上がった `User` モデルは以下の属性を持つことになります： ```pycon >>> user = User.objects.get(pk=1) >>> hasattr(user, "myspecialuser") True >>> hasattr(user, "supervisor_of") True ``` リレーション先テーブルにエントリが存在しない場合、逆リレーションシップにアクセスすると `RelatedObjectDoesNotExist` 例外が発生します。これは対象モデルの [`Model.DoesNotExist`](/ja/6.1/ref/models/class/#django.db.models.Model.DoesNotExist) 例外のサブクラスであり、逆アクセサ (reverse accessor) の属性としてアクセスできます。たとえば、ユーザーに `MySpecialUser` によって指定されたスーパーバイザーがいない場合： ``` try: user.supervisor_of except User.supervisor_of.RelatedObjectDoesNotExist: pass ``` さらに、`OneToOneField` は [`ForeignKey`](#django.db.models.ForeignKey) が受け付ける全ての引数に加え、1つの追加引数を受け付けます： #### `OneToOneField.parent_link` `True` に設定され、他の [concrete model](/ja/6.1/glossary/#term-concrete-model) から継承されたモデルで使用された場合、サブクラス化によって通常は暗黙的に作成される追加の `OneToOneField` の代わりに、このフィールドが親クラスへのリンクとして使用されるべきことを示します。 `OneToOneField` の使用例については [一対一のリレーションシップ](/ja/6.1/topics/db/examples/one_to_one/) を参照してください。 ### 遅延リレーションシップ 遅延リレーションシップを使用すると、モデルを名前（文字列）で参照したり、再帰的リレーションシップを作成したりできます。文字列は、任意のリレーションシップフィールドの最初の引数として使用でき、モデルを遅延参照します。遅延参照には、[再帰的](#recursive-relationships)、[相対的](#relative-relationships)、または [絶対的](#absolute-relationships) 参照が含まれます。 #### 再帰的参照 モデルが自分自身を参照するリレーションシップを定義するには、リレーションシップフィールドの最初の引数に `"self"` を次のように使用します。 ``` from django.db import models class Manufacturer(models.Model): name = models.TextField() suppliers = models.ManyToManyField("self", symmetrical=False) ``` [抽象モデル](/ja/6.1/topics/db/models/#abstract-base-classes) で使用される場合、再帰的リレーションシップは、各具象サブクラスが自分自身を参照するように解決されます。 #### 相対参照 まだ定義されていないモデルとのリレーションシップを作成する必要がある場合、そのモデルオブジェクト自体ではなく、モデル名の文字列で参照できます。 ``` from django.db import models class Car(models.Model): manufacturer = models.ForeignKey( "Manufacturer", on_delete=models.CASCADE, ) class Manufacturer(models.Model): name = models.TextField() suppliers = models.ManyToManyField("self", symmetrical=False) ``` 以下のような方法で [抽象モデル](/ja/6.1/topics/db/models/#abstract-base-classes) で定義されたリレーションシップは、モデルが具象モデルとしてサブクラス化されたときに解決され、抽象モデルの `app_label` とリレーションシップがあるわけではありません： *`products/models.py`* ```python from django.db import models class AbstractCar(models.Model): manufacturer = models.ForeignKey("Manufacturer", on_delete=models.CASCADE) class Meta: abstract = True ``` *`production/models.py`* ```python from django.db import models from products.models import AbstractCar class Manufacturer(models.Model): name = models.TextField() class Car(AbstractCar): pass ``` この例では、`Car.manufacturer` リレーションシップは `production.Manufacturer` に解決されます。なぜなら、`production/models.py` ファイル内で定義された具象モデルを指しているからです。 > **相対参照を使った再利用可能なモデル** > > 相対参照を使うことで、再利用可能な抽象モデルを作成できます。相手のモデルが異なるアプリケーション内にあり、さまざまなサブクラスにおいて違う実装を持っていたとしも、そのモデルへの参照を解決できるようなリレーションシップを持つことができます。 #### 絶対参照 絶対参照は、`app_label` とクラス名を使ってモデルを指定し、異なるアプリケーション間でモデルを参照できるようにします。このタイプの遅延リレーションシップは、循環インポートの解決にも役立ちます。 例えば、`Manufacturer` モデルが別のアプリケーション `thirdpartyapp` に定義されている場合、次のように参照できます： ``` class Car(models.Model): manufacturer = models.ForeignKey( "thirdpartyapp.Manufacturer", on_delete=models.CASCADE, ) ``` 絶対参照は、[抽象モデル](/ja/6.1/topics/db/models/#abstract-base-classes) で使用される場合でも、常に同じモデルを指し示します。 ## フィールド API リファレンス #### `class Field` フィールドはデータベーステーブルのカラムを表す抽象クラスです。Django はフィールドを使ってデータベーステーブルを作成したり ([`db_type()`](#django.db.models.Field.db_type))、 Python の型をデータベースにマッピングしたり ([`get_prep_value()`](#django.db.models.Field.get_prep_value))、逆にしたり ([`from_db_value()`](#django.db.models.Field.from_db_value)) します。 A field is thus a fundamental piece in different Django APIs, notably the [`Model`](/ja/6.1/ref/models/instances/#django.db.models.Model) and the [`QuerySet`](/ja/6.1/ref/models/querysets/#django.db.models.query.QuerySet) APIs. モデルでは、フィールドはクラス属性としてインスタンス化され、特定のテーブルのカラムを表します ([モデル](/ja/6.1/topics/db/models/) 参照)。フィールドには [`null`](#django.db.models.Field.null) や [`unique`](#django.db.models.Field.unique) といった属性と、 Django がフィールドの値をデータベース固有の値にマッピングするためのメソッドがあります。 フィールド `Field` は [`RegisterLookupMixin`](/ja/6.1/ref/models/lookups/#django.db.models.lookups.RegisterLookupMixin) のサブクラスなので、 [`Transform`](/ja/6.1/ref/models/lookups/#django.db.models.Transform) と [`Lookup`](/ja/6.1/ref/models/lookups/#django.db.models.Lookup) の両方を登録して `QuerySet` で使用できます (例: `field_name__exact="foo"`) 。デフォルトでは全ての [組み込みのルックアップ](/ja/6.1/ref/models/querysets/#field-lookups) が登録されています。 [`CharField`](#django.db.models.CharField) のような Django 組み込みのフィールドは全て `Field` の具体的な実装です。独自のフィールドが必要な場合は、組み込みフィールドをサブクラス化するか、一から `Field` を書いてください。どちらの場合でも [カスタムのモデルフィールドを作成する](/ja/6.1/howto/custom-model-fields/) を参照してください。 #### `description` フィールドの詳細な説明。例えば [`django.contrib.admindocs`](/ja/6.1/ref/contrib/admin/admindocs/#module-django.contrib.admindocs) アプリケーションなどのためのものです。 説明文は以下のような形式です： ``` description = _("String (up to %(max_length)s)") ``` 引数はフィールドの `__dict__` から補間されます。 #### `descriptor_class` A class implementing the [descriptor protocol](https://docs.python.org/3/reference/datamodel.html#descriptors) that is instantiated and assigned to the model instance attribute. The constructor must accept a single argument, the `Field` instance. Overriding this class attribute allows for customizing the get and set behavior. フィールド `Field` をデータベース固有の型にマッピングするために、 Django はいくつかのメソッドを公開しています： #### `get_internal_type()` バックエンド固有の目的のために、このフィールドの名前を文字列で返します。デフォルトでは、クラス名を返します。 カスタムフィールドでの使用法については [組み込みフィールド・タイプのエミュレート](/ja/6.1/howto/custom-model-fields/#emulating-built-in-field-types) を参照してください。 #### `db_type(connection)` [`Field`](#django.db.models.Field) のデータベースカラムのデータ型を、`connection` を考慮して返します。 カスタムフィールドでの使用法については [カスタムデータベースタイプ](/ja/6.1/howto/custom-model-fields/#custom-database-types) を参照してください。 #### `rel_db_type(connection)` [`Field`](#django.db.models.Field) を指す `ForeignKey` や `OneToOneField` などのフィールドのデータベースカラムのデータ型を、`connection` を考慮して返します。 カスタムフィールドでの使用法については [カスタムデータベースタイプ](/ja/6.1/howto/custom-model-fields/#custom-database-types) を参照してください。 Django がデータベースのバックエンドやフィールドとやり取りする必要がある場面は、 主に3つあります： - データベースへのクエリ時 (Python の値 -\> データベースのバックエンドの値) - データベースからデータを読み込むとき (データベースのバックエンドの値 -\> Python の値) - データベースへの保存時 (Python の値 -\> データベースのバックエンドの値) クエリでは [`get_db_prep_value()`](#django.db.models.Field.get_db_prep_value) と [`get_prep_value()`](#django.db.models.Field.get_prep_value) が使用されます： #### `get_prep_value(value)` `value` はモデルの属性の現在の値で、メソッドはクエリのパラメータとして使用できるように書かれた形式のデータを返す必要があります。 使い方は [Python オブジェクトをクエリ変数に変換する](/ja/6.1/howto/custom-model-fields/#converting-python-objects-to-query-values) を参照してください。 #### `get_db_prep_value(value, connection, prepared=False)` Converts `value` to a backend-specific value. By default it returns `value` if `prepared=True`, and [`get_prep_value(value)`](#django.db.models.Field.get_prep_value) otherwise. 使い方は [クエリの変数をデータベースの変数に変換する](/ja/6.1/howto/custom-model-fields/#converting-query-values-to-database-values) を参照してください。 データを読み込む際には [`from_db_value()`](#django.db.models.Field.from_db_value) が使用されます： #### `from_db_value(value, expression, connection)` データベースが返す値を Python オブジェクトに変換します。これは [`get_prep_value()`](#django.db.models.Field.get_prep_value) の逆です。 データベースのバックエンドはすでに正しい Python 型を返すか、バックエンド自身が変換を行うので、このメソッドはほとんどの組み込みフィールドには使われません。 `expression` は `self` と同様です。 使い方は [変数を Python オブジェクトに変換する](/ja/6.1/howto/custom-model-fields/#converting-values-to-python-objects) を参照してください。 > **Note** > > パフォーマンス上の理由から、 `from_db_value` は、それを必要としないフィールド (Django の全てのフィールド) では何もしない関数としては実装されていません。そのため、定義内で `super` を呼び出してはいけません。 保存時には [`pre_save()`](#django.db.models.Field.pre_save) と [`get_db_prep_save()`](#django.db.models.Field.get_db_prep_save) が使用されます： #### `get_db_prep_save(value, connection)` [`get_db_prep_value()`](#django.db.models.Field.get_db_prep_value) と同じですが、フィールドの値をデータベースに *保存* しなければならない場合に呼び出されます。デフォルトでは [`get_db_prep_value()`](#django.db.models.Field.get_db_prep_value) を返します。 #### `pre_save(model_instance, add)` 保存する前に値を整えるために [`get_db_prep_save()`](#django.db.models.Field.get_db_prep_save) の前に呼び出されるメソッドです (例えば [`DateField.auto_now`](#django.db.models.DateField.auto_now) の場合など)。 `model_instance` はこのフィールドが属するインスタンスで、`add` はインスタンスが初めてデータベースに保存されるかどうかです。 このフィールドの `model_instance` からは適切な属性の値を返す必要があります。属性名は `self.attname` にあります (これは [`Field`](#django.db.models.Field) で設定します)。 使い方は [保存する前に値を前処理する場合](/ja/6.1/howto/custom-model-fields/#preprocessing-values-before-saving) を参照してください。 フィールドは多くの場合、シリアライズやフォームから別の型として値を受け取ります。 #### `to_python(value)` 値を正しい Python オブジェクトに変換します。これは [`value_to_string()`](#django.db.models.Field.value_to_string) の逆として動作し、 [`clean()`](/ja/6.1/ref/models/instances/#django.db.models.Model.clean) でも呼び出されます。 使い方は [変数を Python オブジェクトに変換する](/ja/6.1/howto/custom-model-fields/#converting-values-to-python-objects) を参照してください。 データベースに保存する方法だけでなく、フィールドはその値をシリアライズする方法も知っておく必要があります： #### `value_from_object(obj)` 指定されたモデルのインスタンスのフィールドの値を返します。 このメソッドは [`value_to_string()`](#django.db.models.Field.value_to_string) でよく使われます。 #### `value_to_string(obj)` `obj` を文字列に変換します。フィールドの値をシリアライズするために使用します。 使い方は [シリアライズするためにフィールドデータを変換する場合](/ja/6.1/howto/custom-model-fields/#converting-model-field-to-serialization) を参照してください。 When using [model forms](/ja/6.1/topics/forms/modelforms/), the `Field` needs to know which form field it should be represented by: #### `formfield(form_class=None, choices_form_class=None, **kwargs)` このフィールドの [`ModelForm`](/ja/6.1/topics/forms/modelforms/#django.forms.ModelForm) に対するデフォルトの [`django.forms.Field`](/ja/6.1/ref/forms/fields/#django.forms.Field) を返します。 [`formfield()`](#django.db.models.Field.formfield) がオーバーライドされて `None` を返すようになった場合、このフィールドは [`ModelForm`](/ja/6.1/topics/forms/modelforms/#django.forms.ModelForm) から除外されます。 デフォルトでは、 `form_class` と `choices_form_class` の両方が `None` の場合、 [`CharField`](/ja/6.1/ref/forms/fields/#django.forms.CharField) を使用します。フィールドに [`choices`](#django.db.models.Field.choices) が指定されていて、 `choices_form_class` が指定されていない場合、 [`TypedChoiceField`](/ja/6.1/ref/forms/fields/#django.forms.TypedChoiceField) を使用します。 使い方は [モデルフィールドのフォームフィールドの指定](/ja/6.1/howto/custom-model-fields/#specifying-form-field-for-model-field) を参照してください。 #### `deconstruct()` フィールドを再作成するのに十分な情報を持つ4値タプルを返します： 1. モデルのフィールド名。 2. フィールドのインポートパス (例 `"django.db.models.IntegerField"`)。移植性は高く保つべきなので、あまり特定しすぎない方が良いかもしれません。 3. 位置引数のリスト。 4. キーワード引数の辞書。 1.7 より前のバージョンでは、 [マイグレーション](/ja/6.1/topics/migrations/) を使用してデータをマイグレーションするために、このメソッドをフィールドに追加する必要がありました。 ## ルックアップの登録と取得 フィールド `Field` は [ルックアップ レジストレーション API](/ja/6.1/ref/models/lookups/#lookup-registration-api) を実装しています。このAPIを使用して、フィールドクラスとそのインスタンスでどのルックアップを利用できるか、またフィールドからどのようにルックアップを取得するかをカスタマイズできます。 # フィールド属性 リファレンス すべての `Field` インスタンスには、その動作を詳しく調べるための属性がいくつか含まれています。フィールドの機能に依存するコードを書く必要がある場合には、 `isinstance` チェックの代わりにこれらの属性を使用してください。これらの属性は [Model.\_meta API](/ja/6.1/ref/models/meta/#model-meta-field-api) と一緒に使うことで、特定のフィールドタイプを絞り込むことができます。カスタムモデルフィールドはこれらのフラグを実装する必要があります。 ## フィールドの属性 #### `Field.auto_created` モデル継承で使用される `OneToOneField` のように、フィールドが自動的に作成されたかどうかを示す真偽値フラグ。 #### `Field.concrete` フィールドにデータベース・カラムが関連付けられているかどうかを示す真偽値。 #### `Field.hidden` デフォルトでは [`Options.get_fields()`](/ja/6.1/ref/models/meta/#django.db.models.options.Options.get_fields) によって返されない隠しフィールドがあるかどうかを示す真偽値のフラグです。例えば、 [`ForeignKey`](#django.db.models.ForeignKey) の逆フィールドで、 `related_name` が `'+'` で始まる場合です。 #### `Field.is_relation` 真偽値フラグで、フィールドが機能のために一つまたは複数の他のモデルへの参照を含んでいるかどうかを示します（例: `ForeignKey`, `ManyToManyField`, `OneToOneField` など）。 #### `Field.model` フィールドが定義されているモデルを返します。フィールドがモデルの基底クラスに定義されている場合、`model` はインスタンスのクラスではなく基底クラスを参照します。 ## リレーションを持つフィールドの属性 これらの属性はリレーションのカーディナリティやその他の詳細をクエリするために使用されます。これらの属性は全てのフィールドに存在しますが、フィールドがリレーションタイプである場合のみ (`None` ではなく) 真偽値を持ちます ([`Field.is_relation=True`](#django.db.models.Field.is_relation))。 #### `Field.many_to_many` 真偽値フラグで、フィールドが多対多のリレーションを持つ場合は `True` となり、そうでない場合は `False` となります。Django で `True` となるフィールドは `ManyToManyField` だけです。 #### `Field.many_to_one` 真偽値フラグで、フィールドが `ForeignKey` のような多対一のリレーションを持っている場合は `True` となり、そうでない場合は `False` となります。 #### `Field.one_to_many` 真偽値フラグで、フィールドが `GenericRelation` や `ForeignKey` のような一対多のリレーションを持っている場合は `True` となり、そうでない場合は `False` となります。 #### `Field.one_to_one` 真偽値フラグで、フィールドが `OneToOneField` のような一対一のリレーションを持っている場合は `True` となり、そうでない場合は `False` となります。 #### `Field.related_model` フィールドのリレーション先となるモデルを指定します。例えば、 `ForeignKey(Author, on_delete=models.CASCADE)` の `Author` です。 `GenericForeignKey` の `related_model` は常に `None` です。