Getting Help

el
en
es
fr
id
it
ko
pl
pt-br
zh-hans
言語: ja

1.10
1.11
2.0
2.1
2.2
3.0
3.1
3.2
4.0
4.1
4.2
5.0
dev
ドキュメントのバージョン: 5.1

モデルフィールドリファレンス¶

このドキュメントには、Django が提供する field options と field types を含む、Field の全ての API リファレンスが記載されています。

参考

If the built-in fields don't do the trick, you can try django-localflavor (documentation), which contains assorted pieces of code that are useful for particular countries and cultures.

さらに、簡単にあなた自身の独自のモデルフィールドを作ることもできます。

注釈

技術的には、これらのモデルは django.db.models.fields 内で定義されていますが、利便性のため django.db.models にインポートされています; 標準的な慣習では、from django.db import models を使って、フィールドを models.<Foo>Field として参照します。

フィールドオプション¶

以下の引数は全てのフィールドタイプで有効です。全て省略可能です。

`null`¶

Field.null¶

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

CharField や TextField のような文字列ベースのフィールドでは null の使用を避けてください。文字列ベースのフィールドに null=True が設定されている場合、"データがない "という意味に2通りの値が設定されていることを意味します。 NULL と空の文字列です。ほとんどの場合、"データなし" に 2 通りの値を指定するのは冗長であり、 Django の慣例では NULL ではなく、空の文字列を指定します。Django の規約では NULL ではなく、空文字列を使うことになっています。例外は CharField に unique=True と blank=True の両方が設定されている場合です。このような場合、 null=True は、空白の値を持つ複数のオブジェクトを保存する際に、ユニーク制約違反を避けるために必要です。

文字列ベースと非文字列ベースのフィールドのどちらでも、フォーム内で空の値を許容したい場合には、blank=True をセットすることも必要となります。これは、null パラメータはデータベーストレー時のみに影響するためです (blank を参照してください)。

注釈

Oracleのデータベースバックエンドを使っているときには、この属性にかかわらず、値 NULL が空の文字列を意味するために保持されます。

`blank`¶

Field.blank¶

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

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

欠損値の補完

blank=True``は ``null=False のフィールドでも使用できますが、この場合、 clean() を実装し、欠損値をプログラムで補完する必要があります。

`choices`¶

Field.choices[ソース]¶

このフィールドの選択肢として使用するための、以下で説明する形式のマッピングまたはイテラブルです。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バウンド操作の結果（キャッシュされる可能性があります）。
ほぼ安定しているが、場合によって、あるいはプロジェクトによって異なる可能性のあるリスト。このカテゴリの例は、通貨、国、言語、タイムゾーンなど、よく知られた値のインベントリを提供するサードパーティのアプリを使用する場合などです。

Changed in Django 5.0:

マッピングと callable のサポートが追加されました。

一般的に、モデルクラスの内部で選択肢を定義し、それぞれの値に適切に名前づけられた定数を定義するのがベストです:

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

注釈

choices の順番を変更すると、変更のたびに新しいマイグレーションが生成されます。

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

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

列挙型¶

さらに 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 と似たような動作をしますが、若干の変更が加えられています：

列挙型のメンバ値は、具象データ型を構築するときに使う引数のタプルです。Django はこのタプルの末尾に、人間が読める名前、つまり label として使われる文字列値を追加することをサポートしています。この label は遅延 (Lazy な) 翻訳が可能な文字列です。したがって、ほとんどの場合、メンバの値は (value, label) の2値タプルになります。より複雑なデータ型を使用した選択肢のサブクラスの例については以下を参照してください。タプルが提供されない場合、あるいは最後の項目が（lazyな）文字列でない場合、 label はメンバー名から自動的に生成されます。
値には .label プロパティが追加され、人間が読める名前を返します。
列挙型クラスには、 .choices, .labels, .values, .names などのカスタムプロパティが追加されており、これらの列挙型の異なる部分のリストに簡単にアクセスできるようになっています。

警告

これらのプロパティ名をメンバ名として使用することはできません。
値が複数回定義できないようにするため、 enum.unique() の使用が強制されます。これはフィールドの choices ではあまり期待されません。

なお、 YearInSchool.SENIOR, YearInSchool['SENIOR'], YearInSchool('SR') を使用して列挙型のメンバにアクセスしたり、メンバの .name と .value プロパティを参照したりすることは期待通りに動作します。

人が読める名前を翻訳する必要がない場合は、メンバ名から推測してそれらを自動設定させることができます（アンダースコアをスペースに置き換え、タイトルケースを使用します）：

>>> 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 を利用することもできます。この場合、ラベルは上記のように自動的に生成されます：

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

さらに注意すべき点がいくつかあります：

列挙型は名前付きグループをサポートしていません。
具体的なデータ型を持つ列挙型では、すべての値がそのデータ型に一致する必要があるため、 blank label をオーバーライドする際に、 None という値を持つメンバを作成することはできません。代わりに、クラスに __empty__ 属性を設定します：
```
class Answer(models.IntegerChoices):
    NO = 0, _("No")
    YES = 1, _("Yes")

    __empty__ = _("(Unknown)")
```

Changed in Django 5.0:

選択肢 choices で列挙型を直接使用できるようになりました。

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

New in Django 5.0.

Field.db_default¶

データベースによって計算されるこのフィールドのデフォルト値。これはリテラル値でも、 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_index`¶

Field.db_index¶

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

代わりに indexes オプションを使用してください。

可能であれば、代わりに Meta.indexes オプションを使用してください。ほとんどの場合、 indexes は db_index よりも多くの機能を提供します。 db_index は将来廃止される可能性があります。

`db_tablespace`¶

Field.db_tablespace[ソース]¶

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

`default`¶

Field.default¶

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

デフォルト値はミュータブルなオブジェクト（モデルのインスタンス、 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 でデータベースレベルで設定することもできます。

`editable`¶

Field.editable¶

False の場合、フィールドは管理画面や他の ModelForm に表示されません。また、モデルのバリデーションの間、フィールドはスキップされます。デフォルトは True です。

`error_messages`¶

Field.error_messages[ソース]¶

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

エラーメッセージのキーには null, blank, invalid, invalid_choice, unique, unique_for_date があります。その他のエラーメッセージのキーは、以下の Field types セクションでフィールドごとに指定します。

これらのエラーメッセージはフォームに伝搬しないことがよくあります。モデルの error_messages のレンダリングを考えるを参照してください。

`help_text`¶

Field.help_text¶

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

この値は自動生成されたフォームではHTMLエスケープされないことに注意してください。これにより、 help_text にHTMLを含めることができます。例えば：

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

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

`primary_key`¶

Field.primary_key¶

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

モデル内のどのフィールドにも primary_key=True を指定しなければ、 Django は自動的に主キーを保持するフィールドを追加しますので、デフォルトの主キーの動作を上書きしたくない限り、どのフィールドにも primary_key=True を設定する必要はありません。自動作成される主キーフィールドの種類は、 AppConfig.default_auto_field でアプリごとに指定するか、 DEFAULT_AUTO_FIELD 設定でグローバルに指定できます。詳しくは自動インクリメントのプライマリーキーフィールドを参照してください。

primary_key=True は null=False と unique=True を意味します。オブジェクトに指定できる主キーは1つだけです。

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

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

`unique`¶

Field.unique[ソース]¶

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

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

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

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

`unique_for_date`¶

Field.unique_for_date¶

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

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

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

これはモデルの検証時に Model.validate_unique() によって強制されますが、データベースレベルでは強制されません。 unique_for_date 制約が ModelForm の一部ではないフィールドを含む場合 (例えば、フィールドの一つが exclude にリストされていたり、 editable=False を持っている場合)、 Model.validate_unique() はその特定の制約の検証をスキップします。

`unique_for_month`¶

Field.unique_for_month¶

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

`unique_for_year`¶

Field.unique_for_year¶

unique_for_date や unique_for_month と同様です。

`verbose_name`¶

Field.verbose_name¶

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

`validators`¶

Field.validators[ソース]¶

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

フィールドの型¶

`AutoField`¶

class AutoField(**options)[ソース]¶

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

`BigAutoField`¶

class BigAutoField(**options)[ソース]¶

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

`BigIntegerField`¶

class BigIntegerField(**options)[ソース]¶

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

`BinaryField`¶

class BinaryField(max_length=None, **options)[ソース]¶

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

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

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

BinaryField を誤用する

ファイルをデータベース内に格納したいと考えるかもしれませんが、99%のケースにおいてそれは悪い設計です。このフィールドは、適切な静的ファイルの取り扱いに対する代替手段では ありません 。

`BooleanField`¶

class BooleanField(**options)[ソース]¶

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

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

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

`CharField`¶

class CharField(max_length=None, **options)[ソース]¶

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

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

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

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

CharField.max_length¶: フィールドの最大長 (文字数)。 MaxLengthValidator を使って、 max_length をデータベースレベルと Django のバリデーションで強制します。これは PostgreSQL 以外の Django に含まれる全てのデータベースバックエンドで必要です。PostgreSQL は無制限の VARCHAR カラムをサポートしています。

注釈

複数のデータベースバックエンド間で使われるアプリケーションを作る場合は、いくつかのバックエンドで max_length に制限があることに注意しなければなりません。詳しくはデータベースバックエンドの注意事項を参照してください。

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

注釈

照合順序名は標準化されていません。そのため、これは複数のデータベースバックエンド間でポータブルではありません。

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

DateField.auto_now_add¶

オブジェクトが最初に作成されるとき、自動的にフィールドに現在の日付をセットします。タイムスタンプの作成に役立ちます。現在の日付が常に使われる点に注意してください; オーバーライドできる単なるデフォルト値ではありません。たとえオブジェクトを作成するときに値をセットしたとしても無視されます。このフィールドを修正できるようにしておきたい場合は、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 は相互に排他的です。これらのオプションを組み合わせるとエラーが発生します。

注釈

現在実装されているように、auto_now や auto_now_add を True にセットすると、フィールドは editable=False と blank=True にセットされます。

注釈

auto_now と auto_now_add オプションは、常に作成時または更新時のデフォルトのタイムゾーンの日付を使用します。もし別のものが必要であれば、auto_now や auto_now_add を使用する代わりに、独自の呼び出し可能オブジェクトをデフォルトとして使用するか、 save() をオーバーライドするか、あるいは DateField の代わりに DateTimeField を使用し、表示時に datetime から date への変換をどのように処理するかを検討するとよいでしょう。

警告

Always use DateField with a datetime.date instance.

If you have a datetime.datetime instance, it's recommended to convert it to a datetime.date first. If you don't, DateField will localize the datetime.datetime to the default timezone and convert it to a datetime.date instance, removing its time component. This is true for both storage and comparison.

`DateTimeField`¶

class DateTimeField(auto_now=False, auto_now_add=False, **options)[ソース]¶

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

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

警告

Always use DateTimeField with a datetime.datetime instance.

If you have a datetime.date instance, it's recommended to convert it to a datetime.datetime first. If you don't, DateTimeField will use midnight in the default timezone for the time component. This is true for both storage and comparison. To compare the date portion of a DateTimeField with a datetime.date instance, use the date lookup.

`DecimalField`¶

class DecimalField(max_digits=None, decimal_places=None, **options)[ソース]¶

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

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

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

DecimalField.decimal_places¶: 数値とともに保持される小数点以下の位の数です。

例えば、小数点以下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 となります。

注釈

FloatField クラスと DecimalField クラスの違いについては FloatField vs. DecimalField を参照してください。また、Decimal に関する SQLite の制限についても注意してください。

`DurationField`¶

class DurationField(**options)[ソース]¶

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

注釈

DurationField での演算はほとんどの場合で機能します。ただし、PostgreSQL 以外のデータベースでは、DurationField の値と DateTimeField インスタンス上の演算を比較することは期待通りに機能しません。

`EmailField`¶

class EmailField(max_length=254, **options)[ソース]¶

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

`FileField`¶

class FileField(upload_to='', storage=None, max_length=100, **options)[ソース]¶

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

注釈

primary_key 引数はサポートされておらず、使用するとエラーになります。

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

FileField.upload_to¶

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

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

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

引数説明

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

instance

FileField が定義されているモデルのインスタンス。具体的には、そのファイルが格納されている特定のインスタンスです。

ほとんどの場合、このオブジェクトはまだデータベースに保存されていないため、デフォルトの AutoField を使用している場合、 主キーフィールドの値をまだ持っていない可能性があります 。

filename ファイルに元々与えられていたファイル名。これは、最終的な宛先パスを決定するときに考慮されることもあれば、考慮されないこともあります。

例:

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

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

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

設定ファイルでは、 MEDIA_ROOT を Django にアップロードされたファイルを保存するディレクトリへのフルパスを指定する必要があります（パフォーマンス上、これらのファイルはデータベースには保存されません）。 MEDIA_URL をそのディレクトリの公開 URL にします。このディレクトリは Web サーバのユーザアカウントで書き込み可能である必要があります。
モデルに FileField または ImageField を追加し、 upload_to オプションを定義して、ファイルをアップロードする MEDIA_ROOT のサブディレクトリを指定します。
データベースに保存されるのは、ファイルへのパス (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 引数を使用して最大長を変更できます。

`FileField` と `FieldFile`¶

class FieldFile[ソース]¶

モデル上の FileField にアクセスするとき、元となるファイルにアアクセスするためのプロキシとして、FieldFile のインスタンスが与えられます。

FieldFile の API は File の API を反映していますが、主な違いが 1 つあります: クラスによってラップされたオブジェクトは必ずしも Python のビルトインのファイルオブジェクトのラッパーであるとは限りません。 代わりに、Storage.open() メソッドの結果を包むラッパーで、これは File オブジェクトもしくは File API の独自ストレージの実装となります。

read() や write() など、File から継承されたAPIに加えて、FieldFile には基になるファイルとやり取りするために使用できるいくつかのメソッドが含まれています：

警告

このクラスの 2 つのメソッド、save() と delete() は、デフォルトで、関連する FieldFile のモデルオブジェクトをデータベースに保存します。

FieldFile.name¶

関連する FileField の Storage のルートからの相対パスを含むファイル名です。

FieldFile.path[ソース]¶

ファイルのローカルファイルシステムパスにアクセスするための読み取り専用プロパティ。基になる Storage クラスの path() メソッドを呼び出します。

FieldFile.size[ソース]¶

元となる Storage.size() メソッドの結果です。

FieldFile.url[ソース]¶

元となる Storage クラスの url() メソッドを呼ぶことによって、ファイルの相対 URL にアクセスするための読み取り専用プロパティです。

FieldFile.open(mode='rb')[ソース]¶

このインスタンスに関連付けられたファイルを、指定された モード で開くか、開き直します。標準の Python の open() メソッドとは違い、ファイルのデスクリプタを返しません。

元となるファイルはアクセスするときに暗黙的に開かれるので、元となるファイルにポインタをリセットするためか モード を変更するため以外には、このメソッドを呼ぶ必要はないでしょう。

FieldFile.close()[ソース]¶

標準の Python の file.close() メソッドのように動作し、このインスタンスに関連付けられたファイルを閉じます。

FieldFile.save(name, content, save=True)[ソース]¶

このメソッドは、ファイル名とファイルの内容を取り、それらをフィールドのストレージクラスに渡し、格納されたファイルをモデルフィールドに関連付けます。手動でファイルデータをモデル上の FileField インスタンスに関連付けるには、 save() メソッドを使用してそのファイルデータを保持します。

2 つの必要な引数をとります: name はファイルの名前で、content はファイルの内容を含むオブジェクトです。省略可能な save 引数は、このフィールドに関連付けられたファイルが変更された後にモデルインスタンスが保存されるかどうかをコントロールします。デフォルトは True です。

content 引数は、Python のビルトインのファイルオブジェクトではなく、django.core.files.File のインスタンスでなければならないことに注意してください。以下のように、既存の Python ファイルオブジェクトから 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")

より詳しくはファイルの管理を参照してください。

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

FilePathField.path¶

必須です。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 がファイル名をフィルタリングするために使用します。正規表現は、フルパスではなくベースファイル名に適用される点に注意してください。例: "foo.*\.txt$"。これは foo23.txt とは合致しますが、bar.txt や foo23.png とは合致しません。

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

FilePathField.allow_files¶: 省略可能です。True か False を取り、デフォルトは True です。指定された場所にあるファイルを含むかどうかを指定します。これか allow_folders のどちらかを True にする必要があります。

FilePathField.allow_folders¶: 省略可能です。True か False を取り、デフォルトは False です。指定した場所にあるフォルダーを含むかどうかを指定します。これか allow_files のどちらかを 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 引数を使って最大文字数を変更できます。

`FloatField`¶

class FloatField(**options)[ソース]¶

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

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

FloatField と DecimalField の比較

FloatField クラスは、DecimalField クラスと混同されることがあります。両方とも実数を表しますが、異なる方法で表現しています。FloatField は内部的には Python の float 型を使い、DecimalField は Python の Decimal 型を使います。この 2 つの違いについては、 Python のドキュメント decimal module を参照してください。

`GeneratedField`¶

New in Django 5.0.

class GeneratedField(expression, output_field, db_persist=None, **kwargs)[ソース]¶

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

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

GeneratedField.expression¶

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

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

GeneratedField.output_field¶: フィールドのデータ型を定義するモデルフィールドインスタンス。

GeneratedField.db_persist¶

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

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

データをリフレッシュしてください

データベースは常に値を計算しているので、 save() の後に新しい値にアクセスするには、例えば refresh_from_db() を使ってオブジェクトをリロードする必要があります。

データベースの制約

生成フィールドに関しては多くのデータベース固有の制限があり、Djangoはそれらを検証しないため、データベースがエラーを発生させる可能性があります。例えば、PostgreSQLでは、生成カラムで参照される関数や演算子は IMMUTABLE としてマークされている必要があります。

あなたのデータベースで expression がサポートされているかどうかを常に確認する必要があります。 MariaDB, MySQL, Oracle, PostgreSQL, SQLite のドキュメントを確認してください。

`GenericIPAddressField`¶

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)[ソース]¶

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

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

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

ImageField.height_field¶: Name of a model field which is auto-populated with the height of the image each time an image object is set.

ImageField.width_field¶: Name of a model field which is auto-populated with the width of the image each time an image object is set.

Requires the pillow library.

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

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

`IntegerField`¶

class IntegerField(**options)[ソース]¶

整数。 -2147483648 から 2147483647 までの値は、 Django がサポートする全てのデータベースで安全です。

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

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

`JSONField`¶

class JSONField(encoder=None, decoder=None, **options)[ソース]¶

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

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

JSONField.encoder¶

オプションの json.JSONEncoder サブクラスで、標準の JSON シリアライザがサポートしていないデータ型 (datetime.datetime や UUID など) をシリアライズできます。例えば、 DjangoJSONEncoder クラスが使用できます。

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

JSONField.decoder¶

オプションの json.JSONDecoder サブクラスで、データベースから取得した値をデシリアライズします。値はカスタムエンコーダーによって選択されたフォーマット(多くの場合文字列)になります。デシリアライズは、入力の型が確定できないことを考慮する必要があります。たとえば、datetime で設定されたのと同じフォーマットでたまたま存在していた文字列があたかも datetime 型であるかのように返却されるリスクがあります。

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

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

デフォルト値について

フィールドに default を指定する場合、 dict クラスのような呼び出し可能オブジェクトか、毎回新しいオブジェクトを返す関数にしてください。 default={} や default=[] のようなミュータブルなオブジェクトを誤って使用すると、すべてのインスタンス間で共有されるミュータブルなデフォルト値が作成されます。

インデックスの作成

Index と Field.db_index はどちらも B-tree インデックスを作成しますが、JSONField をクエリする際には特に役に立ちません。PostgreSQL でだけ、より適した GinIndex を使うことができます。

PostgreSQL ユーザーの場合

PostgreSQLには2つのJSONベースのデータ型があります。 json と jsonb です。これらの主な違いは、格納方法とクエリ方法です。PostgreSQLの json フィールドはJSONの元の文字列表現として格納され、キーに基づいてクエリを行うにはその場でデコードする必要があります。 jsonb フィールドはJSONの実際の構造に基づいて格納され、インデックスを作成できます。そのトレードオフとして、jsonb フィールドへの書き込みに若干の追加コストが発生します。 JSONField は jsonb を使用します。

Oracle のユーザーの場合

Oracle Database は JSON スカラー値の格納をサポートしていません。JSONオブジェクトと配列 (Pythonでは dict と list を使って表現されます) だけがサポートされています。

`PositiveBigIntegerField`¶

class PositiveBigIntegerField(**options)[ソース]¶

PositiveIntegerField のようなものですが、特定の (データベース依存の) 値以下の値しか許しません。 0 から 9223372036854775807 までの値は、 Django がサポートする全てのデータベースで安全です。

`PositiveIntegerField`¶

class PositiveIntegerField(**options)[ソース]¶

IntegerField とほぼ同じですが、正の値かゼロ (0) でなければなりません。Django によってサポートされる全てのデータベースで、0 から 2147483647 までの値は安全です。後方互換性の理由から、値 0 が有効となっています。

`PositiveSmallIntegerField`¶

class PositiveSmallIntegerField(**options)[ソース]¶

PositiveIntegerField とほぼ同じですが、一定の (データベースに依存した) 値より下の値のみを許容します。Django でサポートされている全てのデータベースで、0 から 32767 までの値は安全です。

`SlugField`¶

class SlugField(max_length=50, **options)[ソース]¶

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

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

暗黙的に Field.db_index を True にセットします。

他の値に基づいて SlugField に自動的に値を事前入力すると便利なことがあります。これは prepopulated_fields を使って管理画面で自動で実行できます。

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

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

`SmallAutoField`¶

class SmallAutoField(**options)[ソース]¶

AutoField のようなものですが、一定の (データベース依存の) 制限値以下の値しか許しません。 1 から 32767 までの値は Django がサポートする全てのデータベースで安全です。

`SmallIntegerField`¶

class SmallIntegerField(**options)[ソース]¶

IntegerField とほぼ同じですが、一定の (データベースに依存した) 値より下の値のみを許容します。Django でサポートされている全てのデータベースで、-32768 から 32767 までの値は安全です。

`TextField`¶

class TextField(**options)[ソース]¶

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

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

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

注釈

照合順序名は標準化されていません。そのため、これは複数のデータベースバックエンド間でポータブルではありません。

Oracle

Oracle は TextField の照合順序 (collation) をサポートしていません。

`TimeField`¶

class TimeField(auto_now=False, auto_now_add=False, **options)[ソース]¶

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

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

`URLField`¶

class URLField(max_length=200, **options)[ソース]¶

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

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

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

`UUIDField`¶

class UUIDField(**options)[ソース]¶

一意な識別子を格納するためのフィールドです。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 に渡すことに注意してください。

PostgreSQL と MariaDB 10.7+ におけるルックアップ

PostgreSQL や MariaDB 10.7 以降では、ハイフンがない値に対して iexact, contains, icontains, startswith, istartswith, endswith, iendswith のルックアップを使用しても機能しません。これは、これらのデータベースがハイフン付きのuuidデータ型でそれらを格納するためです。

フィールド API リファレンス¶

class Field[ソース]¶

フィールドはデータベーステーブルのカラムを表す抽象クラスです。Django はフィールドを使ってデータベーステーブルを作成したり (db_type())、 Python の型をデータベースにマッピングしたり (get_prep_value())、逆にしたり (from_db_value()) します。

したがって、フィールドは、特に モデル や クエリセット など、他のDjango APIにおける基本的な要素です。

モデルでは、フィールドはクラス属性としてインスタンス化され、特定のテーブルのカラムを表します (モデル参照)。フィールドには null や unique といった属性と、 Django がフィールドの値をデータベース固有の値にマッピングするためのメソッドがあります。

フィールド Field は RegisterLookupMixin のサブクラスなので、 Transform と Lookup の両方を登録して QuerySet で使用できます (例: field_name__exact="foo") 。デフォルトでは全ての組み込みのルックアップが登録されています。

CharField のような Django 組み込みのフィールドは全て Field の具体的な実装です。独自のフィールドが必要な場合は、組み込みフィールドをサブクラス化するか、一から Field を書いてください。どちらの場合でもカスタムのモデルフィールドを作成するを参照してください。

description¶

フィールドの詳細な説明。例えば django.contrib.admindocs アプリケーションなどのためのものです。

説明文は以下のような形式です：

description = _("String (up to %(max_length)s)")

引数はフィールドの __dict__ から補間されます。

descriptor_class¶: インスタンス化され、モデルのインスタンス属性に割り当てられるデスクリプタ・プロトコルを実装したクラスです。コンストラクタは単一の引数 Field インスタンスを受け取る必要があります。このクラス属性をオーバーライドすることで、get と set の動作をカスタマイズできます。

フィールド Field をデータベース固有の型にマッピングするために、 Django はいくつかのメソッドを公開しています：

get_internal_type()[ソース]¶

バックエンド固有の目的のために、このフィールドの名前を文字列で返します。デフォルトでは、クラス名を返します。

カスタムフィールドでの使用法については組み込みフィールド・タイプのエミュレートを参照してください。

db_type(connection)[ソース]¶

Field のデータベースカラムのデータ型を、connection を考慮して返します。

カスタムフィールドでの使用法についてはカスタムデータベースタイプを参照してください。

rel_db_type(connection)[ソース]¶

Field を指す ForeignKey や OneToOneField などのフィールドのデータベースカラムのデータ型を、connection を考慮して返します。

カスタムフィールドでの使用法についてはカスタムデータベースタイプを参照してください。

Django がデータベースのバックエンドやフィールドとやり取りする必要がある場面は、主に3つあります：

データベースへのクエリ時 (Python の値 -> データベースのバックエンドの値)
データベースからデータを読み込むとき (データベースのバックエンドの値 -> Python の値)
データベースへの保存時 (Python の値 -> データベースのバックエンドの値)

クエリでは get_db_prep_value() と get_prep_value() が使用されます：

get_prep_value(value)[ソース]¶

value はモデルの属性の現在の値で、メソッドはクエリのパラメータとして使用できるように書かれた形式のデータを返す必要があります。

使い方は Python オブジェクトをクエリ変数に変換するを参照してください。

get_db_prep_value(value, connection, prepared=False)[ソース]¶

value をバックエンド固有の値に変換します。デフォルトでは、 prepared=True の場合は value を返し、 False の場合は get_prep_value() を返します。

使い方はクエリの変数をデータベースの変数に変換するを参照してください。

データを読み込む際には from_db_value() が使用されます：

from_db_value(value, expression, connection)¶

データベースが返す値を Python オブジェクトに変換します。これは get_prep_value() の逆です。

データベースのバックエンドはすでに正しい Python 型を返すか、バックエンド自身が変換を行うので、このメソッドはほとんどの組み込みフィールドには使われません。

expression は self と同様です。

使い方は変数を Python オブジェクトに変換するを参照してください。

注釈

パフォーマンス上の理由から、 from_db_value は、それを必要としないフィールド (Django の全てのフィールド) では何もしない関数としては実装されていません。そのため、定義内で super を呼び出してはいけません。

保存時には pre_save() と get_db_prep_save() が使用されます：

get_db_prep_save(value, connection)[ソース]¶: get_db_prep_value() と同じですが、フィールドの値をデータベースに保存しなければならない場合に呼び出されます。デフォルトでは get_db_prep_value() を返します。

pre_save(model_instance, add)[ソース]¶

保存する前に値を整えるために get_db_prep_save() の前に呼び出されるメソッドです (例えば DateField.auto_now の場合など)。

model_instance はこのフィールドが属するインスタンスで、add はインスタンスが初めてデータベースに保存されるかどうかです。

このフィールドの model_instance からは適切な属性の値を返す必要があります。属性名は self.attname にあります (これは Field で設定します)。

使い方は保存する前に値を前処理する場合を参照してください。

フィールドは多くの場合、シリアライズやフォームから別の型として値を受け取ります。

to_python(value)[ソース]¶

値を正しい Python オブジェクトに変換します。これは value_to_string() の逆として動作し、 clean() でも呼び出されます。

使い方は変数を Python オブジェクトに変換するを参照してください。

データベースに保存する方法だけでなく、フィールドはその値をシリアライズする方法も知っておく必要があります：

value_from_object(obj)[ソース]¶

指定されたモデルのインスタンスのフィールドの値を返します。

このメソッドは value_to_string() でよく使われます。

value_to_string(obj)[ソース]¶

obj を文字列に変換します。フィールドの値をシリアライズするために使用します。

使い方はシリアライズするためにフィールドデータを変換する場合を参照してください。

モデルフォーム を使用する場合、 Field はどのフォームフィールドで表現されるべきかを知る必要があります：

formfield(form_class=None, choices_form_class=None, **kwargs)[ソース]¶

このフィールドの ModelForm に対するデフォルトの django.forms.Field を返します。

デフォルトでは、 form_class と choices_form_class の両方が None の場合、 CharField を使用します。フィールドに choices が指定されていて、 choices_form_class が指定されていない場合、 TypedChoiceField を使用します。

使い方はモデルフィールドのフォームフィールドの指定を参照してください。

deconstruct()[ソース]¶

フィールドを再作成するのに十分な情報を持つ4値タプルを返します：

モデルのフィールド名。
フィールドのインポートパス (例 "django.db.models.IntegerField")。移植性は高く保つべきなので、あまり特定しすぎない方が良いかもしれません。
位置引数のリスト。
キーワード引数の辞書。

1.7 より前のバージョンでは、マイグレーションを使用してデータをマイグレーションするために、このメソッドをフィールドに追加する必要がありました。

ルックアップの登録と取得¶

フィールド Field はルックアップレジストレーション API を実装しています。このAPIを使用して、フィールドクラスとそのインスタンスでどのルックアップを利用できるか、またフィールドからどのようにルックアップを取得するかをカスタマイズできます。

フィールド属性リファレンス¶

すべての Field インスタンスには、その動作を詳しく調べるための属性がいくつか含まれています。フィールドの機能に依存するコードを書く必要がある場合には、 isinstance チェックの代わりにこれらの属性を使用してください。これらの属性は Model._meta API と一緒に使うことで、特定のフィールドタイプを絞り込むことができます。カスタムモデルフィールドはこれらのフラグを実装する必要があります。

フィールドの属性¶

Field.auto_created¶: モデル継承で使用される OneToOneField のように、フィールドが自動的に作成されたかどうかを示す真偽値フラグ。

Field.concrete¶: フィールドにデータベース・カラムが関連付けられているかどうかを示す真偽値。

Field.hidden¶: デフォルトでは Options.get_fields() によって返されない隠しフィールドがあるかどうかを示す真偽値のフラグです。例えば、 ForeignKey の逆フィールドで、 related_name が '+' で始まる場合です。

Field.is_relation¶: 真偽値フラグで、フィールドが機能のために一つまたは複数の他のモデルへの参照を含んでいるかどうかを示します（例: ForeignKey, ManyToManyField, OneToOneField など）。

Field.model¶: フィールドが定義されているモデルを返します。フィールドがモデルの基底クラスに定義されている場合、model はインスタンスのクラスではなく基底クラスを参照します。

リレーションを持つフィールドの属性¶

これらの属性はリレーションのカーディナリティやその他の詳細をクエリするために使用されます。これらの属性は全てのフィールドに存在しますが、フィールドがリレーションタイプである場合のみ (None ではなく) 真偽値を持ちます (Field.is_relation=True)。

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 です。

モデル

モデル index リファレンス

ドキュメント

モデルフィールドリファレンス¶

フィールドオプション¶

null¶

blank¶

choices¶

列挙型¶

db_column¶

db_comment¶

db_default¶

db_index¶

db_tablespace¶

default¶

editable¶

error_messages¶

help_text¶

primary_key¶

unique¶

unique_for_date¶

unique_for_month¶

unique_for_year¶

verbose_name¶

validators¶

フィールドの型¶

AutoField¶

BigAutoField¶

BigIntegerField¶

BinaryField¶

BooleanField¶

CharField¶

DateField¶

DateTimeField¶

DecimalField¶

DurationField¶

EmailField¶

FileField¶

FileField と FieldFile¶

FilePathField¶

FloatField¶

GeneratedField¶

GenericIPAddressField¶

ImageField¶

IntegerField¶

JSONField¶

PositiveBigIntegerField¶

PositiveIntegerField¶

PositiveSmallIntegerField¶

SlugField¶

SmallAutoField¶

SmallIntegerField¶

TextField¶

TimeField¶

URLField¶

UUIDField¶

リレーションシップフィールド¶

ForeignKey¶

データベース上の表現¶

引数¶

ManyToManyField¶

データベース上の表現¶

引数¶

OneToOneField¶

フィールド API リファレンス¶

ルックアップの登録と取得¶

フィールド属性 リファレンス¶

フィールドの属性¶

リレーションを持つフィールドの属性¶

追加的な情報

Support Django!

コンテンツ

移動

現在の場所:

助けを求める

ダウンロード:

`null`¶

`blank`¶

`choices`¶

`db_column`¶

`db_comment`¶

`db_default`¶

`db_index`¶

`db_tablespace`¶

`default`¶

`editable`¶

`error_messages`¶

`help_text`¶

`primary_key`¶

`unique`¶

`unique_for_date`¶

`unique_for_month`¶

`unique_for_year`¶

`verbose_name`¶

`validators`¶

`AutoField`¶

`BigAutoField`¶

`BigIntegerField`¶

`BinaryField`¶

`BooleanField`¶

`CharField`¶

`DateField`¶

`DateTimeField`¶

`DecimalField`¶

`DurationField`¶

`EmailField`¶

`FileField`¶

`FileField` と `FieldFile`¶

`FilePathField`¶

`FloatField`¶

`GeneratedField`¶

`GenericIPAddressField`¶

`ImageField`¶

`IntegerField`¶

`JSONField`¶

`PositiveBigIntegerField`¶

`PositiveIntegerField`¶

`PositiveSmallIntegerField`¶

`SlugField`¶

`SmallAutoField`¶

`SmallIntegerField`¶

`TextField`¶

`TimeField`¶

`URLField`¶

`UUIDField`¶

`ForeignKey`¶

`ManyToManyField`¶

`OneToOneField`¶

フィールド属性リファレンス¶