Postgres Pro
Downloads
Home   >   mailing lists

Thread: Undocumented functions

Undocumented functions

From
Marcos Pegoraro
Date:
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 ?

regards
Marcos

Re: Undocumented functions

From
Pavel Stehule
Date:
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
Marcos

Re: Undocumented functions

From
Tom Lane
Date:
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

Re: Undocumented functions

From
Marcos Pegoraro
Date:
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