nullLink to this heading#

Field.nullLink to this definition#

True の場合、Django はデータベース内に NULL として空の値を保持します。デフォルトは False です。

CharField や TextField などの文字列ベースのフィールドでは、 null の使用は避けてください。Django は習慣的に、文字列ベースのフィールドの「データなし」状態には NULL ではなく空文字列を用います。文字列ベースのフィールドが null=False の場合でも、「データなし」として空文字列は保存できます。 null=True の場合は、「データなし」を表す値が NULL と空文字列の 2 通りになります。多くの場合、「データなし」を表す値が 2 つあるのは冗長です。例外として、CharField に unique=True と blank=True の両方を設定する場合があります。この状況では、空文字列のオブジェクトを複数保存する際に一意制約違反を避けるため、 null=True が必要になります。

文字列ベースのフィールドでもそれ以外でも、フォーム内で空の値を許可したいときは blank=True を指定する必要があります。 null パラメーターはデータベースストレージにだけ影響を与えるからです（詳細は blank を参照）。

blankLink to this heading#

Field.blankLink to this definition#

True の場合、フィールドはブランクになることが許容されます。デフォルトは False です。

null とは異なる点に注意してください。null が純粋にデータベースに関連する一方で、blank はバリデーションに関連します。フィールドが blank=True を持つ場合、フォームバリデーションは空の値のエントリーを許容します。blank=False を持つ場合、フィールドは必須となります。

choicesLink to this heading#

Field.choicesLink to this definition#

このフィールドの選択肢として使用するための、以下で説明する形式のマッピングまたはイテラブルです。choices が指定された場合、 モデルのバリデーション によって強制的に、デフォルトのフォームウィジェットが通常のテキストフィールドの代わりにこれらの選択肢を持つセレクトボックスになります。

マッピングが指定された場合、キー要素はモデルに設定される実際の値で、2番目の要素は人間が読める名前です。例えば

YEAR_IN_SCHOOL_CHOICES = {
    "FR": "Freshman",
    "SO": "Sophomore",
    "JR": "Junior",
    "SR": "Senior",
    "GR": "Graduate",
}

また、 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 をハックして動的にするよりは、 ForeignKey を持つ適切なデータベーステーブルを使ったほうがいいでしょう。 choices はあまり変更されない静的なデータのためのものです。

choices が設定されている各モデルフィールドに対して、 Django は選択肢を2値タプルのリストに正規化し、フィールドの現在の値に対して、 人間が読める名前を取得するメソッドを追加します。データベース API ドキュメントの get_FOO_display() を参照してください。

フィールドに default とともに blank=False が指定されない限り、セレクトボックスには "---------" を含むラベルが表示されます。この動作をオーバーライドするには、たとえば (None, "表示したい文字列") のように None を含むタプルを choices に追加してください。もしくは、 None の代わりに空の文字列を使うこともできます。これは特に CharField などに適しています。

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,
        }

>>> class Vehicle(models.TextChoices):
...     CAR = "C"
...     TRUCK = "T"
...     JET_SKI = "J"
...
>>> Vehicle.JET_SKI.label
'Jet Ski'

class Card(models.Model):
    class Suit(models.IntegerChoices):
        DIAMOND = 1
        SPADE = 2
        HEART = 3
        CLUB = 4

    suit = models.IntegerField(choices=Suit)

>>> 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')]

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

db_columnLink to this heading#

Field.db_columnLink to this definition#

このフィールドを使用するためのデータベースのカラムの名前です。もし与えられなければ、Django はフィールド名を使用します。

データベースのカラム名が SQL の予約語だったり、Python の変数名として使用できない文字 (特に多いのがハイフン) が含まれていたとしても大丈夫です。Django はカラムとテーブルの名前を自動的にクオートして処理してくれます。

db_commentLink to this heading#

Field.db_commentLink to this definition#

このフィールドに使うデータベースカラムのコメントです。あなたの Django コードを見ていないような、データベースに直接アクセスできる人のために、フィールドをドキュメント化するのに便利です。例えば：

pub_date = models.DateTimeField(
    db_comment="Date and time when the article was published",
)

db_defaultLink to this heading#

Field.db_defaultLink to this definition#

データベースによって計算されるこのフィールドのデフォルト値。これはリテラル値でも、 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 の両方が指定された場合、Python コードでインスタンスを作成する際には default が優先されます。データベースレベルでも db_default が設定され、ORM の外部で行を挿入するときや、マイグレーションで新しいフィールドを追加するときに使用されます。

フィールドに db_default は設定されているが default が設定されておらず、フィールドに値が割り当てられていない場合、保存されていないモデルインスタンスでは DatabaseDefault オブジェクトがフィールドの値として返されます。フィールドの実際の値は、モデルインスタンスが保存されたときにデータベースによって決定されます。

