facility.
</para>
- <table id="textsearch-operators-table">
- <title>Text Search Operators</title>
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Operator</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry> <literal>@@</literal> </entry>
- <entry><type>boolean</type></entry>
- <entry><type>tsvector</type> matches <type>tsquery</type> ?</entry>
- <entry><literal>to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat')</literal></entry>
- <entry><literal>t</literal></entry>
- </row>
- <row>
- <entry> <literal>@@@</literal> </entry>
- <entry><type>boolean</type></entry>
- <entry>deprecated synonym for <literal>@@</literal></entry>
- <entry><literal>to_tsvector('fat cats ate rats') @@@ to_tsquery('cat & rat')</literal></entry>
- <entry><literal>t</literal></entry>
- </row>
- <row>
- <entry> <literal>||</literal> </entry>
- <entry><type>tsvector</type></entry>
- <entry>concatenate <type>tsvector</type>s</entry>
- <entry><literal>'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector</literal></entry>
- <entry><literal>'a':1 'b':2,5 'c':3 'd':4</literal></entry>
- </row>
- <row>
- <entry> <literal>&&</literal> </entry>
- <entry><type>tsquery</type></entry>
- <entry>AND <type>tsquery</type>s together</entry>
- <entry><literal>'fat | rat'::tsquery && 'cat'::tsquery</literal></entry>
- <entry><literal>( 'fat' | 'rat' ) & 'cat'</literal></entry>
- </row>
- <row>
- <entry> <literal>||</literal> </entry>
- <entry><type>tsquery</type></entry>
- <entry>OR <type>tsquery</type>s together</entry>
- <entry><literal>'fat | rat'::tsquery || 'cat'::tsquery</literal></entry>
- <entry><literal>( 'fat' | 'rat' ) | 'cat'</literal></entry>
- </row>
- <row>
- <entry> <literal>!!</literal> </entry>
- <entry><type>tsquery</type></entry>
- <entry>negate a <type>tsquery</type></entry>
- <entry><literal>!! 'cat'::tsquery</literal></entry>
- <entry><literal>!'cat'</literal></entry>
- </row>
- <row>
- <entry> <literal><-></literal> </entry>
- <entry><type>tsquery</type></entry>
- <entry><type>tsquery</type> followed by <type>tsquery</type></entry>
- <entry><literal>to_tsquery('fat') <-> to_tsquery('rat')</literal></entry>
- <entry><literal>'fat' <-> 'rat'</literal></entry>
- </row>
- <row>
- <entry> <literal>@></literal> </entry>
- <entry><type>boolean</type></entry>
- <entry><type>tsquery</type> contains another ?</entry>
- <entry><literal>'cat'::tsquery @> 'cat & rat'::tsquery</literal></entry>
- <entry><literal>f</literal></entry>
- </row>
- <row>
- <entry> <literal><@</literal> </entry>
- <entry><type>boolean</type></entry>
- <entry><type>tsquery</type> is contained in ?</entry>
- <entry><literal>'cat'::tsquery <@ 'cat & rat'::tsquery</literal></entry>
- <entry><literal>t</literal></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <table id="textsearch-operators-table">
+ <title>Text Search Operators</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="functableentry">
+ Operator<?br?>Description<?br?>Example(s)
+ </entry>
+ </row>
+ </thead>
- <note>
- <para>
- The <type>tsquery</type> containment operators consider only the lexemes
- listed in the two queries, ignoring the combining operators.
- </para>
- </note>
+ <tbody>
+ <row>
+ <entry role="functableentry">
+ <type>tsvector</type> <literal>@@</literal> <type>tsquery</type>
+ or
+ <type>tsquery</type> <literal>@@</literal> <type>tsvector</type>
+ <returnvalue>boolean</returnvalue>
+ <?br?>
+ Does <type>tsvector</type> match <type>tsquery</type>?
+ <?br?>
+ <literal>to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat')</literal>
+ <returnvalue>t</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <type>text</type> <literal>@@</literal> <type>tsquery</type>
+ <returnvalue>boolean</returnvalue>
+ <?br?>
+ Does text string, after implicit invocation
+ of <function>to_tsvector()</function>, match <type>tsquery</type>?
+ <?br?>
+ <literal>'fat cats ate rats' @@ to_tsquery('cat & rat')</literal>
+ <returnvalue>t</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <type>tsvector</type> <literal>@@@</literal> <type>tsquery</type>
+ or
+ <type>tsquery</type> <literal>@@@</literal> <type>tsvector</type>
+ <returnvalue>boolean</returnvalue>
+ <?br?>
+ This is a deprecated synonym for <literal>@@</literal>.
+ <?br?>
+ <literal>to_tsvector('fat cats ate rats') @@@ to_tsquery('cat & rat')</literal>
+ <returnvalue>t</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <type>tsvector</type> <literal>||</literal> <type>tsvector</type>
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Concatenates two <type>tsvector</type>s. If both inputs contain
+ lexeme positions, the second input's positions are adjusted
+ accordingly.
+ <?br?>
+ <literal>'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector</literal>
+ <returnvalue>'a':1 'b':2,5 'c':3 'd':4</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <type>tsquery</type> <literal>&&</literal> <type>tsquery</type>
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ ANDs two <type>tsquery</type>s together, producing a query that
+ matches documents that match both input queries.
+ <?br?>
+ <literal>'fat | rat'::tsquery && 'cat'::tsquery</literal>
+ <returnvalue>( 'fat' | 'rat' ) & 'cat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <type>tsquery</type> <literal>||</literal> <type>tsquery</type>
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ ORs two <type>tsquery</type>s together, producing a query that
+ matches documents that match either input query.
+ <?br?>
+ <literal>'fat | rat'::tsquery || 'cat'::tsquery</literal>
+ <returnvalue>'fat' | 'rat' | 'cat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <literal>!!</literal> <type>tsquery</type>
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ Negates a <type>tsquery</type>, producing a query that matches
+ documents that do not match the input query.
+ <?br?>
+ <literal>!! 'cat'::tsquery</literal>
+ <returnvalue>!'cat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <type>tsquery</type> <literal><-></literal> <type>tsquery</type>
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ Constructs a phrase query, which matches if the two input queries
+ match at successive lexemes.
+ <?br?>
+ <literal>to_tsquery('fat') <-> to_tsquery('rat')</literal>
+ <returnvalue>'fat' <-> 'rat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <type>tsquery</type> <literal>@></literal> <type>tsquery</type>
+ <returnvalue>boolean</returnvalue>
+ <?br?>
+ Does first <type>tsquery</type> contain the second? (This considers
+ only whether all the lexemes appearing in one query appear in the
+ other, ignoring the combining operators.)
+ <?br?>
+ <literal>'cat'::tsquery @> 'cat & rat'::tsquery</literal>
+ <returnvalue>f</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <type>tsquery</type> <literal><@</literal> <type>tsquery</type>
+ <returnvalue>boolean</returnvalue>
+ <?br?>
+ Is first <type>tsquery</type> contained in the second? (This
+ considers only whether all the lexemes appearing in one query appear
+ in the other, ignoring the combining operators.)
+ <?br?>
+ <literal>'cat'::tsquery <@ 'cat & rat'::tsquery</literal>
+ <returnvalue>t</returnvalue>
+ <?br?>
+ <literal>'cat'::tsquery <@ '!cat & rat'::tsquery</literal>
+ <returnvalue>t</returnvalue>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
- In addition to the operators shown in the table, the ordinary B-tree
- comparison operators (<literal>=</literal>, <literal><</literal>, etc) are defined
- for types <type>tsvector</type> and <type>tsquery</type>. These are not very
+ In addition to these specialized operators, the usual comparison
+ operators shown in <xref linkend="functions-comparison-op-table"/> are
+ available for types <type>tsvector</type> and <type>tsquery</type>.
+ These are not very
useful for text searching but allow, for example, unique indexes to be
built on columns of these types.
</para>
- <table id="textsearch-functions-table">
- <title>Text Search Functions</title>
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <indexterm>
- <primary>array_to_tsvector</primary>
- </indexterm>
- <literal><function>array_to_tsvector(<type>text[]</type>)</function></literal>
- </entry>
- <entry><type>tsvector</type></entry>
- <entry>convert array of lexemes to <type>tsvector</type></entry>
- <entry><literal>array_to_tsvector('{fat,cat,rat}'::text[])</literal></entry>
- <entry><literal>'cat' 'fat' 'rat'</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>get_current_ts_config</primary>
- </indexterm>
- <literal><function>get_current_ts_config()</function></literal>
- </entry>
- <entry><type>regconfig</type></entry>
- <entry>get default text search configuration</entry>
- <entry><literal>get_current_ts_config()</literal></entry>
- <entry><literal>english</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>length</primary>
- </indexterm>
- <literal><function>length(<type>tsvector</type>)</function></literal>
- </entry>
- <entry><type>integer</type></entry>
- <entry>number of lexemes in <type>tsvector</type></entry>
- <entry><literal>length('fat:2,4 cat:3 rat:5A'::tsvector)</literal></entry>
- <entry><literal>3</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>numnode</primary>
- </indexterm>
- <literal><function>numnode(<type>tsquery</type>)</function></literal>
- </entry>
- <entry><type>integer</type></entry>
- <entry>number of lexemes plus operators in <type>tsquery</type></entry>
- <entry><literal> numnode('(fat & rat) | cat'::tsquery)</literal></entry>
- <entry><literal>5</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>plainto_tsquery</primary>
- </indexterm>
- <literal><function>plainto_tsquery(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type> , </optional> <replaceable class="parameter">query</replaceable> <type>text</type>)</function></literal>
- </entry>
- <entry><type>tsquery</type></entry>
- <entry>produce <type>tsquery</type> ignoring punctuation</entry>
- <entry><literal>plainto_tsquery('english', 'The Fat Rats')</literal></entry>
- <entry><literal>'fat' & 'rat'</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>phraseto_tsquery</primary>
- </indexterm>
- <literal><function>phraseto_tsquery(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type> , </optional> <replaceable class="parameter">query</replaceable> <type>text</type>)</function></literal>
- </entry>
- <entry><type>tsquery</type></entry>
- <entry>produce <type>tsquery</type> that searches for a phrase,
- ignoring punctuation</entry>
- <entry><literal>phraseto_tsquery('english', 'The Fat Rats')</literal></entry>
- <entry><literal>'fat' <-> 'rat'</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>websearch_to_tsquery</primary>
- </indexterm>
- <literal><function>websearch_to_tsquery(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type> , </optional> <replaceable class="parameter">query</replaceable> <type>text</type>)</function></literal>
- </entry>
- <entry><type>tsquery</type></entry>
- <entry>produce <type>tsquery</type> from a web search style query</entry>
- <entry><literal>websearch_to_tsquery('english', '"fat rat" or rat')</literal></entry>
- <entry><literal>'fat' <-> 'rat' | 'rat'</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>querytree</primary>
- </indexterm>
- <literal><function>querytree(<replaceable class="parameter">query</replaceable> <type>tsquery</type>)</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>get indexable part of a <type>tsquery</type></entry>
- <entry><literal>querytree('foo & ! bar'::tsquery)</literal></entry>
- <entry><literal>'foo'</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>setweight</primary>
- </indexterm>
- <literal><function>setweight(<replaceable class="parameter">vector</replaceable> <type>tsvector</type>, <replaceable class="parameter">weight</replaceable> <type>"char"</type>)</function></literal>
- </entry>
- <entry><type>tsvector</type></entry>
- <entry>assign <replaceable class="parameter">weight</replaceable> to each element of <replaceable class="parameter">vector</replaceable></entry>
- <entry><literal>setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A')</literal></entry>
- <entry><literal>'cat':3A 'fat':2A,4A 'rat':5A</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>setweight</primary>
- <secondary>setweight for specific lexeme(s)</secondary>
- </indexterm>
- <literal><function>setweight(<replaceable class="parameter">vector</replaceable> <type>tsvector</type>, <replaceable class="parameter">weight</replaceable> <type>"char"</type>, <replaceable class="parameter">lexemes</replaceable> <type>text[]</type>)</function></literal>
- </entry>
- <entry><type>tsvector</type></entry>
- <entry>assign <replaceable class="parameter">weight</replaceable> to elements of <replaceable class="parameter">vector</replaceable> that are listed in <replaceable class="parameter">lexemes</replaceable></entry>
- <entry><literal>setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A', '{cat,rat}')</literal></entry>
- <entry><literal>'cat':3A 'fat':2,4 'rat':5A</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>strip</primary>
- </indexterm>
- <literal><function>strip(<type>tsvector</type>)</function></literal>
- </entry>
- <entry><type>tsvector</type></entry>
- <entry>remove positions and weights from <type>tsvector</type></entry>
- <entry><literal>strip('fat:2,4 cat:3 rat:5A'::tsvector)</literal></entry>
- <entry><literal>'cat' 'fat' 'rat'</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>to_tsquery</primary>
- </indexterm>
- <literal><function>to_tsquery(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type> , </optional> <replaceable class="parameter">query</replaceable> <type>text</type>)</function></literal>
- </entry>
- <entry><type>tsquery</type></entry>
- <entry>normalize words and convert to <type>tsquery</type></entry>
- <entry><literal>to_tsquery('english', 'The & Fat & Rats')</literal></entry>
- <entry><literal>'fat' & 'rat'</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>to_tsvector</primary>
- </indexterm>
- <literal><function>to_tsvector(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type> , </optional> <replaceable class="parameter">document</replaceable> <type>text</type>)</function></literal>
- </entry>
- <entry><type>tsvector</type></entry>
- <entry>reduce document text to <type>tsvector</type></entry>
- <entry><literal>to_tsvector('english', 'The Fat Rats')</literal></entry>
- <entry><literal>'fat':2 'rat':3</literal></entry>
- </row>
- <row>
- <entry>
- <literal><function>to_tsvector(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type> , </optional> <replaceable class="parameter">document</replaceable> <type>json(b)</type>)</function></literal>
- </entry>
- <entry><type>tsvector</type></entry>
- <entry>
- reduce each string value in the document to a <type>tsvector</type>, and then
- concatenate those in document order to produce a single <type>tsvector</type>
- </entry>
- <entry><literal>to_tsvector('english', '{"a": "The Fat Rats"}'::json)</literal></entry>
- <entry><literal>'fat':2 'rat':3</literal></entry>
- </row>
- <row>
- <entry>
- <literal><function>json(b)_to_tsvector(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type>,
- </optional> <replaceable class="parameter">document</replaceable> <type>json(b)</type>,
- <replaceable class="parameter">filter</replaceable> <type>json(b)</type>)</function></literal>
- </entry>
- <entry><type>tsvector</type></entry>
- <entry>
- reduce each value in the document, specified by <replaceable class="parameter">filter</replaceable> to a <type>tsvector</type>,
- and then concatenate those in document order to produce a single <type>tsvector</type>.
- <replaceable class="parameter">filter</replaceable> is a <type>jsonb</type> array, that enumerates what kind of elements need to be included
- into the resulting <type>tsvector</type>. Possible values for <replaceable class="parameter">filter</replaceable> are
- <literal>"string"</literal> (to include all string values), <literal>"numeric"</literal> (to include all numeric values in the string format),
- <literal>"boolean"</literal> (to include all Boolean values in the string format <literal>"true"</literal>/<literal>"false"</literal>),
- <literal>"key"</literal> (to include all keys) or <literal>"all"</literal> (to include all above). These values
- can be combined together to include, e.g. all string and numeric values.
- </entry>
- <entry><literal>json_to_tsvector('english', '{"a": "The Fat Rats", "b": 123}'::json, '["string", "numeric"]')</literal></entry>
- <entry><literal>'123':5 'fat':2 'rat':3</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>ts_delete</primary>
- </indexterm>
- <literal><function>ts_delete(<replaceable class="parameter">vector</replaceable> <type>tsvector</type>, <replaceable class="parameter">lexeme</replaceable> <type>text</type>)</function></literal>
- </entry>
- <entry><type>tsvector</type></entry>
- <entry>remove given <replaceable class="parameter">lexeme</replaceable> from <replaceable class="parameter">vector</replaceable></entry>
- <entry><literal>ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat')</literal></entry>
- <entry><literal>'cat':3 'rat':5A</literal></entry>
- </row>
- <row>
- <entry>
- <!-- previous indexterm entry covers this too -->
- <literal><function>ts_delete(<replaceable class="parameter">vector</replaceable> <type>tsvector</type>, <replaceable class="parameter">lexemes</replaceable> <type>text[]</type>)</function></literal>
- </entry>
- <entry><type>tsvector</type></entry>
- <entry>remove any occurrence of lexemes in <replaceable class="parameter">lexemes</replaceable> from <replaceable class="parameter">vector</replaceable></entry>
- <entry><literal>ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat'])</literal></entry>
- <entry><literal>'cat':3</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>ts_filter</primary>
- </indexterm>
- <literal><function>ts_filter(<replaceable class="parameter">vector</replaceable> <type>tsvector</type>, <replaceable class="parameter">weights</replaceable> <type>"char"[]</type>)</function></literal>
- </entry>
- <entry><type>tsvector</type></entry>
- <entry>select only elements with given <replaceable class="parameter">weights</replaceable> from <replaceable class="parameter">vector</replaceable></entry>
- <entry><literal>ts_filter('fat:2,4 cat:3b rat:5A'::tsvector, '{a,b}')</literal></entry>
- <entry><literal>'cat':3B 'rat':5A</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>ts_headline</primary>
- </indexterm>
- <literal><function>ts_headline(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type>, </optional> <replaceable class="parameter">document</replaceable> <type>text</type>, <replaceable class="parameter">query</replaceable> <type>tsquery</type> <optional>, <replaceable class="parameter">options</replaceable> <type>text</type> </optional>)</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>display a query match</entry>
- <entry><literal>ts_headline('x y z', 'z'::tsquery)</literal></entry>
- <entry><literal>x y <b>z</b></literal></entry>
- </row>
- <row>
- <entry>
- <literal><function>ts_headline(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type>, </optional> <replaceable class="parameter">document</replaceable> <type>json(b)</type>, <replaceable class="parameter">query</replaceable> <type>tsquery</type> <optional>, <replaceable class="parameter">options</replaceable> <type>text</type> </optional>)</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>display a query match</entry>
- <entry><literal>ts_headline('{"a":"x y z"}'::json, 'z'::tsquery)</literal></entry>
- <entry><literal>{"a":"x y <b>z</b>"}</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>ts_rank</primary>
- </indexterm>
- <literal><function>ts_rank(<optional> <replaceable class="parameter">weights</replaceable> <type>float4[]</type>, </optional> <replaceable class="parameter">vector</replaceable> <type>tsvector</type>, <replaceable class="parameter">query</replaceable> <type>tsquery</type> <optional>, <replaceable class="parameter">normalization</replaceable> <type>integer</type> </optional>)</function></literal>
- </entry>
- <entry><type>float4</type></entry>
- <entry>rank document for query</entry>
- <entry><literal>ts_rank(textsearch, query)</literal></entry>
- <entry><literal>0.818</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>ts_rank_cd</primary>
- </indexterm>
- <literal><function>ts_rank_cd(<optional> <replaceable class="parameter">weights</replaceable> <type>float4[]</type>, </optional> <replaceable class="parameter">vector</replaceable> <type>tsvector</type>, <replaceable class="parameter">query</replaceable> <type>tsquery</type> <optional>, <replaceable class="parameter">normalization</replaceable> <type>integer</type> </optional>)</function></literal>
- </entry>
- <entry><type>float4</type></entry>
- <entry>rank document for query using cover density</entry>
- <entry><literal>ts_rank_cd('{0.1, 0.2, 0.4, 1.0}', textsearch, query)</literal></entry>
- <entry><literal>2.01317</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>ts_rewrite</primary>
- </indexterm>
- <literal><function>ts_rewrite(<replaceable class="parameter">query</replaceable> <type>tsquery</type>, <replaceable class="parameter">target</replaceable> <type>tsquery</type>, <replaceable class="parameter">substitute</replaceable> <type>tsquery</type>)</function></literal>
- </entry>
- <entry><type>tsquery</type></entry>
- <entry>replace <replaceable>target</replaceable> with <replaceable>substitute</replaceable>
- within query</entry>
- <entry><literal>ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery)</literal></entry>
- <entry><literal>'b' & ( 'foo' | 'bar' )</literal></entry>
- </row>
- <row>
- <entry><literal><function>ts_rewrite(<replaceable class="parameter">query</replaceable> <type>tsquery</type>, <replaceable class="parameter">select</replaceable> <type>text</type>)</function></literal></entry>
- <entry><type>tsquery</type></entry>
- <entry>replace using targets and substitutes from a <command>SELECT</command> command</entry>
- <entry><literal>SELECT ts_rewrite('a & b'::tsquery, 'SELECT t,s FROM aliases')</literal></entry>
- <entry><literal>'b' & ( 'foo' | 'bar' )</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>tsquery_phrase</primary>
- </indexterm>
- <literal><function>tsquery_phrase(<replaceable class="parameter">query1</replaceable> <type>tsquery</type>, <replaceable class="parameter">query2</replaceable> <type>tsquery</type>)</function></literal>
- </entry>
- <entry><type>tsquery</type></entry>
- <entry>make query that searches for <replaceable>query1</replaceable> followed
- by <replaceable>query2</replaceable> (same as <literal><-></literal>
- operator)</entry>
- <entry><literal>tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'))</literal></entry>
- <entry><literal>'fat' <-> 'cat'</literal></entry>
- </row>
- <row>
- <entry>
- <literal><function>tsquery_phrase(<replaceable class="parameter">query1</replaceable> <type>tsquery</type>, <replaceable class="parameter">query2</replaceable> <type>tsquery</type>, <replaceable class="parameter">distance</replaceable> <type>integer</type>)</function></literal>
- </entry>
- <entry><type>tsquery</type></entry>
- <entry>make query that searches for <replaceable>query1</replaceable> followed by
- <replaceable>query2</replaceable> at distance <replaceable>distance</replaceable></entry>
- <entry><literal>tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10)</literal></entry>
- <entry><literal>'fat' <10> 'cat'</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>tsvector_to_array</primary>
- </indexterm>
- <literal><function>tsvector_to_array(<type>tsvector</type>)</function></literal>
- </entry>
- <entry><type>text[]</type></entry>
- <entry>convert <type>tsvector</type> to array of lexemes</entry>
- <entry><literal>tsvector_to_array('fat:2,4 cat:3 rat:5A'::tsvector)</literal></entry>
- <entry><literal>{cat,fat,rat}</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>tsvector_update_trigger</primary>
- </indexterm>
- <literal><function>tsvector_update_trigger()</function></literal>
- </entry>
- <entry><type>trigger</type></entry>
- <entry>trigger function for automatic <type>tsvector</type> column update</entry>
- <entry><literal>CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body)</literal></entry>
- <entry><literal></literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>tsvector_update_trigger_column</primary>
- </indexterm>
- <literal><function>tsvector_update_trigger_column()</function></literal>
- </entry>
- <entry><type>trigger</type></entry>
- <entry>trigger function for automatic <type>tsvector</type> column update</entry>
- <entry><literal>CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, configcol, title, body)</literal></entry>
- <entry><literal></literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>unnest</primary>
- <secondary>for tsvector</secondary>
- </indexterm>
- <literal><function>unnest(<type>tsvector</type>, OUT <replaceable class="parameter">lexeme</replaceable> <type>text</type>, OUT <replaceable class="parameter">positions</replaceable> <type>smallint[]</type>, OUT <replaceable class="parameter">weights</replaceable> <type>text</type>)</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>expand a <type>tsvector</type> to a set of rows</entry>
- <entry><literal>unnest('fat:2,4 cat:3 rat:5A'::tsvector)</literal></entry>
- <entry><literal>(cat,{3},{D}) ...</literal></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <table id="textsearch-functions-table">
+ <title>Text Search Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="functableentry">
+ Function<?br?>Description<?br?>Example(s)
+ </entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>array_to_tsvector</primary>
+ </indexterm>
+ <function>array_to_tsvector</function> ( <type>text[]</type> )
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Converts an array of lexemes to a <type>tsvector</type>.
+ The given strings are used as-is without further processing.
+ <?br?>
+ <literal>array_to_tsvector('{fat,cat,rat}'::text[])</literal>
+ <returnvalue>'cat' 'fat' 'rat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>get_current_ts_config</primary>
+ </indexterm>
+ <function>get_current_ts_config</function> ( )
+ <returnvalue>regconfig</returnvalue>
+ <?br?>
+ Returns the OID of the current default text search configuration
+ (as set by <xref linkend="guc-default-text-search-config"/>).
+ <?br?>
+ <literal>get_current_ts_config()</literal>
+ <returnvalue>english</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>length</primary>
+ </indexterm>
+ <function>length</function> ( <type>tsvector</type> )
+ <returnvalue>integer</returnvalue>
+ <?br?>
+ Returns the number of lexemes in the <type>tsvector</type>.
+ <?br?>
+ <literal>length('fat:2,4 cat:3 rat:5A'::tsvector)</literal>
+ <returnvalue>3</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>numnode</primary>
+ </indexterm>
+ <function>numnode</function> ( <type>tsquery</type> )
+ <returnvalue>integer</returnvalue>
+ <?br?>
+ Returns the number of lexemes plus operators in
+ the <type>tsquery</type>.
+ <?br?>
+ <literal>numnode('(fat & rat) | cat'::tsquery)</literal>
+ <returnvalue>5</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>plainto_tsquery</primary>
+ </indexterm>
+ <function>plainto_tsquery</function> (
+ <optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
+ <replaceable>query</replaceable> <type>text</type> )
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ Converts text to a <type>tsquery</type>, normalizing words according to
+ the specified or default configuration. Any punctuation in the string
+ is ignored (it does not determine query operators). The resulting
+ query matches documents containing all non-stopwords in the text.
+ <?br?>
+ <literal>plainto_tsquery('english', 'The Fat Rats')</literal>
+ <returnvalue>'fat' & 'rat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>phraseto_tsquery</primary>
+ </indexterm>
+ <function>phraseto_tsquery</function> (
+ <optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
+ <replaceable>query</replaceable> <type>text</type> )
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ Converts text to a <type>tsquery</type>, normalizing words according to
+ the specified or default configuration. Any punctuation in the string
+ is ignored (it does not determine query operators). The resulting
+ query matches phrases containing all non-stopwords in the text.
+ <?br?>
+ <literal>phraseto_tsquery('english', 'The Fat Rats')</literal>
+ <returnvalue>'fat' <-> 'rat'</returnvalue>
+ <?br?>
+ <literal>phraseto_tsquery('english', 'The Cat and Rats')</literal>
+ <returnvalue>'cat' <2> 'rat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>websearch_to_tsquery</primary>
+ </indexterm>
+ <function>websearch_to_tsquery</function> (
+ <optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
+ <replaceable>query</replaceable> <type>text</type> )
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ Converts text to a <type>tsquery</type>, normalizing words according to
+ the specified or default configuration. Quoted word sequences are
+ converted to phrase tests, and the word <quote>or</quote> is
+ understood as producing an OR operator. This approximates the
+ behavior of some common web search tools.
+ <?br?>
+ <literal>websearch_to_tsquery('english', '"fat rat" or cat dog')</literal>
+ <returnvalue>'fat' <-> 'rat' | 'cat' & 'dog'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>querytree</primary>
+ </indexterm>
+ <function>querytree</function> ( <type>tsquery</type> )
+ <returnvalue>text</returnvalue>
+ <?br?>
+ Produces a representation of the indexable portion of
+ a <type>tsquery</type>. A result that is empty or
+ just <literal>T</literal> indicates a non-indexable query.
+ <?br?>
+ <literal>querytree('foo & ! bar'::tsquery)</literal>
+ <returnvalue>'foo'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>setweight</primary>
+ </indexterm>
+ <function>setweight</function> ( <replaceable>vector</replaceable> <type>tsvector</type>, <replaceable>weight</replaceable> <type>"char"</type> )
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Assigns the specified <replaceable>weight</replaceable> to each element
+ of the <replaceable>vector</replaceable>.
+ <?br?>
+ <literal>setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A')</literal>
+ <returnvalue>'cat':3A 'fat':2A,4A 'rat':5A</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>setweight</primary>
+ <secondary>setweight for specific lexeme(s)</secondary>
+ </indexterm>
+ <function>setweight</function> ( <replaceable>vector</replaceable> <type>tsvector</type>, <replaceable>weight</replaceable> <type>"char"</type>, <replaceable>lexemes</replaceable> <type>text[]</type> )
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Assigns the specified <replaceable>weight</replaceable> to elements
+ of the <replaceable>vector</replaceable> that are listed
+ in <replaceable>lexemes</replaceable>.
+ <?br?>
+ <literal>setweight('fat:2,4 cat:3 rat:5,6B'::tsvector, 'A', '{cat,rat}')</literal>
+ <returnvalue>'cat':3A 'fat':2,4 'rat':5A,6A</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>strip</primary>
+ </indexterm>
+ <function>strip</function> ( <type>tsvector</type> )
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Removes positions and weights from the <type>tsvector</type>.
+ <?br?>
+ <literal>strip('fat:2,4 cat:3 rat:5A'::tsvector)</literal>
+ <returnvalue>'cat' 'fat' 'rat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>to_tsquery</primary>
+ </indexterm>
+ <function>to_tsquery</function> (
+ <optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
+ <replaceable>query</replaceable> <type>text</type> )
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ Converts text to a <type>tsquery</type>, normalizing words according to
+ the specified or default configuration. The words must be combined
+ by valid <type>tsquery</type> operators.
+ <?br?>
+ <literal>to_tsquery('english', 'The & Fat & Rats')</literal>
+ <returnvalue>'fat' & 'rat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>to_tsvector</primary>
+ </indexterm>
+ <function>to_tsvector</function> (
+ <optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
+ <replaceable>document</replaceable> <type>text</type> )
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Converts text to a <type>tsvector</type>, normalizing words according
+ to the specified or default configuration. Position information is
+ included in the result.
+ <?br?>
+ <literal>to_tsvector('english', 'The Fat Rats')</literal>
+ <returnvalue>'fat':2 'rat':3</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <function>to_tsvector</function> (
+ <optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
+ <replaceable>document</replaceable> <type>json(b)</type> )
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Converts each string value in the JSON document to
+ a <type>tsvector</type>, normalizing words according to the specified
+ or default configuration. The results are then concatenated in
+ document order to produce the output. Position information is
+ generated as though one stopword exists between each pair of string
+ values. (Beware that <quote>document order</quote> of the fields of a
+ JSON object is implementation-dependent when the input
+ is <type>jsonb</type>; observe the difference in the examples.)
+ <?br?>
+ <literal>to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::json)</literal>
+ <returnvalue>'dog':5 'fat':2 'rat':3</returnvalue>
+ <?br?>
+ <literal>to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::jsonb)</literal>
+ <returnvalue>'dog':1 'fat':4 'rat':5</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>json(b)_to_tsvector</primary>
+ </indexterm>
+ <function>json(b)_to_tsvector</function> (
+ <optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
+ <replaceable>document</replaceable> <type>json(b)</type>,
+ <replaceable>filter</replaceable> <type>jsonb</type> )
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Selects each item in the JSON document that is requested by
+ the <replaceable>filter</replaceable> and converts each one to
+ a <type>tsvector</type>, normalizing words according to the specified
+ or default configuration. The results are then concatenated in
+ document order to produce the output. Position information is
+ generated as though one stopword exists between each pair of selected
+ items. (Beware that <quote>document order</quote> of the fields of a
+ JSON object is implementation-dependent when the input
+ is <type>jsonb</type>.)
+ The <replaceable>filter</replaceable> must be a <type>jsonb</type>
+ array containing zero or more of these keywords:
+ <literal>"string"</literal> (to include all string values),
+ <literal>"numeric"</literal> (to include all numeric values),
+ <literal>"boolean"</literal> (to include all boolean values),
+ <literal>"key"</literal> (to include all keys), or
+ <literal>"all"</literal> (to include all the above).
+ As a special case, the <replaceable>filter</replaceable> can also be a
+ simple JSON value that is one of these keywords.
+ <?br?>
+ <literal>json_to_tsvector('english', '{"a": "The Fat Rats", "b": 123}'::json, '["string", "numeric"]')</literal>
+ <returnvalue>'123':5 'fat':2 'rat':3</returnvalue>
+ <?br?>
+ <literal>json_to_tsvector('english', '{"cat": "The Fat Rats", "dog": 123}'::json, '"all"')</literal>
+ <returnvalue>'123':9 'cat':1 'dog':7 'fat':4 'rat':5</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_delete</primary>
+ </indexterm>
+ <function>ts_delete</function> ( <replaceable>vector</replaceable> <type>tsvector</type>, <replaceable>lexeme</replaceable> <type>text</type> )
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Removes any occurrence of the given <replaceable>lexeme</replaceable>
+ from the <replaceable>vector</replaceable>.
+ <?br?>
+ <literal>ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat')</literal>
+ <returnvalue>'cat':3 'rat':5A</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <function>ts_delete</function> ( <replaceable>vector</replaceable> <type>tsvector</type>, <replaceable>lexemes</replaceable> <type>text[]</type> )
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Removes any occurrences of the lexemes
+ in <replaceable>lexemes</replaceable>
+ from the <replaceable>vector</replaceable>.
+ <?br?>
+ <literal>ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat'])</literal>
+ <returnvalue>'cat':3</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_filter</primary>
+ </indexterm>
+ <function>ts_filter</function> ( <replaceable>vector</replaceable> <type>tsvector</type>, <replaceable>weights</replaceable> <type>"char"[]</type> )
+ <returnvalue>tsvector</returnvalue>
+ <?br?>
+ Selects only elements with the given <replaceable>weights</replaceable>
+ from the <replaceable>vector</replaceable>.
+ <?br?>
+ <literal>ts_filter('fat:2,4 cat:3b,7c rat:5A'::tsvector, '{a,b}')</literal>
+ <returnvalue>'cat':3B 'rat':5A</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_headline</primary>
+ </indexterm>
+ <function>ts_headline</function> (
+ <optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
+ <replaceable>document</replaceable> <type>text</type>,
+ <replaceable>query</replaceable> <type>tsquery</type>
+ <optional>, <replaceable>options</replaceable> <type>text</type> </optional> )
+ <returnvalue>text</returnvalue>
+ <?br?>
+ Displays, in an abbreviated form, the match(es) for
+ the <replaceable>query</replaceable> in
+ the <replaceable>document</replaceable>, which must be raw text not
+ a <type>tsvector</type>. Words in the document are normalized
+ according to the specified or default configuration before matching to
+ the query. Use of this function is discussed in
+ <xref linkend="textsearch-headline"/>, which also describes the
+ available <replaceable>options</replaceable>.
+ <?br?>
+ <literal>ts_headline('The fat cat ate the rat.', 'cat')</literal>
+ <returnvalue>The fat <b>cat</b> ate the rat.</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <function>ts_headline</function> (
+ <optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
+ <replaceable>document</replaceable> <type>json(b)</type>,
+ <replaceable>query</replaceable> <type>tsquery</type>
+ <optional>, <replaceable>options</replaceable> <type>text</type> </optional> )
+ <returnvalue>text</returnvalue>
+ <?br?>
+ Displays, in an abbreviated form, match(es) for
+ the <replaceable>query</replaceable> that occur in string values
+ within the JSON <replaceable>document</replaceable>.
+ See <xref linkend="textsearch-headline"/> for more details.
+ <?br?>
+ <literal>ts_headline('{"cat":"raining cats and dogs"}'::jsonb, 'cat')</literal>
+ <returnvalue>{"cat": "raining <b>cats</b> and dogs"}</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_rank</primary>
+ </indexterm>
+ <function>ts_rank</function> (
+ <optional> <replaceable>weights</replaceable> <type>real[]</type>, </optional>
+ <replaceable>vector</replaceable> <type>tsvector</type>,
+ <replaceable>query</replaceable> <type>tsquery</type>
+ <optional>, <replaceable>normalization</replaceable> <type>integer</type> </optional> )
+ <returnvalue>real</returnvalue>
+ <?br?>
+ Computes a score showing how well
+ the <replaceable>vector</replaceable> matches
+ the <replaceable>query</replaceable>. See
+ <xref linkend="textsearch-ranking"/> for details.
+ <?br?>
+ <literal>ts_rank(to_tsvector('raining cats and dogs'), 'cat')</literal>
+ <returnvalue>0.06079271</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_rank_cd</primary>
+ </indexterm>
+ <function>ts_rank_cd</function> (
+ <optional> <replaceable>weights</replaceable> <type>real[]</type>, </optional>
+ <replaceable>vector</replaceable> <type>tsvector</type>,
+ <replaceable>query</replaceable> <type>tsquery</type>
+ <optional>, <replaceable>normalization</replaceable> <type>integer</type> </optional> )
+ <returnvalue>real</returnvalue>
+ <?br?>
+ Computes a score showing how well
+ the <replaceable>vector</replaceable> matches
+ the <replaceable>query</replaceable>, using a cover density
+ algorithm. See <xref linkend="textsearch-ranking"/> for details.
+ <?br?>
+ <literal>ts_rank_cd(to_tsvector('raining cats and dogs'), 'cat')</literal>
+ <returnvalue>0.1</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_rewrite</primary>
+ </indexterm>
+ <function>ts_rewrite</function> ( <replaceable>query</replaceable> <type>tsquery</type>,
+ <replaceable>target</replaceable> <type>tsquery</type>,
+ <replaceable>substitute</replaceable> <type>tsquery</type> )
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ Replaces occurrences of <replaceable>target</replaceable>
+ with <replaceable>substitute</replaceable>
+ within the <replaceable>query</replaceable>.
+ See <xref linkend="textsearch-query-rewriting"/> for details.
+ <?br?>
+ <literal>ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery)</literal>
+ <returnvalue>'b' & ( 'foo' | 'bar' )</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <function>ts_rewrite</function> ( <replaceable>query</replaceable> <type>tsquery</type>,
+ <replaceable>select</replaceable> <type>text</type> )
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ Replaces portions of the <replaceable>query</replaceable> according to
+ target(s) and substitute(s) obtained by executing
+ a <command>SELECT</command> command.
+ See <xref linkend="textsearch-query-rewriting"/> for details.
+ <?br?>
+ <literal>SELECT ts_rewrite('a & b'::tsquery, 'SELECT t,s FROM aliases')</literal>
+ <returnvalue>'b' & ( 'foo' | 'bar' )</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>tsquery_phrase</primary>
+ </indexterm>
+ <function>tsquery_phrase</function> ( <replaceable>query1</replaceable> <type>tsquery</type>, <replaceable>query2</replaceable> <type>tsquery</type> )
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ Constructs a phrase query that searches
+ for matches of <replaceable>query1</replaceable>
+ and <replaceable>query2</replaceable> at successive lexemes (same
+ as <literal><-></literal> operator).
+ <?br?>
+ <literal>tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'))</literal>
+ <returnvalue>'fat' <-> 'cat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <function>tsquery_phrase</function> ( <replaceable>query1</replaceable> <type>tsquery</type>, <replaceable>query2</replaceable> <type>tsquery</type>, <replaceable>distance</replaceable> <type>integer</type> )
+ <returnvalue>tsquery</returnvalue>
+ <?br?>
+ Constructs a phrase query that searches
+ for matches of <replaceable>query1</replaceable> and
+ <replaceable>query2</replaceable> that occur exactly
+ <replaceable>distance</replaceable> lexemes apart.
+ <?br?>
+ <literal>tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10)</literal>
+ <returnvalue>'fat' <10> 'cat'</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>tsvector_to_array</primary>
+ </indexterm>
+ <function>tsvector_to_array</function> ( <type>tsvector</type> )
+ <returnvalue>text[]</returnvalue>
+ <?br?>
+ Converts a <type>tsvector</type> to an array of lexemes.
+ <?br?>
+ <literal>tsvector_to_array('fat:2,4 cat:3 rat:5A'::tsvector)</literal>
+ <returnvalue>{cat,fat,rat}</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>unnest</primary>
+ <secondary>for tsvector</secondary>
+ </indexterm>
+ <function>unnest</function> ( <type>tsvector</type>,
+ <literal>OUT</literal> <replaceable>lexeme</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>positions</replaceable> <type>smallint[]</type>,
+ <literal>OUT</literal> <replaceable>weights</replaceable> <type>text</type> )
+ <returnvalue>setof record</returnvalue>
+ <?br?>
+ Expands a <type>tsvector</type> into a set of rows, one per lexeme.
+ <?br?>
+ <literal>unnest('cat:3 fat:2,4 rat:5A'::tsvector)</literal>
+ <returnvalue>(cat,{3},{D})<?br?>(fat,"{2,4}","{D,D}")<?br?>(rat,{5},{A})</returnvalue><?br?>(3 rows in result)
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<note>
<para>
The functions in
<xref linkend="textsearch-functions-debug-table"/>
are listed separately because they are not usually used in everyday text
- searching operations. They are helpful for development and debugging
- of new text search configurations.
+ searching operations. They are primarily helpful for development and
+ debugging of new text search configurations.
</para>
- <table id="textsearch-functions-debug-table">
- <title>Text Search Debugging Functions</title>
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <indexterm>
- <primary>ts_debug</primary>
- </indexterm>
- <literal><function>ts_debug(<optional> <replaceable class="parameter">config</replaceable> <type>regconfig</type>, </optional> <replaceable class="parameter">document</replaceable> <type>text</type>, OUT <replaceable class="parameter">alias</replaceable> <type>text</type>, OUT <replaceable class="parameter">description</replaceable> <type>text</type>, OUT <replaceable class="parameter">token</replaceable> <type>text</type>, OUT <replaceable class="parameter">dictionaries</replaceable> <type>regdictionary[]</type>, OUT <replaceable class="parameter">dictionary</replaceable> <type>regdictionary</type>, OUT <replaceable class="parameter">lexemes</replaceable> <type>text[]</type>)</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>test a configuration</entry>
- <entry><literal>ts_debug('english', 'The Brightest supernovaes')</literal></entry>
- <entry><literal>(asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ...</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>ts_lexize</primary>
- </indexterm>
- <literal><function>ts_lexize(<replaceable class="parameter">dict</replaceable> <type>regdictionary</type>, <replaceable class="parameter">token</replaceable> <type>text</type>)</function></literal>
- </entry>
- <entry><type>text[]</type></entry>
- <entry>test a dictionary</entry>
- <entry><literal>ts_lexize('english_stem', 'stars')</literal></entry>
- <entry><literal>{star}</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>ts_parse</primary>
- </indexterm>
- <literal><function>ts_parse(<replaceable class="parameter">parser_name</replaceable> <type>text</type>, <replaceable class="parameter">document</replaceable> <type>text</type>, OUT <replaceable class="parameter">tokid</replaceable> <type>integer</type>, OUT <replaceable class="parameter">token</replaceable> <type>text</type>)</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>test a parser</entry>
- <entry><literal>ts_parse('default', 'foo - bar')</literal></entry>
- <entry><literal>(1,foo) ...</literal></entry>
- </row>
- <row>
- <entry><literal><function>ts_parse(<replaceable class="parameter">parser_oid</replaceable> <type>oid</type>, <replaceable class="parameter">document</replaceable> <type>text</type>, OUT <replaceable class="parameter">tokid</replaceable> <type>integer</type>, OUT <replaceable class="parameter">token</replaceable> <type>text</type>)</function></literal></entry>
- <entry><type>setof record</type></entry>
- <entry>test a parser</entry>
- <entry><literal>ts_parse(3722, 'foo - bar')</literal></entry>
- <entry><literal>(1,foo) ...</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>ts_token_type</primary>
- </indexterm>
- <literal><function>ts_token_type(<replaceable class="parameter">parser_name</replaceable> <type>text</type>, OUT <replaceable class="parameter">tokid</replaceable> <type>integer</type>, OUT <replaceable class="parameter">alias</replaceable> <type>text</type>, OUT <replaceable class="parameter">description</replaceable> <type>text</type>)</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>get token types defined by parser</entry>
- <entry><literal>ts_token_type('default')</literal></entry>
- <entry><literal>(1,asciiword,"Word, all ASCII") ...</literal></entry>
- </row>
- <row>
- <entry><literal><function>ts_token_type(<replaceable class="parameter">parser_oid</replaceable> <type>oid</type>, OUT <replaceable class="parameter">tokid</replaceable> <type>integer</type>, OUT <replaceable class="parameter">alias</replaceable> <type>text</type>, OUT <replaceable class="parameter">description</replaceable> <type>text</type>)</function></literal></entry>
- <entry><type>setof record</type></entry>
- <entry>get token types defined by parser</entry>
- <entry><literal>ts_token_type(3722)</literal></entry>
- <entry><literal>(1,asciiword,"Word, all ASCII") ...</literal></entry>
- </row>
- <row>
- <entry>
- <indexterm>
- <primary>ts_stat</primary>
- </indexterm>
- <literal><function>ts_stat(<replaceable class="parameter">sqlquery</replaceable> <type>text</type>, <optional> <replaceable class="parameter">weights</replaceable> <type>text</type>, </optional> OUT <replaceable class="parameter">word</replaceable> <type>text</type>, OUT <replaceable class="parameter">ndoc</replaceable> <type>integer</type>, OUT <replaceable class="parameter">nentry</replaceable> <type>integer</type>)</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>get statistics of a <type>tsvector</type> column</entry>
- <entry><literal>ts_stat('SELECT vector from apod')</literal></entry>
- <entry><literal>(foo,10,15) ...</literal></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <table id="textsearch-functions-debug-table">
+ <title>Text Search Debugging Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="functableentry">
+ Function<?br?>Description<?br?>Example(s)
+ </entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_debug</primary>
+ </indexterm>
+ <function>ts_debug</function> (
+ <optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
+ <replaceable>document</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>alias</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>description</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>token</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>dictionaries</replaceable> <type>regdictionary[]</type>,
+ <literal>OUT</literal> <replaceable>dictionary</replaceable> <type>regdictionary</type>,
+ <literal>OUT</literal> <replaceable>lexemes</replaceable> <type>text[]</type> )
+ <returnvalue>setof record</returnvalue>
+ <?br?>
+ Extracts and normalizes tokens from
+ the <replaceable>document</replaceable> according to the specified or
+ default text search configuration, and returns information about how
+ each token was processed.
+ See <xref linkend="textsearch-configuration-testing"/> for details.
+ <?br?>
+ <literal>ts_debug('english', 'The Brightest supernovaes')</literal>
+ <returnvalue>(asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ...</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_lexize</primary>
+ </indexterm>
+ <function>ts_lexize</function> ( <replaceable>dict</replaceable> <type>regdictionary</type>, <replaceable>token</replaceable> <type>text</type> )
+ <returnvalue>text[]</returnvalue>
+ <?br?>
+ Returns an array of replacement lexemes if the input token is known to
+ the dictionary, or an empty array if the token is known to the
+ dictionary but it is a stop word, or NULL if it is not a known word.
+ See <xref linkend="textsearch-dictionary-testing"/> for details.
+ <?br?>
+ <literal>ts_lexize('english_stem', 'stars')</literal>
+ <returnvalue>{star}</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_parse</primary>
+ </indexterm>
+ <function>ts_parse</function> ( <replaceable>parser_name</replaceable> <type>text</type>,
+ <replaceable>document</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>tokid</replaceable> <type>integer</type>,
+ <literal>OUT</literal> <replaceable>token</replaceable> <type>text</type> )
+ <returnvalue>setof record</returnvalue>
+ <?br?>
+ Extracts tokens from the <replaceable>document</replaceable> using the
+ named parser.
+ See <xref linkend="textsearch-parser-testing"/> for details.
+ <?br?>
+ <literal>ts_parse('default', 'foo - bar')</literal>
+ <returnvalue>(1,foo) ...</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <function>ts_parse</function> ( <replaceable>parser_oid</replaceable> <type>oid</type>,
+ <replaceable>document</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>tokid</replaceable> <type>integer</type>,
+ <literal>OUT</literal> <replaceable>token</replaceable> <type>text</type> )
+ <returnvalue>setof record</returnvalue>
+ <?br?>
+ Extracts tokens from the <replaceable>document</replaceable> using a
+ parser specified by OID.
+ See <xref linkend="textsearch-parser-testing"/> for details.
+ <?br?>
+ <literal>ts_parse(3722, 'foo - bar')</literal>
+ <returnvalue>(1,foo) ...</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_token_type</primary>
+ </indexterm>
+ <function>ts_token_type</function> ( <replaceable>parser_name</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>tokid</replaceable> <type>integer</type>,
+ <literal>OUT</literal> <replaceable>alias</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>description</replaceable> <type>text</type> )
+ <returnvalue>setof record</returnvalue>
+ <?br?>
+ Returns a table that describes each type of token the named parser can
+ recognize.
+ See <xref linkend="textsearch-parser-testing"/> for details.
+ <?br?>
+ <literal>ts_token_type('default')</literal>
+ <returnvalue>(1,asciiword,"Word, all ASCII") ...</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <function>ts_token_type</function> ( <replaceable>parser_oid</replaceable> <type>oid</type>,
+ <literal>OUT</literal> <replaceable>tokid</replaceable> <type>integer</type>,
+ <literal>OUT</literal> <replaceable>alias</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>description</replaceable> <type>text</type> )
+ <returnvalue>setof record</returnvalue>
+ <?br?>
+ Returns a table that describes each type of token a parser specified
+ by OID can recognize.
+ See <xref linkend="textsearch-parser-testing"/> for details.
+ <?br?>
+ <literal>ts_token_type(3722)</literal>
+ <returnvalue>(1,asciiword,"Word, all ASCII") ...</returnvalue>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>ts_stat</primary>
+ </indexterm>
+ <function>ts_stat</function> ( <replaceable>sqlquery</replaceable> <type>text</type>,
+ <optional> <replaceable>weights</replaceable> <type>text</type>, </optional>
+ <literal>OUT</literal> <replaceable>word</replaceable> <type>text</type>,
+ <literal>OUT</literal> <replaceable>ndoc</replaceable> <type>integer</type>,
+ <literal>OUT</literal> <replaceable>nentry</replaceable> <type>integer</type> )
+ <returnvalue>setof record</returnvalue>
+ <?br?>
+ Executes the <replaceable>sqlquery</replaceable>, which must return a
+ single <type>tsvector</type> column, and returns statistics about each
+ distinct lexeme contained in the data.
+ See <xref linkend="textsearch-statistics"/> for details.
+ <?br?>
+ <literal>ts_stat('SELECT vector FROM apod')</literal>
+ <returnvalue>(foo,10,15) ...</returnvalue>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</sect1>
<sect1 id="functions-trigger">
<title>Trigger Functions</title>
- <indexterm>
- <primary>suppress_redundant_updates_trigger</primary>
- </indexterm>
+ <para>
+ While many uses of triggers involve user-written trigger functions,
+ <productname>PostgreSQL</productname> provides a few built-in trigger
+ functions that can be used directly in user-defined triggers. These
+ are summarized in <xref linkend="builtin-triggers-table"/>.
+ (Additional built-in trigger functions exist, which implement foreign
+ key constraints and deferred index constraints. Those are not documented
+ here since users need not use them directly.)
+ </para>
+
+ <para>
+ For more information about creating triggers, see
+ <xref linkend="sql-createtrigger"/>.
+ </para>
+
+ <table id="builtin-triggers-table">
+ <title>Built-In Trigger Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="functableentry">
+ Function<?br?>Description<?br?>Example Usage
+ </entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>suppress_redundant_updates_trigger</primary>
+ </indexterm>
+ <function>suppress_redundant_updates_trigger</function> ( )
+ <returnvalue>trigger</returnvalue>
+ <?br?>
+ Suppresses do-nothing update operations. See below for details.
+ <?br?>
+ <literal>CREATE TRIGGER ... suppress_redundant_updates_trigger()</literal>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>tsvector_update_trigger</primary>
+ </indexterm>
+ <function>tsvector_update_trigger</function> ( )
+ <returnvalue>trigger</returnvalue>
+ <?br?>
+ Automatically updates a <type>tsvector</type> column from associated
+ plain-text document column(s). The text search configuration to use
+ is specified by name as a trigger argument. See
+ <xref linkend="textsearch-update-triggers"/> for details.
+ <?br?>
+ <literal>CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body)</literal>
+ </entry>
+ </row>
+
+ <row>
+ <entry role="functableentry">
+ <indexterm>
+ <primary>tsvector_update_trigger_column</primary>
+ </indexterm>
+ <function>tsvector_update_trigger_column</function> ( )
+ <returnvalue>trigger</returnvalue>
+ <?br?>
+ Automatically updates a <type>tsvector</type> column from associated
+ plain-text document column(s). The text search configuration to use
+ is taken from a <type>regconfig</type> column of the table. See
+ <xref linkend="textsearch-update-triggers"/> for details.
+ <?br?>
+ <literal>CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, tsconfigcol, title, body)</literal>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
- Currently <productname>PostgreSQL</productname> provides one built in trigger
- function, <function>suppress_redundant_updates_trigger</function>,
- which will prevent any update
- that does not actually change the data in the row from taking place, in
- contrast to the normal behavior which always performs the update
+ The <function>suppress_redundant_updates_trigger</function> function,
+ when applied as a row-level <literal>BEFORE UPDATE</literal> trigger,
+ will prevent any update that does not actually change the data in the
+ row from taking place. This overrides the normal behavior which always
+ performs a physical row update
regardless of whether or not the data has changed. (This normal behavior
makes updates run faster, since no checking is required, and is also
useful in certain cases.)
</para>
<para>
- Ideally, you should normally avoid running updates that don't actually
+ Ideally, you should avoid running updates that don't actually
change the data in the record. Redundant updates can cost considerable
unnecessary time, especially if there are lots of indexes to alter,
and space in dead rows that will eventually have to be vacuumed.
<function>suppress_redundant_updates_trigger</function>, which will skip
updates that don't change the data. You should use this with care,
however. The trigger takes a small but non-trivial time for each record,
- so if most of the records affected by an update are actually changed,
- use of this trigger will actually make the update run slower.
+ so if most of the records affected by updates do actually change,
+ use of this trigger will make updates run slower on average.
</para>
<para>
BEFORE UPDATE ON tablename
FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
</programlisting>
- In most cases, you would want to fire this trigger last for each row.
- Bearing in mind that triggers fire in name order, you would then
+ In most cases, you need to fire this trigger last for each row, so that
+ it does not override other triggers that might wish to alter the row.
+ Bearing in mind that triggers fire in name order, you would therefore
choose a trigger name that comes after the name of any other trigger
- you might have on the table.
- </para>
- <para>
- For more information about creating triggers, see
- <xref linkend="sql-createtrigger"/>.
+ you might have on the table. (Hence the <quote>z</quote> prefix in the
+ example.)
</para>
</sect1>
projects / users / rhaas / postgres.git / commitdiff