From f8d3e2ab27d22c1f032b0541fd7650e02e8907f7 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 24 Apr 2020 15:51:35 -0400 Subject: [PATCH] Doc: update section 9.13 for new function table layout. This includes the usual amount of editorial cleanup, such as correcting wrong or less-helpful-than-they-could-be examples. I moved the two tsvector-updating triggers into "9.28 Trigger Functions", which seems like a better home for them. (I believe that section didn't exist when this text was originally written.) --- doc/src/sgml/func.sgml | 1523 +++++++++++++++++++++------------- doc/src/sgml/textsearch.sgml | 7 +- 2 files changed, 953 insertions(+), 577 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 606defc515..86cb2379fc 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -11091,479 +11091,713 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple facility. - - Text Search Operators - - - - Operator - Return Type - Description - Example - Result - - - - - @@ - boolean - tsvector matches tsquery ? - to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat') - t - - - @@@ - boolean - deprecated synonym for @@ - to_tsvector('fat cats ate rats') @@@ to_tsquery('cat & rat') - t - - - || - tsvector - concatenate tsvectors - 'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector - 'a':1 'b':2,5 'c':3 'd':4 - - - && - tsquery - AND tsquerys together - 'fat | rat'::tsquery && 'cat'::tsquery - ( 'fat' | 'rat' ) & 'cat' - - - || - tsquery - OR tsquerys together - 'fat | rat'::tsquery || 'cat'::tsquery - ( 'fat' | 'rat' ) | 'cat' - - - !! - tsquery - negate a tsquery - !! 'cat'::tsquery - !'cat' - - - <-> - tsquery - tsquery followed by tsquery - to_tsquery('fat') <-> to_tsquery('rat') - 'fat' <-> 'rat' - - - @> - boolean - tsquery contains another ? - 'cat'::tsquery @> 'cat & rat'::tsquery - f - - - <@ - boolean - tsquery is contained in ? - 'cat'::tsquery <@ 'cat & rat'::tsquery - t - - - -
+ + Text Search Operators + + + + + OperatorDescriptionExample(s) + + + - - - The tsquery containment operators consider only the lexemes - listed in the two queries, ignoring the combining operators. - - + + + + tsvector @@ tsquery + or + tsquery @@ tsvector + boolean + + Does tsvector match tsquery? + + to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat') + t + + + + + + text @@ tsquery + boolean + + Does text string, after implicit invocation + of to_tsvector(), match tsquery? + + 'fat cats ate rats' @@ to_tsquery('cat & rat') + t + + + + + + tsvector @@@ tsquery + or + tsquery @@@ tsvector + boolean + + This is a deprecated synonym for @@. + + to_tsvector('fat cats ate rats') @@@ to_tsquery('cat & rat') + t + + + + + + tsvector || tsvector + tsvector + + Concatenates two tsvectors. If both inputs contain + lexeme positions, the second input's positions are adjusted + accordingly. + + 'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector + 'a':1 'b':2,5 'c':3 'd':4 + + + + + + tsquery && tsquery + tsquery + + ANDs two tsquerys together, producing a query that + matches documents that match both input queries. + + 'fat | rat'::tsquery && 'cat'::tsquery + ( 'fat' | 'rat' ) & 'cat' + + + + + + tsquery || tsquery + tsquery + + ORs two tsquerys together, producing a query that + matches documents that match either input query. + + 'fat | rat'::tsquery || 'cat'::tsquery + 'fat' | 'rat' | 'cat' + + + + + + !! tsquery + tsquery + + Negates a tsquery, producing a query that matches + documents that do not match the input query. + + !! 'cat'::tsquery + !'cat' + + + + + + tsquery <-> tsquery + tsquery + + Constructs a phrase query, which matches if the two input queries + match at successive lexemes. + + to_tsquery('fat') <-> to_tsquery('rat') + 'fat' <-> 'rat' + + + + + + tsquery @> tsquery + boolean + + Does first tsquery contain the second? (This considers + only whether all the lexemes appearing in one query appear in the + other, ignoring the combining operators.) + + 'cat'::tsquery @> 'cat & rat'::tsquery + f + + + + + + tsquery <@ tsquery + boolean + + Is first tsquery contained in the second? (This + considers only whether all the lexemes appearing in one query appear + in the other, ignoring the combining operators.) + + 'cat'::tsquery <@ 'cat & rat'::tsquery + t + + 'cat'::tsquery <@ '!cat & rat'::tsquery + t + + + + +
- In addition to the operators shown in the table, the ordinary B-tree - comparison operators (=, <, etc) are defined - for types tsvector and tsquery. These are not very + In addition to these specialized operators, the usual comparison + operators shown in are + available for types tsvector and tsquery. + These are not very useful for text searching but allow, for example, unique indexes to be built on columns of these types. - - Text Search Functions - - - - Function - Return Type - Description - Example - Result - - - - - - - array_to_tsvector - - array_to_tsvector(text[]) - - tsvector - convert array of lexemes to tsvector - array_to_tsvector('{fat,cat,rat}'::text[]) - 'cat' 'fat' 'rat' - - - - - get_current_ts_config - - get_current_ts_config() - - regconfig - get default text search configuration - get_current_ts_config() - english - - - - - length - - length(tsvector) - - integer - number of lexemes in tsvector - length('fat:2,4 cat:3 rat:5A'::tsvector) - 3 - - - - - numnode - - numnode(tsquery) - - integer - number of lexemes plus operators in tsquery - numnode('(fat & rat) | cat'::tsquery) - 5 - - - - - plainto_tsquery - - plainto_tsquery( config regconfig , query text) - - tsquery - produce tsquery ignoring punctuation - plainto_tsquery('english', 'The Fat Rats') - 'fat' & 'rat' - - - - - phraseto_tsquery - - phraseto_tsquery( config regconfig , query text) - - tsquery - produce tsquery that searches for a phrase, - ignoring punctuation - phraseto_tsquery('english', 'The Fat Rats') - 'fat' <-> 'rat' - - - - - websearch_to_tsquery - - websearch_to_tsquery( config regconfig , query text) - - tsquery - produce tsquery from a web search style query - websearch_to_tsquery('english', '"fat rat" or rat') - 'fat' <-> 'rat' | 'rat' - - - - - querytree - - querytree(query tsquery) - - text - get indexable part of a tsquery - querytree('foo & ! bar'::tsquery) - 'foo' - - - - - setweight - - setweight(vector tsvector, weight "char") - - tsvector - assign weight to each element of vector - setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A') - 'cat':3A 'fat':2A,4A 'rat':5A - - - - - setweight - setweight for specific lexeme(s) - - setweight(vector tsvector, weight "char", lexemes text[]) - - tsvector - assign weight to elements of vector that are listed in lexemes - setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A', '{cat,rat}') - 'cat':3A 'fat':2,4 'rat':5A - - - - - strip - - strip(tsvector) - - tsvector - remove positions and weights from tsvector - strip('fat:2,4 cat:3 rat:5A'::tsvector) - 'cat' 'fat' 'rat' - - - - - to_tsquery - - to_tsquery( config regconfig , query text) - - tsquery - normalize words and convert to tsquery - to_tsquery('english', 'The & Fat & Rats') - 'fat' & 'rat' - - - - - to_tsvector - - to_tsvector( config regconfig , document text) - - tsvector - reduce document text to tsvector - to_tsvector('english', 'The Fat Rats') - 'fat':2 'rat':3 - - - - to_tsvector( config regconfig , document json(b)) - - tsvector - - reduce each string value in the document to a tsvector, and then - concatenate those in document order to produce a single tsvector - - to_tsvector('english', '{"a": "The Fat Rats"}'::json) - 'fat':2 'rat':3 - - - - json(b)_to_tsvector( config regconfig, - document json(b), - filter json(b)) - - tsvector - - reduce each value in the document, specified by filter to a tsvector, - and then concatenate those in document order to produce a single tsvector. - filter is a jsonb array, that enumerates what kind of elements need to be included - into the resulting tsvector. Possible values for filter are - "string" (to include all string values), "numeric" (to include all numeric values in the string format), - "boolean" (to include all Boolean values in the string format "true"/"false"), - "key" (to include all keys) or "all" (to include all above). These values - can be combined together to include, e.g. all string and numeric values. - - json_to_tsvector('english', '{"a": "The Fat Rats", "b": 123}'::json, '["string", "numeric"]') - '123':5 'fat':2 'rat':3 - - - - - ts_delete - - ts_delete(vector tsvector, lexeme text) - - tsvector - remove given lexeme from vector - ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat') - 'cat':3 'rat':5A - - - - - ts_delete(vector tsvector, lexemes text[]) - - tsvector - remove any occurrence of lexemes in lexemes from vector - ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat']) - 'cat':3 - - - - - ts_filter - - ts_filter(vector tsvector, weights "char"[]) - - tsvector - select only elements with given weights from vector - ts_filter('fat:2,4 cat:3b rat:5A'::tsvector, '{a,b}') - 'cat':3B 'rat':5A - - - - - ts_headline - - ts_headline( config regconfig, document text, query tsquery , options text ) - - text - display a query match - ts_headline('x y z', 'z'::tsquery) - x y <b>z</b> - - - - ts_headline( config regconfig, document json(b), query tsquery , options text ) - - text - display a query match - ts_headline('{"a":"x y z"}'::json, 'z'::tsquery) - {"a":"x y <b>z</b>"} - - - - - ts_rank - - ts_rank( weights float4[], vector tsvector, query tsquery , normalization integer ) - - float4 - rank document for query - ts_rank(textsearch, query) - 0.818 - - - - - ts_rank_cd - - ts_rank_cd( weights float4[], vector tsvector, query tsquery , normalization integer ) - - float4 - rank document for query using cover density - ts_rank_cd('{0.1, 0.2, 0.4, 1.0}', textsearch, query) - 2.01317 - - - - - ts_rewrite - - ts_rewrite(query tsquery, target tsquery, substitute tsquery) - - tsquery - replace target with substitute - within query - ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery) - 'b' & ( 'foo' | 'bar' ) - - - ts_rewrite(query tsquery, select text) - tsquery - replace using targets and substitutes from a SELECT command - SELECT ts_rewrite('a & b'::tsquery, 'SELECT t,s FROM aliases') - 'b' & ( 'foo' | 'bar' ) - - - - - tsquery_phrase - - tsquery_phrase(query1 tsquery, query2 tsquery) - - tsquery - make query that searches for query1 followed - by query2 (same as <-> - operator) - tsquery_phrase(to_tsquery('fat'), to_tsquery('cat')) - 'fat' <-> 'cat' - - - - tsquery_phrase(query1 tsquery, query2 tsquery, distance integer) - - tsquery - make query that searches for query1 followed by - query2 at distance distance - tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10) - 'fat' <10> 'cat' - - - - - tsvector_to_array - - tsvector_to_array(tsvector) - - text[] - convert tsvector to array of lexemes - tsvector_to_array('fat:2,4 cat:3 rat:5A'::tsvector) - {cat,fat,rat} - - - - - tsvector_update_trigger - - tsvector_update_trigger() - - trigger - trigger function for automatic tsvector column update - CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body) - - - - - - tsvector_update_trigger_column - - tsvector_update_trigger_column() - - trigger - trigger function for automatic tsvector column update - CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, configcol, title, body) - - - - - - unnest - for tsvector - - unnest(tsvector, OUT lexeme text, OUT positions smallint[], OUT weights text) - - setof record - expand a tsvector to a set of rows - unnest('fat:2,4 cat:3 rat:5A'::tsvector) - (cat,{3},{D}) ... - - - -
+ + Text Search Functions + + + + + FunctionDescriptionExample(s) + + + + + + + + + array_to_tsvector + + array_to_tsvector ( text[] ) + tsvector + + Converts an array of lexemes to a tsvector. + The given strings are used as-is without further processing. + + array_to_tsvector('{fat,cat,rat}'::text[]) + 'cat' 'fat' 'rat' + + + + + + + get_current_ts_config + + get_current_ts_config ( ) + regconfig + + Returns the OID of the current default text search configuration + (as set by ). + + get_current_ts_config() + english + + + + + + + length + + length ( tsvector ) + integer + + Returns the number of lexemes in the tsvector. + + length('fat:2,4 cat:3 rat:5A'::tsvector) + 3 + + + + + + + numnode + + numnode ( tsquery ) + integer + + Returns the number of lexemes plus operators in + the tsquery. + + numnode('(fat & rat) | cat'::tsquery) + 5 + + + + + + + plainto_tsquery + + plainto_tsquery ( + config regconfig, + query text ) + tsquery + + Converts text to a tsquery, 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. + + plainto_tsquery('english', 'The Fat Rats') + 'fat' & 'rat' + + + + + + + phraseto_tsquery + + phraseto_tsquery ( + config regconfig, + query text ) + tsquery + + Converts text to a tsquery, 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. + + phraseto_tsquery('english', 'The Fat Rats') + 'fat' <-> 'rat' + + phraseto_tsquery('english', 'The Cat and Rats') + 'cat' <2> 'rat' + + + + + + + websearch_to_tsquery + + websearch_to_tsquery ( + config regconfig, + query text ) + tsquery + + Converts text to a tsquery, normalizing words according to + the specified or default configuration. Quoted word sequences are + converted to phrase tests, and the word or is + understood as producing an OR operator. This approximates the + behavior of some common web search tools. + + websearch_to_tsquery('english', '"fat rat" or cat dog') + 'fat' <-> 'rat' | 'cat' & 'dog' + + + + + + + querytree + + querytree ( tsquery ) + text + + Produces a representation of the indexable portion of + a tsquery. A result that is empty or + just T indicates a non-indexable query. + + querytree('foo & ! bar'::tsquery) + 'foo' + + + + + + + setweight + + setweight ( vector tsvector, weight "char" ) + tsvector + + Assigns the specified weight to each element + of the vector. + + setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A') + 'cat':3A 'fat':2A,4A 'rat':5A + + + + + + + setweight + setweight for specific lexeme(s) + + setweight ( vector tsvector, weight "char", lexemes text[] ) + tsvector + + Assigns the specified weight to elements + of the vector that are listed + in lexemes. + + setweight('fat:2,4 cat:3 rat:5,6B'::tsvector, 'A', '{cat,rat}') + 'cat':3A 'fat':2,4 'rat':5A,6A + + + + + + + strip + + strip ( tsvector ) + tsvector + + Removes positions and weights from the tsvector. + + strip('fat:2,4 cat:3 rat:5A'::tsvector) + 'cat' 'fat' 'rat' + + + + + + + to_tsquery + + to_tsquery ( + config regconfig, + query text ) + tsquery + + Converts text to a tsquery, normalizing words according to + the specified or default configuration. The words must be combined + by valid tsquery operators. + + to_tsquery('english', 'The & Fat & Rats') + 'fat' & 'rat' + + + + + + + to_tsvector + + to_tsvector ( + config regconfig, + document text ) + tsvector + + Converts text to a tsvector, normalizing words according + to the specified or default configuration. Position information is + included in the result. + + to_tsvector('english', 'The Fat Rats') + 'fat':2 'rat':3 + + + + + + to_tsvector ( + config regconfig, + document json(b) ) + tsvector + + Converts each string value in the JSON document to + a tsvector, 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 document order of the fields of a + JSON object is implementation-dependent when the input + is jsonb; observe the difference in the examples.) + + to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::json) + 'dog':5 'fat':2 'rat':3 + + to_tsvector('english', '{"aa": "The Fat Rats", "b": "dog"}'::jsonb) + 'dog':1 'fat':4 'rat':5 + + + + + + + json(b)_to_tsvector + + json(b)_to_tsvector ( + config regconfig, + document json(b), + filter jsonb ) + tsvector + + Selects each item in the JSON document that is requested by + the filter and converts each one to + a tsvector, 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 document order of the fields of a + JSON object is implementation-dependent when the input + is jsonb.) + The filter must be a jsonb + array containing zero or more of these keywords: + "string" (to include all string values), + "numeric" (to include all numeric values), + "boolean" (to include all boolean values), + "key" (to include all keys), or + "all" (to include all the above). + As a special case, the filter can also be a + simple JSON value that is one of these keywords. + + json_to_tsvector('english', '{"a": "The Fat Rats", "b": 123}'::json, '["string", "numeric"]') + '123':5 'fat':2 'rat':3 + + json_to_tsvector('english', '{"cat": "The Fat Rats", "dog": 123}'::json, '"all"') + '123':9 'cat':1 'dog':7 'fat':4 'rat':5 + + + + + + + ts_delete + + ts_delete ( vector tsvector, lexeme text ) + tsvector + + Removes any occurrence of the given lexeme + from the vector. + + ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat') + 'cat':3 'rat':5A + + + + + + ts_delete ( vector tsvector, lexemes text[] ) + tsvector + + Removes any occurrences of the lexemes + in lexemes + from the vector. + + ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat']) + 'cat':3 + + + + + + + ts_filter + + ts_filter ( vector tsvector, weights "char"[] ) + tsvector + + Selects only elements with the given weights + from the vector. + + ts_filter('fat:2,4 cat:3b,7c rat:5A'::tsvector, '{a,b}') + 'cat':3B 'rat':5A + + + + + + + ts_headline + + ts_headline ( + config regconfig, + document text, + query tsquery + , options text ) + text + + Displays, in an abbreviated form, the match(es) for + the query in + the document, which must be raw text not + a tsvector. 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 + , which also describes the + available options. + + ts_headline('The fat cat ate the rat.', 'cat') + The fat <b>cat</b> ate the rat. + + + + + + ts_headline ( + config regconfig, + document json(b), + query tsquery + , options text ) + text + + Displays, in an abbreviated form, match(es) for + the query that occur in string values + within the JSON document. + See for more details. + + ts_headline('{"cat":"raining cats and dogs"}'::jsonb, 'cat') + {"cat": "raining <b>cats</b> and dogs"} + + + + + + + ts_rank + + ts_rank ( + weights real[], + vector tsvector, + query tsquery + , normalization integer ) + real + + Computes a score showing how well + the vector matches + the query. See + for details. + + ts_rank(to_tsvector('raining cats and dogs'), 'cat') + 0.06079271 + + + + + + + ts_rank_cd + + ts_rank_cd ( + weights real[], + vector tsvector, + query tsquery + , normalization integer ) + real + + Computes a score showing how well + the vector matches + the query, using a cover density + algorithm. See for details. + + ts_rank_cd(to_tsvector('raining cats and dogs'), 'cat') + 0.1 + + + + + + + ts_rewrite + + ts_rewrite ( query tsquery, + target tsquery, + substitute tsquery ) + tsquery + + Replaces occurrences of target + with substitute + within the query. + See for details. + + ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery) + 'b' & ( 'foo' | 'bar' ) + + + + + + ts_rewrite ( query tsquery, + select text ) + tsquery + + Replaces portions of the query according to + target(s) and substitute(s) obtained by executing + a SELECT command. + See for details. + + SELECT ts_rewrite('a & b'::tsquery, 'SELECT t,s FROM aliases') + 'b' & ( 'foo' | 'bar' ) + + + + + + + tsquery_phrase + + tsquery_phrase ( query1 tsquery, query2 tsquery ) + tsquery + + Constructs a phrase query that searches + for matches of query1 + and query2 at successive lexemes (same + as <-> operator). + + tsquery_phrase(to_tsquery('fat'), to_tsquery('cat')) + 'fat' <-> 'cat' + + + + + + tsquery_phrase ( query1 tsquery, query2 tsquery, distance integer ) + tsquery + + Constructs a phrase query that searches + for matches of query1 and + query2 that occur exactly + distance lexemes apart. + + tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10) + 'fat' <10> 'cat' + + + + + + + tsvector_to_array + + tsvector_to_array ( tsvector ) + text[] + + Converts a tsvector to an array of lexemes. + + tsvector_to_array('fat:2,4 cat:3 rat:5A'::tsvector) + {cat,fat,rat} + + + + + + + unnest + for tsvector + + unnest ( tsvector, + OUT lexeme text, + OUT positions smallint[], + OUT weights text ) + setof record + + Expands a tsvector into a set of rows, one per lexeme. + + unnest('cat:3 fat:2,4 rat:5A'::tsvector) + (cat,{3},{D})(fat,"{2,4}","{D,D}")(rat,{5},{A})(3 rows in result) + + + + +
@@ -11578,100 +11812,165 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple The functions in 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. - - Text Search Debugging Functions - - - - Function - Return Type - Description - Example - Result - - - - - - - ts_debug - - ts_debug( config regconfig, document text, OUT alias text, OUT description text, OUT token text, OUT dictionaries regdictionary[], OUT dictionary regdictionary, OUT lexemes text[]) - - setof record - test a configuration - ts_debug('english', 'The Brightest supernovaes') - (asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ... - - - - - ts_lexize - - ts_lexize(dict regdictionary, token text) - - text[] - test a dictionary - ts_lexize('english_stem', 'stars') - {star} - - - - - ts_parse - - ts_parse(parser_name text, document text, OUT tokid integer, OUT token text) - - setof record - test a parser - ts_parse('default', 'foo - bar') - (1,foo) ... - - - ts_parse(parser_oid oid, document text, OUT tokid integer, OUT token text) - setof record - test a parser - ts_parse(3722, 'foo - bar') - (1,foo) ... - - - - - ts_token_type - - ts_token_type(parser_name text, OUT tokid integer, OUT alias text, OUT description text) - - setof record - get token types defined by parser - ts_token_type('default') - (1,asciiword,"Word, all ASCII") ... - - - ts_token_type(parser_oid oid, OUT tokid integer, OUT alias text, OUT description text) - setof record - get token types defined by parser - ts_token_type(3722) - (1,asciiword,"Word, all ASCII") ... - - - - - ts_stat - - ts_stat(sqlquery text, weights text, OUT word text, OUT ndoc integer, OUT nentry integer) - - setof record - get statistics of a tsvector column - ts_stat('SELECT vector from apod') - (foo,10,15) ... - - - -
+ + Text Search Debugging Functions + + + + + FunctionDescriptionExample(s) + + + + + + + + + ts_debug + + ts_debug ( + config regconfig, + document text, + OUT alias text, + OUT description text, + OUT token text, + OUT dictionaries regdictionary[], + OUT dictionary regdictionary, + OUT lexemes text[] ) + setof record + + Extracts and normalizes tokens from + the document according to the specified or + default text search configuration, and returns information about how + each token was processed. + See for details. + + ts_debug('english', 'The Brightest supernovaes') + (asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ... + + + + + + + ts_lexize + + ts_lexize ( dict regdictionary, token text ) + text[] + + 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 for details. + + ts_lexize('english_stem', 'stars') + {star} + + + + + + + ts_parse + + ts_parse ( parser_name text, + document text, + OUT tokid integer, + OUT token text ) + setof record + + Extracts tokens from the document using the + named parser. + See for details. + + ts_parse('default', 'foo - bar') + (1,foo) ... + + + + + + ts_parse ( parser_oid oid, + document text, + OUT tokid integer, + OUT token text ) + setof record + + Extracts tokens from the document using a + parser specified by OID. + See for details. + + ts_parse(3722, 'foo - bar') + (1,foo) ... + + + + + + + ts_token_type + + ts_token_type ( parser_name text, + OUT tokid integer, + OUT alias text, + OUT description text ) + setof record + + Returns a table that describes each type of token the named parser can + recognize. + See for details. + + ts_token_type('default') + (1,asciiword,"Word, all ASCII") ... + + + + + + ts_token_type ( parser_oid oid, + OUT tokid integer, + OUT alias text, + OUT description text ) + setof record + + Returns a table that describes each type of token a parser specified + by OID can recognize. + See for details. + + ts_token_type(3722) + (1,asciiword,"Word, all ASCII") ... + + + + + + + ts_stat + + ts_stat ( sqlquery text, + weights text, + OUT word text, + OUT ndoc integer, + OUT nentry integer ) + setof record + + Executes the sqlquery, which must return a + single tsvector column, and returns statistics about each + distinct lexeme contained in the data. + See for details. + + ts_stat('SELECT vector FROM apod') + (foo,10,15) ... + + + + +
@@ -23714,23 +24013,97 @@ SELECT (pg_stat_file('filename')).modification; Trigger Functions - - suppress_redundant_updates_trigger - + + While many uses of triggers involve user-written trigger functions, + PostgreSQL provides a few built-in trigger + functions that can be used directly in user-defined triggers. These + are summarized in . + (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.) + + + + For more information about creating triggers, see + . + + + + Built-In Trigger Functions + + + + + FunctionDescriptionExample Usage + + + + + + + + + suppress_redundant_updates_trigger + + suppress_redundant_updates_trigger ( ) + trigger + + Suppresses do-nothing update operations. See below for details. + + CREATE TRIGGER ... suppress_redundant_updates_trigger() + + + + + + + tsvector_update_trigger + + tsvector_update_trigger ( ) + trigger + + Automatically updates a tsvector column from associated + plain-text document column(s). The text search configuration to use + is specified by name as a trigger argument. See + for details. + + CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body) + + + + + + + tsvector_update_trigger_column + + tsvector_update_trigger_column ( ) + trigger + + Automatically updates a tsvector column from associated + plain-text document column(s). The text search configuration to use + is taken from a regconfig column of the table. See + for details. + + CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, tsconfigcol, title, body) + + + + +
- Currently PostgreSQL provides one built in trigger - function, suppress_redundant_updates_trigger, - 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 suppress_redundant_updates_trigger function, + when applied as a row-level BEFORE UPDATE 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.) - 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. @@ -23740,8 +24113,8 @@ SELECT (pg_stat_file('filename')).modification; suppress_redundant_updates_trigger, 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. @@ -23752,14 +24125,12 @@ CREATE TRIGGER z_min_update BEFORE UPDATE ON tablename FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger(); - 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. - - - For more information about creating triggers, see - . + you might have on the table. (Hence the z prefix in the + example.) diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml index 3d02e661d8..ce2b4c664f 100644 --- a/doc/src/sgml/textsearch.sgml +++ b/doc/src/sgml/textsearch.sgml @@ -1705,10 +1705,15 @@ SELECT numnode('foo & bar'::tsquery); or only negated terms. For example: +SELECT querytree(to_tsquery('defined')); + querytree +----------- + 'defin' + SELECT querytree(to_tsquery('!defined')); querytree ----------- - + T