From: Tom Lane Date: Wed, 29 Jun 2016 19:00:25 +0000 (-0400) Subject: Adjust text search documentation for recent commits. X-Git-Tag: REL9_6_BETA3~87 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4242a715c3fca1a8fa31f810b7cffa88b4d4e439;p=postgresql Adjust text search documentation for recent commits. Fix some now-obsolete statements that were overlooked in commits 6734a1cac, 3dbbd0f02, 028350f61. Document the behavior of <0>. Also do a little bit of rearranging and copy-editing for clarity. --- diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 9643746ca4..67d0c349e0 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -3885,12 +3885,12 @@ SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; It is important to understand that the - tsvector type itself does not perform any normalization; - it assumes the words it is given are normalized appropriately - for the application. For example, + tsvector type itself does not perform any word + normalization; it assumes the words it is given are normalized + appropriately for the application. For example, -select 'The Fat Rats'::tsvector; +SELECT 'The Fat Rats'::tsvector; tsvector -------------------- 'Fat' 'Rats' 'The' @@ -3929,12 +3929,20 @@ SELECT to_tsvector('english', 'The Fat Rats'); <-> (FOLLOWED BY). There is also a variant <N> of the FOLLOWED BY operator, where N is an integer constant that - specifies a maximum distance between the two lexemes being searched + specifies the distance between the two lexemes being searched for. <-> is equivalent to <1>. - Parentheses can be used to enforce grouping of the operators: + Parentheses can be used to enforce grouping of these operators. + In the absence of parentheses, ! (NOT) binds most tightly, + <-> (FOLLOWED BY) next most tightly, then + & (AND), with | (OR) binding + the least tightly. + + + + Here are some examples: SELECT 'fat & rat'::tsquery; @@ -3951,17 +3959,21 @@ SELECT 'fat & rat & ! cat'::tsquery; tsquery ------------------------ 'fat' & 'rat' & !'cat' + +SELECT '(fat | rat) <-> cat'::tsquery; + tsquery +----------------------------------- + 'fat' <-> 'cat' | 'rat' <-> 'cat' - In the absence of parentheses, ! (NOT) binds most tightly, - and & (AND) and <-> (FOLLOWED BY) - both bind more tightly than | (OR). + The last example demonstrates that tsquery sometimes + rearranges nested operators into a logically equivalent formulation. Optionally, lexemes in a tsquery can be labeled with one or more weight letters, which restricts them to match only - tsvector lexemes with matching weights: + tsvector lexemes with one of those weights: SELECT 'fat:ab & cat'::tsquery; @@ -3981,25 +3993,7 @@ SELECT 'super:*'::tsquery; 'super':* This query will match any word in a tsvector that begins - with super. Note that prefixes are first processed by - text search configurations, which means this comparison returns - true: - -SELECT to_tsvector( 'postgraduate' ) @@ to_tsquery( 'postgres:*' ); - ?column? ----------- - t -(1 row) - - because postgres gets stemmed to postgr: - -SELECT to_tsquery('postgres:*'); - to_tsquery ------------- - 'postgr':* -(1 row) - - which then matches postgraduate. + with super. @@ -4015,6 +4009,24 @@ SELECT to_tsquery('Fat:ab & Cats'); ------------------ 'fat':AB & 'cat' + + Note that to_tsquery will process prefixes in the same way + as other words, which means this comparison returns true: + + +SELECT to_tsvector( 'postgraduate' ) @@ to_tsquery( 'postgres:*' ); + ?column? +---------- + t + + because postgres gets stemmed to postgr: + +SELECT to_tsvector( 'postgraduate' ), to_tsquery( 'postgres:*' ); + to_tsvector | to_tsquery +---------------+------------ + 'postgradu':1 | 'postgr':* + + which will match the stemmed form of postgraduate. diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml index df4732e654..41151ef4bd 100644 --- a/doc/src/sgml/textsearch.sgml +++ b/doc/src/sgml/textsearch.sgml @@ -322,8 +322,7 @@ text @@ text match. Similarly, the | (OR) operator specifies that at least one of its arguments must appear, while the ! (NOT) operator specifies that its argument must not appear in - order to have a match. Parentheses can be used to control nesting of - these operators. + order to have a match. @@ -346,10 +345,10 @@ SELECT to_tsvector('error is not fatal') @@ to_tsquery('fatal <-> error'); There is a more general version of the FOLLOWED BY operator having the form <N>, - where N is an integer standing for the exact distance - allowed between the matching lexemes. <1> is + where N is an integer standing for the difference between + the positions of the matching lexemes. <1> is the same as <->, while <2> - allows one other lexeme to appear between the matches, and so + allows exactly one other lexeme to appear between the matches, and so on. The phraseto_tsquery function makes use of this operator to construct a tsquery that can match a multi-word phrase when some of the words are stop words. For example: @@ -366,9 +365,17 @@ SELECT phraseto_tsquery('the cats ate the rats'); 'cat' <-> 'ate' <2> 'rat' + + + A special case that's sometimes useful is that <0> + can be used to require that two patterns match the same word. + + - The precedence of tsquery operators is as follows: |, &, - <->, !. + Parentheses can be used to control nesting of the tsquery + operators. Without parentheses, | binds least tightly, + then &, then <->, + and ! most tightly. @@ -1423,9 +1430,10 @@ FROM (SELECT id, body, q, ts_rank_cd(ti, q) AS rank lacks any position or weight information. The result is usually much smaller than an unstripped vector, but it is also less useful. Relevance ranking does not work as well on stripped vectors as - unstripped ones. Also, when given stripped input, + unstripped ones. Also, the <-> (FOLLOWED BY) tsquery operator - effectively degenerates to a simple & (AND) test. + will never match stripped input, since it cannot determine the + distance between lexeme occurrences.