db_indexLink to this heading#

Field.db_indexLink to this definition#

True の場合、データベースインデックスがこのフィールドのために生成されます。

db_tablespaceLink to this heading#

Field.db_tablespaceLink to this definition#

このフィールドにインデックスが作成されている場合に、このフィールドのインデックスに使用する データベース テーブル空間 の名前です。デフォルトはプロジェクトの DEFAULT_INDEX_TABLESPACE が設定されている場合はその設定値、またはモデルの db_tablespace が設定されている場合はその設定値です。バックエンドがインデックスのテーブル空間をサポートしていない場合、このオプションは無視されます。

defaultLink to this heading#

Field.defaultLink to this definition#

そのフィールドのデフォルト値です。このオプションには特定の値もしくは呼び出し可能オブジェクトを渡すことができます。もし渡した値が呼び出し可能であれば新しくオブジェクトが生成される度に呼び出されます。

デフォルト値はミュータブルなオブジェクト（モデルのインスタンス、 list 、 set など）にはできません。そのオブジェクトの同じインスタンスへの参照が、すべての新しいモデルインスタンスのデフォルト値として使用されてしまうからです。代わりに、必要なデフォルト値を呼び出し可能オブジェクトでラップします。例えば、 JSONField に対してデフォルトの dict を指定したい場合、下記のような関数を使用します：

def contact_default():
    return {"email": "to1@example.com"}


contact_info = JSONField("ContactInfo", default=contact_default)

lambda は マイグレーションでシリアライズ できないので、default のようなフィールドオプションには使えません。その他の注意点についてはドキュメントを参照してください。

ForeignKey のようにモデルインスタンスにマッピングされるフィールドの場合、デフォルトはモデルインスタンスではなく、参照するフィールドの値 (to_field が設定されていない限り pk) になります。

デフォルト値は、新しいモデルインスタンスが作成され、フィールドに値が提供されていない場合に使用されます。フィールドが主キーの場合、フィールドが None に設定されているときにもデフォルト値が使われます。

デフォルト値は Field.db_default でデータベースレベルで設定することもできます。

editableLink to this heading#

Field.editableLink to this definition#

False の場合、フィールドは管理サイトやその他の ModelForm において表示されません。このとき model validation の過程でもスキップされます。デフォルトは True です。

error_messagesLink to this heading#

Field.error_messagesLink to this definition#

引数 error_messages を指定すると、フィールドが表示するデフォルトのメッセージを上書きできます。オーバーライドしたいエラーメッセージにマッチするキーを持つ辞書を渡してください。

エラーメッセージのキーには null, blank, invalid, invalid_choice, unique, unique_for_date があります。以下の Field types セクションで説明する各フィールドには、追加のエラーメッセージキーが指定されています。

これらのエラーメッセージはフォームに反映されないことがよくあります。詳細は モデルの error_messages についての注意 を参照してください。

help_textLink to this heading#

Field.help_textLink to this definition#

フォームウィジェットと共に表示される "補助" テキストになります。この値はフィールドがフォームとして利用されない場合でもドキュメント化する際に有用です。

この値は自動生成のフォームではHTMLエスケープ されません 。そのため、 help_text にはHTMLが使えます。例：

help_text = "Please use the following format: <em>YYYY-MM-DD</em>."

あるいは、プレーンテキストを使い、 django.utils.html.escape() で HTML の特殊文字をエスケープすることもできます。クロスサイトスクリプティング攻撃を避けるために、信頼できないユーザから来る可能性のあるヘルプテキストは必ずエスケープしてください。

primary_keyLink to this heading#

Field.primary_keyLink to this definition#

True の場合、設定したフィールドはそのモデルの主キーとなります。

モデル内のいずれのフィールドにも primary_key=True を指定せず、かつ複合主キーを定義していない場合、 Django は主キーを保持するためのフィールドを自動的に追加します。したがって、既定の主キー動作を上書きしたくなければ、どのフィールドにも primary_key=True を設定する必要はありません。自動作成される主キーの型は、アプリ単位では AppConfig.default_auto_field 、グローバルには DEFAULT_AUTO_FIELD 設定で指定できます。詳しくは 自動インクリメントの主キーフィールド を参照してください。

primary_key=True は null=False および unique=True を含意します。1 つのモデルで primary_key=True を設定できるフィールドは 1 つだけです。この不変条件を維持するため、複合主キーは、すべてのフィールドにこのフラグを True と設定するのではなく、CompositePrimaryKey を使用して定義しなければなりません。

主キーフィールドは読み取り専用です。既存のオブジェクトの主キーの値を変更して保存すると、古いオブジェクトはそのままで新しいオブジェクトが作成されます。

オブジェクトを 削除する 際に、主キーフィールドは None に設定されます。

uniqueLink to this heading#

