<para>

A <type>tsquery</type> value stores lexemes that are to be

searched for, and combines them honoring the Boolean operators

<literal>&amp;</literal> (AND), <literal>|</literal> (OR), and

<literal>!</> (NOT). Parentheses can be used to enforce grouping

<literal>&amp;</literal> (AND), <literal>|</literal> (OR),

<literal>!</> (NOT) and <literal>?</> (FOLLOWED BY) phrase search

operator. Parentheses can be used to enforce grouping

of the operators:

<programlisting>

</programlisting>

In the absence of parentheses, <literal>!</> (NOT) binds most tightly,

and <literal>&amp;</literal> (AND)binds more tightly than

<literal>|</literal> (OR).

and <literal>&amp;</literal> (AND)and <literal>?</literal> (FOLLOWED BY)

both bind more tightly than<literal>|</literal> (OR).

</para>

<para>

<entry><literal>!! 'cat'::tsquery</literal></entry>

<entry><literal>!'cat'</literal></entry>

</row>

<row>

<entry> <literal>??</literal> </entry>

<entry><type>tsquery</> followed by <type>tsquery</></entry>

<entry><literal>to_tsquery('fat') ?? to_tsquery('rat')</literal></entry>

<entry><literal>'fat' ? 'rat'</literal></entry>

</row>

<row>

<entry> <literal>@&gt;</literal> </entry>

<entry><type>tsquery</> contains another ?</entry>

<entry><literal>plainto_tsquery('english', 'The Fat Rats')</literal></entry>

<entry><literal>'fat' &amp; 'rat'</literal></entry>

</row>

<row>

<entry>

<indexterm>

<primary>phraseto_tsquery</primary>

</indexterm>

<literal><function>phraseto_tsquery(<optional> <replaceable class="PARAMETER">config</> <type>regconfig</> , </optional> <replaceable class="PARAMETER">query</> <type>text</type>)</function></literal>

</entry>

<entry><type>tsquery</type></entry>

<entry>produce <type>tsquery</> ignoring punctuation</entry>

<entry><literal>phraseto_tsquery('english', 'The Fat Rats')</literal></entry>

<entry><literal>'fat' ? 'rat'</literal></entry>

</row>

<row>

<entry>

<indexterm>

<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>

<literal><function>setweight(<type>tsquery</>, <type>"char"</>)</function></literal>

</entry>

<entry><type>tsquery</type></entry>

<entry>add weight to each element of <type>tsquery</></entry>

<entry><literal>setweight('fat ? cat &amp; rat:B'::tsquery, 'A')</literal></entry>

<entry><literal>( 'fat':A ? 'cat':A ) &amp; 'rat':AB</literal></entry>

</row>

<row>

<entry>

<indexterm>

<entry><literal>SELECT ts_rewrite('a &amp; b'::tsquery, 'SELECT t,s FROM aliases')</literal></entry>

<entry><literal>'b' &amp; ( 'foo' | 'bar' )</literal></entry>

</row>

<row>

<entry>

<indexterm>

<primary>tsquery_phrase</primary>

</indexterm>

