database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-31 22:04:40 +03:00
Code Activity

Add an in-core GiST index opclass for inet/cidr types.

Browse Source 
This operator class can accelerate subnet/supernet tests as well as
btree-equivalent ordered comparisons.  It also handles a new network
operator inet && inet (overlaps, a/k/a "is supernet or subnet of"),
which is expected to be useful in exclusion constraints.

Ideally this opclass would be the default for GiST with inet/cidr data,
but we can't mark it that way until we figure out how to do a more or
less graceful transition from the current situation, in which the
really-completely-bogus inet/cidr opclasses in contrib/btree_gist are
marked as default.  Having the opclass in core and not default is better
than not having it at all, though.

While at it, add new documentation sections to allow us to officially
document GiST/GIN/SP-GiST opclasses, something there was never a clear
place to do before.  I filled these in with some simple tables listing
the existing opclasses and the operators they support, but there's
certainly scope to put more information there.

Emre Hasegeli, reviewed by Andreas Karlsson, further hacking by me
This commit is contained in:
Tom Lane
2014-04-08 15:46:14 -04:00
parent 02f65617ea
commit f23a5630eb
21 changed files with 1839 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
doc/src/sgml/func.sgml
View File

@ -8434,8 +8434,9 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
<xref linkend="cidr-inet-operators-table"> shows the operators
available for the <type>cidr</type> and <type>inet</type> types.
The operators <literal>&lt;&lt;</literal>,
<literal>&lt;&lt;=</literal>, <literal>&gt;&gt;</literal>, and
<literal>&gt;&gt;=</literal> test for subnet inclusion. They
<literal>&lt;&lt;=</literal>, <literal>&gt;&gt;</literal>,
<literal>&gt;&gt;=</literal>, and <literal>&amp;&amp;</literal>
test for subnet inclusion. They
consider only the network parts of the two addresses (ignoring any
host part) and determine whether one network is identical to
or a subnet of the other.
@ -8484,12 +8485,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
</row>
<row>
<entry> <literal>&lt;&lt;</literal> </entry>
<entry>is contained within</entry>
<entry>is contained by</entry>
<entry><literal>inet '192.168.1.5' &lt;&lt; inet '192.168.1/24'</literal></entry>
</row>
<row>
<entry> <literal>&lt;&lt;=</literal> </entry>
<entry>is contained within or equals</entry>
<entry>is contained by or equals</entry>
<entry><literal>inet '192.168.1/24' &lt;&lt;= inet '192.168.1/24'</literal></entry>
</row>
<row>
@ -8502,6 +8503,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
<entry>contains or equals</entry>
<entry><literal>inet '192.168.1/24' &gt;&gt;= inet '192.168.1/24'</literal></entry>
</row>
<row>
<entry> <literal>&amp;&amp;</literal> </entry>
<entry>contains or is contained by</entry>
<entry><literal>inet '192.168.1/24' &amp;&amp; inet '192.168.1.80/28'</literal></entry>
</row>
<row>
<entry> <literal>~</literal> </entry>
<entry>bitwise NOT</entry>

359
doc/src/sgml/gin.sgml
View File

