=====================
Model index reference
=====================

.. module:: django.db.models.indexes

.. currentmodule:: django.db.models

Index classes ease creating database indexes. They can be added using the
:attr:`Meta.indexes <django.db.models.Options.indexes>` option. This document
explains the API references of :class:`Index` which includes the `index
options`_.

.. admonition:: Referencing built-in indexes

    Indexes are defined in ``django.db.models.indexes``, 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 the indexes as
    ``models.<IndexClass>``.

``Index`` options
=================

.. class:: Index(fields=[], name=None, db_tablespace=None)

    Creates an index (B-Tree) in the database.

``fields``
----------

.. attribute:: Index.fields

A list of the name of the fields on which the index is desired.

By default, indexes are created with an ascending order for each column. To
define an index with a descending order for a column, add a hyphen before the
field's name.

For example ``Index(fields=['headline', '-pub_date'])`` would create SQL with
``(headline, pub_date DESC)``. Index ordering isn't supported on MySQL. In that
case, a descending index is created as a normal index.

.. admonition:: Support for column ordering on SQLite

    Column ordering is supported on SQLite 3.3.0+ and only for some database
    file formats. Refer to the `SQLite docs
    <https://www.sqlite.org/lang_createindex.html>`_ for specifics.

``name``
--------

.. attribute:: Index.name

The name of the index. If ``name`` isn't provided Django will auto-generate a
name. For compatibility with different databases, index names cannot be longer
than 30 characters and shouldn't start with a number (0-9) or underscore (_).

``db_tablespace``
-----------------

.. attribute:: Index.db_tablespace

.. versionadded:: 2.0

The name of the :doc:`database tablespace </topics/db/tablespaces>` to use for
this index. For single field indexes, if ``db_tablespace`` isn't provided, the
index is created in the ``db_tablespace`` of the field.

If :attr:`.Field.db_tablespace` isn't specified (or if the index uses multiple
fields), the index is created in tablespace specified in the
:attr:`~django.db.models.Options.db_tablespace` option inside the model's
``class Meta``. If neither of those tablespaces are set, the index is created
in the same tablespace as the table.

.. seealso::

    For a list of PostgreSQL-specific indexes, see
    :mod:`django.contrib.postgres.indexes`.