=====================

Model field reference

=====================

.. module:: django.db.models.fields

   :synopsis: Built-in field types.

.. currentmodule:: django.db.models

This document contains all the gory details about all the `field options`_ and

`field types`_ Django's got to offer.

.. seealso::

    If the built-in fields don't do the trick, you can easily :doc:`write your

    own custom model fields </howto/custom-model-fields>`.

.. note::

    Technically, these models are defined in :mod:`django.db.models.fields`, but

    for convenience they're imported into :mod:`django.db.models`; the standard

    convention is to use ``from django.db import models`` and refer to fields as

    ``models.<Foo>Field``.

.. _common-model-field-options:

Field options

=============

The following arguments are available to all field types. All are optional.

``null``

--------

.. attribute:: Field.null

If ``True``, Django will store empty values as ``NULL`` in the database. Default

is ``False``.

Note that empty string values will always get stored as empty strings, not as

``NULL``. Only use ``null=True`` for non-string fields such as integers,

booleans and dates. For both types of fields, you will also need to set

``blank=True`` if you wish to permit empty values in forms, as the

:attr:`~Field.null` parameter only affects database storage (see

:attr:`~Field.blank`).

Avoid using :attr:`~Field.null` on string-based fields such as

:class:`CharField` and :class:`TextField` unless you have an excellent reason.

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;" Django convention is to use the empty

string, not ``NULL``.

.. note::

    When using the Oracle database backend, the ``null=True`` option will be

    coerced for string-based fields that have the empty string as a possible

    value, and the value ``NULL`` will be stored to denote the empty string.

``blank``

---------

.. attribute:: Field.blank

If ``True``, the field is allowed to be blank. Default is ``False``.

Note that this is different than :attr:`~Field.null`. :attr:`~Field.null` is

purely database-related, whereas :attr:`~Field.blank` is validation-related. If

a field has ``blank=True``, validation on Django's admin site will allow entry

of an empty value. If a field has ``blank=False``, the field will be required.

.. _field-choices:

``choices``

-----------

.. attribute:: Field.choices

An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this

field.

If this is given, Django's admin will use a select box instead of the standard

text field and will limit choices to the choices given.

A choices list looks like this::

    YEAR_IN_SCHOOL_CHOICES = (

        ('FR', 'Freshman'),

        ('SO', 'Sophomore'),

        ('JR', 'Junior'),

        ('SR', 'Senior'),

        ('GR', 'Graduate'),

    )

The first element in each tuple is the actual value to be stored. The second

element is the human-readable name for the option.

The choices list can be defined either as part of your model class::

    class Foo(models.Model):

        GENDER_CHOICES = (

            ('M', 'Male'),

            ('F', 'Female'),

        )

        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)

or outside your model class altogether::

    GENDER_CHOICES = (

        ('M', 'Male'),

        ('F', 'Female'),

    )

    class Foo(models.Model):

        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)

You can also collect your available choices into named groups that can

be used for organizational purposes::

    MEDIA_CHOICES = (

        ('Audio', (

                ('vinyl', 'Vinyl'),

                ('cd', 'CD'),

            )

        ),

        ('Video', (

                ('vhs', 'VHS Tape'),

                ('dvd', 'DVD'),

            )

        ),

        ('unknown', 'Unknown'),

    )

The first element in each tuple is the name to apply to the group. The

second element is an iterable of 2-tuples, with each 2-tuple containing

a value and a human-readable name for an option. Grouped options may be

combined with ungrouped options within a single list (such as the

`unknown` option in this example).

For each model field that has :attr:`~Field.choices` set, Django will add a

method to retrieve the human-readable name for the field's current value. See

:meth:`~django.db.models.Model.get_FOO_display` in the database API

documentation.

Finally, note that choices can be any iterable object -- not necessarily a list

or tuple. This lets you construct choices dynamically. But if you find yourself

hacking :attr:`~Field.choices` to be dynamic, you're probably better off using a

proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is

meant for static data that doesn't change much, if ever.

``db_column``

-------------

.. attribute:: Field.db_column

The name of the database column to use for this field. If this isn't given,

Django will use the field's name.

If your database column name is an SQL reserved word, or contains

characters that aren't allowed in Python variable names -- notably, the

hyphen -- that's OK. Django quotes column and table names behind the

scenes.

``db_index``

------------

.. attribute:: Field.db_index

If ``True``, djadmin:`django-admin.py sqlindexes <sqlindexes>` will output a

``CREATE INDEX`` statement for this field.

``db_tablespace``

-----------------

.. attribute:: Field.db_tablespace

.. versionadded:: 1.0

The name of the database tablespace to use for this field's index, if this field

is indexed. The default is the project's :setting:`DEFAULT_INDEX_TABLESPACE`

setting, if set, or the :attr:`~Field.db_tablespace` of the model, if any. If

the backend doesn't support tablespaces, this option is ignored.

``default``

-----------

.. attribute:: Field.default

The default value for the field. This can be a value or a callable object. If

callable it will be called every time a new object is created.

``editable``

------------

.. attribute:: Field.editable

If ``False``, the field will not be editable in the admin or via forms

automatically generated from the model class. Default is ``True``.

``error_messages``

------------------

.. versionadded:: 1.2

.. attribute:: Field.error_messages

The ``error_messages`` argument lets you override the default messages that the

field will raise. Pass in a dictionary with keys matching the error messages you

want to override.

``help_text``

-------------

.. attribute:: Field.help_text

Extra "help" text to be displayed under the field on the object's admin form.

It's useful for documentation even if your object doesn't have an admin form.

Note that this value is *not* HTML-escaped when it's displayed in the admin

interface. This lets you include HTML in :attr:`~Field.help_text` if you so

desire. For example::

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

Alternatively you can use plain text and

``django.utils.html.escape()`` to escape any HTML special characters.

``primary_key``

---------------

.. attribute:: Field.primary_key

If ``True``, this field is the primary key for the model.

If you don't specify ``primary_key=True`` for any fields in your model, Django

will automatically add an :class:`IntegerField` 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. For more, see

:ref:`automatic-primary-key-fields`.

``primary_key=True`` implies :attr:`null=False <Field.null>` and :attr:`unique=True <Field.unique>`.

Only one primary key is allowed on an object.

``unique``

----------

.. attribute:: Field.unique

If ``True``, this field must be unique throughout the table.

This is enforced at the database level and at the Django admin-form level. If

you try to save a model with a duplicate value in a :attr:`~Field.unique`

field, a :exc:`django.db.IntegrityError` will be raised by the model's

:meth:`~django.db.models.Model.save` method.

This option is valid on all field types except :class:`ManyToManyField` and

:class:`FileField`.

``unique_for_date``

-------------------

.. attribute:: Field.unique_for_date

Set this to the name of a :class:`DateField` or :class:`DateTimeField` to

require that this field be unique for the value of the date field.

For example, if you have a field ``title`` that has

``unique_for_date="pub_date"``, then Django wouldn't allow the entry of two

records with the same ``title`` and ``pub_date``.

This is enforced at the Django admin-form level but not at the database level.

``unique_for_month``

--------------------

.. attribute:: Field.unique_for_month

Like :attr:`~Field.unique_for_date`, but requires the field to be unique with

respect to the month.

``unique_for_year``

-------------------

.. attribute:: Field.unique_for_year

Like :attr:`~Field.unique_for_date` and :attr:`~Field.unique_for_month`.

``verbose_name``

-------------------

.. attribute:: Field.verbose_name

A human-readable name for the field. If the verbose name isn't given, Django

will automatically create it using the field's attribute name, converting

underscores to spaces. See :ref:`Verbose field names <verbose-field-names>`.

``validators``

-------------------

.. versionadded:: 1.2

.. attribute:: Field.validators

A list of validators to run for this field.See the :doc:`validators