Field.uniqueLink to this definition#

True の場合、そのフィールドはテーブル上で一意となる制約を受けます。

これはデータベースレベルとモデルのバリデーションで強制されます。 unique フィールドの値が重複しているモデルを保存しようとすると、モデルの save() メソッドによって django.db.IntegrityError が発生します。

このオプションは ManyToManyField と OneToOneField 以外の全てのフィールドタイプで有効です。

unique が True の場合、db_index を指定する必要はないことに注意してください。なぜなら unique がインデックスの作成を意味するからです。

unique_for_dateLink to this heading#

Field.unique_for_dateLink to this definition#

これを DateField または DateTimeField の名前に設定すると、このフィールドが日付フィールドの値に対して一意であることを要求します。

例えば、 title フィールドに unique_for_date="pub_date" を指定した場合、 Django は同じ title と pub_date を持つ 2 つのレコードの入力を許可しません。

DateTimeField を指すように設定した場合は、フィールドの日付部分のみが考慮されることに注意してください。また、 USE_TZ が True の場合、オブジェクトの保存時に カレントタイムゾーン でチェックが行われます。

This is enforced by Model.validate_unique() during model validation but not at the database level. If any unique_for_date constraint involves fields that are not part of a ModelForm (for example, if one of the fields is listed in exclude or has editable=False), Model.validate_unique() will skip validation for that particular constraint.

unique_for_monthLink to this heading#

Field.unique_for_monthLink to this definition#

unique_for_date と似ていますが、フィールドが月に対して一意である必要があります。

unique_for_yearLink to this heading#

Field.unique_for_yearLink to this definition#

unique_for_date や unique_for_month と同様です。

verbose_nameLink to this heading#

Field.verbose_nameLink to this definition#

人間が読めるフィールド名。verbose な名前が指定されていない場合、 Django はフィールドの属性名を使って自動的にフィールドを作成し、アンダースコアをスペースに変換します。詳しくは verbose なフィールド名 を参照してください。

validatorsLink to this heading#

Field.validatorsLink to this definition#

このフィールドに対して実行するバリデータのリスト。詳細は バリデータのドキュメント を参照してください。

AutoFieldLink to this heading#

class AutoField(**options)Link to this definition#

利用可能な ID に応じて、自動的にインクリメントする IntegerField です。通常は直接使う必要はありません; 指定しない場合は、主キーのフィールドが自動的にモデルに追加されます。自動インクリメントの主キーフィールド も参照してください。

BigAutoFieldLink to this heading#

class BigAutoField(**options)Link to this definition#

64 ビットの数値です。1 から 9223372036854775807 までの数を扱える以外は、AutoField と同じです。

BigIntegerFieldLink to this heading#

class BigIntegerField(**options)Link to this definition#

64 ビットの整数で、 IntegerField とよく似ていますが、 -9223372036854775808 から 9223372036854775807 までの数値が入ることが保証されています。このフィールドのデフォルトのフォームウィジェットは NumberInput です。

BinaryFieldLink to this heading#

class BinaryField(max_length=None, **options)Link to this definition#

生のバイナリデータを格納するフィールドです。 bytes, bytearray または memoryview を指定できます。

デフォルトでは、 BinaryField は editable を False に設定します。この場合、 ModelForm に含めることはできません。

BinaryField.max_lengthLink to this definition#

オプション。フィールドの最大長 (バイト単位)。最大長は MaxLengthValidator を使ったDjango のバリデーションで強制されます。

BooleanFieldLink to this heading#

class BooleanField(**options)Link to this definition#

true/false のフィールドです。

このフィールドのデフォルトのフォームウィジェットは CheckboxInput で、 null=True の場合は NullBooleanSelect です。

Field.default が定義されていないときの BooleanField のデフォルト値は None です。

CompositePrimaryKeyLink to this heading#

class CompositePrimaryKey(*field_names, **options)Link to this definition#

複合主キーを定義するために用いられる仮想的なフィールドです。

このフィールドはモデルの pk 属性として定義しなければなりません。これが存在する場合、 Django は基盤となるモデルテーブルを複合主キーで作成します。

*field_names 引数は主キーを構成する位置フィールド名のリストです。

詳細は 複合主キー を参照してください。

CharFieldLink to this heading#

class CharField(max_length=None, **options)Link to this definition#

小 - 大サイズの文字列のフィールドです。

多量のテキストを扱うときは TextField を使ってください。

このフィールドのデフォルトのフォームウィジェットは TextInput です。

CharField には以下の追加引数があります：

CharField.max_lengthLink to this definition#

フィールドの（文字数の）最大値。 max_length はデータベース層および class:~django.core.validators.MaxLengthValidator を使用した Django のバリデーションによる制約を受けます。無制限の VARCHAR 列をサポートする PostgreSQL と SQLite を除き、 Django でサポートされるすべてのデータベースバックエンドにおいて必須です。

