Django automatically creates an index on each ForeignKey field.You can disable this by setting db_index=False on the ForeignKey field. This is useful when:<ul><li> you are creating a foreign key for consistency and you don't use it in JOINs,</li><li>you have a multi-column index that covers this column in the kind of queries that you run.</li></ul>

Foreign Key fields are indexed by default

computerscience

Computer Science

This document contains all the API references of <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field"><code>Field </code> </a>including the <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#field-options">field options </a>and <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#field-types">field types </a>Django offers.

If the built-in fields don’t do the trick, you can try <a href="https://github.com/django/django-localflavor">django-localflavor </a>(<a href="https://django-localflavor.readthedocs.io/">documentation </a>), which contains assorted pieces of code that are useful for particular countries and cultures.

Technically, these models are defined in <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#module-django.db.models.fields"><code>django.db.models.fields </code> </a>, but for convenience they’re imported into <a href="https://docs.djangoproject.com/en/3.2/topics/db/models/#module-django.db.models"><code>django.db.models </code> </a>; the standard convention is to use <code>from django.db import models </code>and refer to fields as <code>models.Field </code>.

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

If <code>True </code>, Django will store empty values as <code>NULL </code>in the database. Default is <code>False </code>.

Avoid using <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.null"><code>null </code> </a>on string-based fields such as <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.CharField"><code>CharField </code> </a>and <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.TextField"><code>TextField </code> </a>. If a string-based field has <code>null=True </code>, that means it has two possible values for “no data”: <code>NULL </code>, and the empty string. In most cases, it’s redundant to have two possible values for “no data;” the Django convention is to use the empty string, not <code>NULL </code>. One exception is when a <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.CharField"><code>CharField </code> </a>has both <code>unique=True </code>and <code>blank=True </code>set. In this situation, <code>null=True </code>is required to avoid unique constraint violations when saving multiple objects with blank values.

For both string-based and non-string-based fields, you will also need to set <code>blank=True </code>if you wish to permit empty values in forms, as the <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.null"><code>null </code> </a>parameter only affects database storage (see <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.blank"><code>blank </code> </a>).

When using the Oracle database backend, the value <code>NULL </code>will be stored to denote the empty string regardless of this attribute.

If <code>True </code>, the field is allowed to be blank. Default is <code>False </code>.

Note that this is different than <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.null"><code>null </code> </a>. <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.null"><code>null </code> </a>is purely database-related, whereas <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.blank"><code>blank </code> </a>is validation-related. If a field has <code>blank=True </code>, form validation will allow entry of an empty value. If a field has <code>blank=False </code>, the field will be required.

A <a href="https://docs.python.org/3/glossary.html#term-sequence">sequence </a>consisting itself of iterables of exactly two items (e.g. <code>[(A, B), (A, B) ...] </code>) to use as choices for this field. If choices are given, they’re enforced by <a href="https://docs.djangoproject.com/en/3.2/ref/models/instances/#validating-objects">model validation </a>and the default form widget will be a select box with these choices instead of the standard text field.

The first element in each tuple is the actual value to be set on the model, and the second element is the human-readable name. For example:

Generally, it’s best to define choices inside a model class, and to define a suitably-named constant for each value:

Though you can define a choices list outside of a model class and then refer to it, defining the choices and names for each choice inside the model class keeps all of that information with the class that uses it, and helps reference the choices (e.g, <code>Student.SOPHOMORE </code>will work anywhere that the <code>Student </code>model has been imported).

You can also collect your available choices into named groups that can be used for organizational purposes:

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 <code>'unknown' </code>option in this example).

For each model field that has <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.choices"><code>choices </code> </a>set, Django will add a method to retrieve the human-readable name for the field’s current value. See <a href="https://docs.djangoproject.com/en/3.2/ref/models/instances/#django.db.models.Model.get_FOO_display"><code>get_FOO_display() </code> </a>in the database API documentation.

