2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/intarray.sgml -->
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2011-05-08 04:29:20 +02:00
|
|
|
<sect1 id="intarray" xreflabel="intarray">
|
2007-11-11 00:30:46 +01:00
|
|
|
<title>intarray</title>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<indexterm zone="intarray">
|
|
|
|
<primary>intarray</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The <filename>intarray</filename> module provides a number of useful functions
|
2011-01-09 06:39:21 +01:00
|
|
|
and operators for manipulating null-free arrays of integers.
|
2007-12-10 06:32:51 +01:00
|
|
|
There is also support for indexed searches using some of the operators.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
|
|
|
|
2011-01-09 06:39:21 +01:00
|
|
|
<para>
|
|
|
|
All of these operations will throw an error if a supplied array contains any
|
|
|
|
NULL elements.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Many of these operations are only sensible for one-dimensional arrays.
|
|
|
|
Although they will accept input arrays of more dimensions, the data is
|
|
|
|
treated as though it were a linear array in storage order.
|
|
|
|
</para>
|
|
|
|
|
2020-02-13 21:02:35 +01:00
|
|
|
<para>
|
|
|
|
This module is considered <quote>trusted</quote>, that is, it can be
|
|
|
|
installed by non-superusers who have <literal>CREATE</literal> privilege
|
|
|
|
on the current database.
|
|
|
|
</para>
|
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<sect2>
|
2017-10-09 03:44:17 +02:00
|
|
|
<title><filename>intarray</filename> Functions and Operators</title>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2011-05-04 19:24:07 +02:00
|
|
|
<para>
|
|
|
|
The functions provided by the <filename>intarray</filename> module
|
2017-11-23 15:39:47 +01:00
|
|
|
are shown in <xref linkend="intarray-func-table"/>, the operators
|
|
|
|
in <xref linkend="intarray-op-table"/>.
|
2011-05-04 19:24:07 +02:00
|
|
|
</para>
|
|
|
|
|
2007-12-10 06:32:51 +01:00
|
|
|
<table id="intarray-func-table">
|
2017-10-09 03:44:17 +02:00
|
|
|
<title><filename>intarray</filename> Functions</title>
|
2020-05-07 20:25:18 +02:00
|
|
|
<tgroup cols="1">
|
|
|
|
<thead>
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
Function
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Description
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Example(s)
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
</thead>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2020-05-07 20:25:18 +02:00
|
|
|
<tbody>
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<indexterm><primary>icount</primary></indexterm>
|
|
|
|
<function>icount</function> ( <type>integer[]</type> )
|
|
|
|
<returnvalue>integer</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Returns the number of elements in the array.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literal>icount('{1,2,3}'::integer[])</literal>
|
|
|
|
<returnvalue>3</returnvalue>
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2020-05-07 20:25:18 +02:00
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<indexterm><primary>sort</primary></indexterm>
|
|
|
|
<function>sort</function> ( <type>integer[]</type>, <parameter>dir</parameter> <type>text</type> )
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Sorts the array in either ascending or descending order.
|
|
|
|
<parameter>dir</parameter> must be <literal>asc</literal>
|
|
|
|
or <literal>desc</literal>.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literal>sort('{1,3,2}'::integer[], 'desc')</literal>
|
|
|
|
<returnvalue>{3,2,1}</returnvalue>
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<function>sort</function> ( <type>integer[]</type> )
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para role="func_signature">
|
|
|
|
<indexterm><primary>sort_asc</primary></indexterm>
|
|
|
|
<function>sort_asc</function> ( <type>integer[]</type> )
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Sorts in ascending order.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literal>sort(array[11,77,44])</literal>
|
|
|
|
<returnvalue>{11,44,77}</returnvalue>
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<indexterm><primary>sort_desc</primary></indexterm>
|
|
|
|
<function>sort_desc</function> ( <type>integer[]</type> )
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Sorts in descending order.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literal>sort_desc(array[11,77,44])</literal>
|
|
|
|
<returnvalue>{77,44,11}</returnvalue>
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<indexterm><primary>uniq</primary></indexterm>
|
|
|
|
<function>uniq</function> ( <type>integer[]</type> )
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Removes adjacent duplicates.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literal>uniq(sort('{1,2,3,2,1}'::integer[]))</literal>
|
|
|
|
<returnvalue>{1,2,3}</returnvalue>
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<indexterm><primary>idx</primary></indexterm>
|
|
|
|
<function>idx</function> ( <type>integer[]</type>, <parameter>item</parameter> <type>integer</type> )
|
|
|
|
<returnvalue>integer</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Returns index of the first array element
|
|
|
|
matching <parameter>item</parameter>, or 0 if no match.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literal>idx(array[11,22,33,22,11], 22)</literal>
|
|
|
|
<returnvalue>2</returnvalue>
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<indexterm><primary>subarray</primary></indexterm>
|
|
|
|
<function>subarray</function> ( <type>integer[]</type>, <parameter>start</parameter> <type>integer</type>, <parameter>len</parameter> <type>integer</type> )
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Extracts the portion of the array starting at
|
|
|
|
position <parameter>start</parameter>, with <parameter>len</parameter>
|
|
|
|
elements.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literal>subarray('{1,2,3,2,1}'::integer[], 2, 3)</literal>
|
|
|
|
<returnvalue>{2,3,2}</returnvalue>
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<function>subarray</function> ( <type>integer[]</type>, <parameter>start</parameter> <type>integer</type> )
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Extracts the portion of the array starting at
|
|
|
|
position <parameter>start</parameter>.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literal>subarray('{1,2,3,2,1}'::integer[], 2)</literal>
|
|
|
|
<returnvalue>{2,3,2,1}</returnvalue>
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<indexterm><primary>intset</primary></indexterm>
|
|
|
|
<function>intset</function> ( <type>integer</type> )
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Makes a single-element array.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literal>intset(42)</literal>
|
|
|
|
<returnvalue>{42}</returnvalue>
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
2007-12-10 06:32:51 +01:00
|
|
|
</tbody>
|
|
|
|
</tgroup>
|
|
|
|
</table>
|
|
|
|
|
|
|
|
<table id="intarray-op-table">
|
2017-10-09 03:44:17 +02:00
|
|
|
<title><filename>intarray</filename> Operators</title>
|
2020-05-07 20:25:18 +02:00
|
|
|
<tgroup cols="1">
|
|
|
|
<thead>
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
Operator
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Description
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
</thead>
|
|
|
|
|
|
|
|
<tbody>
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>&&</literal> <type>integer[]</type>
|
|
|
|
<returnvalue>boolean</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Do arrays overlap (have at least one element in common)?
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>@></literal> <type>integer[]</type>
|
|
|
|
<returnvalue>boolean</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Does left array contain right array?
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal><@</literal> <type>integer[]</type>
|
|
|
|
<returnvalue>boolean</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Is left array contained in right array?
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type></type> <literal>#</literal> <type>integer[]</type>
|
|
|
|
<returnvalue>integer</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Returns the number of elements in the array.
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2020-05-07 20:25:18 +02:00
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>#</literal> <type>integer</type>
|
|
|
|
<returnvalue>integer</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Returns index of the first array element
|
|
|
|
matching the right argument, or 0 if no match.
|
|
|
|
(Same as <function>idx</function> function.)
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>+</literal> <type>integer</type>
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Adds element to end of array.
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>+</literal> <type>integer[]</type>
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Concatenates the arrays.
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>-</literal> <type>integer</type>
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Removes entries matching the right argument from the array.
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>-</literal> <type>integer[]</type>
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Removes elements of the right array from the left array.
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>|</literal> <type>integer</type>
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Computes the union of the arguments.
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>|</literal> <type>integer[]</type>
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Computes the union of the arguments.
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>&</literal> <type>integer[]</type>
|
|
|
|
<returnvalue>integer[]</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Computes the intersection of the arguments.
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>integer[]</type> <literal>@@</literal> <type>query_int</type>
|
|
|
|
<returnvalue>boolean</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Does array satisfy query? (see below)
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry role="func_table_entry"><para role="func_signature">
|
|
|
|
<type>query_int</type> <literal>~~</literal> <type>integer[]</type>
|
|
|
|
<returnvalue>boolean</returnvalue>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Does array satisfy query? (commutator of <literal>@@</literal>)
|
|
|
|
</para></entry>
|
|
|
|
</row>
|
2007-11-11 00:30:46 +01:00
|
|
|
</tbody>
|
|
|
|
</tgroup>
|
|
|
|
</table>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2009-06-07 22:09:34 +02:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The operators <literal>&&</literal>, <literal>@></literal> and
|
|
|
|
<literal><@</literal> are equivalent to <productname>PostgreSQL</productname>'s built-in
|
2011-01-09 06:39:21 +01:00
|
|
|
operators of the same names, except that they work only on integer arrays
|
|
|
|
that do not contain nulls, while the built-in operators work for any array
|
|
|
|
type. This restriction makes them faster than the built-in operators
|
|
|
|
in many cases.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The <literal>@@</literal> and <literal>~~</literal> operators test whether an array
|
|
|
|
satisfies a <firstterm>query</firstterm>, which is expressed as a value of a
|
|
|
|
specialized data type <type>query_int</type>. A <firstterm>query</firstterm>
|
2007-12-10 06:32:51 +01:00
|
|
|
consists of integer values that are checked against the elements of
|
2017-10-09 03:44:17 +02:00
|
|
|
the array, possibly combined using the operators <literal>&</literal>
|
|
|
|
(AND), <literal>|</literal> (OR), and <literal>!</literal> (NOT). Parentheses
|
2007-12-10 06:32:51 +01:00
|
|
|
can be used as needed. For example,
|
2017-10-09 03:44:17 +02:00
|
|
|
the query <literal>1&(2|3)</literal> matches arrays that contain 1
|
2007-12-10 06:32:51 +01:00
|
|
|
and also contain either 2 or 3.
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Index Support</title>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<filename>intarray</filename> provides index support for the
|
2020-08-08 23:26:29 +02:00
|
|
|
<literal>&&</literal>, <literal>@></literal>,
|
2017-10-09 03:44:17 +02:00
|
|
|
and <literal>@@</literal> operators, as well as regular array equality.
|
2007-12-10 06:32:51 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2020-04-01 13:42:17 +02:00
|
|
|
Two parameterized GiST index operator classes are provided:
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>gist__int_ops</literal> (used by default) is suitable for
|
2009-03-18 21:18:18 +01:00
|
|
|
small- to medium-size data sets, while
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>gist__intbig_ops</literal> uses a larger signature and is more
|
2009-03-18 21:18:18 +01:00
|
|
|
suitable for indexing large data sets (i.e., columns containing
|
|
|
|
a large number of distinct array values).
|
2009-04-05 02:40:35 +02:00
|
|
|
The implementation uses an RD-tree data structure with
|
|
|
|
built-in lossy compression.
|
2007-12-10 06:32:51 +01:00
|
|
|
</para>
|
2020-05-07 20:25:18 +02:00
|
|
|
|
Implement operator class parameters
PostgreSQL provides set of template index access methods, where opclasses have
much freedom in the semantics of indexing. These index AMs are GiST, GIN,
SP-GiST and BRIN. There opclasses define representation of keys, operations on
them and supported search strategies. So, it's natural that opclasses may be
faced some tradeoffs, which require user-side decision. This commit implements
opclass parameters allowing users to set some values, which tell opclass how to
index the particular dataset.
This commit doesn't introduce new storage in system catalog. Instead it uses
pg_attribute.attoptions, which is used for table column storage options but
unused for index attributes.
In order to evade changing signature of each opclass support function, we
implement unified way to pass options to opclass support functions. Options
are set to fn_expr as the constant bytea expression. It's possible due to the
fact that opclass support functions are executed outside of expressions, so
fn_expr is unused for them.
This commit comes with some examples of opclass options usage. We parametrize
signature length in GiST. That applies to multiple opclasses: tsvector_ops,
gist__intbig_ops, gist_ltree_ops, gist__ltree_ops, gist_trgm_ops and
gist_hstore_ops. Also we parametrize maximum number of integer ranges for
gist__int_ops. However, the main future usage of this feature is expected
to be json, where users would be able to specify which way to index particular
json parts.
Catversion is bumped.
Discussion: https://postgr.es/m/d22c3a18-31c7-1879-fc11-4c1ce2f5e5af%40postgrespro.ru
Author: Nikita Glukhov, revised by me
Reviwed-by: Nikolay Shaplov, Robert Haas, Tom Lane, Tomas Vondra, Alvaro Herrera
2020-03-30 18:17:11 +02:00
|
|
|
<para>
|
2020-04-01 13:42:17 +02:00
|
|
|
<literal>gist__int_ops</literal> approximates an integer set as an array of
|
|
|
|
integer ranges. Its optional integer parameter <literal>numranges</literal>
|
|
|
|
determines the maximum number of ranges in
|
|
|
|
one index key. The default value of <literal>numranges</literal> is 100.
|
Implement operator class parameters
PostgreSQL provides set of template index access methods, where opclasses have
much freedom in the semantics of indexing. These index AMs are GiST, GIN,
SP-GiST and BRIN. There opclasses define representation of keys, operations on
them and supported search strategies. So, it's natural that opclasses may be
faced some tradeoffs, which require user-side decision. This commit implements
opclass parameters allowing users to set some values, which tell opclass how to
index the particular dataset.
This commit doesn't introduce new storage in system catalog. Instead it uses
pg_attribute.attoptions, which is used for table column storage options but
unused for index attributes.
In order to evade changing signature of each opclass support function, we
implement unified way to pass options to opclass support functions. Options
are set to fn_expr as the constant bytea expression. It's possible due to the
fact that opclass support functions are executed outside of expressions, so
fn_expr is unused for them.
This commit comes with some examples of opclass options usage. We parametrize
signature length in GiST. That applies to multiple opclasses: tsvector_ops,
gist__intbig_ops, gist_ltree_ops, gist__ltree_ops, gist_trgm_ops and
gist_hstore_ops. Also we parametrize maximum number of integer ranges for
gist__int_ops. However, the main future usage of this feature is expected
to be json, where users would be able to specify which way to index particular
json parts.
Catversion is bumped.
Discussion: https://postgr.es/m/d22c3a18-31c7-1879-fc11-4c1ce2f5e5af%40postgrespro.ru
Author: Nikita Glukhov, revised by me
Reviwed-by: Nikolay Shaplov, Robert Haas, Tom Lane, Tomas Vondra, Alvaro Herrera
2020-03-30 18:17:11 +02:00
|
|
|
Valid values are between 1 and 253. Using larger arrays as GiST index
|
2020-04-01 14:07:53 +02:00
|
|
|
keys leads to a more precise search (scanning a smaller fraction of the index and
|
2020-04-01 13:42:17 +02:00
|
|
|
fewer heap pages), at the cost of a larger index.
|
Implement operator class parameters
PostgreSQL provides set of template index access methods, where opclasses have
much freedom in the semantics of indexing. These index AMs are GiST, GIN,
SP-GiST and BRIN. There opclasses define representation of keys, operations on
them and supported search strategies. So, it's natural that opclasses may be
faced some tradeoffs, which require user-side decision. This commit implements
opclass parameters allowing users to set some values, which tell opclass how to
index the particular dataset.
This commit doesn't introduce new storage in system catalog. Instead it uses
pg_attribute.attoptions, which is used for table column storage options but
unused for index attributes.
In order to evade changing signature of each opclass support function, we
implement unified way to pass options to opclass support functions. Options
are set to fn_expr as the constant bytea expression. It's possible due to the
fact that opclass support functions are executed outside of expressions, so
fn_expr is unused for them.
This commit comes with some examples of opclass options usage. We parametrize
signature length in GiST. That applies to multiple opclasses: tsvector_ops,
gist__intbig_ops, gist_ltree_ops, gist__ltree_ops, gist_trgm_ops and
gist_hstore_ops. Also we parametrize maximum number of integer ranges for
gist__int_ops. However, the main future usage of this feature is expected
to be json, where users would be able to specify which way to index particular
json parts.
Catversion is bumped.
Discussion: https://postgr.es/m/d22c3a18-31c7-1879-fc11-4c1ce2f5e5af%40postgrespro.ru
Author: Nikita Glukhov, revised by me
Reviwed-by: Nikolay Shaplov, Robert Haas, Tom Lane, Tomas Vondra, Alvaro Herrera
2020-03-30 18:17:11 +02:00
|
|
|
</para>
|
2020-05-07 20:25:18 +02:00
|
|
|
|
Implement operator class parameters
PostgreSQL provides set of template index access methods, where opclasses have
much freedom in the semantics of indexing. These index AMs are GiST, GIN,
SP-GiST and BRIN. There opclasses define representation of keys, operations on
them and supported search strategies. So, it's natural that opclasses may be
faced some tradeoffs, which require user-side decision. This commit implements
opclass parameters allowing users to set some values, which tell opclass how to
index the particular dataset.
This commit doesn't introduce new storage in system catalog. Instead it uses
pg_attribute.attoptions, which is used for table column storage options but
unused for index attributes.
In order to evade changing signature of each opclass support function, we
implement unified way to pass options to opclass support functions. Options
are set to fn_expr as the constant bytea expression. It's possible due to the
fact that opclass support functions are executed outside of expressions, so
fn_expr is unused for them.
This commit comes with some examples of opclass options usage. We parametrize
signature length in GiST. That applies to multiple opclasses: tsvector_ops,
gist__intbig_ops, gist_ltree_ops, gist__ltree_ops, gist_trgm_ops and
gist_hstore_ops. Also we parametrize maximum number of integer ranges for
gist__int_ops. However, the main future usage of this feature is expected
to be json, where users would be able to specify which way to index particular
json parts.
Catversion is bumped.
Discussion: https://postgr.es/m/d22c3a18-31c7-1879-fc11-4c1ce2f5e5af%40postgrespro.ru
Author: Nikita Glukhov, revised by me
Reviwed-by: Nikolay Shaplov, Robert Haas, Tom Lane, Tomas Vondra, Alvaro Herrera
2020-03-30 18:17:11 +02:00
|
|
|
<para>
|
2020-04-01 13:42:17 +02:00
|
|
|
<literal>gist__intbig_ops</literal> approximates an integer set as a bitmap
|
|
|
|
signature. Its optional integer parameter <literal>siglen</literal>
|
|
|
|
determines the signature length in bytes.
|
|
|
|
The default signature length is 16 bytes. Valid values of signature length
|
|
|
|
are between 1 and 2024 bytes. Longer signatures lead to a more precise
|
|
|
|
search (scanning a smaller fraction of the index and fewer heap pages), at
|
|
|
|
the cost of a larger index.
|
Implement operator class parameters
PostgreSQL provides set of template index access methods, where opclasses have
much freedom in the semantics of indexing. These index AMs are GiST, GIN,
SP-GiST and BRIN. There opclasses define representation of keys, operations on
them and supported search strategies. So, it's natural that opclasses may be
faced some tradeoffs, which require user-side decision. This commit implements
opclass parameters allowing users to set some values, which tell opclass how to
index the particular dataset.
This commit doesn't introduce new storage in system catalog. Instead it uses
pg_attribute.attoptions, which is used for table column storage options but
unused for index attributes.
In order to evade changing signature of each opclass support function, we
implement unified way to pass options to opclass support functions. Options
are set to fn_expr as the constant bytea expression. It's possible due to the
fact that opclass support functions are executed outside of expressions, so
fn_expr is unused for them.
This commit comes with some examples of opclass options usage. We parametrize
signature length in GiST. That applies to multiple opclasses: tsvector_ops,
gist__intbig_ops, gist_ltree_ops, gist__ltree_ops, gist_trgm_ops and
gist_hstore_ops. Also we parametrize maximum number of integer ranges for
gist__int_ops. However, the main future usage of this feature is expected
to be json, where users would be able to specify which way to index particular
json parts.
Catversion is bumped.
Discussion: https://postgr.es/m/d22c3a18-31c7-1879-fc11-4c1ce2f5e5af%40postgrespro.ru
Author: Nikita Glukhov, revised by me
Reviwed-by: Nikolay Shaplov, Robert Haas, Tom Lane, Tomas Vondra, Alvaro Herrera
2020-03-30 18:17:11 +02:00
|
|
|
</para>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
There is also a non-default GIN operator class
|
2020-08-08 23:26:29 +02:00
|
|
|
<literal>gin__int_ops</literal>, which supports these operators as well
|
|
|
|
as <literal><@</literal>.
|
2007-12-10 06:32:51 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The choice between GiST and GIN indexing depends on the relative
|
|
|
|
performance characteristics of GiST and GIN, which are discussed elsewhere.
|
|
|
|
</para>
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Example</title>
|
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2017-10-09 03:44:17 +02:00
|
|
|
-- a message can be in one or more <quote>sections</quote>
|
2007-12-10 06:32:51 +01:00
|
|
|
CREATE TABLE message (mid INT PRIMARY KEY, sections INT[], ...);
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2020-09-09 17:53:39 +02:00
|
|
|
-- create specialized index with signature length of 32 bytes
|
2021-06-04 03:07:12 +02:00
|
|
|
CREATE INDEX message_rdtree_idx ON message USING GIST (sections gist__intbig_ops (siglen = 32));
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2007-12-10 06:32:51 +01:00
|
|
|
-- select messages in section 1 OR 2 - OVERLAP operator
|
|
|
|
SELECT message.mid FROM message WHERE message.sections && '{1,2}';
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2007-12-10 06:32:51 +01:00
|
|
|
-- select messages in sections 1 AND 2 - CONTAINS operator
|
2007-12-04 00:49:51 +01:00
|
|
|
SELECT message.mid FROM message WHERE message.sections @> '{1,2}';
|
2007-12-10 06:32:51 +01:00
|
|
|
|
|
|
|
-- the same, using QUERY operator
|
|
|
|
SELECT message.mid FROM message WHERE message.sections @@ '1&2'::query_int;
|
2010-07-29 21:34:41 +02:00
|
|
|
</programlisting>
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Benchmark</title>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The source directory <filename>contrib/intarray/bench</filename> contains a
|
2016-05-21 21:43:57 +02:00
|
|
|
benchmark test suite, which can be run against an installed
|
2017-10-09 03:44:17 +02:00
|
|
|
<productname>PostgreSQL</productname> server. (It also requires <filename>DBD::Pg</filename>
|
2016-05-21 21:43:57 +02:00
|
|
|
to be installed.) To run:
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2016-05-21 21:43:57 +02:00
|
|
|
cd .../contrib/intarray/bench
|
2010-07-29 21:34:41 +02:00
|
|
|
createdb TEST
|
2016-05-21 21:43:57 +02:00
|
|
|
psql -c "CREATE EXTENSION intarray" TEST
|
2010-07-29 21:34:41 +02:00
|
|
|
./create_test.pl | psql TEST
|
|
|
|
./bench.pl
|
|
|
|
</programlisting>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The <filename>bench.pl</filename> script has numerous options, which
|
2007-12-10 06:32:51 +01:00
|
|
|
are displayed when it is run without any arguments.
|
|
|
|
</para>
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Authors</title>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2009-04-05 02:40:35 +02:00
|
|
|
All work was done by Teodor Sigaev (<email>teodor@sigaev.ru</email>) and
|
2007-12-10 06:32:51 +01:00
|
|
|
Oleg Bartunov (<email>oleg@sai.msu.su</email>). See
|
2010-03-17 18:12:31 +01:00
|
|
|
<ulink url="http://www.sai.msu.su/~megera/postgres/gist/"></ulink> for
|
2007-11-12 02:37:34 +01:00
|
|
|
additional information. Andrey Oktyabrski did a great work on adding new
|
2007-11-11 00:30:46 +01:00
|
|
|
functions and operations.
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
</sect1>
|