CharField.db_collationLink to this definition#

オプション。フィールドのデータベース照合順序名(collation name)です。

DateFieldLink to this heading#

class DateField(auto_now=False, auto_now_add=False, **options)Link to this definition#

Python で datetime.date インスタンスによって表される日付です。多少の追加的な省略可能な引数を持ちます:

DateField.auto_nowLink to this definition#

オブジェクトが保存される度に自動的に現在の日付をセットします。"最後の変更" タイムスタンプに役立ちます。現在の日付が常に使われる点に注意してください; オーバーライドできる単なるデフォルト値ではありません。

Model.save() が呼ばれたとき、フィールドは自動的に更新されるだけです。QuerySet.update() のような別の方法で他のフィールドに更新を加えるとき、フィールドは更新されません。あのように更新の中でフィールドの独自の値を指定できるとしてもです。

DateField.auto_now_addLink to this definition#

オブジェクトが最初に作成されるとき、自動的にフィールドに現在の日付をセットします。タイムスタンプの作成に役立ちます。現在の日付が 常に 使われる点に注意してください; オーバーライドできる単なるデフォルト値ではありません。たとえオブジェクトを作成するときに値をセットしたとしても無視されます。このフィールドを修正できるようにしておきたい場合は、auto_now_add=True の代わりに以下をセットしてください:

• DateField に対して: default=date.today - datetime.date.today() より

• DateTimeField に対して: default=timezone.now - django.utils.timezone.now() より

このフィールドのデフォルトのフォームウィジェットは DateInput です。admin は JavaScript カレンダーと "Today" のショートカットを追加します。追加の invalid_date エラーメッセージキーを含みます。

オプション auto_now_add、auto_now、default は相互に排他的です。これらのオプションを組み合わせるとエラーが発生します。

DateTimeFieldLink to this heading#

class DateTimeField(auto_now=False, auto_now_add=False, **options)Link to this definition#

Python で datetime.datetime インスタンスによって表される日付と時刻です。DateField と同じくいくつかの追加的な引数を持ちます:

このフィールドのデフォルトのフォームウィジェットは DateTimeInput です。管理画面では、JavaScript のショートカットを使って TextInput ウィジェットを 2 つに分けて使用します。

DecimalFieldLink to this heading#

class DecimalField(max_digits=None, decimal_places=None, **options)Link to this definition#

固定精度の10進数で、Python では Decimal インスタンスで表されます。これは DecimalValidator を使用して入力を検証します。

以下の 必須の 引数があります：

DecimalField.max_digitsLink to this definition#

数値内で使える桁数の最大値です。 decimal_places 以上でなければならない点に注意してください。

DecimalField.decimal_placesLink to this definition#

数値とともに保持される小数点以下の位の数です。

例えば、小数点以下2桁の分解能で 999.99 までの数値を保存するには、次のようにします：

models.DecimalField(..., max_digits=5, decimal_places=2)

小数点以下第10位の精度で約10億までを保持するには:

models.DecimalField(..., max_digits=19, decimal_places=10)

このフィールドのデフォルトのフォームウィジェットは、localize が False のとき NumberInput で、そうでなければ TextInput となります。

DurationFieldLink to this heading#

class DurationField(**options)Link to this definition#

時刻の期間を保持するフィールドで、 Python の timedelta によってモデル化されます。PostgreSQL で使われるときに用いられるデータ型は interval で、Oracle でのデータ型は INTERVAL DAY(9) TO SECOND(6) です。 それ以外では、マイクロ秒の bigint が使われます。

EmailFieldLink to this heading#

class EmailField(max_length=254, **options)Link to this definition#

EmailValidator を使って、値が有効なメールアドレスであるかどうかをチェックする CharField です。

FileFieldLink to this heading#

class FileField(upload_to='', storage=None, max_length=100, **options)Link to this definition#

ファイルアップロードのフィールドです。

以下のオプション引数があります：

FileField.upload_toLink to this definition#

この属性は、アップロードディレクトリとファイル名を設定する方法を提供し、2 つの方法でセットできます。どちらの場合も、値は Storage.save() メソッドに渡されます。

文字列値または Path を指定する場合、 strftime() フォーマットを含むことができます。これはファイルアップロードの日時に置き換えられます（アップロードされたファイルで指定されたディレクトリが一杯にならないようにするためです）。例えば以下のようにします：

Code

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 を使用している場合、この文字列の値が MEDIA_ROOT パスに追加され、アップロードされたファイルが保存されるローカルファイルシステムの場所になります。別のストレージを使用している場合は、そのストレージのドキュメントで upload_to の扱い方を確認してください。

