Skip to content

Commit 6581e93

Browse files
tglsfdctglsfdc
committed
Polish the documentation concerning phrase text search.
Fix grammar, improve examples, etc. I did not attempt to document the current behavior concerning distance-zero matches, because I think that's broken and needs to change, so I'm not going to use up brain cells figuring out how to explain how it works now. One way or the other, there's still more to write here.
1 parent f721e94 commit 6581e93

File tree

3 files changed

+136
-85
lines changed

3 files changed

+136
-85
lines changed

‎doc/src/sgml/datatype.sgml‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3923,11 +3923,18 @@ SELECT to_tsvector('english', 'The Fat Rats');
39233923

39243924
<para>
39253925
A <type>tsquery</type> value stores lexemes that are to be
3926-
searched for, and combines them honoring the Boolean operators
3927-
<literal>&amp;</literal> (AND), <literal>|</literal> (OR),
3928-
<literal>!</> (NOT) and <literal>&lt;-&gt;</> (FOLLOWED BY) phrase search
3929-
operator. Parentheses can be used to enforce grouping
3930-
of the operators:
3926+
searched for, and can combine them using the Boolean operators
3927+
<literal>&amp;</literal> (AND), <literal>|</literal> (OR), and
3928+
<literal>!</> (NOT), as well as the phrase search operator
3929+
<literal>&lt;-&gt;</> (FOLLOWED BY). There is also a variant
3930+
<literal>&lt;<replaceable>N</>&gt;</literal> of the FOLLOWED BY
3931+
operator, where <replaceable>N</> is an integer constant that
3932+
specifies a maximum distance between the two lexemes being searched
3933+
for. <literal>&lt;-&gt;</> is equivalent to <literal>&lt;1&gt;</>.
3934+
</para>
3935+
3936+
<para>
3937+
Parentheses can be used to enforce grouping of the operators:
39313938

39323939
<programlisting>
39333940
SELECT 'fat &amp; rat'::tsquery;

‎doc/src/sgml/func.sgml‎

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9081,10 +9081,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
90819081

