I attached the patch, which fixes the pg_trgm documentation.
On 19.03.2016 01:18, Artur Zakirov wrote:
2016-03-18 23:46 GMT+03:00 Jeff Janes <[email protected]
<mailto:[email protected]>>:
<% and <<-> are not documented at all. Is that a deliberate choice?
Since they were added as convenience functions for the user, I think
they really need to be in the user documentation.
I can send a patch a little bit later. I documented %>
and <->> because examples of other operators have the following order:
SELECT t, t <-> 'word' AS dist
FROM test_trgm
ORDER BY dist LIMIT 10;
and
SELECT * FROM test_trgm WHERE t LIKE '%foo%bar';
I did not include <% and <<-> because I did not know how to document
commutators. But I can fix it.
And honestly the following order:
SELECT 'word' <% t FROM test_trgm;
is more convenient to me too.
Do you know how do not break the line in the operators table in the
first column? Now I see:
Operator| Returns
----------------|------------------
text % | boolean
text |
But the following is better:
Operator| Returns
----------------|------------------
text % text | boolean
Also, the documentation should probably include <% and <<-> as the
"parent" operators and use them in the examples, and only mention %>
and <->> in passing, as the commutators. That is because <% and <<->
take their arguments in the same order as word_similarity does. It
would be less confusing if the documentation and the examples didn't
need to keep changing the argument orders.
Cheers,
Jeff
--
Artur Zakirov
Postgres Professional: http://www.postgrespro.com
Russian Postgres Company
--
Artur Zakirov
Postgres Professional: http://www.postgrespro.com
Russian Postgres Company
*** a/doc/src/sgml/pgtrgm.sgml
--- b/doc/src/sgml/pgtrgm.sgml
***************
*** 153,167 ****
</entry>
</row>
<row>
! <entry><type>text</> <literal>%></literal> <type>text</></entry>
! <entry><type>boolean</type></entry>
! <entry>
! Returns <literal>true</> if its first argument has the similar word in
! the second argument and they have a similarity that is greater than the
! current word similarity threshold set by
! <varname>pg_trgm.word_similarity_threshold</> parameter.
! </entry>
! </row>
<row>
<entry><type>text</> <literal><-></literal> <type>text</></entry>
<entry><type>real</type></entry>
--- 153,174 ----
</entry>
</row>
<row>
! <entry><type>text</> <literal><%</literal> <type>text</></entry>
! <entry><type>boolean</type></entry>
! <entry>
! Returns <literal>true</> if its first argument has the similar word in
! the second argument and they have a similarity that is greater than the
! current word similarity threshold set by
! <varname>pg_trgm.word_similarity_threshold</> parameter.
! </entry>
! </row>
! <row>
! <entry><type>text</> <literal>%></literal> <type>text</></entry>
! <entry><type>boolean</type></entry>
! <entry>
! Commutator of the <literal><%</> operator.
! </entry>
! </row>
<row>
<entry><type>text</> <literal><-></literal> <type>text</></entry>
<entry><type>real</type></entry>
***************
*** 171,184 ****
</entry>
</row>
<row>
! <entry>
! <type>text</> <literal><->></literal> <type>text</>
! </entry>
! <entry><type>real</type></entry>
! <entry>
! Returns the <quote>distance</> between the arguments, that is
! one minus the <function>word_similarity()</> value.
! </entry>
</row>
</tbody>
</tgroup>
--- 178,200 ----
</entry>
</row>
<row>
! <entry>
! <type>text</> <literal><<-></literal> <type>text</>
! </entry>
! <entry><type>real</type></entry>
! <entry>
! Returns the <quote>distance</> between the arguments, that is
! one minus the <function>word_similarity()</> value.
! </entry>
! </row>
! <row>
! <entry>
! <type>text</> <literal><->></literal> <type>text</>
! </entry>
! <entry><type>real</type></entry>
! <entry>
! Commutator of the <literal><<-></> operator.
! </entry>
</row>
</tbody>
</tgroup>
***************
*** 215,221 ****
<listitem>
<para>
Sets the current word similarity threshold that is used by
! the <literal>%></> operator. The threshold must be between
0 and 1 (default is 0.6).
</para>
</listitem>
--- 231,237 ----
<listitem>
<para>
Sets the current word similarity threshold that is used by
! the <literal><%</> operator. The threshold must be between
0 and 1 (default is 0.6).
</para>
</listitem>
***************
*** 283,289 **** SELECT t, t <-> '<replaceable>word</>' AS dist
<programlisting>
SELECT t, word_similarity('<replaceable>word</>', t) AS sml
FROM test_trgm
! WHERE t %> '<replaceable>word</>'
ORDER BY sml DESC, t;
</programlisting>
This will return all values in the text column that have a word
--- 299,305 ----
<programlisting>
SELECT t, word_similarity('<replaceable>word</>', t) AS sml
FROM test_trgm
! WHERE '<replaceable>word</>' <% t
ORDER BY sml DESC, t;
</programlisting>
This will return all values in the text column that have a word
***************
*** 295,301 **** SELECT t, word_similarity('<replaceable>word</>', t) AS sml
<para>
A variant of the above query is
<programlisting>
! SELECT t, t <->> '<replaceable>word</>' AS dist
FROM test_trgm
ORDER BY dist LIMIT 10;
</programlisting>
--- 311,317 ----
<para>
A variant of the above query is
<programlisting>
! SELECT t, '<replaceable>word</>' <<-> t AS dist
FROM test_trgm
ORDER BY dist LIMIT 10;
</programlisting>
--
Sent via pgsql-hackers mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