upload_to は関数のなどの呼び出し可能オブジェクトにすることもできます。これはファイル名を含むアップロードパスを取得するために呼び出されます。この呼び出し可能オブジェクトは2つの引数を受け取り、ストレージシステムに渡すUnixスタイルのパス（フォワードスラッシュ付き）を返さなければなりません。2つの引数は

引数	説明
instance	FileField が定義されているモデルのインスタンス。具体的には、そのファイルが格納されている特定のインスタンスです。 ほとんどの場合、このオブジェクトはまだデータベースに保存されていないため、デフォルトの AutoField を使用している場合、 主キーフィールドの値をまだ持っていない可能性があります 。
filename	ファイルに元々与えられていたファイル名。これは、最終的な宛先パスを決定するときに考慮されることもあれば、考慮されないこともあります。

例:

Code

def user_directory_path(instance, filename):
    # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
    return "user_{0}/{1}".format(instance.user.id, filename)


class MyModel(models.Model):
    upload = models.FileField(upload_to=user_directory_path)

FileField.storageLink to this definition#

ストレージオブジェクト、またはストレージオブジェクトを返す呼び出し可能オブジェクトです。これはファイルの保存と取得を行います。このオブジェクトの渡し方の詳細については ファイルの管理 を参照してください。

このフィールドのデフォルトのフォームウィジェットは ClearableFileInput です。

モデル内で a FileField や ImageField (後述) 使うにはいくつかのステップを取ります:

1. 設定ファイルでは、 MEDIA_ROOT を Django にアップロードされたファイルを保存するディレクトリへのフルパスを指定する必要があります（パフォーマンス上、これらのファイルはデータベースには保存されません）。 MEDIA_URL をそのディレクトリの公開 URL にします。このディレクトリは Web サーバのユーザアカウントで書き込み可能である必要があります。

2. モデルに FileField または ImageField を追加し、 upload_to オプションを定義して、ファイルをアップロードする MEDIA_ROOT のサブディレクトリを指定します。

3. データベースに保存されるのは、ファイルへのパス (MEDIA_ROOT からの相対パス) だけです。Django 組み込みの url 属性を使うと便利です。例えば、 ImageField が mug_shot という名前の場合、 {{ object.mug_shot.url }} でテンプレート内の画像の絶対パスを取得できます。

例えば、 MEDIA_ROOT が '/home/media' に設定され、 upload_to が 'photos/%Y/%m/%d' に設定されているとします。 upload_to の '%Y/%m/%d' の部分は strftime() フォーマットです。'%Y' は4桁の年、'%m' は2桁の月、'%d' は2桁の日です。2007年1月15日にファイルをアップロードすると、 /home/media/photos/2007/01/15 というディレクトリに保存されます。

アップロードされたファイルのディスク上のファイル名やファイルサイズを取得したい場合は、それぞれ name 属性と size 属性を使うことができます。利用可能な属性やメソッドの詳細については File クラスリファレンス と ファイルの管理 トピックガイド を参照してください。

アップロードされたファイルの相対URLは url 属性で取得できます。内部的には、 Storage クラスの url() メソッドを呼び出します。

アップロードされたファイルを扱うときは常に、セキュリティホールを避けるために、アップロードする場所とファイルの種類に細心の注意を払う必要があることに注意してください。 アップロードされたすべてのファイルを検証し 、そのファイルがあなたが考えているものであることを確認してください。例えば、誰かがあなたのウェブサーバーのドキュメントルートにあるディレクトリに、検証なしでファイルをアップロードするのをやみくもに許可すると、誰かがCGIやPHPスクリプトをアップロードし、あなたのサイトのそのURLにアクセスしてスクリプトを実行できます。それを許してはいけません。

また、アップロードされたHTMLファイルであっても、ブラウザが実行できるため（サーバは実行できませんが）、XSS攻撃やCSRF攻撃と同様のセキュリティ上の脅威をもたらす可能性があることに注意してください。

FileField インスタンスは varchar カラムとしてデータベースに作成され、デフォルトの最大長は100文字です。他のフィールドと同様に、 max_length 引数を使用して最大長を変更できます。

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)

from django.core.files.base import ContentFile

myfile = ContentFile("hello world")

FilePathFieldLink to this heading#

class FilePathField(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options)Link to this definition#

CharField は選択肢をファイルシステム上の特定のディレクトリにあるファイル名に限定します。いくつかの特別な引数を持ちますが、最初の引数は 必須 です：

FilePathField.pathLink to this definition#

必須です。FilePathField が選択肢から取得するディレクトリへの、ファイルシステムの絶対パスです。例: "/home/images"。

path には呼び出し可能オブジェクトを指定することもでき、これは例えば実行時に動的にパスを設定する関数などです。例：

Code

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.matchLink to this definition#

