Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit b7412e2

Browse files
committed
Doc: add a bit to indices.sgml about what is an indexable clause.
We didn't explain this clearly until somewhere deep in the "Extending SQL" chapter, but really it ought to be mentioned in the introductory material too. Discussion: https://postgr.es/m/4097442.1694967650@sss.pgh.pa.us
1 parent 3c9d9ac commit b7412e2

File tree

1 file changed

+34
-1
lines changed

1 file changed

+34
-1
lines changed

doc/src/sgml/indices.sgml

+34-1
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,39 @@ CREATE INDEX test1_id_index ON test1 (id);
9090
also significantly speed up queries with joins.
9191
</para>
9292

93+
<para>
94+
In general, <productname>PostgreSQL</productname> indexes can be used
95+
to optimize queries that contain one or more <literal>WHERE</literal>
96+
or <literal>JOIN</literal> clauses of the form
97+
98+
<synopsis>
99+
<replaceable>indexed-column</replaceable> <replaceable>indexable-operator</replaceable> <replaceable>comparison-value</replaceable>
100+
</synopsis>
101+
102+
Here, the <replaceable>indexed-column</replaceable> is whatever
103+
column or expression the index has been defined on.
104+
The <replaceable>indexable-operator</replaceable> is an operator that
105+
is a member of the index's <firstterm>operator class</firstterm> for
106+
the indexed column. (More details about that appear below.)
107+
And the <replaceable>comparison-value</replaceable> can be any
108+
expression that is not volatile and does not reference the index's
109+
table.
110+
</para>
111+
112+
<para>
113+
In some cases the query planner can extract an indexable clause of
114+
this form from another SQL construct. A simple example is that if
115+
the original clause was
116+
117+
<synopsis>
118+
<replaceable>comparison-value</replaceable> <replaceable>operator</replaceable> <replaceable>indexed-column</replaceable>
119+
</synopsis>
120+
121+
then it can be flipped around into indexable form if the
122+
original <replaceable>operator</replaceable> has a commutator
123+
operator that is a member of the index's operator class.
124+
</para>
125+
93126
<para>
94127
Creating an index on a large table can take a long time. By default,
95128
<productname>PostgreSQL</productname> allows reads (<command>SELECT</command> statements) to occur
@@ -120,7 +153,7 @@ CREATE INDEX test1_id_index ON test1 (id);
120153
B-tree, Hash, GiST, SP-GiST, GIN, BRIN, and the extension <link
121154
linkend="bloom">bloom</link>.
122155
Each index type uses a different
123-
algorithm that is best suited to different types of queries.
156+
algorithm that is best suited to different types of indexable clauses.
124157
By default, the <link linkend="sql-createindex"><command>CREATE
125158
INDEX</command></link> command creates
126159
B-tree indexes, which fit the most common situations.

0 commit comments

Comments
 (0)