documentation </ref/validators>` for more information.

.. _model-field-types:

Field types

===========

.. currentmodule:: django.db.models

``AutoField``

-------------

.. class:: AutoField(**options)

An :class:`IntegerField` that automatically increments

according to available IDs. You usually won't need to use this directly; a

primary key field will automatically be added to your model if you don't specify

otherwise. See :ref:`automatic-primary-key-fields`.

``BigIntegerField``

-------------------

.. versionadded:: 1.2

.. class:: BigIntegerField([**options])

A 64 bit integer, much like an :class:`IntegerField` except that it is

guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The

admin represents this as an ``<input type="text">`` (a single-line input).

``BooleanField``

----------------

.. class:: BooleanField(**options)

A true/false field.

The admin represents this as a checkbox.

.. versionchanged:: 1.2

    In previous versions of Django when running under MySQL ``BooleanFields``

    would return their data as ``ints``, instead of true ``bools``.  See the

    release notes for a complete description of the change.

``CharField``

-------------

.. class:: CharField(max_length=None, [**options])

A string field, for small- to large-sized strings.

For large amounts of text, use :class:`~django.db.models.TextField`.

The admin represents this as an ``<input type="text">`` (a single-line input).

:class:`CharField` has one extra required argument:

.. attribute:: CharField.max_length

    The maximum length (in characters) of the field. The max_length is enforced

    at the database level and in Django's validation.

.. note::

    If you are writing an application that must be portable to multiple

    database backends, you should be aware that there are restrictions on

    ``max_length`` for some backends. Refer to the :doc:`database backend

    notes </ref/databases>` for details.

.. admonition:: MySQL users

    If you are using this field with MySQLdb 1.2.2 and the ``utf8_bin``

    collation (which is *not* the default), there are some issues to be aware

    of. Refer to the :ref:`MySQL database notes <mysql-collation>` for

    details.

``CommaSeparatedIntegerField``

------------------------------

.. class:: CommaSeparatedIntegerField(max_length=None, [**options])

A field of integers separated by commas. As in :class:`CharField`, the

:attr:`~CharField.max_length` argument is required and the note about database

portability mentioned there should be heeded.

``DateField``

-------------

.. class:: DateField([auto_now=False, auto_now_add=False, **options])

A date, represented in Python by a ``datetime.date`` instance. Has a few extra,

optional arguments:

.. attribute:: DateField.auto_now

    Automatically set the field to now every time the object is saved. Useful

    for "last-modified" timestamps. Note that the current date is *always*

    used; it's not just a default value that you can override.

.. attribute:: DateField.auto_now_add

    Automatically set the field to now when the object is first created. Useful

    for creation of timestamps. Note that the current date is *always* used;

    it's not just a default value that you can override.

The admin represents this as an ``<input type="text">`` with a JavaScript

calendar, and a shortcut for "Today".  The JavaScript calendar will always

start the week on a Sunday.

.. note::

    As currently implemented, setting ``auto_now`` or ``auto_add_now`` to

    ``True`` will cause the field to have ``editable=False`` and ``blank=True``

    set.

``DateTimeField``

-----------------

.. class:: DateTimeField([auto_now=False, auto_now_add=False, **options])

A date and time, represented in Python by a ``datetime.datetime`` instance.

Takes the same extra arguments as :class:`DateField`.

The admin represents this as two ``<input type="text">`` fields, with

JavaScript shortcuts.

``DecimalField``

----------------

.. versionadded:: 1.0

.. class:: DecimalField(max_digits=None, decimal_places=None, [**options])

A fixed-precision decimal number, represented in Python by a

:class:`~decimal.Decimal` instance. Has two **required** arguments:

.. attribute:: DecimalField.max_digits

    The maximum number of digits allowed in the number

.. attribute:: DecimalField.decimal_places

    The number of decimal places to store with the number

For example, to store numbers up to 999 with a resolution of 2 decimal places,

you'd use::

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

And to store numbers up to approximately one billion with a resolution of 10

decimal places::

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

The admin represents this as an ``<input type="text">`` (a single-line input).

``EmailField``

--------------

.. class:: EmailField([max_length=75, **options])

A :class:`CharField` that checks that the value is a valid e-mail address.

``FileField``

-------------

.. class:: FileField(upload_to=None, [max_length=100, **options])

A file-upload field.

.. note::

    The ``primary_key`` and ``unique`` arguments are not supported, and will

    raise a ``TypeError`` if used.

Has one **required** argument:

.. attribute:: FileField.upload_to

    A local filesystem path that will be appended to your :setting:`MEDIA_ROOT`

    setting to determine the value of the :attr:`~django.core.files.File.url`

    attribute.

    This path may contain `strftime formatting`_, which will be replaced by the

    date/time of the file upload (so that uploaded files don't fill up the given

    directory).

    .. versionchanged:: 1.0

    This may also be a callable, such as a function, which will be called to

    obtain the upload path, including the filename. This callable must be able

    to accept two arguments, and return a Unix-style path (with forward slashes)

    to be passed along to the storage system. The two arguments that will be

    passed are:

        ======================  ===============================================

        Argument                Description

        ======================  ===============================================

        ``instance``            An instance of the model where the

                                ``FileField`` is defined. More specifically,

                                this is the particular instance where the

                                current file is being attached.

                                In most cases, this object will not have been

                                saved to the database yet, so if it uses the

                                default ``AutoField``, *it might not yet have a

                                value for its primary key field*.

        ``filename``            The filename that was originally given to the

                                file. This may or may not be taken into account

                                when determining the final destination path.

        ======================  ===============================================

Also has one optional argument:

.. attribute:: FileField.storage

    .. versionadded:: 1.0

    Optional. A storage object, which handles the storage and retrieval of your

    files. See :doc:`/topics/files` for details on how to provide this object.

The admin represents this field as an ``<input type="file">`` (a file-upload

widget).