Note that choices can be any sequence object – not necessarily a list or tuple. This lets you construct choices dynamically. But if you find yourself hacking <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.choices"><code>choices </code> </a>to be dynamic, you’re probably better off using a proper database table with a <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.ForeignKey"><code>ForeignKey </code> </a>. <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.choices"><code>choices </code> </a>is meant for static data that doesn’t change much, if ever.

A new migration is created each time the order of <code>choices </code>changes.

Unless <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.blank"><code>blank=False </code> </a>is set on the field along with a <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.default"><code>default </code> </a>then a label containing <code>"---------" </code>will be rendered with the select box. To override this behavior, add a tuple to <code>choices </code>containing <code>None </code>; e.g. <code>(None, 'Your String For Display') </code>. Alternatively, you can use an empty string instead of <code>None </code>where this makes sense - such as on a <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.CharField"><code>CharField </code> </a>.

In addition, Django provides enumeration types that you can subclass to define choices in a concise way:

These work similar to <a href="https://docs.python.org/3/library/enum.html#module-enum"><code>enum </code> </a>from Python’s standard library, but with some modifications:

<ul><li>Enum member values are a tuple of arguments to use when constructing the concrete data type. Django supports adding an extra string value to the end of this tuple to be used as the human-readable name, or <code>label </code>. The <code>label </code>can be a lazy translatable string. Thus, in most cases, the member value will be a <code>(value, label) </code>two-tuple. See below for <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#field-choices-enum-subclassing">an example of subclassing choices </a>using a more complex data type. If a tuple is not provided, or the last item is not a (lazy) string, the <code>label </code>is <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#field-choices-enum-auto-label">automatically generated </a>from the member name. </li><li>A <code>.label </code>property is added on values, to return the human-readable name. </li><li>A number of custom properties are added to the enumeration classes – <code>.choices </code>, <code>.labels </code>, <code>.values </code>, and <code>.names </code>– to make it easier to access lists of those separate parts of the enumeration. Use <code>.choices </code>as a suitable value to pass to <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.choices"><code>choices </code> </a>in a field definition. </li><li>The use of <a href="https://docs.python.org/3/library/enum.html#enum.unique"><code>enum.unique() </code> </a>is enforced to ensure that values cannot be defined multiple times. This is unlikely to be expected in choices for a field. </li> </ul>

Note that using <code>YearInSchool.SENIOR </code>, <code>YearInSchool['SENIOR'] </code>, or <code>YearInSchool('SR') </code>to access or lookup enum members work as expected, as do the <code>.name </code>and <code>.value </code>properties on the members.

If you don’t need to have the human-readable names translated, you can have them inferred from the member name (replacing underscores with spaces and using title-case):

Since the case where the enum values need to be integers is extremely common, Django provides an <code>IntegerChoices </code>class. For example:

It is also possible to make use of the <a href="https://docs.python.org/3/library/enum.html#functional-api">Enum Functional API </a>with the caveat that labels are automatically generated as highlighted above:

If you require support for a concrete data type other than <code>int </code>or <code>str </code>, you can subclass <code>Choices </code>and the required concrete data type, e.g. <a href="https://docs.python.org/3/library/datetime.html#datetime.date"><code>date </code> </a>for use with <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.DateField"><code>DateField </code> </a>:

There are some additional caveats to be aware of:

<ul><li>Enumeration types do not support <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#field-choices-named-groups">named groups </a>. </li><li>Because an enumeration with a concrete data type requires all values to match the type, overriding the <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#field-choices-blank-label">blank label </a>cannot be achieved by creating a member with a value of <code>None </code>. Instead, set the <code>__empty__ </code>attribute on the class: <pre>class Answer ( models . IntegerChoices ): NO = 0 , _ ( 'No' ) YES = 1 , _ ( 'Yes' ) __empty__ = _ ( '(Unknown)' ) </pre> </li> </ul>

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.

If <code>True </code>, a database index will be created for this field.

