Django/Field Types

This is a quick reference for common built-in Django field types. A more comprehensive guide is available in the Django documentation. There is also a section that deals with the base Field class and how to create custom subclasses.

The built in fields are imported from django.db.models.

Text field types

CharField

A generic text field, which uses a single-line textbox control for entry. Requires a max_length argument defining the maximum number of characters that can be entered.

TextField

A generic text field, which uses a multi-line textarea control for entry.

EmailField

A CharField containing an email address. max_length defaults to 75, but should be 254 to hold all valid email addresses.

URLField

A CharField containing a URL. max_length defaults to 200.

Numeric field types

IntegerField

A 32-bit signed integer.

BigIntegerField

A 64-bit signed integer.

SmallIntegerField

A 16-bit signed integer.

PositiveIntegerField

An IntegerField that must be greater than or equal to 0.

PositiveSmallIntegerField

A SmallIntegerField that must be greater than or equal to 0.

FloatField

A floating point numeric value.

DecimalField

A fixed point numeric value. It requires two argments:

• decimal_places - The number of decimal places to use.
• max_digits - The maximum total number of digits allowed, on both sides of the decimal point.

Boolean field types

BooleanField

A simple boolean (True/False) value.

NullBooleanField

A boolean field that allows a NULL value in addition to True or False.

Date and time field types

TimeField

A datetime.date, datetime.datetime, or datetime.time instance. Optional arguments:

• auto_now - Field is always updated to the current date/time when the record is saved.
• auto_now_add - Field is set to the current date/time when the record is first created.

Relationship field types

ForeignKey

Set up a foreign key referencing another model. The first argument must be the model to which the relationship is set up, either by object or by string name. Other common arguments:

• related_name - The name to use to reference back from the foreign model.
• to_field - The field to reference in the foreign model. Defaults to the primary key.
• on_delete - Set behavior when the foreign record is deleted. One of:
  • 'CASCADE' (default) - Cascade delete.
  • 'PROTECT' - Do not allow the deletion of the foreign record.
  • 'SET_NULL' - Set ForeignKey field to NULL.
  • 'SET_DEFAULT' - Set ForeignKey field to default value.
  • 'SET()' - Set ForeignKey field to value or result of callable passed.
  • 'DO_NOTHING' - Do nothing.

Arguments available to all field types

blank

Default False. Determines whether the user may leave the field without a value.

choices

If defined, the user will be presented with a list of values to choose from. It contains a sequence, each element of which must be either:

• A 2-tuple containing an internal value name to store and a human-readable form to display.
• A 2-tuple containing a group name and a sequence of 2-tuples as above. This will group the items together in the selection list.

Example:

(
  ('Felids', (
               ('T', 'Tiger'),
               ('L', 'Lion'),
               ('P', 'Panther')
             )
  ),
  ('Canids', (
               ('W', 'Wolf'),
               ('F', 'Fox')
             )
  ),
  ('M', 'Other Mammal'),
  ('N', 'Non-mammal')
)

db_column

Default: field name. The name to use for the database column storing this field.

db_index

If True, an index for this column will be created in the database. Fields with unique=True are automatically indexed.

db_tablespace

Default: the project’s DEFAULT_INDEX_TABLESPACE setting, or the db_tablespace of the model. This represents the name of the database tablespace to use for this field’s index, if this field is indexed.

default

A value or callable returning a default value for this field. Do not directly use mutable objects here; rather, wrap them in a callable:

JSONField("ContactInfo", default=lambda:{"email": "to1@example.com"})

editable

Default: True. If False, the field will not be displayed in the admin form or other ModelForms.

error_messages

A dictionary containing custom error messages to return to the user. Generic error messages can be given for:

• null
• blank
• invalid
• invalid_choice
• unique

help_text

Additional informational text to be displyed to the user about this field. Can contain HTML.

null

Default: False. If True, a NULL value will be stored in the database for blank values entered. Also requires blank=True.

primary_key

If True, this field will be used as the table's primary key.

unique

If True, this field's value must be unique within the database. Unique fields are automatically indexed. Does not apply to ManyToManyField, OneToOneField, or FileField.

unique_for_year

When set to the string name of a DateField or DateTimeField, these will require the value to be unique only among records that share its date/month/year.

verbose_name

Default: field name. This sets a more readable name to display for the field.

validators

A sequence of validators to run for this field.