Documented parameter names differ from callable proargnames for several built-ins

From: Mi cro <micro6947(at)gmail(dot)com>
To: pgsql-docs(at)postgresql(dot)org
Subject: Documented parameter names differ from callable proargnames for several built-ins
Date: 2026-10-31 06:39:20
Message-ID: 19D9D4CB-8C31-493E-982A-1E17042D68C5@gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-docs

Hello,

Several built-in functions are documented with parameter names that differ from
the names registered in pg_proc. PostgreSQL supports named-argument calls, so
these differences directly affect whether the documented call can be used.

For example, on PostgreSQL 16.14:

SELECT parse_ident(str => 'a.b');
-- {a,b}

SELECT parse_ident(qualified_identifier => 'a.b');
-- ERROR: function parse_ident(qualified_identifier => unknown) does not exist

The current REL_18_STABLE documentation uses qualified_identifier/strict_mode,
while pg_proc.dat registers the names as str/strict.

The same class of mismatch appears in:

- make_timestamp and make_timestamptz: documentation uses day;
pg_proc uses mday.
- jsonb_set, jsonb_set_lax, and jsonb_insert: documentation uses
target/new_value; the registered names are jsonb_in/replacement.
- table_to_xml, table_to_xmlschema, and table_to_xml_and_xmlschema:
documentation uses table; pg_proc uses tbl.
- pg_logical_emit_message in PG18: documentation uses content; the SQL-visible
name is message for both overloads.

References:

https://www.postgresql.org/docs/current/sql-syntax-calling-funcs.html
https://github.com/postgres/postgres/blob/REL_18_STABLE/doc/src/sgml/func.sgml
https://github.com/postgres/postgres/blob/REL_18_STABLE/src/include/catalog/pg_proc.dat
https://github.com/postgres/postgres/blob/REL_18_STABLE/src/backend/catalog/system_functions.sql

I suggest updating the displayed names to the SQL-visible parameter names.
Renaming the runtime parameters would change named-call compatibility.

Regards

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message PG Doc comments form 2026-10-31 06:56:18 routine_sequence_usage column is named sequence_catalog, not schema_catalog
Previous Message Michael Paquier 2026-10-31 00:21:35 Re: postmaster.pid also contains shared memory key