Debian Codegraph @

docs/ref/contrib/postgres/indexes.txt

raw
1 =================================
2 PostgreSQL specific model indexes
3 =================================
4
5 .. module:: django.contrib.postgres.indexes
6
7 The following are PostgreSQL specific :doc:`indexes </ref/models/indexes>`
8 available from the ``django.contrib.postgres.indexes`` module.
9
10 ``BloomIndex``
11 ==============
12
13 .. class:: BloomIndex(*expressions, length=None, columns=(), **options)
14
15 Creates a bloom_ index.
16
17 To use this index access you need to activate the bloom_ extension on
18 PostgreSQL. You can install it using the
19 :class:`~django.contrib.postgres.operations.BloomExtension` migration
20 operation.
21
22 Provide an integer number of bits from 1 to 4096 to the ``length``
23 parameter to specify the length of each index entry. PostgreSQL's default
24 is 80.
25
26 The ``columns`` argument takes a tuple or list of up to 32 values that are
27 integer number of bits from 1 to 4095.
28
29 .. _bloom: https://www.postgresql.org/docs/current/bloom.html
30
31 ``BrinIndex``
32 =============
33
34 .. class:: BrinIndex(*expressions, autosummarize=None, pages_per_range=None, **options)
35
36 Creates a `BRIN index
37 <https://www.postgresql.org/docs/current/brin.html>`_.
38
39 Set the ``autosummarize`` parameter to ``True`` to enable `automatic
40 summarization`_ to be performed by autovacuum.
41
42 The ``pages_per_range`` argument takes a positive integer.
43
44 .. _automatic summarization: https://www.postgresql.org/docs/current/brin.html#BRIN-OPERATION
45
46 ``BTreeIndex``
47 ==============
48
49 .. class:: BTreeIndex(*expressions, fillfactor=None, deduplicate_items=None, **options)
50
51 Creates a B-Tree index.
52
53 Provide an integer value from 10 to 100 to the fillfactor_ parameter to
54 tune how packed the index pages will be. PostgreSQL's default is 90.
55
56 Provide a boolean value to the deduplicate_items_ parameter to control
57 whether deduplication is enabled. PostgreSQL enables deduplication by
58 default.
59
60 .. versionchanged:: 5.1
61
62 The ``deduplicate_items`` parameter was added.
63
64 .. _fillfactor: https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS
65 .. _deduplicate_items: https://www.postgresql.org/docs/current/btree.html#BTREE-DEDUPLICATION
66
67 ``GinIndex``
68 ============
69
70 .. class:: GinIndex(*expressions, fastupdate=None, gin_pending_list_limit=None, **options)
71
72 Creates a `gin index <https://www.postgresql.org/docs/current/gin.html>`_.
73
74 To use this index on data types not in the `built-in operator classes
75 <https://www.postgresql.org/docs/current/gin.html#GIN-BUILTIN-OPCLASSES>`_,
76 you need to activate the `btree_gin extension
77 <https://www.postgresql.org/docs/current/btree-gin.html>`_ on
78 PostgreSQL. You can install it using the
79 :class:`~django.contrib.postgres.operations.BtreeGinExtension` migration
80 operation.
81
82 Set the ``fastupdate`` parameter to ``False`` to disable the `GIN Fast
83 Update Technique`_ that's enabled by default in PostgreSQL.
84
85 Provide an integer number of kilobytes to the gin_pending_list_limit_
86 parameter to tune the maximum size of the GIN pending list which is used
87 when ``fastupdate`` is enabled.
88
89 .. _GIN Fast Update Technique: https://www.postgresql.org/docs/current/gin.html#GIN-FAST-UPDATE
90 .. _gin_pending_list_limit: https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-GIN-PENDING-LIST-LIMIT
91
92 ``GistIndex``
93 =============
94
95 .. class:: GistIndex(*expressions, buffering=None, fillfactor=None, **options)
96
97 Creates a `GiST index
98 <https://www.postgresql.org/docs/current/gist.html>`_. These indexes are
99 automatically created on spatial fields with :attr:`spatial_index=True
100 <django.contrib.gis.db.models.BaseSpatialField.spatial_index>`. They're
101 also useful on other types, such as
102 :class:`~django.contrib.postgres.fields.HStoreField` or the :ref:`range
103 fields <range-fields>`.
104
105 To use this index on data types not in the built-in `gist operator classes
106 <https://www.postgresql.org/docs/current/gist.html#GIST-BUILTIN-OPCLASSES>`_,
107 you need to activate the `btree_gist extension
108 <https://www.postgresql.org/docs/current/btree-gist.html>`_ on PostgreSQL.
109 You can install it using the
110 :class:`~django.contrib.postgres.operations.BtreeGistExtension` migration
111 operation.
112
113 Set the ``buffering`` parameter to ``True`` or ``False`` to manually enable
114 or disable `buffering build`_ of the index.
115
116 Provide an integer value from 10 to 100 to the fillfactor_ parameter to
117 tune how packed the index pages will be. PostgreSQL's default is 90.
118
119 .. _buffering build: https://www.postgresql.org/docs/current/gist.html#GIST-BUFFERING-BUILD
120 .. _fillfactor: https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS
121
122 ``HashIndex``
123 =============
124
125 .. class:: HashIndex(*expressions, fillfactor=None, **options)
126
127 Creates a hash index.
128
129 Provide an integer value from 10 to 100 to the fillfactor_ parameter to
130 tune how packed the index pages will be. PostgreSQL's default is 90.
131
132 .. _fillfactor: https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS
133
134 ``SpGistIndex``
135 ===============
136
137 .. class:: SpGistIndex(*expressions, fillfactor=None, **options)
138
139 Creates an `SP-GiST index
140 <https://www.postgresql.org/docs/current/spgist.html>`_.
141
142 Provide an integer value from 10 to 100 to the fillfactor_ parameter to
143 tune how packed the index pages will be. PostgreSQL's default is 90.
144
145 .. _fillfactor: https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-STORAGE-PARAMETERS
146
147 ``OpClass()`` expressions
148 =========================
149
150 .. class:: OpClass(expression, name)
151
152 An ``OpClass()`` expression represents the ``expression`` with a custom
153 `operator class`_ that can be used to define functional indexes, functional
154 unique constraints, or exclusion constraints. To use it, you need to add
155 ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`. Set the
156 ``name`` parameter to the name of the `operator class`_.
157
158 For example::
159
160 Index(
161 OpClass(Lower("username"), name="varchar_pattern_ops"),
162 name="lower_username_idx",
163 )
164
165 creates an index on ``Lower('username')`` using ``varchar_pattern_ops``.
166 ::
167
168 UniqueConstraint(
169 OpClass(Upper("description"), name="text_pattern_ops"),
170 name="upper_description_unique",
171 )
172
173 creates a unique constraint on ``Upper('description')`` using
174 ``text_pattern_ops``.
175 ::
176
177 ExclusionConstraint(
178 name="exclude_overlapping_ops",
179 expressions=[
180 (OpClass("circle", name="circle_ops"), RangeOperators.OVERLAPS),
181 ],
182 )
183
184 creates an exclusion constraint on ``circle`` using ``circle_ops``.
185
186 .. _operator class: https://www.postgresql.org/docs/current/indexes-opclass.html