The name of the <a href="https://docs.djangoproject.com/en/3.2/topics/db/tablespaces/">database tablespace </a>to use for this field’s index, if this field is indexed. The default is the project’s <a href="https://docs.djangoproject.com/en/3.2/ref/settings/#std-setting-DEFAULT_INDEX_TABLESPACE"><code>DEFAULT_INDEX_TABLESPACE </code> </a>setting, if set, or the <a href="https://docs.djangoproject.com/en/3.2/ref/models/options/#django.db.models.Options.db_tablespace"><code>db_tablespace </code> </a>of the model, if any. If the backend doesn’t support tablespaces for indexes, this option is ignored.

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.

The default can’t be a mutable object (model instance, <code>list </code>, <code>set </code>, etc.), as a reference to the same instance of that object would be used as the default value in all new model instances. Instead, wrap the desired default in a callable. For example, if you want to specify a default <code>dict </code>for <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.JSONField"><code>JSONField </code> </a>, use a function:

<code>lambda </code>s can’t be used for field options like <code>default </code>because they can’t be <a href="https://docs.djangoproject.com/en/3.2/topics/migrations/#migration-serializing">serialized by migrations </a>. See that documentation for other caveats.

For fields like <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.ForeignKey"><code>ForeignKey </code> </a>that map to model instances, defaults should be the value of the field they reference (<code>pk </code>unless <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.ForeignKey.to_field"><code>to_field </code> </a>is set) instead of model instances.

The default value is used when new model instances are created and a value isn’t provided for the field. When the field is a primary key, the default is also used when the field is set to <code>None </code>.

If <code>False </code>, the field will not be displayed in the admin or any other <a href="https://docs.djangoproject.com/en/3.2/topics/forms/modelforms/#django.forms.ModelForm"><code>ModelForm </code> </a>. They are also skipped during <a href="https://docs.djangoproject.com/en/3.2/ref/models/instances/#validating-objects">model validation </a>. Default is <code>True </code>.

The <code>error_messages </code>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.

Error message keys include <code>null </code>, <code>blank </code>, <code>invalid </code>, <code>invalid_choice </code>, <code>unique </code>, and <code>unique_for_date </code>. Additional error message keys are specified for each field in the <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#field-types">Field types </a>section below.

These error messages often don’t propagate to forms. See <a href="https://docs.djangoproject.com/en/3.2/topics/forms/modelforms/#considerations-regarding-model-errormessages">Considerations regarding model’s error_messages </a>.

Extra “help” text to be displayed with the form widget. It’s useful for documentation even if your field isn’t used on a form.

Note that this value is not HTML-escaped in automatically-generated forms. This lets you include HTML in <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.help_text"><code>help_text </code> </a>if you so desire. For example:

Alternatively you can use plain text and <a href="https://docs.djangoproject.com/en/3.2/ref/utils/#django.utils.html.escape"><code>django.utils.html.escape() </code> </a>to escape any HTML special characters. Ensure that you escape any help text that may come from untrusted users to avoid a cross-site scripting attack.

If <code>True </code>, this field is the primary key for the model.

If you don’t specify <code>primary_key=True </code>for any field in your model, Django will automatically add a field to hold the primary key, so you don’t need to set <code>primary_key=True </code>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 <a href="https://docs.djangoproject.com/en/3.2/ref/applications/#django.apps.AppConfig.default_auto_field"><code>AppConfig.default_auto_field </code> </a>or globally in the <a href="https://docs.djangoproject.com/en/3.2/ref/settings/#std-setting-DEFAULT_AUTO_FIELD"><code>DEFAULT_AUTO_FIELD </code> </a>setting. For more, see <a href="https://docs.djangoproject.com/en/3.2/topics/db/models/#automatic-primary-key-fields">Automatic primary key fields </a>.

<code>primary_key=True </code>implies <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.null"><code>null=False </code> </a>and <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.unique"><code>unique=True </code> </a>. Only one primary key is allowed on an object.