省略可能です。正規表現で、文字列として、FilePathField がファイル名をフィルタリングするために使用します。 正規表現は、フルパスではなくベースファイル名に適用される点に注意してください。 例: "foo.*\.txt$"。これは foo23.txt とは合致しますが、bar.txt や foo23.png とは合致しません。

FilePathField.recursiveLink to this definition#

省略可能です。True か False のどちらかを取り、デフォルトは False です。path の全てのサブディレクトリを含むかどうかを指定します。

FilePathField.allow_filesLink to this definition#

Optional. Either True or False. Default is True. Specifies whether files in the specified location should be included. Either this or allow_folders must be True.

FilePathField.allow_foldersLink to this definition#

Optional. Either True or False. Default is False. Specifies whether folders in the specified location should be included. Either this or allow_files must be True.

1つの可能性は、フルパスではなく、ベースファイル名に match が適用されることです。 したがって、この例:

FilePathField(path="/home/images", match="foo.*", recursive=True)

...は、/home/images/foo/bar.png ではなく /home/images/foo.png とマッチします。これは、match がベースのファイル名に適用されるからです (foo.png と bar.png)。

FilePathField のインスタンスは、デフォルトが最大 100 文字の varchar カラムとして、データベース上に生成されます。他のフィールドと同様に、max_length 引数を使って最大文字数を変更できます。

FloatFieldLink to this heading#

class FloatField(**options)Link to this definition#

float インスタンスによって表される Python の浮動小数点数です。

このフィールドのデフォルトのフォームウィジェットは、localize が False のとき NumberInput で、そうでなければ TextInput となります。

GeneratedFieldLink to this heading#

class GeneratedField(*, expression, output_field, db_persist, **kwargs)Link to this definition#

常にモデル内の他のフィールドに基づいて計算されるフィールド。このフィールドはデータベース自身によって管理・更新されます。 GENERATED ALWAYS SQL 構文を使います。

生成カラムには、格納と仮想の2種類があります。格納生成カラムは書き込まれる (挿入もしくは更新される) ときに計算され、通常のカラムと同じようにストレージを占有します。仮想生成カラムはストレージを占有せず、読み込まれるときに計算されます。したがって、仮想生成カラムはビューに似ており、格納生成カラムはマテリアライズド・ビューに似ています。

GeneratedField.expressionLink to this definition#

モデルが変更されるたびにフィールドの値を自動的に設定するためにデータベースによって使用される Expression 。

式は決定論的でなければならず、モデル内の（同じデータベース・テーブル内の）フィールドだけを参照しなければなりません。生成フィールドは他の生成フィールドを参照することはできません。データベースのバックエンドはさらなる制限を課すことができます。

GeneratedField.output_fieldLink to this definition#

フィールドのデータ型を定義するモデルフィールドインスタンス。

GeneratedField.db_persistLink to this definition#

データベースカラムが実際のカラムのようにストレージを占有するかどうかを決定します。 False の場合、カラムは仮想カラムとして動作し、データベースのストレージ領域を占有しません。

PostgreSQLは永続化 (persist) 列のみをサポートしています。Oracle は仮想列のみをサポートしています。

GenericIPAddressFieldLink to this heading#

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)Link to this definition#

IPv4 か IPv6 のアドレスで、文字列フォーマットです (例: 192.0.2.30 ないし 2a02:42fe::4)。このフィールドのデフォルトのフォームウィジェットは TextInput です。

IPv6 アドレスは、 RFC 4291 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.protocolLink to this definition#

有効なインプットを、指定したプロトコルに制限します。 使用可能な値は 'both' (デフォルト)、'IPv4'、'IPv6' のどれかです。マッチングは大文字と小文字を区別しません。

GenericIPAddressField.unpack_ipv4Link to this definition#

IPv4 にマッピングされた ::ffff:192.0.2.1 のようなアドレスをアンパックします。このオプションを有効にすると、このアドレスは 192.0.2.1 とアンパックされます。デフォルトは無効です。protocol が 'both' に設定されている場合にだけ使用できます。

ブランク値を要する場合、ブランク値は null として保持されるため、null 値を許容する必要があります。

ImageFieldLink to this heading#

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)Link to this definition#

FileField から全ての属性とメソッドを継承して、さらにアップロードされたオブジェクトが有効な画像であることを検証します。

FileField で使える専用の属性に加えて、ImageField には height と width 属性があります。

これらの属性に対するクエリを容易にするために、ImageField は以下のオプション引数を持ちます：

ImageField.height_fieldLink to this definition#

画像オブジェクトがセットされるたびに自動的に画像の高さが入力されるモデルフィールドの名前。

ImageField.width_fieldLink to this definition#

画像オブジェクトがセットされるたびに自動的に画像の幅が入力されるモデルフィールドの名前。

pillow ライブラリを必要とします。

ImageField のインスタンスは、デフォルトが最大 100 文字の varchar カラムとして、データベース上に生成されます。他のフィールドと同様に、max_length 引数を使って最大文字数を変更できます。