<literal><function>tsquery_phrase(<replaceable class="PARAMETER">query1</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">query2</replaceable> <type>tsquery</>)</function></literal>

</entry>

<entry><type>tsquery</type></entry>

<entry>implementation of <literal>??</> (FOLLOWED BY) 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</>, <replaceable class="PARAMETER">query2</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">distance</replaceable> <type>integer</>)</function></literal>

</entry>

<entry><type>tsquery</type></entry>

<entry>phrase-concatenate with distance</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>

<para>

<productname>&productname;</productname> provides the

functions <function>to_tsquery</function> and

<function>plainto_tsquery</function> for converting a query to

the <type>tsquery</type> data type. <function>to_tsquery</function>

offers access to more features than <function>plainto_tsquery</function>,

but is less forgiving about its input.

functions <function>to_tsquery</function>,

<function>plainto_tsquery</function> and

<function>phraseto_tsquery</function>

for converting a query to the <type>tsquery</type> data type.

<function>to_tsquery</function> offers access to more features

than both <function>plainto_tsquery</function> and

<function>phraseto_tsquery</function>, but is less forgiving

about its input.

</para>

<indexterm>

<function>to_tsquery</function> creates a <type>tsquery</> value from

<replaceable>querytext</replaceable>, which must consist of single tokens

separated by the Boolean operators <literal>&amp;</literal> (AND),

<literal>|</literal> (OR) and <literal>!</literal> (NOT). These operators

<literal>|</literal> (OR), <literal>!</literal> (NOT), and also the

<literal>?</literal> (FOLLOWED BY) phrase search operator. These operators

can be grouped using parentheses. In other words, the input to

<function>to_tsquery</function> must already follow the general rules for

<type>tsquery</> input, as described in <xref

</screen>

Note that <function>plainto_tsquery</> cannot

recognize Boolean operators, weight labels, or prefix-match labels

in its input:

recognize Booleanand phrase searchoperators, weight labels,

or prefix-match labelsin its input:

<screen>

SELECT plainto_tsquery('english', 'The Fat &amp; Rats:C');

Here, all the input punctuation was discarded as being space symbols.

</para>

<indexterm>

<primary>phraseto_tsquery</primary>

</indexterm>

<synopsis>

phraseto_tsquery(<optional> <replaceable class="PARAMETER">config</replaceable> <type>regconfig</>, </optional> <replaceable class="PARAMETER">querytext</replaceable> <type>text</>) returns <type>tsquery</>

</synopsis>

<para>

<function>phraseto_tsquery</> behaves much like

<function>plainto_tsquery</>, with the exception

that it utilizes the <literal>?</literal> (FOLLOWED BY) phrase search

operator instead of the <literal>&amp;</literal> (AND) Boolean operator.

This is particularly useful when searching for exact lexeme sequences,

since the phrase search operator helps to maintain lexeme order.

</para>

<para>

Example:

<screen>

SELECT phraseto_tsquery('english', 'The Fat Rats');

phraseto_tsquery

------------------

'fat' ? 'rat'

</screen>

Just like the <function>plainto_tsquery</>, the

<function>phraseto_tsquery</> function cannot

recognize Boolean and phrase search operators, weight labels,

or prefix-match labels in its input:

<screen>

SELECT phraseto_tsquery('english', 'The Fat &amp; Rats:C');

phraseto_tsquery

-------------------------

( 'fat' ? 'rat' ) ? 'c'

</screen>

</para>

</sect2>

<sect2 id="textsearch-ranking">

</varlistentry>

<varlistentry>

<term>

<literal><type>tsquery</> ?? <type>tsquery</></literal>

</term>

<listitem>

<para>

Returns the phrase-concatenation of the two given queries.

<screen>

SELECT to_tsquery('fat') ?? to_tsquery('cat | rat');

?column?

-------------------------------

'fat' ? 'cat' | 'fat' ? 'rat'

</screen>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<indexterm>

<primary>tsquery_phrase</primary>

</indexterm>

<literal><type>tsquery_phrase(<replaceable class="PARAMETER">query1</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">query2</replaceable> <type>tsquery</> [, <replaceable class="PARAMETER">distance</replaceable> <type>integer</> ]) returns <type>tsquery</></literal>

</term>

<listitem>

<para>

Returns the distanced phrase-concatenation of the two given queries.

This function lies in the implementation of the <literal>??</> operator.

<screen>

SELECT tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10);

tsquery_phrase

-------------------

'fat' ?[10] 'cat'

</screen>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<indexterm>

<primary>setweight</primary>

</indexterm>

<literal>setweight(<replaceable class="PARAMETER">query</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">weight</replaceable> <type>"char"</>) returns <type>tsquery</></literal>

</term>

<listitem>

<para>

<function>setweight</> returns a copy of the input query in which every

position has been labeled with the given <replaceable>weight</>, either

<literal>A</literal>, <literal>B</literal>, <literal>C</literal>, or

<literal>D</literal>. These labels are retained when queries are

concatenated, allowing words from different parts of a document

to be weighted differently by ranking functions.

</para>

<para>

Note that weight labels apply to <emphasis>positions</>, not

<emphasis>lexemes</>. If the input query has been stripped of

positions then <function>setweight</> does nothing.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>