]> granicus.if.org Git - postgresql/blob - doc/src/sgml/gin.sgml
Fix assorted inconsistencies in GIN opclass support function declarations.
[postgresql] / doc / src / sgml / gin.sgml
1 <!-- doc/src/sgml/gin.sgml -->
2
3 <chapter id="GIN">
4 <title>GIN Indexes</title>
5
6    <indexterm>
7     <primary>index</primary>
8     <secondary>GIN</secondary>
9    </indexterm>
10
11 <sect1 id="gin-intro">
12  <title>Introduction</title>
13
14  <para>
15   <acronym>GIN</acronym> stands for Generalized Inverted Index.
16   <acronym>GIN</acronym> is designed for handling cases where the items
17   to be indexed are composite values, and the queries to be handled by
18   the index need to search for element values that appear within
19   the composite items.  For example, the items could be documents,
20   and the queries could be searches for documents containing specific words.
21  </para>
22
23  <para>
24   We use the word <firstterm>item</> to refer to a composite value that
25   is to be indexed, and the word <firstterm>key</> to refer to an element
26   value.  <acronym>GIN</acronym> always stores and searches for keys,
27   not item values per se.
28  </para>
29
30  <para>
31   A <acronym>GIN</acronym> index stores a set of (key, posting list) pairs,
32   where a <firstterm>posting list</> is a set of row IDs in which the key
33   occurs.  The same row ID can appear in multiple posting lists, since
34   an item can contain more than one key.  Each key value is stored only
35   once, so a <acronym>GIN</acronym> index is very compact for cases
36   where the same key appears many times.
37  </para>
38
39  <para>
40   <acronym>GIN</acronym> is generalized in the sense that the
41   <acronym>GIN</acronym> access method code does not need to know the
42   specific operations that it accelerates.
43   Instead, it uses custom strategies defined for particular data types.
44   The strategy defines how keys are extracted from indexed items and
45   query conditions, and how to determine whether a row that contains
46   some of the key values in a query actually satisfies the query.
47  </para>
48
49  <para>
50   One advantage of <acronym>GIN</acronym> is that it allows the development
51   of custom data types with the appropriate access methods, by
52   an expert in the domain of the data type, rather than a database expert.
53   This is much the same advantage as using <acronym>GiST</acronym>.
54  </para>
55
56  <para>
57   The <acronym>GIN</acronym>
58   implementation in <productname>PostgreSQL</productname> is primarily
59   maintained by Teodor Sigaev and Oleg Bartunov. There is more
60   information about <acronym>GIN</acronym> on their
61   <ulink url="http://www.sai.msu.su/~megera/wiki/Gin">website</ulink>.
62  </para>
63 </sect1>
64
65 <sect1 id="gin-builtin-opclasses">
66  <title>Built-in Operator Classes</title>
67
68  <para>
69   The core <productname>PostgreSQL</> distribution
70   includes the <acronym>GIN</acronym> operator classes shown in
71   <xref linkend="gin-builtin-opclasses-table">.
72   (Some of the optional modules described in <xref linkend="contrib">
73   provide additional <acronym>GIN</acronym> operator classes.)
74  </para>
75
76   <table id="gin-builtin-opclasses-table">
77    <title>Built-in <acronym>GIN</acronym> Operator Classes</title>
78    <tgroup cols="3">
79     <thead>
80      <row>
81       <entry>Name</entry>
82       <entry>Indexed Data Type</entry>
83       <entry>Indexable Operators</entry>
84      </row>
85     </thead>
86     <tbody>
87      <row>
88       <entry><literal>_abstime_ops</></entry>
89       <entry><type>abstime[]</></entry>
90       <entry>
91        <literal>&amp;&amp;</>
92        <literal>&lt;@</>
93        <literal>=</>
94        <literal>@&gt;</>
95       </entry>
96      </row>
97      <row>
98       <entry><literal>_bit_ops</></entry>
99       <entry><type>bit[]</></entry>
100       <entry>
101        <literal>&amp;&amp;</>
102        <literal>&lt;@</>
103        <literal>=</>
104        <literal>@&gt;</>
105       </entry>
106      </row>
107      <row>
108       <entry><literal>_bool_ops</></entry>
109       <entry><type>boolean[]</></entry>
110       <entry>
111        <literal>&amp;&amp;</>
112        <literal>&lt;@</>
113        <literal>=</>
114        <literal>@&gt;</>
115       </entry>
116      </row>
117      <row>
118       <entry><literal>_bpchar_ops</></entry>
119       <entry><type>character[]</></entry>
120       <entry>
121        <literal>&amp;&amp;</>
122        <literal>&lt;@</>
123        <literal>=</>
124        <literal>@&gt;</>
125       </entry>
126      </row>
127      <row>
128       <entry><literal>_bytea_ops</></entry>
129       <entry><type>bytea[]</></entry>
130       <entry>
131        <literal>&amp;&amp;</>
132        <literal>&lt;@</>
133        <literal>=</>
134        <literal>@&gt;</>
135       </entry>
136      </row>
137      <row>
138       <entry><literal>_char_ops</></entry>
139       <entry><type>"char"[]</></entry>
140       <entry>
141        <literal>&amp;&amp;</>
142        <literal>&lt;@</>
143        <literal>=</>
144        <literal>@&gt;</>
145       </entry>
146      </row>
147      <row>
148       <entry><literal>_cidr_ops</></entry>
149       <entry><type>cidr[]</></entry>
150       <entry>
151        <literal>&amp;&amp;</>
152        <literal>&lt;@</>
153        <literal>=</>
154        <literal>@&gt;</>
155       </entry>
156      </row>
157      <row>
158       <entry><literal>_date_ops</></entry>
159       <entry><type>date[]</></entry>
160       <entry>
161        <literal>&amp;&amp;</>
162        <literal>&lt;@</>
163        <literal>=</>
164        <literal>@&gt;</>
165       </entry>
166      </row>
167      <row>
168       <entry><literal>_float4_ops</></entry>
169       <entry><type>float4[]</></entry>
170       <entry>
171        <literal>&amp;&amp;</>
172        <literal>&lt;@</>
173        <literal>=</>
174        <literal>@&gt;</>
175       </entry>
176      </row>
177      <row>
178       <entry><literal>_float8_ops</></entry>
179       <entry><type>float8[]</></entry>
180       <entry>
181        <literal>&amp;&amp;</>
182        <literal>&lt;@</>
183        <literal>=</>
184        <literal>@&gt;</>
185       </entry>
186      </row>
187      <row>
188       <entry><literal>_inet_ops</></entry>
189       <entry><type>inet[]</></entry>
190       <entry>
191        <literal>&amp;&amp;</>
192        <literal>&lt;@</>
193        <literal>=</>
194        <literal>@&gt;</>
195       </entry>
196      </row>
197      <row>
198       <entry><literal>_int2_ops</></entry>
199       <entry><type>smallint[]</></entry>
200       <entry>
201        <literal>&amp;&amp;</>
202        <literal>&lt;@</>
203        <literal>=</>
204        <literal>@&gt;</>
205       </entry>
206      </row>
207      <row>
208       <entry><literal>_int4_ops</></entry>
209       <entry><type>integer[]</></entry>
210       <entry>
211        <literal>&amp;&amp;</>
212        <literal>&lt;@</>
213        <literal>=</>
214        <literal>@&gt;</>
215       </entry>
216      </row>
217      <row>
218       <entry><literal>_int8_ops</></entry>
219       <entry><type>bigint[]</></entry>
220       <entry>
221        <literal>&amp;&amp;</>
222        <literal>&lt;@</>
223        <literal>=</>
224        <literal>@&gt;</>
225       </entry>
226      </row>
227      <row>
228       <entry><literal>_interval_ops</></entry>
229       <entry><type>interval[]</></entry>
230       <entry>
231        <literal>&amp;&amp;</>
232        <literal>&lt;@</>
233        <literal>=</>
234        <literal>@&gt;</>
235       </entry>
236      </row>
237      <row>
238       <entry><literal>_macaddr_ops</></entry>
239       <entry><type>macaddr[]</></entry>
240       <entry>
241        <literal>&amp;&amp;</>
242        <literal>&lt;@</>
243        <literal>=</>
244        <literal>@&gt;</>
245       </entry>
246      </row>
247      <row>
248       <entry><literal>_money_ops</></entry>
249       <entry><type>money[]</></entry>
250       <entry>
251        <literal>&amp;&amp;</>
252        <literal>&lt;@</>
253        <literal>=</>
254        <literal>@&gt;</>
255       </entry>
256      </row>
257      <row>
258       <entry><literal>_name_ops</></entry>
259       <entry><type>name[]</></entry>
260       <entry>
261        <literal>&amp;&amp;</>
262        <literal>&lt;@</>
263        <literal>=</>
264        <literal>@&gt;</>
265       </entry>
266      </row>
267      <row>
268       <entry><literal>_numeric_ops</></entry>
269       <entry><type>numeric[]</></entry>
270       <entry>
271        <literal>&amp;&amp;</>
272        <literal>&lt;@</>
273        <literal>=</>
274        <literal>@&gt;</>
275       </entry>
276      </row>
277      <row>
278       <entry><literal>_oid_ops</></entry>
279       <entry><type>oid[]</></entry>
280       <entry>
281        <literal>&amp;&amp;</>
282        <literal>&lt;@</>
283        <literal>=</>
284        <literal>@&gt;</>
285       </entry>
286      </row>
287      <row>
288       <entry><literal>_oidvector_ops</></entry>
289       <entry><type>oidvector[]</></entry>
290       <entry>
291        <literal>&amp;&amp;</>
292        <literal>&lt;@</>
293        <literal>=</>
294        <literal>@&gt;</>
295       </entry>
296      </row>
297      <row>
298       <entry><literal>_reltime_ops</></entry>
299       <entry><type>reltime[]</></entry>
300       <entry>
301        <literal>&amp;&amp;</>
302        <literal>&lt;@</>
303        <literal>=</>
304        <literal>@&gt;</>
305       </entry>
306      </row>
307      <row>
308       <entry><literal>_text_ops</></entry>
309       <entry><type>text[]</></entry>
310       <entry>
311        <literal>&amp;&amp;</>
312        <literal>&lt;@</>
313        <literal>=</>
314        <literal>@&gt;</>
315       </entry>
316      </row>
317      <row>
318       <entry><literal>_time_ops</></entry>
319       <entry><type>time[]</></entry>
320       <entry>
321        <literal>&amp;&amp;</>
322        <literal>&lt;@</>
323        <literal>=</>
324        <literal>@&gt;</>
325       </entry>
326      </row>
327      <row>
328       <entry><literal>_timestamp_ops</></entry>
329       <entry><type>timestamp[]</></entry>
330       <entry>
331        <literal>&amp;&amp;</>
332        <literal>&lt;@</>
333        <literal>=</>
334        <literal>@&gt;</>
335       </entry>
336      </row>
337      <row>
338       <entry><literal>_timestamptz_ops</></entry>
339       <entry><type>timestamp with time zone[]</></entry>
340       <entry>
341        <literal>&amp;&amp;</>
342        <literal>&lt;@</>
343        <literal>=</>
344        <literal>@&gt;</>
345       </entry>
346      </row>
347      <row>
348       <entry><literal>_timetz_ops</></entry>
349       <entry><type>time with time zone[]</></entry>
350       <entry>
351        <literal>&amp;&amp;</>
352        <literal>&lt;@</>
353        <literal>=</>
354        <literal>@&gt;</>
355       </entry>
356      </row>
357      <row>
358       <entry><literal>_tinterval_ops</></entry>
359       <entry><type>tinterval[]</></entry>
360       <entry>
361        <literal>&amp;&amp;</>
362        <literal>&lt;@</>
363        <literal>=</>
364        <literal>@&gt;</>
365       </entry>
366      </row>
367      <row>
368       <entry><literal>_varbit_ops</></entry>
369       <entry><type>bit varying[]</></entry>
370       <entry>
371        <literal>&amp;&amp;</>
372        <literal>&lt;@</>
373        <literal>=</>
374        <literal>@&gt;</>
375       </entry>
376      </row>
377      <row>
378       <entry><literal>_varchar_ops</></entry>
379       <entry><type>character varying[]</></entry>
380       <entry>
381        <literal>&amp;&amp;</>
382        <literal>&lt;@</>
383        <literal>=</>
384        <literal>@&gt;</>
385       </entry>
386      </row>
387      <row>
388       <entry><literal>jsonb_ops</></entry>
389       <entry><type>jsonb</></entry>
390       <entry>
391        <literal>?</>
392        <literal>?&amp;</>
393        <literal>?|</>
394        <literal>@&gt;</>
395       </entry>
396      </row>
397      <row>
398       <entry><literal>jsonb_path_ops</></entry>
399       <entry><type>jsonb</></entry>
400       <entry>
401        <literal>@&gt;</>
402       </entry>
403      </row>
404      <row>
405       <entry><literal>tsvector_ops</></entry>
406       <entry><type>tsvector</></entry>
407       <entry>
408        <literal>@@</>
409        <literal>@@@</>
410       </entry>
411      </row>
412     </tbody>
413    </tgroup>
414   </table>
415
416  <para>
417   Of the two operator classes for type <type>jsonb</>, <literal>jsonb_ops</>
418   is the default.  <literal>jsonb_path_ops</> supports fewer operators but
419   offers better performance for those operators.
420   See <xref linkend="json-indexing"> for details.
421  </para>
422
423 </sect1>
424
425 <sect1 id="gin-extensibility">
426  <title>Extensibility</title>
427
428  <para>
429    The <acronym>GIN</acronym> interface has a high level of abstraction,
430    requiring the access method implementer only to implement the semantics of
431    the data type being accessed.  The <acronym>GIN</acronym> layer itself
432    takes care of concurrency, logging and searching the tree structure.
433  </para>
434
435  <para>
436    All it takes to get a <acronym>GIN</acronym> access method working is to
437    implement a few user-defined methods, which define the behavior of
438    keys in the tree and the relationships between keys, indexed items,
439    and indexable queries. In short, <acronym>GIN</acronym> combines
440    extensibility with generality, code reuse, and a clean interface.
441  </para>
442
443  <para>
444    There are three methods that an operator class for
445    <acronym>GIN</acronym> must provide:
446
447  <variablelist>
448     <varlistentry>
449      <term><function>int compare(Datum a, Datum b)</></term>
450      <listitem>
451       <para>
452        Compares two keys (not indexed items!) and returns an integer less than
453        zero, zero, or greater than zero, indicating whether the first key is
454        less than, equal to, or greater than the second.  Null keys are never
455        passed to this function.
456       </para>
457      </listitem>
458     </varlistentry>
459
460     <varlistentry>
461      <term><function>Datum *extractValue(Datum itemValue, int32 *nkeys,
462         bool **nullFlags)</></term>
463      <listitem>
464       <para>
465        Returns a palloc'd array of keys given an item to be indexed.  The
466        number of returned keys must be stored into <literal>*nkeys</>.
467        If any of the keys can be null, also palloc an array of
468        <literal>*nkeys</> <type>bool</type> fields, store its address at
469        <literal>*nullFlags</>, and set these null flags as needed.
470        <literal>*nullFlags</> can be left <symbol>NULL</symbol> (its initial value)
471        if all keys are non-null.
472        The return value can be <symbol>NULL</symbol> if the item contains no keys.
473       </para>
474      </listitem>
475     </varlistentry>
476
477     <varlistentry>
478      <term><function>Datum *extractQuery(Datum query, int32 *nkeys,
479         StrategyNumber n, bool **pmatch, Pointer **extra_data,
480         bool **nullFlags, int32 *searchMode)</></term>
481      <listitem>
482       <para>
483        Returns a palloc'd array of keys given a value to be queried; that is,
484        <literal>query</> is the value on the right-hand side of an
485        indexable operator whose left-hand side is the indexed column.
486        <literal>n</> is the strategy number of the operator within the
487        operator class (see <xref linkend="xindex-strategies">).
488        Often, <function>extractQuery</> will need
489        to consult <literal>n</> to determine the data type of
490        <literal>query</> and the method it should use to extract key values.
491        The number of returned keys must be stored into <literal>*nkeys</>.
492        If any of the keys can be null, also palloc an array of
493        <literal>*nkeys</> <type>bool</type> fields, store its address at
494        <literal>*nullFlags</>, and set these null flags as needed.
495        <literal>*nullFlags</> can be left <symbol>NULL</symbol> (its initial value)
496        if all keys are non-null.
497        The return value can be <symbol>NULL</symbol> if the <literal>query</> contains no keys.
498       </para>
499
500       <para>
501        <literal>searchMode</> is an output argument that allows
502        <function>extractQuery</> to specify details about how the search
503        will be done.
504        If <literal>*searchMode</> is set to
505        <literal>GIN_SEARCH_MODE_DEFAULT</> (which is the value it is
506        initialized to before call), only items that match at least one of
507        the returned keys are considered candidate matches.
508        If <literal>*searchMode</> is set to
509        <literal>GIN_SEARCH_MODE_INCLUDE_EMPTY</>, then in addition to items
510        containing at least one matching key, items that contain no keys at
511        all are considered candidate matches.  (This mode is useful for
512        implementing is-subset-of operators, for example.)
513        If <literal>*searchMode</> is set to <literal>GIN_SEARCH_MODE_ALL</>,
514        then all non-null items in the index are considered candidate
515        matches, whether they match any of the returned keys or not.  (This
516        mode is much slower than the other two choices, since it requires
517        scanning essentially the entire index, but it may be necessary to
518        implement corner cases correctly.  An operator that needs this mode
519        in most cases is probably not a good candidate for a GIN operator
520        class.)
521        The symbols to use for setting this mode are defined in
522        <filename>access/gin.h</>.
523       </para>
524
525       <para>
526        <literal>pmatch</> is an output argument for use when partial match
527        is supported.  To use it, <function>extractQuery</> must allocate
528        an array of <literal>*nkeys</> booleans and store its address at
529        <literal>*pmatch</>.  Each element of the array should be set to TRUE
530        if the corresponding key requires partial match, FALSE if not.
531        If <literal>*pmatch</> is set to <symbol>NULL</symbol> then GIN assumes partial match
532        is not required.  The variable is initialized to <symbol>NULL</symbol> before call,
533        so this argument can simply be ignored by operator classes that do
534        not support partial match.
535       </para>
536
537       <para>
538        <literal>extra_data</> is an output argument that allows
539        <function>extractQuery</> to pass additional data to the
540        <function>consistent</> and <function>comparePartial</> methods.
541        To use it, <function>extractQuery</> must allocate
542        an array of <literal>*nkeys</> Pointers and store its address at
543        <literal>*extra_data</>, then store whatever it wants to into the
544        individual pointers.  The variable is initialized to <symbol>NULL</symbol> before
545        call, so this argument can simply be ignored by operator classes that
546        do not require extra data.  If <literal>*extra_data</> is set, the
547        whole array is passed to the <function>consistent</> method, and
548        the appropriate element to the <function>comparePartial</> method.
549       </para>
550
551      </listitem>
552     </varlistentry>
553   </variablelist>
554
555   An operator class must also provide a function to check if an indexed item
556   matches the query. It comes in two flavors, a boolean <function>consistent</>
557   function, and a ternary <function>triConsistent</> function.
558   <function>triConsistent</> covers the functionality of both, so providing
559   <function>triConsistent</> alone is sufficient. However, if the boolean
560   variant is significantly cheaper to calculate, it can be advantageous to
561   provide both.  If only the boolean variant is provided, some optimizations
562   that depend on refuting index items before fetching all the keys are
563   disabled.
564
565   <variablelist>
566     <varlistentry>
567      <term><function>bool consistent(bool check[], StrategyNumber n, Datum query,
568         int32 nkeys, Pointer extra_data[], bool *recheck,
569         Datum queryKeys[], bool nullFlags[])</></term>
570      <listitem>
571       <para>
572        Returns TRUE if an indexed item satisfies the query operator with
573        strategy number <literal>n</> (or might satisfy it, if the recheck
574        indication is returned).  This function does not have direct access
575        to the indexed item's value, since <acronym>GIN</acronym> does not
576        store items explicitly.  Rather, what is available is knowledge
577        about which key values extracted from the query appear in a given
578        indexed item.  The <literal>check</> array has length
579        <literal>nkeys</>, which is the same as the number of keys previously
580        returned by <function>extractQuery</> for this <literal>query</> datum.
581        Each element of the
582        <literal>check</> array is TRUE if the indexed item contains the
583        corresponding query key, i.e., if (check[i] == TRUE) the i-th key of the
584        <function>extractQuery</> result array is present in the indexed item.
585        The original <literal>query</> datum is
586        passed in case the <function>consistent</> method needs to consult it,
587        and so are the <literal>queryKeys[]</> and <literal>nullFlags[]</>
588        arrays previously returned by <function>extractQuery</>.
589        <literal>extra_data</> is the extra-data array returned by
590        <function>extractQuery</>, or <symbol>NULL</symbol> if none.
591       </para>
592
593       <para>
594        When <function>extractQuery</> returns a null key in
595        <literal>queryKeys[]</>, the corresponding <literal>check[]</> element
596        is TRUE if the indexed item contains a null key; that is, the
597        semantics of <literal>check[]</> are like <literal>IS NOT DISTINCT
598        FROM</>.  The <function>consistent</> function can examine the
599        corresponding <literal>nullFlags[]</> element if it needs to tell
600        the difference between a regular value match and a null match.
601       </para>
602
603       <para>
604        On success, <literal>*recheck</> should be set to TRUE if the heap
605        tuple needs to be rechecked against the query operator, or FALSE if
606        the index test is exact.  That is, a FALSE return value guarantees
607        that the heap tuple does not match the query; a TRUE return value with
608        <literal>*recheck</> set to FALSE guarantees that the heap tuple does
609        match the query; and a TRUE return value with
610        <literal>*recheck</> set to TRUE means that the heap tuple might match
611        the query, so it needs to be fetched and rechecked by evaluating the
612        query operator directly against the originally indexed item.
613       </para>
614      </listitem>
615     </varlistentry>
616
617     <varlistentry>
618      <term><function>GinTernaryValue triConsistent(GinTernaryValue check[], StrategyNumber n, Datum query,
619         int32 nkeys, Pointer extra_data[],
620         Datum queryKeys[], bool nullFlags[])</></term>
621      <listitem>
622       <para>
623        <function>triConsistent</> is similar to <function>consistent</>,
624        but instead of booleans in the <literal>check</> vector, there are
625        three possible values for each
626        key: <literal>GIN_TRUE</>, <literal>GIN_FALSE</> and
627        <literal>GIN_MAYBE</>. <literal>GIN_FALSE</> and <literal>GIN_TRUE</>
628        have the same meaning as regular boolean values, while
629        <literal>GIN_MAYBE</> means that the presence of that key is not known.
630        When <literal>GIN_MAYBE</> values are present, the function should only
631        return <literal>GIN_TRUE</> if the item certainly matches whether or
632        not the index item contains the corresponding query keys. Likewise, the
633        function must return <literal>GIN_FALSE</> only if the item certainly
634        does not match, whether or not it contains the <literal>GIN_MAYBE</>
635        keys. If the result depends on the <literal>GIN_MAYBE</> entries, i.e.,
636        the match cannot be confirmed or refuted based on the known query keys,
637        the function must return <literal>GIN_MAYBE</>.
638       </para>
639       <para>
640        When there are no <literal>GIN_MAYBE</> values in the <literal>check</>
641        vector, a <literal>GIN_MAYBE</> return value is the equivalent of
642        setting the <literal>recheck</> flag in the
643        boolean <function>consistent</> function.
644       </para>
645      </listitem>
646     </varlistentry>
647   </variablelist>
648
649   Optionally, an operator class for <acronym>GIN</acronym> can supply the
650   following method:
651
652   <variablelist>
653     <varlistentry>
654      <term><function>int comparePartial(Datum partial_key, Datum key, StrategyNumber n,
655                               Pointer extra_data)</></term>
656      <listitem>
657       <para>
658        Compare a partial-match query key to an index key.  Returns an integer
659        whose sign indicates the result: less than zero means the index key
660        does not match the query, but the index scan should continue; zero
661        means that the index key does match the query; greater than zero
662        indicates that the index scan should stop because no more matches
663        are possible.  The strategy number <literal>n</> of the operator
664        that generated the partial match query is provided, in case its
665        semantics are needed to determine when to end the scan.  Also,
666        <literal>extra_data</> is the corresponding element of the extra-data
667        array made by <function>extractQuery</>, or <symbol>NULL</symbol> if none.
668        Null keys are never passed to this function.
669       </para>
670      </listitem>
671     </varlistentry>
672   </variablelist>
673  </para>
674
675  <para>
676   To support <quote>partial match</> queries, an operator class must
677   provide the <function>comparePartial</> method, and its
678   <function>extractQuery</> method must set the <literal>pmatch</>
679   parameter when a partial-match query is encountered.  See
680   <xref linkend="gin-partial-match"> for details.
681  </para>
682
683  <para>
684   The actual data types of the various <literal>Datum</> values mentioned
685   above vary depending on the operator class.  The item values passed to
686   <function>extractValue</> are always of the operator class's input type, and
687   all key values must be of the class's <literal>STORAGE</> type.  The type of
688   the <literal>query</> argument passed to <function>extractQuery</>,
689   <function>consistent</> and <function>triConsistent</> is whatever is the
690   right-hand input type of the class member operator identified by the
691   strategy number.  This need not be the same as the indexed type, so long as
692   key values of the correct type can be extracted from it.  However, it is
693   recommended that the SQL declarations of these three support functions use
694   the opclass's indexed data type for the <literal>query</> argument, even
695   though the actual type might be something else depending on the operator.
696  </para>
697
698 </sect1>
699
700 <sect1 id="gin-implementation">
701  <title>Implementation</title>
702
703  <para>
704   Internally, a <acronym>GIN</acronym> index contains a B-tree index
705   constructed over keys, where each key is an element of one or more indexed
706   items (a member of an array, for example) and where each tuple in a leaf
707   page contains either a pointer to a B-tree of heap pointers (a
708   <quote>posting tree</>), or a simple list of heap pointers (a <quote>posting
709   list</>) when the list is small enough to fit into a single index tuple along
710   with the key value.
711  </para>
712
713  <para>
714   As of <productname>PostgreSQL</productname> 9.1, null key values can be
715   included in the index.  Also, placeholder nulls are included in the index
716   for indexed items that are null or contain no keys according to
717   <function>extractValue</>.  This allows searches that should find empty
718   items to do so.
719  </para>
720
721  <para>
722   Multicolumn <acronym>GIN</acronym> indexes are implemented by building
723   a single B-tree over composite values (column number, key value).  The
724   key values for different columns can be of different types.
725  </para>
726
727  <sect2 id="gin-fast-update">
728   <title>GIN Fast Update Technique</title>
729
730   <para>
731    Updating a <acronym>GIN</acronym> index tends to be slow because of the
732    intrinsic nature of inverted indexes: inserting or updating one heap row
733    can cause many inserts into the index (one for each key extracted
734    from the indexed item). As of <productname>PostgreSQL</productname> 8.4,
735    <acronym>GIN</> is capable of postponing much of this work by inserting
736    new tuples into a temporary, unsorted list of pending entries.
737    When the table is vacuumed, or if the pending list becomes larger than
738    <xref linkend="guc-gin-pending-list-limit">, the entries are moved to the
739    main <acronym>GIN</acronym> data structure using the same bulk insert
740    techniques used during initial index creation.  This greatly improves
741    <acronym>GIN</acronym> index update speed, even counting the additional
742    vacuum overhead.  Moreover the overhead work can be done by a background
743    process instead of in foreground query processing.
744   </para>
745
746   <para>
747    The main disadvantage of this approach is that searches must scan the list
748    of pending entries in addition to searching the regular index, and so
749    a large list of pending entries will slow searches significantly.
750    Another disadvantage is that, while most updates are fast, an update
751    that causes the pending list to become <quote>too large</> will incur an
752    immediate cleanup cycle and thus be much slower than other updates.
753    Proper use of autovacuum can minimize both of these problems.
754   </para>
755
756   <para>
757    If consistent response time is more important than update speed,
758    use of pending entries can be disabled by turning off the
759    <literal>fastupdate</literal> storage parameter for a
760    <acronym>GIN</acronym> index.  See <xref linkend="sql-createindex">
761    for details.
762   </para>
763  </sect2>
764
765  <sect2 id="gin-partial-match">
766   <title>Partial Match Algorithm</title>
767
768   <para>
769    GIN can support <quote>partial match</> queries, in which the query
770    does not determine an exact match for one or more keys, but the possible
771    matches fall within a reasonably narrow range of key values (within the
772    key sorting order determined by the <function>compare</> support method).
773    The <function>extractQuery</> method, instead of returning a key value
774    to be matched exactly, returns a key value that is the lower bound of
775    the range to be searched, and sets the <literal>pmatch</> flag true.
776    The key range is then scanned using the <function>comparePartial</>
777    method.  <function>comparePartial</> must return zero for a matching
778    index key, less than zero for a non-match that is still within the range
779    to be searched, or greater than zero if the index key is past the range
780    that could match.
781   </para>
782  </sect2>
783
784 </sect1>
785
786 <sect1 id="gin-tips">
787 <title>GIN Tips and Tricks</title>
788
789  <variablelist>
790   <varlistentry>
791    <term>Create vs. insert</term>
792    <listitem>
793     <para>
794      Insertion into a <acronym>GIN</acronym> index can be slow
795      due to the likelihood of many keys being inserted for each item.
796      So, for bulk insertions into a table it is advisable to drop the GIN
797      index and recreate it after finishing bulk insertion.
798     </para>
799
800     <para>
801      As of <productname>PostgreSQL</productname> 8.4, this advice is less
802      necessary since delayed indexing is used (see <xref
803      linkend="gin-fast-update"> for details).  But for very large updates
804      it may still be best to drop and recreate the index.
805     </para>
806    </listitem>
807   </varlistentry>
808
809   <varlistentry>
810    <term><xref linkend="guc-maintenance-work-mem"></term>
811    <listitem>
812     <para>
813      Build time for a <acronym>GIN</acronym> index is very sensitive to
814      the <varname>maintenance_work_mem</> setting; it doesn't pay to
815      skimp on work memory during index creation.
816     </para>
817    </listitem>
818   </varlistentry>
819
820   <varlistentry>
821    <term><xref linkend="guc-gin-pending-list-limit"></term>
822    <listitem>
823     <para>
824      During a series of insertions into an existing <acronym>GIN</acronym>
825      index that has <literal>fastupdate</> enabled, the system will clean up
826      the pending-entry list whenever the list grows larger than
827      <varname>gin_pending_list_limit</>. To avoid fluctuations in observed
828      response time, it's desirable to have pending-list cleanup occur in the
829      background (i.e., via autovacuum).  Foreground cleanup operations
830      can be avoided by increasing <varname>gin_pending_list_limit</>
831      or making autovacuum more aggressive.
832      However, enlarging the threshold of the cleanup operation means that
833      if a foreground cleanup does occur, it will take even longer.
834     </para>
835     <para>
836      <varname>gin_pending_list_limit</> can be overridden for individual
837      GIN indexes by changing storage parameters, and which allows each
838      GIN index to have its own cleanup threshold.
839      For example, it's possible to increase the threshold only for the GIN
840      index which can be updated heavily, and decrease it otherwise.
841     </para>
842    </listitem>
843   </varlistentry>
844
845   <varlistentry>
846    <term><xref linkend="guc-gin-fuzzy-search-limit"></term>
847    <listitem>
848     <para>
849      The primary goal of developing <acronym>GIN</acronym> indexes was
850      to create support for highly scalable full-text search in
851      <productname>PostgreSQL</productname>, and there are often situations when
852      a full-text search returns a very large set of results.  Moreover, this
853      often happens when the query contains very frequent words, so that the
854      large result set is not even useful.  Since reading many
855      tuples from the disk and sorting them could take a lot of time, this is
856      unacceptable for production.  (Note that the index search itself is very
857      fast.)
858     </para>
859     <para>
860      To facilitate controlled execution of such queries,
861      <acronym>GIN</acronym> has a configurable soft upper limit on the
862      number of rows returned: the
863      <varname>gin_fuzzy_search_limit</varname> configuration parameter.
864      It is set to 0 (meaning no limit) by default.
865      If a non-zero limit is set, then the returned set is a subset of
866      the whole result set, chosen at random.
867     </para>
868     <para>
869      <quote>Soft</quote> means that the actual number of returned results
870      could differ somewhat from the specified limit, depending on the query
871      and the quality of the system's random number generator.
872     </para>
873     <para>
874      From experience, values in the thousands (e.g., 5000 &mdash; 20000)
875      work well.
876     </para>
877    </listitem>
878   </varlistentry>
879  </variablelist>
880
881 </sect1>
882
883 <sect1 id="gin-limit">
884  <title>Limitations</title>
885
886  <para>
887   <acronym>GIN</acronym> assumes that indexable operators are strict.  This
888   means that <function>extractValue</> will not be called at all on a null
889   item value (instead, a placeholder index entry is created automatically),
890   and <function>extractQuery</function> will not be called on a null query
891   value either (instead, the query is presumed to be unsatisfiable).  Note
892   however that null key values contained within a non-null composite item
893   or query value are supported.
894  </para>
895 </sect1>
896
897 <sect1 id="gin-examples">
898  <title>Examples</title>
899
900  <para>
901   The <productname>PostgreSQL</productname> source distribution includes
902   <acronym>GIN</acronym> operator classes for <type>tsvector</> and
903   for one-dimensional arrays of all internal types.  Prefix searching in
904   <type>tsvector</> is implemented using the <acronym>GIN</> partial match
905   feature.
906   The following <filename>contrib</> modules also contain
907   <acronym>GIN</acronym> operator classes:
908
909  <variablelist>
910   <varlistentry>
911    <term><filename>btree_gin</></term>
912    <listitem>
913     <para>B-tree equivalent functionality for several data types</para>
914    </listitem>
915   </varlistentry>
916
917   <varlistentry>
918    <term><filename>hstore</></term>
919    <listitem>
920     <para>Module for storing (key, value) pairs</para>
921    </listitem>
922   </varlistentry>
923
924   <varlistentry>
925    <term><filename>intarray</></term>
926    <listitem>
927     <para>Enhanced support for <type>int[]</type></para>
928    </listitem>
929   </varlistentry>
930
931   <varlistentry>
932    <term><filename>pg_trgm</></term>
933    <listitem>
934     <para>Text similarity using trigram matching</para>
935    </listitem>
936   </varlistentry>
937  </variablelist>
938  </para>
939 </sect1>
940
941 </chapter>