このフィールドのデフォルトのフォームウィジェットは ClearableFileInput です。

IntegerFieldLink to this heading#

class IntegerField(**options)Link to this definition#

整数値です。特定範囲の値のみ使用可能です (その範囲はデータベースに依存します)。 -2147483648 から 2147483647 までの値は、Django がサポートするすべてのデータベースで安全に使用できます。

MinValueValidator と MaxValueValidator を使って、デフォルトのデータベースがサポートする値に基づいて入力を検証します。

このフィールドのデフォルトのフォームウィジェットは、localize が False のとき NumberInput で、そうでなければ TextInput となります。

JSONFieldLink to this heading#

class JSONField(encoder=None, decoder=None, **options)Link to this definition#

JSON エンコードされたデータを格納するためのフィールドです。Python では、データは Python ネイティブフォーマットで表現されます。辞書、リスト、文字列、数値、真偽値、そして None です。

JSONField はMariaDB、MySQL、Oracle、PostgreSQL、(JSON1 エクステンションが有効な) SQLite でサポートされています。

JSONField.encoderLink to this definition#

An optional json.JSONEncoder subclass to serialize data types not supported by the standard JSON serializer (e.g. datetime.datetime or UUID). For example, you can use the DjangoJSONEncoder class.

デフォルトは json.JSONEncoder です。

JSONField.decoderLink to this definition#

An optional 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 datetimes.

デフォルトは json.JSONDecoder です。

データベース内の JSONField をクエリするには、 JSONField へのクエリ を参照してください。

PositiveBigIntegerFieldLink to this heading#

class PositiveBigIntegerField(**options)Link to this definition#

PositiveIntegerField とほぼ同じですが、特定の数以下の値のみ使用可能です (その上限はデータベースに依存します)。 0 から 9223372036854775807 までの値は、 Django がサポートする全てのデータベースで安全に使用できます。

PositiveIntegerFieldLink to this heading#

class PositiveIntegerField(**options)Link to this definition#

IntegerField とほぼ同じですが、ゼロ( 0 )以上の整数で、特定の数以下の値のみ使用可能です (その上限はデータベースに依存します)。 0 から 2147483647 までの値は、 Django がサポートするすべてのデータベースで安全に使用できます。値 0 は後方互換性のために許容されています。

PositiveSmallIntegerFieldLink to this heading#

class PositiveSmallIntegerField(**options)Link to this definition#

class:PositiveIntegerField とほぼ同じですが、特定の数以下の値のみ使用可能です (その上限はデータベースに依存します)。 0 から 32767 までの値は、 Django がサポートする全てのデータベースで安全に使用できます。

SlugFieldLink to this heading#

class SlugField(max_length=50, **options)Link to this definition#

スラグ (slug) は新聞用語です。スラグとは、アルファベット、数字、アンダースコア、またはハイフンのみを含む、何かの短いラベルです。一般的にURLで使われます。

CharField のように、max_length を指定することもできます (データベースの可搬性についてのノートとそのセクションの max_length も参照してください)。max_length が指定されていないとき、Django はデフォルトの文字数 50 を使います。

暗黙的に 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.

バリデーションには validate_slug または validate_unicode_slug を使用します。

SlugField.allow_unicodeLink to this definition#

True なら、フィールドはASCII文字に加えてUnicode文字も受け付けます。デフォルトは False です。

SmallAutoFieldLink to this heading#

class SmallAutoField(**options)Link to this definition#

class:AutoField とほぼ同じですが、特定の数以下の値のみ使用可能です (その上限はデータベースに依存します)。 1 から 32767 までの値は、 Django がサポートする全てのデータベースで安全に使用できます。

SmallIntegerFieldLink to this heading#

class SmallIntegerField(**options)Link to this definition#

class:IntegerField とほぼ同じですが、特定の数以下の値のみ使用可能です (その上限はデータベースに依存します)。 -32768 から 32767 までの値は、 Django がサポートする全てのデータベースで安全に使用できます。

TextFieldLink to this heading#

class TextField(**options)Link to this definition#

多量のテキストのフィールドです。このフィールドのデフォルトのフォームウィジェットは Textarea です。

max_length 属性を指定した場合、自動生成されたフォームフィールドの Textarea ウィジェット内で反映されます。ただし、モデルやデータベースのレベルでは施行されません。そのためには CharField を使用してください。

TextField.db_collationLink to this definition#

オプション。フィールドのデータベース照合順序名(collation name)です。

TimeFieldLink to this heading#

class TimeField(auto_now=False, auto_now_add=False, **options)Link to this definition#

Python で datetime.time インスタンスによって表される時刻です。DateField と同じ自動入力されるオプションを受け入れます。

このフィールドのデフォルトのフォームウィジェットは TimeInput です。admin はいくつかの JavaScript ショートカットを追加します。

URLFieldLink to this heading#

class URLField(max_length=200, **options)Link to this definition#

URLの CharField で、 URLValidator によってバリデーションされます。

このフィールドのデフォルトのフォームウィジェットは URLInput です。

全ての CharField サブクラスと同じく、URLField は省略可能な max_length 引数を取ります。max_length を指定しない場合、デフォルトの 200 が使われます。

UUIDFieldLink to this heading#

class UUIDField(**options)Link to this definition#

一意な識別子を格納するためのフィールドです。Python の UUID クラスを使用します。PostgreSQL と MariaDB 10.7+ で使用する場合、 uuid データ型で保存されます。

UUID は primary_key に代わる AutoField への良い選択肢です。 データベースはあなたのための UUID を生成しないため、 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 に渡すことに注意してください。

ForeignKeyLink to this heading#

class ForeignKey(to, on_delete, **options)Link to this definition#

多対一のリレーションシップです。モデルが関連するクラスと、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)

最初の位置引数には、具象モデルクラスまたはモデルクラスへの 遅延参照 のいずれかを指定できます。モデルが自分自身とリレーションシップを持つ 再帰的リレーションシップ もサポートされています。

2番目の位置引数の詳細については、ForeignKey.on_delete を参照してください。

A database index is automatically created on the ForeignKey. You can disable this by setting 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.

ManyToManyFieldLink to this heading#

class ManyToManyField(to, **options)Link to this definition#

多対多のリレーションシップ。位置引数が必要で、モデルがリレーションを持つクラスを指定します。これは ForeignKey での使用と全く同じ方法で機能し、再帰的なリレーションシップ や 遅延リレーションシップ を含みます。

リレーション先オブジェクトはフィールドの RelatedManager で追加、削除、作成ができます。

OneToOneFieldLink to this heading#

class OneToOneField(to, on_delete, parent_link=False, **options)Link to this definition#

一対一のリレーションシップです。概念的には ForeignKey に unique=True を指定したものと似ていますが、リレーションの "反対側" が直接1つのオブジェクトを返します。

これは、何らかの方法で別のモデルを「拡張」するモデルの主キーとして最も有用です。例えば、マルチテーブル継承 は、子モデルから親モデルへの暗黙の一対一リレーションシップを追加することによって実装されます。

位置引数が1つ必要で、モデルが関連付けられるクラスを指定します。これは ForeignKey と全く同じ方法で機能し、再帰的なリレーションシップ や 遅延リレーションシップ に関するすべてのオプションが含まれます。

もし OneToOneField に 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 モデルは以下の属性を持つことになります：

>>> user = User.objects.get(pk=1)
>>> hasattr(user, "myspecialuser")
True
>>> hasattr(user, "supervisor_of")
True

リレーション先テーブルにエントリが存在しない場合、逆リレーションシップにアクセスすると RelatedObjectDoesNotExist 例外が発生します。これは対象モデルの Model.DoesNotExist 例外のサブクラスであり、逆アクセサ (reverse accessor) の属性としてアクセスできます。たとえば、ユーザーに MySpecialUser によって指定されたスーパーバイザーがいない場合：

try:
    user.supervisor_of
except User.supervisor_of.RelatedObjectDoesNotExist:
    pass

さらに、OneToOneField は ForeignKey が受け付ける全ての引数に加え、1つの追加引数を受け付けます：

OneToOneField.parent_linkLink to this definition#

True に設定され、他の concrete model から継承されたモデルで使用された場合、サブクラス化によって通常は暗黙的に作成される追加の OneToOneField の代わりに、このフィールドが親クラスへのリンクとして使用されるべきことを示します。

OneToOneField の使用例については 一対一のリレーションシップ を参照してください。

遅延リレーションシップLink to this heading#

遅延リレーションシップを使用すると、モデルを名前（文字列）で参照したり、再帰的リレーションシップを作成したりできます。文字列は、任意のリレーションシップフィールドの最初の引数として使用でき、モデルを遅延参照します。遅延参照には、再帰的、相対的、または 絶対的 参照が含まれます。

from django.db import models


class Manufacturer(models.Model):
    name = models.TextField()
    suppliers = models.ManyToManyField("self", symmetrical=False)

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)

from django.db import models


class AbstractCar(models.Model):
    manufacturer = models.ForeignKey("Manufacturer", on_delete=models.CASCADE)

    class Meta:
        abstract = True

from django.db import models
from products.models import AbstractCar


class Manufacturer(models.Model):
    name = models.TextField()


class Car(AbstractCar):
    pass

class Car(models.Model):
    manufacturer = models.ForeignKey(
        "thirdpartyapp.Manufacturer",
        on_delete=models.CASCADE,
    )