1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
=====================
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, opclasses=(), condition=None)
Creates an index (B-Tree) in the database.
``fields``
----------
.. attribute:: Index.fields
A list or tuple 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.
.. versionchanged:: 2.1
Older versions don't accept a tuple.
``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 (_).
.. admonition:: Partial indexes in abstract base classes
You must always specify a unique name for an index. As such, you
cannot normally specify a partial index on an abstract base class, since
the :attr:`Meta.indexes <django.db.models.Options.indexes>` option is
inherited by subclasses, with exactly the same values for the attributes
(including ``name``) each time. Instead, specify the ``indexes`` option
on subclasses directly, providing a unique name for each index.
``db_tablespace``
-----------------
.. attribute:: Index.db_tablespace
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`.
``opclasses``
-------------
.. attribute:: Index.opclasses
.. versionadded:: 2.2
The names of the `PostgreSQL operator classes
<https://www.postgresql.org/docs/current/indexes-opclass.html>`_ to use for
this index. If you require a custom operator class, you must provide one for
each field in the index.
For example, ``GinIndex(name='json_index', fields=['jsonfield'],
opclasses=['jsonb_path_ops'])`` creates a gin index on ``jsonfield`` using
``jsonb_path_ops``.
``opclasses`` are ignored for databases besides PostgreSQL.
:attr:`Index.name` is required when using ``opclasses``.
``condition``
-------------
.. attribute:: Index.condition
.. versionadded:: 2.2
If the table is very large and your queries mostly target a subset of rows,
it may be useful to restrict an index to that subset. Specify a condition as a
:class:`~django.db.models.Q`. For example, ``condition=Q(pages__gt=400)``
indexes records with more than 400 pages.
:attr:`Index.name` is required when using ``condition``.
.. admonition:: Restrictions on PostgreSQL
PostgreSQL requires functions referenced in the condition to be marked as
IMMUTABLE. Django doesn't validate this but PostgreSQL will error. This
means that functions such as :ref:`date-functions` and
:class:`~django.db.models.functions.Concat` aren't accepted. If you store
dates in :class:`~django.db.models.DateTimeField`, comparison to
:class:`~datetime.datetime` objects may require the ``tzinfo`` argument
to be provided because otherwise the comparison could result in a mutable
function due to the casting Django does for :ref:`lookups <field-lookups>`.
.. admonition:: Restrictions on SQLite
SQLite `imposes restrictions <https://www.sqlite.org/partialindex.html>`_
on how a partial index can be constructed.
.. admonition:: Oracle
Oracle does not support partial indexes. Instead, partial indexes can be
emulated using functional indexes. Use a :doc:`migration
</topics/migrations>` to add the index using :class:`.RunSQL`.
.. admonition:: MySQL and MariaDB
The ``condition`` argument is ignored with MySQL and MariaDB as neither
supports conditional indexes.
|