90829082
<table id="textsearch-operators-table">
90839083
<title>Text Search Operators</title>
9084-
<tgroup cols="4">
9084+
<tgroup cols="5">
90859085
<thead>
90869086
<row>
90879087
<entry>Operator</entry>
9088+
<entry>Return Type</entry>
90889089
<entry>Description</entry>
90899090
<entry>Example</entry>
90909091
<entry>Result</entry>
@@ -9093,54 +9094,63 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
90939094
<tbody>
90949095
<row>
90959096
<entry> <literal>@@</literal> </entry>
9097+
<entry><type>boolean</></entry>
90969098
<entry><type>tsvector</> matches <type>tsquery</> ?</entry>
90979099
<entry><literal>to_tsvector('fat cats ate rats') @@ to_tsquery('cat &amp; rat')</literal></entry>
90989100
<entry><literal>t</literal></entry>
90999101
</row>
91009102
<row>
91019103
<entry> <literal>@@@</literal> </entry>
9104+
<entry><type>boolean</></entry>
91029105
<entry>deprecated synonym for <literal>@@</></entry>
91039106
<entry><literal>to_tsvector('fat cats ate rats') @@@ to_tsquery('cat &amp; rat')</literal></entry>
91049107
<entry><literal>t</literal></entry>
91059108
</row>
91069109
<row>
91079110
<entry> <literal>||</literal> </entry>
9111+
<entry><type>tsvector</></entry>
91089112
<entry>concatenate <type>tsvector</>s</entry>
91099113
<entry><literal>'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector</literal></entry>
91109114
<entry><literal>'a':1 'b':2,5 'c':3 'd':4</literal></entry>
91119115
</row>
91129116
<row>
91139117
<entry> <literal>&amp;&amp;</literal> </entry>
9118+
<entry><type>tsquery</></entry>
91149119
<entry>AND <type>tsquery</>s together</entry>
91159120
<entry><literal>'fat | rat'::tsquery &amp;&amp; 'cat'::tsquery</literal></entry>
91169121
<entry><literal>( 'fat' | 'rat' ) &amp; 'cat'</literal></entry>
91179122
</row>
91189123
<row>
91199124
<entry> <literal>||</literal> </entry>
9125+
<entry><type>tsquery</></entry>
91209126
<entry>OR <type>tsquery</>s together</entry>
91219127
<entry><literal>'fat | rat'::tsquery || 'cat'::tsquery</literal></entry>
91229128
<entry><literal>( 'fat' | 'rat' ) | 'cat'</literal></entry>
91239129
</row>
91249130
<row>
91259131
<entry> <literal>!!</literal> </entry>
9132+
<entry><type>tsquery</></entry>
91269133
<entry>negate a <type>tsquery</></entry>
91279134
<entry><literal>!! 'cat'::tsquery</literal></entry>
91289135
<entry><literal>!'cat'</literal></entry>
91299136
</row>
91309137
<row>
91319138
<entry> <literal>&lt;-&gt;</literal> </entry>
9139+
<entry><type>tsquery</></entry>
91329140
<entry><type>tsquery</> followed by <type>tsquery</></entry>
91339141
<entry><literal>to_tsquery('fat') &lt;-&gt; to_tsquery('rat')</literal></entry>
91349142
<entry><literal>'fat' &lt;-&gt; 'rat'</literal></entry>
91359143
</row>
91369144
<row>
91379145
<entry> <literal>@&gt;</literal> </entry>
9146+
<entry><type>boolean</></entry>
91389147
<entry><type>tsquery</> contains another ?</entry>
91399148
<entry><literal>'cat'::tsquery @&gt; 'cat &amp; rat'::tsquery</literal></entry>
91409149
<entry><literal>f</literal></entry>
91419150
</row>
91429151
<row>
91439152
<entry> <literal>&lt;@</literal> </entry>
9153+
<entry><type>boolean</></entry>
91449154
<entry><type>tsquery</> is contained in ?</entry>
91459155
<entry><literal>'cat'::tsquery &lt;@ 'cat &amp; rat'::tsquery</literal></entry>
91469156
<entry><literal>t</literal></entry>
@@ -9245,7 +9255,8 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
92459255
<literal><function>phraseto_tsquery(<optional> <replaceable class="PARAMETER">config</> <type>regconfig</> , </optional> <replaceable class="PARAMETER">query</> <type>text</type>)</function></literal>
92469256
</entry>
92479257
<entry><type>tsquery</type></entry>
9248-
<entry>produce <type>tsquery</> ignoring punctuation</entry>
9258+
<entry>produce <type>tsquery</> that searches for a phrase,
9259+
ignoring punctuation</entry>
92499260
<entry><literal>phraseto_tsquery('english', 'The Fat Rats')</literal></entry>
92509261
<entry><literal>'fat' &lt;-&gt; 'rat'</literal></entry>
92519262
</row>
@@ -9400,7 +9411,8 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
94009411
<literal><function>ts_rewrite(<replaceable class="PARAMETER">query</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">target</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">substitute</replaceable> <type>tsquery</>)</function></literal>
94019412
</entry>
94029413
<entry><type>tsquery</type></entry>
9403-
<entry>replace target with substitute within query</entry>
9414+
<entry>replace <replaceable>target</> with <replaceable>substitute</>
9415+
within query</entry>
94049416
<entry><literal>ts_rewrite('a &amp; b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery)</literal></entry>
94059417
<entry><literal>'b' &amp; ( 'foo' | 'bar' )</literal></entry>
94069418
</row>
@@ -9419,7 +9431,9 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
94199431
<literal><function>tsquery_phrase(<replaceable class="PARAMETER">query1</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">query2</replaceable> <type>tsquery</>)</function></literal>
94209432
</entry>
94219433
<entry><type>tsquery</type></entry>
9422-
<entry>implementation of <literal>&lt;-&gt;</> (FOLLOWED BY) operator</entry>
9434+
<entry>make query that searches for <replaceable>query1</> followed
9435+
by <replaceable>query2</> (same as <literal>&lt;-&gt;</>
9436+
operator)</entry>
94239437
<entry><literal>tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'))</literal></entry>
94249438
<entry><literal>'fat' &lt;-&gt; 'cat'</literal></entry>
94259439
</row>
@@ -9428,7 +9442,8 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
94289442
<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>
94299443
</entry>
94309444
<entry><type>tsquery</type></entry>
9431-
<entry>phrase-concatenate with distance</entry>
9445+
<entry>make query that searches for <replaceable>query1</> followed by
9446+
<replaceable>query2</> at maximum distance <replaceable>distance</></entry>
94329447
<entry><literal>tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10)</literal></entry>
94339448
<entry><literal>'fat' &lt;10&gt; 'cat'</literal></entry>
94349449
</row>

0 commit comments

Comments
 (0)