The primary key field is read-only. If you change the value of the primary key on an existing object and then save it, a new object will be created alongside the old one.

<code>Field </code>implements the <a href="https://docs.djangoproject.com/en/3.2/ref/models/lookups/#lookup-registration-api">lookup registration API </a>. The API can be used to customize which lookups are available for a field class, and how lookups are fetched from a field.

class

** options

An <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.IntegerField"><code>IntegerField </code> </a>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 <a href="https://docs.djangoproject.com/en/3.2/topics/db/models/#automatic-primary-key-fields">Automatic primary key fields </a>.

A 64-bit integer, much like an <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.AutoField"><code>AutoField </code> </a>except that it is guaranteed to fit numbers from <code>1 </code>to <code>9223372036854775807 </code>.

A 64-bit integer, much like an <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.IntegerField"><code>IntegerField </code> </a>except that it is guaranteed to fit numbers from <code>-9223372036854775808 </code>to <code>9223372036854775807 </code>. The default form widget for this field is a <a href="https://docs.djangoproject.com/en/3.2/ref/forms/widgets/#django.forms.NumberInput"><code>NumberInput </code> </a>.

A <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.CharField"><code>CharField </code> </a>for a URL, validated by <a href="https://docs.djangoproject.com/en/3.2/ref/validators/#django.core.validators.URLValidator"><code>URLValidator </code> </a>.

The default form widget for this field is a <a href="https://docs.djangoproject.com/en/3.2/ref/forms/widgets/#django.forms.URLInput"><code>URLInput </code> </a>.

Like all <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.CharField"><code>CharField </code> </a>subclasses, <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.URLField"><code>URLField </code> </a>takes the optional <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.CharField.max_length"><code>max_length </code> </a>argument. If you don’t specify <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.CharField.max_length"><code>max_length </code> </a>, a default of 200 is used.

A field for storing universally unique identifiers. Uses Python’s <a href="https://docs.python.org/3/library/uuid.html#uuid.UUID"><code>UUID </code> </a>class. When used on PostgreSQL, this stores in a <code>uuid </code>datatype, otherwise in a <code>char(32) </code>.

Universally unique identifiers are a good alternative to <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.AutoField"><code>AutoField </code> </a>for <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.primary_key"><code>primary_key </code> </a>. The database will not generate the UUID for you, so it is recommended to use <a href="https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.Field.default"><code>default </code> </a>:

Note that a callable (with the parentheses omitted) is passed to <code>default </code>, not an instance of <code>UUID </code>.

Using <a href="https://docs.djangoproject.com/en/3.2/ref/models/querysets/#std-fieldlookup-iexact"><code>iexact </code> </a>, <a href="https://docs.djangoproject.com/en/3.2/ref/models/querysets/#std-fieldlookup-contains"><code>contains </code> </a>, <a href="https://docs.djangoproject.com/en/3.2/ref/models/querysets/#std-fieldlookup-icontains"><code>icontains </code> </a>, <a href="https://docs.djangoproject.com/en/3.2/ref/models/querysets/#std-fieldlookup-startswith"><code>startswith </code> </a>, <a href="https://docs.djangoproject.com/en/3.2/ref/models/querysets/#std-fieldlookup-istartswith"><code>istartswith </code> </a>, <a href="https://docs.djangoproject.com/en/3.2/ref/models/querysets/#std-fieldlookup-endswith"><code>endswith </code> </a>, or <a href="https://docs.djangoproject.com/en/3.2/ref/models/querysets/#std-fieldlookup-iendswith"><code>iendswith </code> </a>lookups on PostgreSQL don’t work for values without hyphens, because PostgreSQL stores them in a hyphenated uuid datatype type.

Django also defines a set of fields that represent relations.

on_delete

Foreign Key on Models | Django documentation

Foreign Key fields are indexed by default

Related collections

Other curated ideas on this topic: