このドキュメントには、Django が提供するフィールドオプション field options とフィールド型 field types を含む、Field のすべての API リファレンスが記載されています。
参考
組み込みフィールドが目的に合わない場合は、 django-localflavor (ドキュメント) を試してみてください。これは、特定の国や文化に役立つさまざまなコードを含んでいます。
さらに、簡単に あなた自身の独自のモデルフィールドを作ることもできます。
注釈
フィールドは django.db.models.fields に定義されていますが、利便性のために django.db.models にインポートされています。標準的な慣例としては、from django.db import models を使用し、フィールドを models.<Foo>Field として参照します。
以下の引数は全てのフィールドタイプで有効です。全て省略可能です。
null¶True の場合、Django はデータベース内に NULL として空の値を保持します。デフォルトは False です。
Avoid using null on string-based fields such as
CharField and TextField. The Django convention is to use an
empty string, not NULL, as the "no data" state for string-based fields. If a
string-based field has null=False, empty strings can still be saved for "no
data". If a string-based field has null=True, that means it has two possible
values for "no data": NULL, and the empty string. In most cases, it's
redundant to have two possible values for "no data". One exception is when a
CharField has both unique=True and blank=True set. In this
situation, null=True is required to avoid unique constraint violations when
saving multiple objects with blank values.
文字列ベースのフィールドでもそれ以外でも、フォーム内で空の値を許可したいときは blank=True を指定する必要があります。 null パラメーターはデータベースストレージにだけ影響を与えるからです(詳細は blank を参照)。
注釈
Oracleのデータベースバックエンドを使っているときには、この属性にかかわらず、値 NULL が空の文字列を意味するために保持されます。
blank¶True の場合、フィールドはブランクになることが許容されます。デフォルトは False です。
null とは異なる点に注意してください。null が純粋にデータベースに関連する一方で、blank はバリデーションに関連します。フィールドが blank=True を持つ場合、フォームバリデーションは空の値のエントリーを許容します。blank=False を持つ場合、フィールドは必須となります。
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バウンド操作の結果(キャッシュされる可能性があります)。
ほぼ安定しているが、場合によって、あるいはプロジェクトによって異なる可能性のあるリスト。このカテゴリの例は、通貨、国、言語、タイムゾーンなど、よく知られた値のインベントリを提供するサードパーティのアプリを使用する場合などです。
一般的に、モデルクラスの内部で選択肢を定義し、それぞれの値に適切に名前づけられた定数を定義するのがベストです:
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 の順番を変更すると、変更のたびに新しいマイグレーションが生成されます。
choices が設定されている各モデルフィールドに対して、 Django は選択肢を2値タプルのリストに正規化し、フィールドの現在の値に対して、 人間が読める名前を取得するメソッドを追加します。データベース API ドキュメントの get_FOO_display() を参照してください。
フィールドに default とともに blank=False が指定されない限り、セレクトボックスには "---------" を含むラベルが表示されます。この動作をオーバーライドするには、たとえば (None, "表示したい文字列") のように None を含むタプルを choices に追加してください。もしくは、 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)")
db_column¶このフィールドを使用するためのデータベースのカラムの名前です。もし与えられなければ、Django はフィールド名を使用します。
データベースのカラム名が SQL の予約語だったり、Python の変数名として使用できない文字 (特に多いのがハイフン) が含まれていたとしても大丈夫です。Django はカラムとテーブルの名前を自動的にクオートして処理してくれます。
db_comment¶このフィールドに使うデータベースカラムのコメントです。あなたの Django コードを見ていないような、データベースに直接アクセスできる人のために、フィールドをドキュメント化するのに便利です。例えば:
pub_date = models.DateTimeField(
db_comment="Date and time when the article was published",
)
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_default は設定されているが default が設定されておらず、フィールドに値が割り当てられていない場合、保存されていないモデルインスタンスでは DatabaseDefault オブジェクトがフィールドの値として返されます。フィールドの実際の値は、モデルインスタンスが保存されたときにデータベースによって決定されます。
db_index¶True の場合、データベースインデックスがこのフィールドのために生成されます。
db_tablespace¶このフィールドにインデックスが作成されている場合に、このフィールドのインデックスに使用する データベース テーブル空間 の名前です。デフォルトはプロジェクトの DEFAULT_INDEX_TABLESPACE が設定されている場合はその設定値、またはモデルの db_tablespace が設定されている場合はその設定値です。バックエンドがインデックスのテーブル空間をサポートしていない場合、このオプションは無視されます。
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¶If False, the field will not be displayed in the admin or any other
ModelForm. It will also be skipped during model
validation. Default is True.
error_messages¶引数 error_messages を指定すると、フィールドが表示するデフォルトのメッセージを上書きできます。オーバーライドしたいエラーメッセージにマッチするキーを持つ辞書を渡してください。
エラーメッセージのキーには null, blank, invalid, invalid_choice, unique, unique_for_date があります。以下の Field types セクションで説明する各フィールドには、追加のエラーメッセージキーが指定されています。
これらのエラーメッセージはフォームに反映されないことがよくあります。詳細は モデルの error_messages についての注意 を参照してください。
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¶True の場合、設定したフィールドはそのモデルの主キーとなります。
If you don't specify primary_key=True for any field in your model and have
not defined a composite primary key, Django will automatically add a field to
hold the primary key. So, you don't need to set primary_key=True on any of
your fields unless you want to override the default primary-key behavior. The
type of auto-created primary key fields can be specified per app in
AppConfig.default_auto_field
or globally in the DEFAULT_AUTO_FIELD setting. For more, see
自動インクリメントのプライマリキーフィールド.
primary_key=True implies null=False and
unique=True. Only one field per model can set
primary_key=True. Composite primary keys must be defined using
CompositePrimaryKey instead of setting this flag to True for all
fields to maintain this invariant.
プライマリキーフィールドは読み取り専用です。既存のオブジェクトのプライマリキーの値を変更して保存すると、古いオブジェクトはそのままで新しいオブジェクトが作成されます。
オブジェクトを 削除する 際に、プライマリキーフィールドは None に設定されます。
The CompositePrimaryKey field was added.
unique¶True の場合、そのフィールドはテーブル上で一意となる制約を受けます。
これはデータベースレベルとモデルのバリデーションで強制されます。 unique フィールドの値が重複しているモデルを保存しようとすると、モデルの save() メソッドによって django.db.IntegrityError が発生します。
このオプションは ManyToManyField と OneToOneField 以外の全てのフィールドタイプで有効です。
unique が True の場合、db_index を指定する必要はないことに注意してください。なぜなら unique がインデックスの作成を意味するからです。
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¶unique_for_date と似ていますが、フィールドが月に対して一意である必要があります。
unique_for_year¶unique_for_date や unique_for_month と同様です。
verbose_name¶人間が読めるフィールド名。verbose な名前が指定されていない場合、 Django はフィールドの属性名を使って自動的にフィールドを作成し、アンダースコアをスペースに変換します。詳しくは verbose なフィールド名 を参照してください。
validators¶このフィールドに対して実行するバリデータのリスト。詳細は バリデータのドキュメント を参照してください。
AutoField¶利用可能な ID に応じて、自動的にインクリメントする IntegerField です。通常は直接使う必要はありません; 指定しない場合は、主キーのフィールドが自動的にモデルに追加されます。自動インクリメントのプライマリキーフィールド も参照してください。
BigAutoField¶64 ビットの数値です。1 から 9223372036854775807 までの数を扱える以外は、AutoField と同じです。
BigIntegerField¶64 ビットの整数で、 IntegerField とよく似ていますが、 -9223372036854775808 から 9223372036854775807 までの数値が入ることが保証されています。このフィールドのデフォルトのフォームウィジェットは NumberInput です。
BinaryField¶生のバイナリデータを格納するフィールドです。 bytes, bytearray または memoryview を指定できます。
デフォルトでは、 BinaryField は editable を False に設定します。この場合、 ModelForm に含めることはできません。
オプション。フィールドの最大長 (バイト単位)。最大長は MaxLengthValidator を使ったDjango のバリデーションで強制されます。
BinaryField を誤用する
ファイルをデータベース内に格納したいと考えるかもしれませんが、99%のケースにおいてそれは悪い設計です。このフィールドは、適切な 静的ファイル の取り扱いに対する代替手段では ありません 。
BooleanField¶true/false のフィールドです。
このフィールドのデフォルトのフォームウィジェットは CheckboxInput で、 null=True の場合は NullBooleanSelect です。
Field.default が定義されていないときの BooleanField のデフォルト値は None です。
CompositePrimaryKey¶A virtual field used for defining a composite primary key.
This field must be defined as the model's pk attribute. If present, Django
will create the underlying model table with a composite primary key.
The *field_names argument is a list of positional field names that compose
the primary key.
See Composite primary keys for more details.
CharField¶小 - 大サイズの文字列のフィールドです。
多量のテキストを扱うときは TextField を使ってください。
このフィールドのデフォルトのフォームウィジェットは TextInput です。
CharField には以下の追加引数があります:
The maximum length (in characters) of the field. The max_length
is enforced at the database level and in Django's validation using
MaxLengthValidator. It's required for all
database backends included with Django except PostgreSQL and SQLite, which
supports unlimited VARCHAR columns.
注釈
複数のデータベースバックエンド間で使われるアプリケーションを作る場合は、いくつかのバックエンドで max_length に制限があることに注意しなければなりません。詳しくは データベースバックエンドの注意事項 を参照してください。
Support for unlimited VARCHAR columns was added on SQLite.
オプション。フィールドのデータベース照合順序名(collation name)です。
注釈
照合順序名は標準化されていません。そのため、これは複数のデータベースバックエンド間でポータブルではありません。
Oracle
Oracle が照合順序をサポートするのは、MAX_STRING_SIZE データベース初期化パラメータが EXTENDED に設定されている場合だけです。
DateField¶Python で datetime.date インスタンスによって表される日付です。多少の追加的な省略可能な引数を持ちます:
オブジェクトが保存される度に自動的に現在の日付をセットします。"最後の変更" タイムスタンプに役立ちます。現在の日付が常に使われる点に注意してください; オーバーライドできる単なるデフォルト値ではありません。
Model.save() が呼ばれたとき、フィールドは自動的に更新されるだけです。QuerySet.update() のような別の方法で他のフィールドに更新を加えるとき、フィールドは更新されません。あのように更新の中でフィールドの独自の値を指定できるとしてもです。
オブジェクトが最初に作成されるとき、自動的にフィールドに現在の日付をセットします。タイムスタンプの作成に役立ちます。現在の日付が 常に 使われる点に注意してください; オーバーライドできる単なるデフォルト値ではありません。たとえオブジェクトを作成するときに値をセットしたとしても無視されます。このフィールドを修正できるようにしておきたい場合は、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 への変換をどのように処理するかを検討するとよいでしょう。
警告
DateField には常に datetime.date インスタンスを使用してください。
datetime.datetime インスタンスを持っている場合は、まずそれを datetime.date に変換することをお勧めします。変換しない場合、DateField は datetime.datetime を デフォルトのタイムゾーン にローカライズし、datetime.date インスタンスに変換してその時間部分を削除します。これは、保存および比較の両方において当てはまります。
DateTimeField¶Python で datetime.datetime インスタンスによって表される日付と時刻です。DateField と同じくいくつかの追加的な引数を持ちます:
このフィールドのデフォルトのフォームウィジェットは DateTimeInput です。管理画面では、JavaScript のショートカットを使って TextInput ウィジェットを 2 つに分けて使用します。
警告
DateTimeField には常に datetime.datetime インスタンスを使用してください。
datetime.date インスタンスを持っている場合は、まずそれを datetime.datetime に変換することをお勧めします。変換しない場合、DateTimeField は時間部分に デフォルトのタイムゾーン の午前0時を使用します。これは、保存および比較の両方において当てはまります。datetime.date インスタンスと DateTimeField の日付部分を比較するには、date ルックアップを使用してください。
DecimalField¶固定精度の10進数で、Python では Decimal インスタンスで表されます。これは DecimalValidator を使用して入力を検証します。
以下の 必須の 引数があります:
数値内で使える桁数の最大値です。 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¶時刻の期間を保持するフィールドで、 Python の timedelta によってモデル化されます。PostgreSQL で使われるときに用いられるデータ型は interval で、Oracle でのデータ型は INTERVAL DAY(9) TO SECOND(6) です。 それ以外では、マイクロ秒の bigint が使われます。
注釈
DurationField での演算はほとんどの場合で機能します。ただし、PostgreSQL 以外のデータベースでは、DurationField の値と DateTimeField インスタンス上の演算を比較することは期待通りに機能しません。
EmailField¶EmailValidator を使って、値が有効なメールアドレスであるかどうかをチェックする CharField です。
FileField¶ファイルアップロードのフィールドです。
注釈
primary_key 引数はサポートされておらず、使用するとエラーになります。
以下のオプション引数があります:
この属性は、アップロードディレクトリとファイル名を設定する方法を提供し、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つの引数は
引数 |
説明 |
|---|---|
|
ほとんどの場合、このオブジェクトはまだデータベースに保存されていないため、デフォルトの |
|
ファイルに元々与えられていたファイル名。これは、最終的な宛先パスを決定するときに考慮されることもあれば、考慮されないこともあります。 |
例:
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)
ストレージオブジェクト、またはストレージオブジェクトを返す呼び出し可能オブジェクトです。これはファイルの保存と取得を行います。このオブジェクトの渡し方の詳細については ファイルの管理 を参照してください。
このフィールドのデフォルトのフォームウィジェットは 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¶モデル上の FileField にアクセスするとき、元となるファイルにアアクセスするためのプロキシとして、FieldFile のインスタンスが与えられます。
FieldFile の API は File の API を反映していますが、主な違いが 1 つあります: クラスによってラップされたオブジェクトは必ずしも Python のビルトインのファイルオブジェクトのラッパーであるとは限りません。 代わりに、Storage.open() メソッドの結果を包むラッパーで、これは File オブジェクトもしくは File API の独自ストレージの実装となります。
read() や write() など、File から継承されたAPIに加えて、FieldFile には基になるファイルとやり取りするために使用できるいくつかのメソッドが含まれています:
関連する FileField の Storage のルートからの相対パスを含むファイル名です。
ファイルのローカルファイルシステムパスにアクセスするための読み取り専用プロパティ。基になる Storage クラスの path() メソッドを呼び出します。
元となる Storage.size() メソッドの結果です。
元となる Storage クラス の url() メソッドを呼ぶことによって、ファイルの相対 URL にアクセスするための読み取り専用プロパティです。
このインスタンスに関連付けられたファイルを、指定された モード で開くか、開き直します。標準の Python の open() メソッドとは違い、ファイルのデスクリプタを返しません。
元となるファイルはアクセスするときに暗黙的に開かれるので、元となるファイルにポインタをリセットするためか モード を変更するため以外には、このメソッドを呼ぶ必要はないでしょう。
標準の Python の file.close() メソッドのように動作し、このインスタンスに関連付けられたファイルを閉じます。
このメソッドは、ファイル名とファイルの内容を取り、それらをフィールドのストレージクラスに渡し、格納されたファイルをモデルフィールドに関連付けます。 手動でファイルデータをモデル上の 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")
より詳しくは ファイルの管理 を参照してください。
このインスタンスに関連付けられているファイルを削除し、フィールドのすべての属性をクリアします。 注: このメソッドは、delete() が呼び出されたときにファイルが開いた場合、ファイルを閉じます。
省略可能な save 引数は、このフィールドに関連付けられたファイルが削除された後にモデルインスタンスを保存するかどうかをコントロールします。 デフォルトは True です。
モデルを削除するとき、関連ファイルは削除されない点に注意してください。 孤立したファイルをクリーンアップする必要がある場合、自分で処理する必要があります (たとえば、手動で実行したり、cron などを通して定期的に実行される独自の管理コマンドです)。
FilePathField¶CharField は選択肢をファイルシステム上の特定のディレクトリにあるファイル名に限定します。いくつかの特別な引数を持ちますが、最初の引数は 必須 です:
必須です。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 がファイル名をフィルタリングするために使用します。 正規表現は、フルパスではなくベースファイル名に適用される点に注意してください。 例: "foo.*\.txt$"。これは foo23.txt とは合致しますが、bar.txt や foo23.png とは合致しません。
省略可能です。True か False のどちらかを取り、デフォルトは False です。path の全てのサブディレクトリを含むかどうかを指定します。
省略可能です。True か False を取り、デフォルトは True です。指定された場所にあるファイルを含むかどうかを指定します。 これか allow_folders のどちらかを True にする必要があります。
省略可能です。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¶float インスタンスによって表される Python の浮動小数点数です。
このフィールドのデフォルトのフォームウィジェットは、localize が False のとき NumberInput で、そうでなければ TextInput となります。
FloatField と DecimalField の比較
FloatField クラスは、DecimalField クラスと混同されることがあります。両方とも実数を表しますが、異なる方法で表現しています。FloatField は内部的には Python の float 型を使い、DecimalField は Python の Decimal 型を使います。この 2 つの違いについては、 Python のドキュメント decimal module を参照してください。
GeneratedField¶常にモデル内の他のフィールドに基づいて計算されるフィールド。このフィールドはデータベース自身によって管理・更新されます。 GENERATED ALWAYS SQL 構文を使います。
生成カラムには、格納と仮想の2種類があります。格納生成カラムは書き込まれる (挿入もしくは更新される) ときに計算され、通常のカラムと同じようにストレージを占有します。仮想生成カラムはストレージを占有せず、読み込まれるときに計算されます。したがって、仮想生成カラムはビューに似ており、格納生成カラムはマテリアライズド・ビューに似ています。
モデルが変更されるたびにフィールドの値を自動的に設定するためにデータベースによって使用される Expression 。
式は決定論的でなければならず、モデル内の(同じデータベース・テーブル内の)フィールドだけを参照しなければなりません。生成フィールドは他の生成フィールドを参照することはできません。データベースのバックエンドはさらなる制限を課すことができます。
フィールドのデータ型を定義するモデルフィールドインスタンス。
データベースカラムが実際のカラムのようにストレージを占有するかどうかを決定します。 False の場合、カラムは仮想カラムとして動作し、データベースのストレージ領域を占有しません。
PostgreSQLは永続化 (persist) 列のみをサポートしています。Oracle は仮想列のみをサポートしています。
データをリフレッシュしてください
Since the database computes the value, the object must be reloaded to
access the new value after save(), for example, by using
refresh_from_db().
データベースの制約
生成フィールドに関しては多くのデータベース固有の制限があり、Djangoはそれらを検証しないため、データベースがエラーを発生させる可能性があります。例えば、PostgreSQLでは、生成カラムで参照される関数や演算子は IMMUTABLE としてマークされている必要があります。
あなたのデータベースで expression がサポートされているかどうかを常に確認する必要があります。 MariaDB, MySQL, Oracle, PostgreSQL, SQLite のドキュメントを確認してください。
GenericIPAddressField¶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 と正規化されます。そして、すべての文字は小文字に変換されます。
有効なインプットを、指定したプロトコルに制限します。 使用可能な値は 'both' (デフォルト)、'IPv4'、'IPv6' のどれかです。マッチングは大文字と小文字を区別しません。
IPv4 にマッピングされた ::ffff:192.0.2.1 のようなアドレスをアンパックします。このオプションを有効にすると、このアドレスは 192.0.2.1 とアンパックされます。デフォルトは無効です。protocol が 'both' に設定されている場合にだけ使用できます。
ブランク値を要する場合、ブランク値は null として保持されるため、null 値を許容する必要があります。
ImageField¶FileField から全ての属性とメソッドを継承して、さらにアップロードされたオブジェクトが有効な画像であることを検証します。
FileField で使える専用の属性に加えて、ImageField には height と width 属性があります。
これらの属性に対するクエリを容易にするために、ImageField は以下のオプション引数を持ちます:
画像オブジェクトがセットされるたびに自動的に画像の高さが入力されるモデルフィールドの名前。
画像オブジェクトがセットされるたびに自動的に画像の幅が入力されるモデルフィールドの名前。
pillow ライブラリを必要とします。
ImageField のインスタンスは、デフォルトが最大 100 文字の varchar カラムとして、データベース上に生成されます。他のフィールドと同様に、max_length 引数を使って最大文字数を変更できます。
このフィールドのデフォルトのフォームウィジェットは ClearableFileInput です。
IntegerField¶An integer. Values are only allowed between certain (database-dependent)
points. Values from -2147483648 to 2147483647 are compatible in all
databases supported by Django.
MinValueValidator と MaxValueValidator を使って、デフォルトのデータベースがサポートする値に基づいて入力を検証します。
このフィールドのデフォルトのフォームウィジェットは、localize が False のとき NumberInput で、そうでなければ TextInput となります。
JSONField¶JSON エンコードされたデータを格納するためのフィールドです。Python では、データは Python ネイティブフォーマットで表現されます。辞書、リスト、文字列、数値、真偽値、そして None です。
JSONField はMariaDB、MySQL、Oracle、PostgreSQL、(JSON1 エクステンションが有効な) SQLite でサポートされています。
オプションの json.JSONEncoder サブクラスで、標準の JSON シリアライザがサポートしていないデータ型 (datetime.datetime や UUID など) をシリアライズできます。例えば、 DjangoJSONEncoder クラスが使用できます。
デフォルトは json.JSONEncoder です。
オプションの 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 を使用します。
PositiveBigIntegerField¶Like a PositiveIntegerField, but only allows values under a certain
(database-dependent) point. Values from 0 to 9223372036854775807 are
compatible in all databases supported by Django.
PositiveIntegerField¶Like an IntegerField, but must be either positive or zero (0).
Values are only allowed under a certain (database-dependent) point. Values from
0 to 2147483647 are compatible in all databases supported by Django.
The value 0 is accepted for backward compatibility reasons.
PositiveSmallIntegerField¶Like a PositiveIntegerField, but only allows values under a certain
(database-dependent) point. Values from 0 to 32767 are compatible in
all databases supported by Django.
SlugField¶スラグ (slug) は新聞用語です。スラグとは、アルファベット、数字、アンダースコア、またはハイフンのみを含む、何かの短いラベルです。一般的にURLで使われます。
CharField のように、max_length を指定することもできます (データベースの可搬性についてのノートとそのセクションの max_length も参照してください)。max_length が指定されていないとき、Django はデフォルトの文字数 50 を使います。
暗黙的に Field.db_index を True にセットします。
他の値に基づいて SlugField に自動的に値を事前入力すると便利なことがあります。 これは prepopulated_fields を使って管理画面で自動で実行できます。
バリデーションには validate_slug または validate_unicode_slug を使用します。
True なら、フィールドはASCII文字に加えてUnicode文字も受け付けます。デフォルトは False です。
SmallAutoField¶Like an AutoField, but only allows values under a certain
(database-dependent) limit. Values from 1 to 32767 are compatible in
all databases supported by Django.
SmallIntegerField¶Like an IntegerField, but only allows values under a certain
(database-dependent) point. Values from -32768 to 32767 are compatible
in all databases supported by Django.
TextField¶多量のテキストのフィールドです。このフィールドのデフォルトのフォームウィジェットは Textarea です。
max_length 属性を指定した場合、自動生成されたフォームフィールドの Textarea ウィジェット内で反映されます。ただし、モデルやデータベースのレベルでは施行されません。そのためには CharField を使用してください。
オプション。フィールドのデータベース照合順序名(collation name)です。
注釈
照合順序名は標準化されていません。そのため、これは複数のデータベースバックエンド間でポータブルではありません。
Oracle
Oracle は TextField の照合順序 (collation) をサポートしていません。
TimeField¶Python で datetime.time インスタンスによって表される時刻です。DateField と同じ自動入力されるオプションを受け入れます。
このフィールドのデフォルトのフォームウィジェットは TimeInput です。admin はいくつかの JavaScript ショートカットを追加します。
URLField¶URLの CharField で、 URLValidator によってバリデーションされます。
このフィールドのデフォルトのフォームウィジェットは URLInput です。
全ての CharField サブクラスと同じく、URLField は省略可能な max_length 引数を取ります。max_length を指定しない場合、デフォルトの 200 が使われます。
UUIDField¶一意な識別子を格納するためのフィールドです。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データ型でそれらを格納するためです。
フィールドはデータベーステーブルのカラムを表す抽象クラスです。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 を書いてください。どちらの場合でも カスタムのモデルフィールドを作成する を参照してください。
フィールドの詳細な説明。例えば django.contrib.admindocs アプリケーションなどのためのものです。
説明文は以下のような形式です:
description = _("String (up to %(max_length)s)")
引数はフィールドの __dict__ から補間されます。
インスタンス化され、モデルのインスタンス属性に割り当てられる デスクリプタ・プロトコル を実装したクラスです。コンストラクタは単一の引数 Field インスタンスを受け取る必要があります。このクラス属性をオーバーライドすることで、get と set の動作をカスタマイズできます。
フィールド Field をデータベース固有の型にマッピングするために、 Django はいくつかのメソッドを公開しています:
バックエンド固有の目的のために、このフィールドの名前を文字列で返します。デフォルトでは、クラス名を返します。
カスタムフィールドでの使用法については 組み込みフィールド・タイプのエミュレート を参照してください。
Field のデータベースカラムのデータ型を、connection を考慮して返します。
カスタムフィールドでの使用法については カスタムデータベースタイプ を参照してください。
Field を指す ForeignKey や OneToOneField などのフィールドのデータベースカラムのデータ型を、connection を考慮して返します。
カスタムフィールドでの使用法については カスタムデータベースタイプ を参照してください。
Django がデータベースのバックエンドやフィールドとやり取りする必要がある場面は、 主に3つあります:
データベースへのクエリ時 (Python の値 -> データベースのバックエンドの値)
データベースからデータを読み込むとき (データベースのバックエンドの値 -> Python の値)
データベースへの保存時 (Python の値 -> データベースのバックエンドの値)
クエリでは get_db_prep_value() と get_prep_value() が使用されます:
value はモデルの属性の現在の値で、メソッドはクエリのパラメータとして使用できるように書かれた形式のデータを返す必要があります。
使い方は Python オブジェクトをクエリ変数に変換する を参照してください。
value をバックエンド固有の値に変換します。デフォルトでは、 prepared=True の場合は value を返し、 False の場合は get_prep_value() を返します。
使い方は クエリの変数をデータベースの変数に変換する を参照してください。
データを読み込む際には from_db_value() が使用されます:
データベースが返す値を Python オブジェクトに変換します。これは get_prep_value() の逆です。
データベースのバックエンドはすでに正しい Python 型を返すか、バックエンド自身が変換を行うので、このメソッドはほとんどの組み込みフィールドには使われません。
expression は self と同様です。
使い方は 変数を Python オブジェクトに変換する を参照してください。
注釈
パフォーマンス上の理由から、 from_db_value は、それを必要としないフィールド (Django の全てのフィールド) では何もしない関数としては実装されていません。そのため、定義内で super を呼び出してはいけません。
保存時には pre_save() と get_db_prep_save() が使用されます:
get_db_prep_value() と同じですが、フィールドの値をデータベースに 保存 しなければならない場合に呼び出されます。デフォルトでは get_db_prep_value() を返します。
保存する前に値を整えるために get_db_prep_save() の前に呼び出されるメソッドです (例えば DateField.auto_now の場合など)。
model_instance はこのフィールドが属するインスタンスで、add はインスタンスが初めてデータベースに保存されるかどうかです。
このフィールドの model_instance からは適切な属性の値を返す必要があります。属性名は self.attname にあります (これは Field で設定します)。
使い方は 保存する前に値を前処理する場合 を参照してください。
フィールドは多くの場合、シリアライズやフォームから別の型として値を受け取ります。
値を正しい Python オブジェクトに変換します。これは value_to_string() の逆として動作し、 clean() でも呼び出されます。
使い方は 変数を Python オブジェクトに変換する を参照してください。
データベースに保存する方法だけでなく、フィールドはその値をシリアライズする方法も知っておく必要があります:
指定されたモデルのインスタンスのフィールドの値を返します。
このメソッドは value_to_string() でよく使われます。
obj を文字列に変換します。フィールドの値をシリアライズするために使用します。
使い方は シリアライズするためにフィールドデータを変換する場合 を参照してください。
モデルフォーム を使用する場合、 Field はどのフォームフィールドで表現されるべきかを知る必要があります:
このフィールドの ModelForm に対するデフォルトの django.forms.Field を返します。
If formfield() is overridden to return None, this field
is excluded from the ModelForm.
デフォルトでは、 form_class と choices_form_class の両方が None の場合、 CharField を使用します。フィールドに choices が指定されていて、 choices_form_class が指定されていない場合、 TypedChoiceField を使用します。
使い方は モデルフィールドのフォームフィールドの指定 を参照してください。
フィールド Field は ルックアップ レジストレーション API を実装しています。このAPIを使用して、フィールドクラスとそのインスタンスでどのルックアップを利用できるか、またフィールドからどのようにルックアップを取得するかをカスタマイズできます。
すべての Field インスタンスには、その動作を詳しく調べるための属性がいくつか含まれています。フィールドの機能に依存するコードを書く必要がある場合には、 isinstance チェックの代わりにこれらの属性を使用してください。これらの属性は Model._meta API と一緒に使うことで、特定のフィールドタイプを絞り込むことができます。カスタムモデルフィールドはこれらのフラグを実装する必要があります。
モデル継承で使用される OneToOneField のように、フィールドが自動的に作成されたかどうかを示す真偽値フラグ。
フィールドにデータベース・カラムが関連付けられているかどうかを示す真偽値。
デフォルトでは Options.get_fields() によって返されない隠しフィールドがあるかどうかを示す真偽値のフラグです。例えば、 ForeignKey の逆フィールドで、 related_name が '+' で始まる場合です。
真偽値フラグで、フィールドが機能のために一つまたは複数の他のモデルへの参照を含んでいるかどうかを示します(例: ForeignKey, ManyToManyField, OneToOneField など)。
フィールドが定義されているモデルを返します。フィールドがモデルの基底クラスに定義されている場合、model はインスタンスのクラスではなく基底クラスを参照します。
これらの属性はリレーションのカーディナリティやその他の詳細をクエリするために使用されます。これらの属性は全てのフィールドに存在しますが、フィールドがリレーションタイプである場合のみ (None ではなく) 真偽値を持ちます (Field.is_relation=True)。
真偽値フラグで、フィールドが多対多のリレーションを持つ場合は True となり、そうでない場合は False となります。Django で True となるフィールドは ManyToManyField だけです。
真偽値フラグで、フィールドが ForeignKey のような多対一のリレーションを持っている場合は True となり、そうでない場合は False となります。
真偽値フラグで、フィールドが GenericRelation や ForeignKey のような一対多のリレーションを持っている場合は True となり、そうでない場合は False となります。
真偽値フラグで、フィールドが OneToOneField のような一対一のリレーションを持っている場合は True となり、そうでない場合は False となります。
フィールドのリレーション先となるモデルを指定します。例えば、 ForeignKey(Author, on_delete=models.CASCADE) の Author です。 GenericForeignKey の related_model は常に None です。
7月 02, 2025