From 47046763c3ed1f16b81a389df7e44be5f3dba83c Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 4 May 2020 13:48:30 -0400 Subject: [PATCH] Doc: standardize markup a bit more. We had a mishmash of , , and markup for operator/function arguments. Use consistently for things that are in fact names of parameters (including OUT parameters), reserving for things that aren't. The latter class includes some made-up-by-the-docs type class names, like "numeric_type", as well as placeholders for arguments that don't have well-defined types. Possibly we could do better with those categories as well, but for the moment I'm content not to have parameter names marked up in different ways in different places. (This commit aligns the earlier sections of chapter 9 with a policy that I'd arrived at while working on commit 1ad23335f, which is why the last few sections need no changes.) --- doc/src/sgml/func.sgml | 696 +++++++++++++++++++++-------------------- 1 file changed, 350 insertions(+), 346 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index bfaf139487..d9b3598977 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1995,13 +1995,13 @@ repeat('Pg', 4) PgPgPgPg atan2 - atan2 ( y double precision, - x double precision ) + atan2 ( y double precision, + x double precision ) double precision Inverse tangent of - y/x, + y/x, result in radians @@ -2015,13 +2015,13 @@ repeat('Pg', 4) PgPgPgPg atan2d - atan2d ( y double precision, - x double precision ) + atan2d ( y double precision, + x double precision ) double precision Inverse tangent of - y/x, + y/x, result in degrees @@ -2637,7 +2637,7 @@ repeat('Pg', 4) PgPgPgPg - substring ( string text FROM pattern text ) + substring ( string text FROM pattern text ) text @@ -2652,7 +2652,7 @@ repeat('Pg', 4) PgPgPgPg - substring ( string text FROM pattern text FOR escape text ) + substring ( string text FROM pattern text FOR escape text ) text @@ -2898,9 +2898,9 @@ repeat('Pg', 4) PgPgPgPg text - Returns first n characters in the - string, or when n is negative, returns - all but last |n| characters. + Returns first n characters in the + string, or when n is negative, returns + all but last |n| characters. left('abcde', 2) @@ -3296,9 +3296,9 @@ repeat('Pg', 4) PgPgPgPg text - Returns last n characters in the string, - or when n is negative, returns all but - first |n| characters. + Returns last n characters in the string, + or when n is negative, returns all but + first |n| characters. right('abcde', 2) @@ -3558,12 +3558,12 @@ repeat('Pg', 4) PgPgPgPg format(formatstr text [, formatarg "any" [, ...] ]) - formatstr is a format string that specifies how the + formatstr is a format string that specifies how the result should be formatted. Text in the format string is copied directly to the result, except where format specifiers are used. Format specifiers act as placeholders in the string, defining how subsequent function arguments should be formatted and inserted into the - result. Each formatarg argument is converted to text + result. Each formatarg argument is converted to text according to the usual output rules for its data type, and then formatted and inserted into the result string according to the format specifier(s). @@ -3572,39 +3572,39 @@ repeat('Pg', 4) PgPgPgPg Format specifiers are introduced by a % character and have the form -%[position][flags][width]type +%[position][flags][width]type where the component fields are: - position (optional) + position (optional) - A string of the form n$ where - n is the index of the argument to print. + A string of the form n$ where + n is the index of the argument to print. Index 1 means the first argument after - formatstr. If the position is + formatstr. If the position is omitted, the default is to use the next argument in sequence. - flags (optional) + flags (optional) Additional options controlling how the format specifier's output is formatted. Currently the only supported flag is a minus sign (-) which will cause the format specifier's output to be - left-justified. This has no effect unless the width + left-justified. This has no effect unless the width field is also specified. - width (optional) + width (optional) Specifies the minimum number of characters to use to @@ -3614,8 +3614,8 @@ repeat('Pg', 4) PgPgPgPg truncation of the output, but is simply ignored. The width may be specified using any of the following: a positive integer; an asterisk (*) to use the next function argument as the - width; or a string of the form *n$ to - use the nth function argument as the width. + width; or a string of the form *n$ to + use the nth function argument as the width. @@ -3623,13 +3623,13 @@ repeat('Pg', 4) PgPgPgPg consumed before the argument that is used for the format specifier's value. If the width argument is negative, the result is left aligned (as if the - flag had been specified) within a - field of length abs(width). + field of length abs(width). - type (required) + type (required) The type of format conversion to use to produce the format @@ -3687,7 +3687,7 @@ SELECT format('INSERT INTO %I VALUES(%L)', 'locations', 'C:\Program Files'); - Here are examples using width fields + Here are examples using width fields and the - flag: @@ -3712,7 +3712,7 @@ SELECT format('|%-*s|', -10, 'foo'); - These examples show use of position fields: + These examples show use of position fields: SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three'); @@ -3729,9 +3729,9 @@ SELECT format('|%1$*2$s|', 'foo', 10, 'bar'); Unlike the standard C function sprintf, PostgreSQL's format function allows format - specifiers with and without position fields to be mixed + specifiers with and without position fields to be mixed in the same format string. A format specifier without a - position field always uses the next argument after the + position field always uses the next argument after the last argument consumed. In addition, the format function does not require all function arguments to be used in the format string. @@ -12372,8 +12372,8 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple plainto_tsquery plainto_tsquery ( - config regconfig, - query text ) + config regconfig, + query text ) tsquery @@ -12394,8 +12394,8 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple phraseto_tsquery phraseto_tsquery ( - config regconfig, - query text ) + config regconfig, + query text ) tsquery @@ -12420,8 +12420,8 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple websearch_to_tsquery websearch_to_tsquery ( - config regconfig, - query text ) + config regconfig, + query text ) tsquery @@ -12462,12 +12462,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple setweight - setweight ( vector tsvector, weight "char" ) + setweight ( vector tsvector, weight "char" ) tsvector - Assigns the specified weight to each element - of the vector. + Assigns the specified weight to each element + of the vector. setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A') @@ -12481,13 +12481,13 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple setweight setweight for specific lexeme(s) - setweight ( vector tsvector, weight "char", lexemes text[] ) + setweight ( vector tsvector, weight "char", lexemes text[] ) tsvector - Assigns the specified weight to elements - of the vector that are listed - in lexemes. + 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}') @@ -12518,8 +12518,8 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple to_tsquery to_tsquery ( - config regconfig, - query text ) + config regconfig, + query text ) tsquery @@ -12539,8 +12539,8 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple to_tsvector to_tsvector ( - config regconfig, - document text ) + config regconfig, + document text ) tsvector @@ -12557,14 +12557,14 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple to_tsvector ( - config regconfig, - document json ) + config regconfig, + document json ) tsvector to_tsvector ( - config regconfig, - document jsonb ) + config regconfig, + document jsonb ) tsvector @@ -12593,9 +12593,9 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple json_to_tsvector json_to_tsvector ( - config regconfig, - document json, - filter jsonb ) + config regconfig, + document json, + filter jsonb ) tsvector @@ -12603,14 +12603,14 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple jsonb_to_tsvector jsonb_to_tsvector ( - config regconfig, - document jsonb, - filter jsonb ) + config regconfig, + document jsonb, + filter jsonb ) tsvector Selects each item in the JSON document that is requested by - the filter and converts each one to + 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 @@ -12618,14 +12618,14 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple 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 + 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 + As a special case, the filter can also be a simple JSON value that is one of these keywords. @@ -12643,12 +12643,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_delete - ts_delete ( vector tsvector, lexeme text ) + ts_delete ( vector tsvector, lexeme text ) tsvector - Removes any occurrence of the given lexeme - from the vector. + Removes any occurrence of the given lexeme + from the vector. ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, 'fat') @@ -12658,13 +12658,13 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - ts_delete ( vector tsvector, lexemes text[] ) + ts_delete ( vector tsvector, lexemes text[] ) tsvector Removes any occurrences of the lexemes - in lexemes - from the vector. + in lexemes + from the vector. ts_delete('fat:2,4 cat:3 rat:5A'::tsvector, ARRAY['fat','rat']) @@ -12677,12 +12677,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_filter - ts_filter ( vector tsvector, weights "char"[] ) + ts_filter ( vector tsvector, weights "char"[] ) tsvector - Selects only elements with the given weights - from the vector. + Selects only elements with the given weights + from the vector. ts_filter('fat:2,4 cat:3b,7c rat:5A'::tsvector, '{a,b}') @@ -12696,21 +12696,21 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_headline ts_headline ( - config regconfig, - document text, - query tsquery - , options text ) + 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 + 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. + available options. ts_headline('The fat cat ate the rat.', 'cat') @@ -12721,24 +12721,24 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_headline ( - config regconfig, - document json, - query tsquery - , options text ) + config regconfig, + document json, + query tsquery + , options text ) text ts_headline ( - config regconfig, - document jsonb, - query tsquery - , options text ) + config regconfig, + document jsonb, + query tsquery + , options text ) text Displays, in an abbreviated form, match(es) for - the query that occur in string values - within the JSON document. + the query that occur in string values + within the JSON document. See for more details. @@ -12753,16 +12753,16 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_rank ts_rank ( - weights real[], - vector tsvector, - query tsquery - , normalization integer ) + weights real[], + vector tsvector, + query tsquery + , normalization integer ) real Computes a score showing how well - the vector matches - the query. See + the vector matches + the query. See for details. @@ -12777,16 +12777,16 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_rank_cd ts_rank_cd ( - weights real[], - vector tsvector, - query tsquery - , normalization integer ) + weights real[], + vector tsvector, + query tsquery + , normalization integer ) real Computes a score showing how well - the vector matches - the query, using a cover density + the vector matches + the query, using a cover density algorithm. See for details. @@ -12800,15 +12800,15 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_rewrite - ts_rewrite ( query tsquery, - target tsquery, - substitute tsquery ) + ts_rewrite ( query tsquery, + target tsquery, + substitute tsquery ) tsquery - Replaces occurrences of target - with substitute - within the query. + Replaces occurrences of target + with substitute + within the query. See for details. @@ -12819,12 +12819,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - ts_rewrite ( query tsquery, - select text ) + ts_rewrite ( query tsquery, + select text ) tsquery - Replaces portions of the query according to + Replaces portions of the query according to target(s) and substitute(s) obtained by executing a SELECT command. See for details. @@ -12840,13 +12840,13 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple tsquery_phrase - tsquery_phrase ( query1 tsquery, query2 tsquery ) + tsquery_phrase ( query1 tsquery, query2 tsquery ) tsquery Constructs a phrase query that searches - for matches of query1 - and query2 at successive lexemes (same + for matches of query1 + and query2 at successive lexemes (same as <-> operator). @@ -12857,14 +12857,14 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - tsquery_phrase ( query1 tsquery, query2 tsquery, distance integer ) + 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. + for matches of query1 and + query2 that occur exactly + distance lexemes apart. tsquery_phrase(to_tsquery('fat'), to_tsquery('cat'), 10) @@ -12897,9 +12897,9 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple unnest ( tsvector ) setof record - ( lexeme text, - positions smallint[], - weights text ) + ( lexeme text, + positions smallint[], + weights text ) Expands a tsvector into a set of rows, one per lexeme. @@ -12961,19 +12961,19 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_debug ts_debug ( - config regconfig, - document text ) + config regconfig, + document text ) setof record - ( alias text, - description text, - token text, - dictionaries regdictionary[], - dictionary regdictionary, - lexemes text[] ) + ( alias text, + description text, + token text, + dictionaries regdictionary[], + dictionary regdictionary, + lexemes text[] ) Extracts and normalizes tokens from - the document according to the specified or + the document according to the specified or default text search configuration, and returns information about how each token was processed. See for details. @@ -12989,7 +12989,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_lexize - ts_lexize ( dict regdictionary, token text ) + ts_lexize ( dict regdictionary, token text ) text[] @@ -13009,14 +13009,14 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_parse - ts_parse ( parser_name text, - document text ) + ts_parse ( parser_name text, + document text ) setof record - ( tokid integer, - token text ) + ( tokid integer, + token text ) - Extracts tokens from the document using the + Extracts tokens from the document using the named parser. See for details. @@ -13028,14 +13028,14 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - ts_parse ( parser_oid oid, - document text ) + ts_parse ( parser_oid oid, + document text ) setof record - ( tokid integer, - token text ) + ( tokid integer, + token text ) - Extracts tokens from the document using a + Extracts tokens from the document using a parser specified by OID. See for details. @@ -13050,11 +13050,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_token_type - ts_token_type ( parser_name text ) + ts_token_type ( parser_name text ) setof record - ( tokid integer, - alias text, - description text ) + ( tokid integer, + alias text, + description text ) Returns a table that describes each type of token the named parser can @@ -13069,11 +13069,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - ts_token_type ( parser_oid oid ) + ts_token_type ( parser_oid oid ) setof record - ( tokid integer, - alias text, - description text ) + ( tokid integer, + alias text, + description text ) Returns a table that describes each type of token a parser specified @@ -13091,15 +13091,15 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_stat - ts_stat ( sqlquery text - , weights text ) + ts_stat ( sqlquery text + , weights text ) setof record - ( word text, - ndoc integer, - nentry integer ) + ( word text, + ndoc integer, + nentry integer ) - Executes the sqlquery, which must return a + Executes the sqlquery, which must return a single tsvector column, and returns statistics about each distinct lexeme contained in the data. See for details. @@ -13756,14 +13756,14 @@ SELECT xml_is_well_formed_document('test -xpath_exists ( xpath text, xml xml , nsarray text[] ) boolean +xpath_exists ( xpath text, xml xml , nsarray text[] ) boolean @@ -14143,32 +14143,32 @@ SELECT xmltable.* The following functions map the contents of relational tables to XML values. They can be thought of as XML export functionality: -table_to_xml ( table regclass, nulls boolean, - tableforest boolean, targetns text ) xml -query_to_xml ( query text, nulls boolean, - tableforest boolean, targetns text ) xml -cursor_to_xml ( cursor refcursor, count integer, nulls boolean, - tableforest boolean, targetns text ) xml +table_to_xml ( table regclass, nulls boolean, + tableforest boolean, targetns text ) xml +query_to_xml ( query text, nulls boolean, + tableforest boolean, targetns text ) xml +cursor_to_xml ( cursor refcursor, count integer, nulls boolean, + tableforest boolean, targetns text ) xml table_to_xml maps the content of the named - table, passed as parameter table. The + table, passed as parameter table. The regclass type accepts strings identifying tables using the usual notation, including optional schema qualifications and double quotes. query_to_xml executes the query whose text is passed as parameter - query and maps the result set. + query and maps the result set. cursor_to_xml fetches the indicated number of rows from the cursor specified by the parameter - cursor. This variant is recommended if + cursor. This variant is recommended if large tables have to be mapped, because the result value is built up in memory by each function. - If tableforest is false, then the resulting + If tableforest is false, then the resulting XML document looks like this: @@ -14185,7 +14185,7 @@ SELECT xmltable.* ]]> - If tableforest is true, the result is an + If tableforest is true, the result is an XML content fragment that looks like this: @@ -14222,7 +14222,7 @@ SELECT xmltable.* - The parameter nulls determines whether null + The parameter nulls determines whether null values should be included in the output. If true, null values in columns are represented as: - The parameter targetns specifies the + The parameter targetns specifies the desired XML namespace of the result. If no particular namespace is wanted, an empty string should be passed. @@ -14244,12 +14244,12 @@ SELECT xmltable.* The following functions return XML Schema documents describing the mappings performed by the corresponding functions above: -table_to_xmlschema ( table regclass, nulls boolean, - tableforest boolean, targetns text ) xml -query_to_xmlschema ( query text, nulls boolean, - tableforest boolean, targetns text ) xml -cursor_to_xmlschema ( cursor refcursor, nulls boolean, - tableforest boolean, targetns text ) xml +table_to_xmlschema ( table regclass, nulls boolean, + tableforest boolean, targetns text ) xml +query_to_xmlschema ( query text, nulls boolean, + tableforest boolean, targetns text ) xml +cursor_to_xmlschema ( cursor refcursor, nulls boolean, + tableforest boolean, targetns text ) xml It is essential that the same parameters are passed in order to obtain matching XML data mappings and XML Schema documents. @@ -14261,10 +14261,10 @@ SELECT xmltable.* together. They can be useful where self-contained and self-describing results are wanted: -table_to_xml_and_xmlschema ( table regclass, nulls boolean, - tableforest boolean, targetns text ) xml -query_to_xml_and_xmlschema ( query text, nulls boolean, - tableforest boolean, targetns text ) xml +table_to_xml_and_xmlschema ( table regclass, nulls boolean, + tableforest boolean, targetns text ) xml +query_to_xml_and_xmlschema ( query text, nulls boolean, + tableforest boolean, targetns text ) xml @@ -14273,19 +14273,19 @@ SELECT xmltable.* analogous mappings of entire schemas or the entire current database: -schema_to_xml ( schema name, nulls boolean, - tableforest boolean, targetns text ) xml -schema_to_xmlschema ( schema name, nulls boolean, - tableforest boolean, targetns text ) xml -schema_to_xml_and_xmlschema ( schema name, nulls boolean, - tableforest boolean, targetns text ) xml +schema_to_xml ( schema name, nulls boolean, + tableforest boolean, targetns text ) xml +schema_to_xmlschema ( schema name, nulls boolean, + tableforest boolean, targetns text ) xml +schema_to_xml_and_xmlschema ( schema name, nulls boolean, + tableforest boolean, targetns text ) xml -database_to_xml ( nulls boolean, - tableforest boolean, targetns text ) xml -database_to_xmlschema ( nulls boolean, - tableforest boolean, targetns text ) xml -database_to_xml_and_xmlschema ( nulls boolean, - tableforest boolean, targetns text ) xml +database_to_xml ( nulls boolean, + tableforest boolean, targetns text ) xml +database_to_xmlschema ( nulls boolean, + tableforest boolean, targetns text ) xml +database_to_xml_and_xmlschema ( nulls boolean, + tableforest boolean, targetns text ) xml These functions ignore tables that are not readable by the current user. @@ -14475,7 +14475,7 @@ table2-mapping jsonb - Extracts n'th element of JSON array + Extracts n'th element of JSON array (array elements are indexed from zero, but negative integers count from the end). @@ -14517,7 +14517,7 @@ table2-mapping text - Extracts n'th element of JSON array, + Extracts n'th element of JSON array, as text. @@ -15020,11 +15020,11 @@ table2-mapping - json_object ( keys text[], values text[] ) + json_object ( keys text[], values text[] ) json - jsonb_object ( keys text[], values text[] ) + jsonb_object ( keys text[], values text[] ) jsonb @@ -15155,16 +15155,18 @@ table2-mapping json_each json_each ( json ) - setof key text, - value json + setof record + ( key text, + value json ) jsonb_each jsonb_each ( jsonb ) - setof key text, - value jsonb + setof record + ( key text, + value jsonb ) Expands the top-level JSON object into a set of key/value pairs. @@ -15187,20 +15189,22 @@ table2-mapping json_each_text json_each_text ( json ) - setof key text, - value text + setof record + ( key text, + value text ) jsonb_each_text jsonb_each_text ( jsonb ) - setof key text, - value text + setof record + ( key text, + value text ) Expands the top-level JSON object into a set of key/value pairs. - The returned values will be of + The returned values will be of type text. @@ -15220,14 +15224,14 @@ table2-mapping json_extract_path - json_extract_path ( from_json json, VARIADIC path_elems text[] ) + json_extract_path ( from_json json, VARIADIC path_elems text[] ) json jsonb_extract_path - jsonb_extract_path ( from_json jsonb, VARIADIC path_elems text[] ) + jsonb_extract_path ( from_json jsonb, VARIADIC path_elems text[] ) jsonb @@ -15247,14 +15251,14 @@ table2-mapping json_extract_path_text - json_extract_path_text ( from_json json, VARIADIC path_elems text[] ) + json_extract_path_text ( from_json json, VARIADIC path_elems text[] ) text jsonb_extract_path_text - jsonb_extract_path_text ( from_json jsonb, VARIADIC path_elems text[] ) + jsonb_extract_path_text ( from_json jsonb, VARIADIC path_elems text[] ) text @@ -15303,26 +15307,26 @@ table2-mapping json_populate_record - json_populate_record ( base anyelement, from_json json ) + json_populate_record ( base anyelement, from_json json ) anyelement jsonb_populate_record - jsonb_populate_record ( base anyelement, from_json jsonb ) + jsonb_populate_record ( base anyelement, from_json jsonb ) anyelement Expands the top-level JSON object to a row having the composite type - of the base argument. The JSON object + of the base argument. The JSON object is scanned for fields whose names match column names of the output row type, and their values are inserted into those columns of the output. (Fields that do not correspond to any output column name are ignored.) - In typical use, the value of base is just + In typical use, the value of base is just NULL, which means that any output columns that do not match any object field will be filled with nulls. However, - if base isn't NULL then + if base isn't NULL then the values it contains will be used for unmatched columns. @@ -15395,19 +15399,19 @@ table2-mapping json_populate_recordset - json_populate_recordset ( base anyelement, from_json json ) + json_populate_recordset ( base anyelement, from_json json ) setof anyelement jsonb_populate_recordset - jsonb_populate_recordset ( base anyelement, from_json jsonb ) + jsonb_populate_recordset ( base anyelement, from_json jsonb ) setof anyelement Expands the top-level JSON array of objects to a set of rows having - the composite type of the base argument. + the composite type of the base argument. Each element of the JSON array is processed as described above for json[b]_populate_record. @@ -15500,24 +15504,24 @@ table2-mapping jsonb_set - jsonb_set ( target jsonb, path text[], new_value jsonb , create_if_missing boolean ) + jsonb_set ( target jsonb, path text[], new_value jsonb , create_if_missing boolean ) jsonb - Returns target - with the item designated by path - replaced by new_value, or with - new_value added if - create_if_missing is true (which is the - default) and the item designated by path + Returns target + with the item designated by path + replaced by new_value, or with + new_value added if + create_if_missing is true (which is the + default) and the item designated by path does not exist. All earlier steps in the path must exist, or - the target is returned unchanged. + the target is returned unchanged. As with the path oriented operators, negative integers that - appear in the path count from the end + appear in the path count from the end of JSON arrays. If the last path step is an array index that is out of range, - and create_if_missing is true, the new + and create_if_missing is true, the new value is added at the beginning of the array if the index is negative, or at the end of the array if it is positive. @@ -15536,14 +15540,14 @@ table2-mapping jsonb_set_lax - jsonb_set_lax ( target jsonb, path text[], new_value jsonb , create_if_missing boolean , null_value_treatment text ) + jsonb_set_lax ( target jsonb, path text[], new_value jsonb , create_if_missing boolean , null_value_treatment text ) jsonb - If new_value is not NULL, + If new_value is not NULL, behaves identically to jsonb_set. Otherwise behaves according to the value - of null_value_treatment which must be one + of null_value_treatment which must be one of 'raise_exception', 'use_json_null', 'delete_key', or 'return_target'. The default is @@ -15564,24 +15568,24 @@ table2-mapping jsonb_insert - jsonb_insert ( target jsonb, path text[], new_value jsonb , insert_after boolean ) + jsonb_insert ( target jsonb, path text[], new_value jsonb , insert_after boolean ) jsonb - Returns target - with new_value inserted. If the item - designated by the path is an array - element, new_value will be inserted before - that item if insert_after is false (which + Returns target + with new_value inserted. If the item + designated by the path is an array + element, new_value will be inserted before + that item if insert_after is false (which is the default), or after it - if insert_after is true. If the item - designated by the path is an object - field, new_value will be inserted only if + if insert_after is true. If the item + designated by the path is an object + field, new_value will be inserted only if the object does not already contain that key. All earlier steps in the path must exist, or - the target is returned unchanged. + the target is returned unchanged. As with the path oriented operators, negative integers that - appear in the path count from the end + appear in the path count from the end of JSON arrays. If the last path step is an array index that is out of range, the new value is added at the beginning of the array if the index is negative, @@ -15628,16 +15632,16 @@ table2-mapping jsonb_path_exists - jsonb_path_exists ( target jsonb, path jsonpath , vars jsonb , silent boolean ) + jsonb_path_exists ( target jsonb, path jsonpath , vars jsonb , silent boolean ) boolean Checks whether the JSON path returns any item for the specified JSON value. - If the vars argument is specified, it must + If the vars argument is specified, it must be a JSON object, and its fields provide named values to be substituted into the jsonpath expression. - If the silent argument is specified and + If the silent argument is specified and is true, the function suppresses the same errors as the @? and @@ operators do. @@ -15652,15 +15656,15 @@ table2-mapping jsonb_path_match - jsonb_path_match ( target jsonb, path jsonpath , vars jsonb , silent boolean ) + jsonb_path_match ( target jsonb, path jsonpath , vars jsonb , silent boolean ) boolean Returns the result of a JSON path predicate check for the specified JSON value. Only the first item of the result is taken into account. If the result is not Boolean, then NULL is returned. - The optional vars - and silent arguments act the same as + The optional vars + and silent arguments act the same as for jsonb_path_exists. @@ -15674,14 +15678,14 @@ table2-mapping jsonb_path_query - jsonb_path_query ( target jsonb, path jsonpath , vars jsonb , silent boolean ) + jsonb_path_query ( target jsonb, path jsonpath , vars jsonb , silent boolean ) setof jsonb Returns all JSON items returned by the JSON path for the specified JSON value. - The optional vars - and silent arguments act the same as + The optional vars + and silent arguments act the same as for jsonb_path_exists. @@ -15702,14 +15706,14 @@ table2-mapping jsonb_path_query_array - jsonb_path_query_array ( target jsonb, path jsonpath , vars jsonb , silent boolean ) + jsonb_path_query_array ( target jsonb, path jsonpath , vars jsonb , silent boolean ) jsonb Returns all JSON items returned by the JSON path for the specified JSON value, as a JSON array. - The optional vars - and silent arguments act the same as + The optional vars + and silent arguments act the same as for jsonb_path_exists. @@ -15723,15 +15727,15 @@ table2-mapping jsonb_path_query_first - jsonb_path_query_first ( target jsonb, path jsonpath , vars jsonb , silent boolean ) + jsonb_path_query_first ( target jsonb, path jsonpath , vars jsonb , silent boolean ) jsonb Returns the first JSON item returned by the JSON path for the specified JSON value. Returns NULL if there are no results. - The optional vars - and silent arguments act the same as + The optional vars + and silent arguments act the same as for jsonb_path_exists. @@ -15745,35 +15749,35 @@ table2-mapping jsonb_path_exists_tz - jsonb_path_exists_tz ( target jsonb, path jsonpath , vars jsonb , silent boolean ) + jsonb_path_exists_tz ( target jsonb, path jsonpath , vars jsonb , silent boolean ) boolean jsonb_path_match_tz - jsonb_path_match_tz ( target jsonb, path jsonpath , vars jsonb , silent boolean ) + jsonb_path_match_tz ( target jsonb, path jsonpath , vars jsonb , silent boolean ) boolean jsonb_path_query_tz - jsonb_path_query_tz ( target jsonb, path jsonpath , vars jsonb , silent boolean ) + jsonb_path_query_tz ( target jsonb, path jsonpath , vars jsonb , silent boolean ) setof jsonb jsonb_path_query_array_tz - jsonb_path_query_array_tz ( target jsonb, path jsonpath , vars jsonb , silent boolean ) + jsonb_path_query_array_tz ( target jsonb, path jsonpath , vars jsonb , silent boolean ) jsonb jsonb_path_query_first_tz - jsonb_path_query_first_tz ( target jsonb, path jsonpath , vars jsonb , silent boolean ) + jsonb_path_query_first_tz ( target jsonb, path jsonpath , vars jsonb , silent boolean ) jsonb @@ -17720,14 +17724,14 @@ SELECT NULLIF(value, '(none)') ... array_to_string - array_to_string ( array anyarray, delimiter text , null_string text ) + array_to_string ( array anyarray, delimiter text , null_string text ) text Converts each array element to its text representation, and concatenates those separated by - the delimiter string. - If null_string is given and is + the delimiter string. + If null_string is given and is not NULL, then NULL array entries are represented by that string; otherwise, they are omitted. @@ -17777,19 +17781,19 @@ SELECT NULLIF(value, '(none)') ... string_to_array - string_to_array ( string text, delimiter text , null_string text ) + string_to_array ( string text, delimiter text , null_string text ) text[] - Splits the string at occurrences - of delimiter and forms the remaining data + Splits the string at occurrences + of delimiter and forms the remaining data into a text array. - If delimiter is NULL, - each character in the string will become a + If delimiter is NULL, + each character in the string will become a separate element in the array. - If delimiter is an empty string, then - the string is treated as a single field. - If null_string is supplied and is + If delimiter is an empty string, then + the string is treated as a single field. + If null_string is supplied and is not NULL, fields matching that string are converted to NULL entries. @@ -18535,8 +18539,8 @@ SELECT NULLIF(value, '(none)') ... json_object_agg - json_object_agg ( key - "any", value + json_object_agg ( key + "any", value "any" ) json @@ -18544,8 +18548,8 @@ SELECT NULLIF(value, '(none)') ... jsonb_object_agg - jsonb_object_agg ( key - "any", value + jsonb_object_agg ( key + "any", value "any" ) jsonb @@ -18601,19 +18605,19 @@ SELECT NULLIF(value, '(none)') ... string_agg - string_agg ( value - text, delimiter text ) + string_agg ( value + text, delimiter text ) text - string_agg ( value - bytea, delimiter bytea ) + string_agg ( value + bytea, delimiter bytea ) bytea Concatenates the non-null input values into a string. Each value after the first is preceded by the - corresponding delimiter (if it's not null). + corresponding delimiter (if it's not null). No @@ -18763,10 +18767,10 @@ SELECT count(*) FROM sometable; bigint, numeric, real, and double precision. Where the description mentions - N, it means the + N, it means the number of input rows for which all the input expressions are non-null. In all cases, null is returned if the computation is meaningless, - for example when N is zero. + for example when N is zero. @@ -18802,7 +18806,7 @@ SELECT count(*) FROM sometable; corr - corr ( Y double precision, X double precision ) + corr ( Y double precision, X double precision ) double precision @@ -18820,7 +18824,7 @@ SELECT count(*) FROM sometable; covar_pop - covar_pop ( Y double precision, X double precision ) + covar_pop ( Y double precision, X double precision ) double precision @@ -18838,7 +18842,7 @@ SELECT count(*) FROM sometable; covar_samp - covar_samp ( Y double precision, X double precision ) + covar_samp ( Y double precision, X double precision ) double precision @@ -18852,12 +18856,12 @@ SELECT count(*) FROM sometable; regr_avgx - regr_avgx ( Y double precision, X double precision ) + regr_avgx ( Y double precision, X double precision ) double precision Computes the average of the independent variable, - sum(X)/N. + sum(X)/N. Yes @@ -18867,12 +18871,12 @@ SELECT count(*) FROM sometable; regr_avgy - regr_avgy ( Y double precision, X double precision ) + regr_avgy ( Y double precision, X double precision ) double precision Computes the average of the dependent variable, - sum(Y)/N. + sum(Y)/N. Yes @@ -18882,7 +18886,7 @@ SELECT count(*) FROM sometable; regr_count - regr_count ( Y double precision, X double precision ) + regr_count ( Y double precision, X double precision ) bigint @@ -18899,13 +18903,13 @@ SELECT count(*) FROM sometable; regr_intercept - regr_intercept ( Y double precision, X double precision ) + regr_intercept ( Y double precision, X double precision ) double precision Computes the y-intercept of the least-squares-fit linear equation determined by the - (X, Y) pairs. + (X, Y) pairs. Yes @@ -18915,7 +18919,7 @@ SELECT count(*) FROM sometable; regr_r2 - regr_r2 ( Y double precision, X double precision ) + regr_r2 ( Y double precision, X double precision ) double precision @@ -18932,12 +18936,12 @@ SELECT count(*) FROM sometable; regr_slope - regr_slope ( Y double precision, X double precision ) + regr_slope ( Y double precision, X double precision ) double precision Computes the slope of the least-squares-fit linear equation determined - by the (X, Y) + by the (X, Y) pairs. Yes @@ -18948,13 +18952,13 @@ SELECT count(*) FROM sometable; regr_sxx - regr_sxx ( Y double precision, X double precision ) + regr_sxx ( Y double precision, X double precision ) double precision Computes the sum of squares of the independent variable, - sum(X^2) - sum(X)^2/N. + sum(X^2) - sum(X)^2/N. Yes @@ -18964,13 +18968,13 @@ SELECT count(*) FROM sometable; regr_sxy - regr_sxy ( Y double precision, X double precision ) + regr_sxy ( Y double precision, X double precision ) double precision Computes the sum of products of independent times dependent variables, - sum(X*Y) - sum(X) * sum(Y)/N. + sum(X*Y) - sum(X) * sum(Y)/N. Yes @@ -18980,13 +18984,13 @@ SELECT count(*) FROM sometable; regr_syy - regr_syy ( Y double precision, X double precision ) + regr_syy ( Y double precision, X double precision ) double precision Computes the sum of squares of the dependent variable, - sum(Y^2) - sum(Y)^2/N. + sum(Y^2) - sum(Y)^2/N. Yes @@ -19119,9 +19123,9 @@ SELECT count(*) FROM sometable; ORDER BY, and they may also take a direct argument that is not aggregated, but is computed only once. All these functions ignore null values in their aggregated input. - For those that take a fraction parameter, the + For those that take a fraction parameter, the fraction value must be between 0 and 1; an error is thrown if not. - However, a null fraction value simply produces a + However, a null fraction value simply produces a null result. @@ -19175,16 +19179,16 @@ SELECT count(*) FROM sometable; percentile continuous - percentile_cont ( fraction double precision ) WITHIN GROUP ( ORDER BY double precision ) + percentile_cont ( fraction double precision ) WITHIN GROUP ( ORDER BY double precision ) double precision - percentile_cont ( fraction double precision ) WITHIN GROUP ( ORDER BY interval ) + percentile_cont ( fraction double precision ) WITHIN GROUP ( ORDER BY interval ) interval Computes the continuous percentile, a value - corresponding to the specified fraction + corresponding to the specified fraction within the ordered set of aggregated argument values. This will interpolate between adjacent input items if needed. @@ -19193,16 +19197,16 @@ SELECT count(*) FROM sometable; - percentile_cont ( fractions double precision[] ) WITHIN GROUP ( ORDER BY double precision ) + percentile_cont ( fractions double precision[] ) WITHIN GROUP ( ORDER BY double precision ) double precision[] - percentile_cont ( fractions double precision[] ) WITHIN GROUP ( ORDER BY interval ) + percentile_cont ( fractions double precision[] ) WITHIN GROUP ( ORDER BY interval ) interval[] Computes multiple continuous percentiles. The result is an array of - the same dimensions as the fractions + the same dimensions as the fractions parameter, with each non-null element replaced by the (possibly interpolated) value corresponding to that percentile. @@ -19215,14 +19219,14 @@ SELECT count(*) FROM sometable; percentile discrete - percentile_disc ( fraction double precision ) WITHIN GROUP ( ORDER BY anyelement ) + percentile_disc ( fraction double precision ) WITHIN GROUP ( ORDER BY anyelement ) anyelement Computes the discrete percentile, the first value within the ordered set of aggregated argument values whose position in the ordering equals or exceeds the - specified fraction. The aggregated + specified fraction. The aggregated argument must be of a sortable type. No @@ -19230,12 +19234,12 @@ SELECT count(*) FROM sometable; - percentile_disc ( fractions double precision[] ) WITHIN GROUP ( ORDER BY anyelement ) + percentile_disc ( fractions double precision[] ) WITHIN GROUP ( ORDER BY anyelement ) anyarray Computes multiple discrete percentiles. The result is an array of the - same dimensions as the fractions parameter, + same dimensions as the fractions parameter, with each non-null element replaced by the input value corresponding to that percentile. The aggregated argument must be of a sortable type. @@ -19347,7 +19351,7 @@ SELECT count(*) FROM sometable; Computes the cumulative distribution, that is (number of rows preceding or peers with hypothetical row) / (total rows). The value - thus ranges from 1/N to 1. + thus ranges from 1/N to 1. No @@ -19550,7 +19554,7 @@ SELECT count(*) FROM sometable; Returns the cumulative distribution, that is (number of partition rows preceding or peers with current row) / (total partition rows). - The value thus ranges from 1/N to 1. + The value thus ranges from 1/N to 1. @@ -19559,7 +19563,7 @@ SELECT count(*) FROM sometable; ntile - ntile ( num_buckets integer ) + ntile ( num_buckets integer ) integer @@ -19573,23 +19577,23 @@ SELECT count(*) FROM sometable; lag - lag ( value anyelement - , offset integer - , default anyelement ) + lag ( value anyelement + , offset integer + , default anyelement ) anyelement - Returns value evaluated at - the row that is offset + Returns value evaluated at + the row that is offset rows before the current row within the partition; if there is no such - row, instead returns default + row, instead returns default (which must be of the same type as - value). - Both offset and - default are evaluated + value). + Both offset and + default are evaluated with respect to the current row. If omitted, - offset defaults to 1 and - default to NULL. + offset defaults to 1 and + default to NULL. @@ -19598,23 +19602,23 @@ SELECT count(*) FROM sometable; lead - lead ( value anyelement - , offset integer - , default anyelement ) + lead ( value anyelement + , offset integer + , default anyelement ) anyelement - Returns value evaluated at - the row that is offset + Returns value evaluated at + the row that is offset rows after the current row within the partition; if there is no such - row, instead returns default + row, instead returns default (which must be of the same type as - value). - Both offset and - default are evaluated + value). + Both offset and + default are evaluated with respect to the current row. If omitted, - offset defaults to 1 and - default to NULL. + offset defaults to 1 and + default to NULL. @@ -19623,11 +19627,11 @@ SELECT count(*) FROM sometable; first_value - first_value ( value anyelement ) + first_value ( value anyelement ) anyelement - Returns value evaluated + Returns value evaluated at the row that is the first row of the window frame. @@ -19637,11 +19641,11 @@ SELECT count(*) FROM sometable; last_value - last_value ( value anyelement ) + last_value ( value anyelement ) anyelement - Returns value evaluated + Returns value evaluated at the row that is the last row of the window frame. @@ -19651,12 +19655,12 @@ SELECT count(*) FROM sometable; nth_value - nth_value ( value anyelement, n integer ) + nth_value ( value anyelement, n integer ) anyelement - Returns value evaluated - at the row that is the n'th + Returns value evaluated + at the row that is the n'th row of the window frame (counting from 1); returns NULL if there is no such row.