Undocumented functions

Hi

so 7. 9. 2024 v 20:58 odesílatel Marcos Pegoraro <marcos@f10.com.br> napsal:

Some days ago Tom Lane said ...

SELECT events & 4 != 0 AS can_upd, events & 8 != 0 AS can_ins, events & 16
!= 0 AS can_del FROM
pg_catalog.pg_relation_is_updatable('_pessoa'::regclass, false) t(events);

Well, I didn't find that function on DOCs and then I thought, are there
other functions which are not documented ? Why ?
Then if I get all functions from pg_catalog
select string_agg(distinct format('"%s"',proname),',') from pg_proc where
pronamespace::regnamespace::text = 'pg_catalog'

using PowerShell declare a variable, on the SGML folder I use ...

$vv = (result of that select)
foreach ($v in $vv) {if (!((Get-Content . | %{$_ -match $v}) -contains
$true)) {
Write-Host $v}}

I'll get all functions which are on pg_catalog but not on SGML files, so
are not documented.

Example, elem_contained_by_range is not documented. I know I can use
select 2 <@ '[1,3]'::int4range
But why is that function not documented ?
select elem_contained_by_range(2,'[1,3]'::int4range);

And what other functions are cool to use but are not documented ?

there are lot of useful undocumented functions - see queries from
https://github.com/postgres/postgres/blob/master/src/bin/psql/describe.c

I see the main reason for the existence of undocumented functions inside
Postgres or MSSQL is a missing guarantee of stability or existence.

Everything in the pg_catalog schema can be different with every major
release. pg_relation_is_updatable is part of FDW support, it is not
designed for users.

Regards

Pavel

Marcos Pegoraro <marcos@f10.com.br> writes:

Example, elem_contained_by_range is not documented. I know I can use
select 2 <@ '[1,3]'::int4range
But why is that function not documented ?

Functions that are primarily meant to implement operators are
normally not documented separately: we feel it would bloat the
docs without adding a lot. There are pg_description entries for
them, eg

regression=# \df+ elem_contained_by_range
List of functions
Schema | Name | Result data type | Argument data types | Type | Volatility | Parallel | Owner | Security | Access privileges | Language | Internal name | Description
------------+-------------------------+------------------+----------------------+------+------------+----------+----------+----------+-------------------+----------+-------------------------+-------------------------------
pg_catalog | elem_contained_by_range | boolean | anyelement, anyrange | func | immutable | safe | postgres | invoker | | internal | elem_contained_by_range | implementation of <@ operator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(1 row)

I think pg_relation_is_updatable is primarily meant as support for the
information_schema views, which may explain why it's not in the docs
either. There's less of a formal policy about functions underlying
system views, but the majority of them probably aren't documented.

regards, tom lane

Em sáb., 7 de set. de 2024 às 17:18, Tom Lane <tgl@sss.pgh.pa.us> escreveu
Functions that are primarily meant to implement operators are normally not
documented separately: we feel it would bloat the
docs without adding a lot

Those two functions, elem_contained_by_range and pg_relation_is_updatable
were only examples of hundreds of functions which are not documented.
The real question here is not for the ones that are used internally because
operators or types need them, I'm talking about those ones which does not
have a way to replace it ?

pg_get_shmem_allocations is cool and is not mentioned on DOC
pg_is_in_backup was mentioned until version 12, then removed. Why, it´s not
used anymore.

This is the question, what functions exist and are useful but are not
documented ?

regards
Marcos

Marcos