@ -62,6 +62,365 @@
</para>
</sect1>
<sect1 id="gin-builtin-opclasses">
<title>Built-in Operator Classes</title>
<para>
The core <productname>PostgreSQL</> distribution
includes the <acronym>GIN</acronym> operator classes shown in
<xref linkend="gin-builtin-opclasses-table">.
(Some of the optional modules described in <xref linkend="contrib">
provide additional <acronym>GIN</acronym> operator classes.)
</para>
<table id="gin-builtin-opclasses-table">
<title>Built-in <acronym>GIN</acronym> Operator Classes</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Indexed Data Type</entry>
<entry>Indexable Operators</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>_abstime_ops</></entry>
<entry><type>abstime[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_bit_ops</></entry>
<entry><type>bit[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_bool_ops</></entry>
<entry><type>boolean[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_bpchar_ops</></entry>
<entry><type>character[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_bytea_ops</></entry>
<entry><type>bytea[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_char_ops</></entry>
<entry><type>"char"[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_cidr_ops</></entry>
<entry><type>cidr[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_date_ops</></entry>
<entry><type>date[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_float4_ops</></entry>
<entry><type>float4[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_float8_ops</></entry>
<entry><type>float8[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_inet_ops</></entry>
<entry><type>inet[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_int2_ops</></entry>
<entry><type>smallint[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_int4_ops</></entry>
<entry><type>integer[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_int8_ops</></entry>
<entry><type>bigint[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_interval_ops</></entry>
<entry><type>interval[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_macaddr_ops</></entry>
<entry><type>macaddr[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_money_ops</></entry>
<entry><type>money[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_name_ops</></entry>
<entry><type>name[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_numeric_ops</></entry>
<entry><type>numeric[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_oid_ops</></entry>
<entry><type>oid[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_oidvector_ops</></entry>
<entry><type>oidvector[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_reltime_ops</></entry>
<entry><type>reltime[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_text_ops</></entry>
<entry><type>text[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_time_ops</></entry>
<entry><type>time[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_timestamp_ops</></entry>
<entry><type>timestamp[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_timestamptz_ops</></entry>
<entry><type>timestamp with time zone[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_timetz_ops</></entry>
<entry><type>time with time zone[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_tinterval_ops</></entry>
<entry><type>tinterval[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_varbit_ops</></entry>
<entry><type>bit varying[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>_varchar_ops</></entry>
<entry><type>character varying[]</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&lt;@</>
<literal>=</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>jsonb_ops</></entry>
<entry><type>jsonb</></entry>
<entry>
<literal>?</>
<literal>?&amp;</>
<literal>?|</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>jsonb_hash_ops</></entry>
<entry><type>jsonb</></entry>
<entry>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>tsvector_ops</></entry>
<entry><type>tsvector</></entry>
<entry>
<literal>@@</>
<literal>@@@</>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Of the two operator classes for type <type>jsonb</>, <literal>jsonb_ops</>
is the default. <literal>jsonb_hash_ops</> supports fewer operators but
will work with larger indexed values than <literal>jsonb_ops</> can support.
</para>
</sect1>
<sect1 id="gin-extensibility">
<title>Extensibility</title>

178
doc/src/sgml/gist.sgml
View File

@ -40,6 +40,184 @@
</sect1>
<sect1 id="gist-builtin-opclasses">
<title>Built-in Operator Classes</title>
<para>
The core <productname>PostgreSQL</> distribution
includes the <acronym>GiST</acronym> operator classes shown in
<xref linkend="gist-builtin-opclasses-table">.
(Some of the optional modules described in <xref linkend="contrib">
provide additional <acronym>GiST</acronym> operator classes.)
</para>
<table id="gist-builtin-opclasses-table">
<title>Built-in <acronym>GiST</acronym> Operator Classes</title>
<tgroup cols="4">
<thead>
<row>
<entry>Name</entry>
<entry>Indexed Data Type</entry>
<entry>Indexable Operators</entry>
<entry>Ordering Operators</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>box_ops</></entry>
<entry><type>box</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&amp;&gt;</>
<literal>&amp;&lt;</>
<literal>&amp;&lt;|</>
<literal>&gt;&gt;</>
<literal>&lt;&lt;</>
<literal>&lt;&lt;|</>
<literal>&lt;@</>
<literal>@&gt;</>
<literal>@</>
<literal>|&amp;&gt;</>
<literal>|&gt;&gt;</>
<literal>~</>
<literal>~=</>
</entry>
<entry>
</entry>
</row>
<row>
<entry><literal>circle_ops</></entry>
<entry><type>circle</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&amp;&gt;</>
<literal>&amp;&lt;</>
<literal>&amp;&lt;|</>
<literal>&gt;&gt;</>
<literal>&lt;&lt;</>
<literal>&lt;&lt;|</>
<literal>&lt;@</>
<literal>@&gt;</>
<literal>@</>
<literal>|&amp;&gt;</>
<literal>|&gt;&gt;</>
<literal>~</>
<literal>~=</>
</entry>
<entry>
</entry>
</row>
<row>
<entry><literal>inet_ops</></entry>
<entry><type>inet</>, <type>cidr</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&gt;&gt;</>
<literal>&gt;&gt;=</>
<literal>&gt;</>
<literal>&gt;=</>
<literal>&lt;&gt;</>
<literal>&lt;&lt;</>
<literal>&lt;&lt;=</>
<literal>&lt;</>
<literal>&lt;=</>
<literal>=</>
</entry>
<entry>
</entry>
</row>
<row>
<entry><literal>point_ops</></entry>
<entry><type>point</></entry>
<entry>
<literal>&gt;&gt;</>
<literal>&gt;^</>
<literal>&lt;&lt;</>
<literal>&lt;@</>
<literal>&lt;@</>
<literal>&lt;@</>
<literal>&lt;^</>
<literal>~=</>
</entry>
<entry>
<literal>&lt;-&gt;</>
</entry>
</row>
<row>
<entry><literal>poly_ops</></entry>
<entry><type>polygon</></entry>
<entry>
<literal>&amp;&amp;</>
<literal>&amp;&gt;</>
<literal>&amp;&lt;</>
<literal>&amp;&lt;|</>
<literal>&gt;&gt;</>
<literal>&lt;&lt;</>
<literal>&lt;&lt;|</>
<literal>&lt;@</>
<literal>@&gt;</>
<literal>@</>
<literal>|&amp;&gt;</>
<literal>|&gt;&gt;</>
<literal>~</>
<literal>~=</>
</entry>
<entry>
</entry>
</row>
<row>
<entry><literal>range_ops</></entry>
<entry>any range type</entry>
<entry>
<literal>&amp;&amp;</>
<literal>&amp;&gt;</>
<literal>&amp;&lt;</>
<literal>&gt;&gt;</>
<literal>&lt;&lt;</>
<literal>&lt;@</>
<literal>-|-</>
<literal>=</>
<literal>@&gt;</>
<literal>@&gt;</>
</entry>
<entry>
</entry>
</row>
<row>
<entry><literal>tsquery_ops</></entry>
<entry><type>tsquery</></entry>
<entry>
<literal>&lt;@</>
<literal>@&gt;</>
</entry>
<entry>
</entry>
</row>
<row>
<entry><literal>tsvector_ops</></entry>
<entry><type>tsvector</></entry>
<entry>
<literal>@@</>
</entry>
<entry>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
For historical reasons, the <literal>inet_ops</> operator class is
not the default class for types <type>inet</> and <type>cidr</>.
To use it, mention the class name in <command>CREATE INDEX</>,
for example
<programlisting>
CREATE INDEX ON my_table USING gist (my_inet_column inet_ops);
</programlisting>
</para>
</sect1>
<sect1 id="gist-extensibility">
<title>Extensibility</title>

28
doc/src/sgml/indices.sgml
View File

@ -239,6 +239,8 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
(See <xref linkend="functions-geometry"> for the meaning of
these operators.)
The GiST operator classes included in the standard distribution are
documented in <xref linkend="gist-builtin-opclasses-table">.
Many other GiST operator
classes are available in the <literal>contrib</> collection or as separate
projects. For more information see <xref linkend="GiST">.
@ -253,6 +255,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
</programlisting>
which finds the ten places closest to a given target point. The ability
to do this is again dependent on the particular operator class being used.
In <xref linkend="gist-builtin-opclasses-table">, operators that can be
used in this way are listed in the column <quote>Ordering Operators</>.
</para>
<para>
@ -283,6 +287,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
(See <xref linkend="functions-geometry"> for the meaning of
these operators.)
The SP-GiST operator classes included in the standard distribution are
documented in <xref linkend="spgist-builtin-opclasses-table">.
For more information see <xref linkend="SPGiST">.
</para>
@ -314,6 +320,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
(See <xref linkend="functions-array"> for the meaning of
these operators.)
The GIN operator classes included in the standard distribution are
documented in <xref linkend="gin-builtin-opclasses-table">.
Many other GIN operator
classes are available in the <literal>contrib</> collection or as separate
projects. For more information see <xref linkend="GIN">.
@ -1003,7 +1011,9 @@ CREATE INDEX test_index ON test_table (col varchar_pattern_ops);
<programlisting>
SELECT am.amname AS index_method,
opc.opcname AS opclass_name
opc.opcname AS opclass_name,
opc.opcintype::regtype AS indexed_type,
opc.opcdefault AS is_default
FROM pg_am am, pg_opclass opc
WHERE opc.opcmethod = am.oid
ORDER BY index_method, opclass_name;
@ -1020,6 +1030,22 @@ SELECT am.amname AS index_method,
associated with any single class within the family.
</para>
<para>
This expanded version of the previous query shows the operator family
each operator class belongs to:
<programlisting>
SELECT am.amname AS index_method,
opc.opcname AS opclass_name,
opf.opfname AS opfamily_name,
opc.opcintype::regtype AS indexed_type,
opc.opcdefault AS is_default
FROM pg_am am, pg_opclass opc, pg_opfamily opf
WHERE opc.opcmethod = am.oid AND
opc.opcfamily = opf.oid
ORDER BY index_method, opclass_name;
</programlisting>
</para>
<para>
This query shows all defined operator families and all
the operators included in each family:

87
doc/src/sgml/spgist.sgml
View File

@ -53,6 +53,93 @@
</sect1>
<sect1 id="spgist-builtin-opclasses">
<title>Built-in Operator Classes</title>
<para>
The core <productname>PostgreSQL</> distribution
includes the <acronym>SP-GiST</acronym> operator classes shown in
<xref linkend="spgist-builtin-opclasses-table">.
</para>
<table id="spgist-builtin-opclasses-table">
<title>Built-in <acronym>SP-GiST</acronym> Operator Classes</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Indexed Data Type</entry>
<entry>Indexable Operators</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>kd_point_ops</></entry>
<entry><type>point</></entry>
<entry>
<literal>&lt;&lt;</>
<literal>&lt;@</>
<literal>&lt;^</>
<literal>&gt;&gt;</>
<literal>&gt;^</>
<literal>~=</>
</entry>
</row>
<row>
<entry><literal>quad_point_ops</></entry>
<entry><type>point</></entry>
<entry>
<literal>&lt;&lt;</>
<literal>&lt;@</>
<literal>&lt;^</>
<literal>&gt;&gt;</>
<literal>&gt;^</>
<literal>~=</>
</entry>
</row>
<row>
<entry><literal>range_ops</></entry>
<entry>any range type</entry>
<entry>
<literal>&amp;&amp;</>
<literal>&amp;&lt;</>
<literal>&amp;&gt;</>
<literal>-|-</>
<literal>&lt;&lt;</>
<literal>&lt;@</>
<literal>=</>
<literal>&gt;&gt;</>
<literal>@&gt;</>
</entry>
</row>
<row>
<entry><literal>text_ops</></entry>
<entry><type>text</></entry>
<entry>
<literal>&lt;</>
<literal>&lt;=</>
<literal>=</>
<literal>&gt;</>
<literal>&gt;=</>
<literal>~&lt;=~</>
<literal>~&lt;~</>
<literal>~&gt;=~</>
<literal>~&gt;~</>
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Of the two operator classes for type <type>point</>,
<literal>quad_point_ops</> is the default. <literal>kd_point_ops</>
supports the same operators but uses a different index data structure which
may offer better performance in some applications.
</para>
</sect1>
<sect1 id="spgist-extensibility">
<title>Extensibility</title>