From 875d00e88d23389e49c6f8552f84052da1a679d9 Mon Sep 17 00:00:00 2001 From: Fujii Masao Date: Mon, 2 Nov 2026 00:56:18 +0900 Subject: [PATCH v1] doc: Match built-in function parameter names to their SQL names Several documented function signatures used parameter names that differed from the registered SQL names, causing named-argument calls using the documented names to fail. Update the signatures and corresponding descriptions to use the SQL-visible names, without affecting existing calls. Backpatch to all supported versions, except for the changes to pg_logical_emit_message and pg_input_error_info, which are backpatched through v17 and v16, respectively. Reported-by: Mi cro Author: Fujii Masao Discussion: https://postgr.es/m/19D9D4CB-8C31-493E-982A-1E17042D68C5%40gmail.com Backpatch-through: 14 --- doc/src/sgml/func/func-admin.sgml | 6 +++--- doc/src/sgml/func/func-datetime.sgml | 4 ++-- doc/src/sgml/func/func-info.sgml | 6 +++--- doc/src/sgml/func/func-json.sgml | 26 +++++++++++++------------- doc/src/sgml/func/func-string.sgml | 8 ++++---- doc/src/sgml/func/func-textsearch.sgml | 12 ++++++------ doc/src/sgml/func/func-xml.sgml | 8 ++++---- doc/src/sgml/textsearch.sgml | 10 +++++----- 8 files changed, 40 insertions(+), 40 deletions(-) diff --git a/doc/src/sgml/func/func-admin.sgml b/doc/src/sgml/func/func-admin.sgml index 64b0e7bb972..ed872264f02 100644 --- a/doc/src/sgml/func/func-admin.sgml +++ b/doc/src/sgml/func/func-admin.sgml @@ -1457,11 +1457,11 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset pg_logical_emit_message - pg_logical_emit_message ( transactional boolean, prefix text, content text , flush boolean DEFAULT false ) + pg_logical_emit_message ( transactional boolean, prefix text, message text , flush boolean DEFAULT false ) pg_lsn - pg_logical_emit_message ( transactional boolean, prefix text, content bytea , flush boolean DEFAULT false ) + pg_logical_emit_message ( transactional boolean, prefix text, message bytea , flush boolean DEFAULT false ) pg_lsn @@ -1473,7 +1473,7 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset reads the record. The prefix parameter is a textual prefix that can be used by logical decoding plugins to easily recognize messages that are interesting for them. - The content parameter is the content of the + The message parameter is the content of the message, given either in text or binary form. The flush parameter (default set to false) controls if the message is immediately diff --git a/doc/src/sgml/func/func-datetime.sgml b/doc/src/sgml/func/func-datetime.sgml index 39dddde4fe1..63fb9c53c0d 100644 --- a/doc/src/sgml/func/func-datetime.sgml +++ b/doc/src/sgml/func/func-datetime.sgml @@ -863,7 +863,7 @@ make_timestamp ( year int, month int, - day int, + mday int, hour int, min int, sec double precision ) @@ -886,7 +886,7 @@ make_timestamptz ( year int, month int, - day int, + mday int, hour int, min int, sec double precision diff --git a/doc/src/sgml/func/func-info.sgml b/doc/src/sgml/func/func-info.sgml index c9c0261b52f..b6c080715ba 100644 --- a/doc/src/sgml/func/func-info.sgml +++ b/doc/src/sgml/func/func-info.sgml @@ -2729,8 +2729,8 @@ acl | {postgres=arwdDxtm/postgres,foo=r/postgres} pg_input_error_info pg_input_error_info ( - string text, - type text + value text, + type_name text ) record ( message text, @@ -2739,7 +2739,7 @@ acl | {postgres=arwdDxtm/postgres,foo=r/postgres} sql_error_code text ) - Tests whether the given string is valid + Tests whether the given value is valid input for the specified data type; if not, return the details of the error that would have been thrown. If the input is valid, the results are NULL. The inputs are the same as diff --git a/doc/src/sgml/func/func-json.sgml b/doc/src/sgml/func/func-json.sgml index 0763ec81ed8..ede39e7d024 100644 --- a/doc/src/sgml/func/func-json.sgml +++ b/doc/src/sgml/func/func-json.sgml @@ -1470,19 +1470,19 @@ ERROR: value too long for type character(2) jsonb_set - jsonb_set ( target jsonb, path text[], new_value jsonb , create_if_missing boolean ) + jsonb_set ( jsonb_in jsonb, path text[], replacement jsonb , create_if_missing boolean ) jsonb - Returns target + Returns jsonb_in with the item designated by path - replaced by new_value, or with - new_value added if + replaced by replacement, or with + replacement 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 jsonb_in is returned unchanged. As with the path oriented operators, negative integers that appear in the path count from the end of JSON arrays. @@ -1506,11 +1506,11 @@ ERROR: value too long for type character(2) jsonb_set_lax - jsonb_set_lax ( target jsonb, path text[], new_value jsonb , create_if_missing boolean , null_value_treatment text ) + jsonb_set_lax ( jsonb_in jsonb, path text[], replacement jsonb , create_if_missing boolean , null_value_treatment text ) jsonb - If new_value is not NULL, + If replacement is not NULL, behaves identically to jsonb_set. Otherwise behaves according to the value of null_value_treatment which must be one @@ -1534,22 +1534,22 @@ ERROR: value too long for type character(2) jsonb_insert - jsonb_insert ( target jsonb, path text[], new_value jsonb , insert_after boolean ) + jsonb_insert ( jsonb_in jsonb, path text[], replacement jsonb , insert_after boolean ) jsonb - Returns target - with new_value inserted. If the item + Returns jsonb_in + with replacement inserted. If the item designated by the path is an array - element, new_value will be inserted before + element, replacement 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 + field, replacement 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 jsonb_in is returned unchanged. As with the path oriented operators, negative integers that appear in the path count from the end of JSON arrays. diff --git a/doc/src/sgml/func/func-string.sgml b/doc/src/sgml/func/func-string.sgml index 941ebd3cd68..c50fe0bb396 100644 --- a/doc/src/sgml/func/func-string.sgml +++ b/doc/src/sgml/func/func-string.sgml @@ -830,13 +830,13 @@ parse_ident - parse_ident ( qualified_identifier text - , strict_mode boolean DEFAULT true ) + parse_ident ( str text + , strict boolean DEFAULT true ) text[] - Splits qualified_identifier into an array of - identifiers, removing any quoting of individual identifiers. By + Splits the qualified identifier str into an + array of identifiers, removing any quoting of individual identifiers. By default, extra characters after the last identifier are considered an error; but if the second parameter is false, then such extra characters are ignored. (This behavior is useful for parsing diff --git a/doc/src/sgml/func/func-textsearch.sgml b/doc/src/sgml/func/func-textsearch.sgml index 290ad81d697..4d2d9ec9110 100644 --- a/doc/src/sgml/func/func-textsearch.sgml +++ b/doc/src/sgml/func/func-textsearch.sgml @@ -940,13 +940,13 @@ ts_parse ts_parse ( parser_name text, - document text ) + txt text ) setof record ( tokid integer, token text ) - Extracts tokens from the document using the + Extracts tokens from the document txt using the named parser. See for details. @@ -959,13 +959,13 @@ ts_parse ( parser_oid oid, - document text ) + txt text ) setof record ( tokid integer, token text ) - Extracts tokens from the document using a + Extracts tokens from the document txt using a parser specified by OID. See for details. @@ -1021,7 +1021,7 @@ ts_stat - ts_stat ( sqlquery text + ts_stat ( query text , weights text ) setof record ( word text, @@ -1029,7 +1029,7 @@ nentry integer ) - Executes the sqlquery, which must return a + Executes the query, which must return a single tsvector column, and returns statistics about each distinct lexeme contained in the data. See for details. diff --git a/doc/src/sgml/func/func-xml.sgml b/doc/src/sgml/func/func-xml.sgml index 511bc90852a..3b42a3100f9 100644 --- a/doc/src/sgml/func/func-xml.sgml +++ b/doc/src/sgml/func/func-xml.sgml @@ -1023,7 +1023,7 @@ 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, +table_to_xml ( tbl regclass, nulls boolean, tableforest boolean, targetns text ) xml query_to_xml ( query text, nulls boolean, tableforest boolean, targetns text ) xml @@ -1034,7 +1034,7 @@ SELECT xmltable.* table_to_xml maps the content of the named - table, passed as parameter table. The + table, passed as parameter tbl. The regclass type accepts strings identifying tables using the usual notation, including optional schema qualification and double quotes (see for details). @@ -1125,7 +1125,7 @@ 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, +table_to_xmlschema ( tbl regclass, nulls boolean, tableforest boolean, targetns text ) xml query_to_xmlschema ( query text, nulls boolean, tableforest boolean, targetns text ) xml @@ -1142,7 +1142,7 @@ 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, +table_to_xml_and_xmlschema ( tbl regclass, nulls boolean, tableforest boolean, targetns text ) xml query_to_xml_and_xmlschema ( query text, nulls boolean, tableforest boolean, targetns text ) xml diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml index 2f3a76bef1e..e78346fa64a 100644 --- a/doc/src/sgml/textsearch.sgml +++ b/doc/src/sgml/textsearch.sgml @@ -2010,13 +2010,13 @@ CREATE TRIGGER tsvectorupdate BEFORE INSERT OR UPDATE -ts_stat(sqlquery text, weights text, +ts_stat(query text, weights text, OUT word text, OUT ndoc integer, OUT nentry integer) returns setof record - sqlquery is a text value containing an SQL + query is a text value containing an SQL query which must return a single tsvector column. ts_stat executes the query and returns statistics about each distinct lexeme (word) contained in the tsvector @@ -3549,14 +3549,14 @@ FROM ts_debug('public.english', 'The Brightest supernovaes'); -ts_parse(parser_name text, document text, +ts_parse(parser_name text, txt text, OUT tokid integer, OUT token text) returns setof record -ts_parse(parser_oid oid, document text, +ts_parse(parser_oid oid, txt text, OUT tokid integer, OUT token text) returns setof record - ts_parse parses the given document + ts_parse parses the document txt and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the -- 2.56.0