Обсуждение: builtin functions, parameter names and psql's \df

Hi,

on a regular basis I remember a builtin function's name, or can figure it out
using \df etc, but can't remember the argument order. A typical example is
regexp_*, where I never remember whether the pattern or the input string comes
first.

Unfortunatly \df does not really help with that:

=# \df regexp_split_to_table
┌────────────┬───────────────────────┬──────────────────┬─────────────────────┬──────┐
│   Schema   │         Name          │ Result data type │ Argument data types │ Type │
├────────────┼───────────────────────┼──────────────────┼─────────────────────┼──────┤
│ pg_catalog │ regexp_split_to_table │ SETOF text       │ text, text          │ func │
│ pg_catalog │ regexp_split_to_table │ SETOF text       │ text, text, text    │ func │
└────────────┴───────────────────────┴──────────────────┴─────────────────────┴──────┘

If the parameters were named however, it'd be clear:

=# CREATE OR REPLACE FUNCTION pg_catalog.regexp_split_to_table(string text, pattern text)
 RETURNS SETOF text
 LANGUAGE internal
 IMMUTABLE PARALLEL SAFE STRICT
AS $function$regexp_split_to_table_no_flags$function$

=# \df regexp_split_to_table
┌────────────┬───────────────────────┬──────────────────┬──────────────────────────┬──────┐
│   Schema   │         Name          │ Result data type │   Argument data types    │ Type │
├────────────┼───────────────────────┼──────────────────┼──────────────────────────┼──────┤
│ pg_catalog │ regexp_split_to_table │ SETOF text       │ string text, pattern text │ func │
│ pg_catalog │ regexp_split_to_table │ SETOF text       │ text, text, text         │ func │
└────────────┴───────────────────────┴──────────────────┴──────────────────────────┴──────┘

(I intentionally left the three parameter version unchanged, to show the difference)


In the docs we already name the parameters using SQL like syntax, see [1]. How
about we actually do so for at least the more common / complicated functions?
It may not be worth adding operator names for every comparator, but for
functions we expect to be used directly it seems worthwhile?

It sure would be some initial work, but it seems doable.

Comments?


A mildly related note: It's a bit annoying that the "Pattern Matching"
documentation page [2] does not appear to contain a link to the documentation
about the individual pattern matching functions [1].  Am I missing something?

Greetings,

Andres Freund

[1] https://www.postgresql.org/docs/current/functions-string.html#FUNCTIONS-STRING-OTHER
[2] https://www.postgresql.org/docs/current/functions-matching.html

On Wed, Sep 2, 2020 at 9:13 AM Oleksandr Shulgin
<oleksandr.shulgin@zalando.de> wrote:
>
> On Wed, Sep 2, 2020 at 7:35 AM Andres Freund <andres@anarazel.de> wrote:
>>
>> Hi,
>>
>> on a regular basis I remember a builtin function's name, or can figure it out
>> using \df etc, but can't remember the argument order. A typical example is
>> regexp_*, where I never remember whether the pattern or the input string comes
>> first.
>>
>> Unfortunatly \df does not really help with that:
>>
>> =# \df regexp_split_to_table
>> ┌────────────┬───────────────────────┬──────────────────┬─────────────────────┬──────┐
>> │   Schema   │         Name          │ Result data type │ Argument data types │ Type │
>> ├────────────┼───────────────────────┼──────────────────┼─────────────────────┼──────┤
>> │ pg_catalog │ regexp_split_to_table │ SETOF text       │ text, text          │ func │
>> │ pg_catalog │ regexp_split_to_table │ SETOF text       │ text, text, text    │ func │
>> └────────────┴───────────────────────┴──────────────────┴─────────────────────┴──────┘
>>
>> If the parameters were named however, it'd be clear:
>>
>> =# CREATE OR REPLACE FUNCTION pg_catalog.regexp_split_to_table(string text, pattern text)
>>  RETURNS SETOF text
>>  LANGUAGE internal
>>  IMMUTABLE PARALLEL SAFE STRICT
>> AS $function$regexp_split_to_table_no_flags$function$
>>
>> =# \df regexp_split_to_table
>> ┌────────────┬───────────────────────┬──────────────────┬──────────────────────────┬──────┐
>> │   Schema   │         Name          │ Result data type │   Argument data types    │ Type │
>> ├────────────┼───────────────────────┼──────────────────┼──────────────────────────┼──────┤
>> │ pg_catalog │ regexp_split_to_table │ SETOF text       │ string text, pattern text │ func │
>> │ pg_catalog │ regexp_split_to_table │ SETOF text       │ text, text, text         │ func │
>> └────────────┴───────────────────────┴──────────────────┴──────────────────────────┴──────┘
>>
>> (I intentionally left the three parameter version unchanged, to show the difference)
>>
>>
>> In the docs we already name the parameters using SQL like syntax, see [1]. How
>> about we actually do so for at least the more common / complicated functions?
>
>
> +many
>
> I find myself in the same situation a lot.
> I've never realized that's an implementation detail and not something fundamental preventing the parameters from
beingnamed in the built-in functions.
 

Same here, it would be a very nice improvement.

On 02/09/2020 19:15, Julien Rouhaud wrote:
> On Wed, Sep 2, 2020 at 9:13 AM Oleksandr Shulgin
> <oleksandr.shulgin@zalando.de> wrote:
>> On Wed, Sep 2, 2020 at 7:35 AM Andres Freund <andres@anarazel.de> wrote:
>>> Hi,
>>>
>>> on a regular basis I remember a builtin function's name, or can figure it out
>>> using \df etc, but can't remember the argument order. A typical example is
>>> regexp_*, where I never remember whether the pattern or the input string comes
>>> first.
>>>
>>> Unfortunatly \df does not really help with that:
>>>
>>> =# \df regexp_split_to_table
>>> ┌────────────┬───────────────────────┬──────────────────┬─────────────────────┬──────┐
>>> │   Schema   │         Name          │ Result data type │ Argument data types │ Type │
>>> ├────────────┼───────────────────────┼──────────────────┼─────────────────────┼──────┤
>>> │ pg_catalog │ regexp_split_to_table │ SETOF text       │ text, text          │ func │
>>> │ pg_catalog │ regexp_split_to_table │ SETOF text       │ text, text, text    │ func │
>>> └────────────┴───────────────────────┴──────────────────┴─────────────────────┴──────┘
>>>
>>> If the parameters were named however, it'd be clear:
>>>
>>> =# CREATE OR REPLACE FUNCTION pg_catalog.regexp_split_to_table(string text, pattern text)
>>>   RETURNS SETOF text
>>>   LANGUAGE internal
>>>   IMMUTABLE PARALLEL SAFE STRICT
>>> AS $function$regexp_split_to_table_no_flags$function$
>>>
>>> =# \df regexp_split_to_table
>>> ┌────────────┬───────────────────────┬──────────────────┬──────────────────────────┬──────┐
>>> │   Schema   │         Name          │ Result data type │   Argument data types    │ Type │
>>> ├────────────┼───────────────────────┼──────────────────┼──────────────────────────┼──────┤
>>> │ pg_catalog │ regexp_split_to_table │ SETOF text       │ string text, pattern text │ func │
>>> │ pg_catalog │ regexp_split_to_table │ SETOF text       │ text, text, text         │ func │
>>> └────────────┴───────────────────────┴──────────────────┴──────────────────────────┴──────┘
>>>
>>> (I intentionally left the three parameter version unchanged, to show the difference)
>>>
>>>
>>> In the docs we already name the parameters using SQL like syntax, see [1]. How
>>> about we actually do so for at least the more common / complicated functions?
>>
>> +many
>>
>> I find myself in the same situation a lot.
>> I've never realized that's an implementation detail and not something fundamental preventing the parameters from
beingnamed in the built-in functions.
 
> Same here, it would be a very nice improvement.

+1

Oleksandr Shulgin <oleksandr.shulgin@zalando.de> writes:
> On Wed, Sep 2, 2020 at 7:35 AM Andres Freund <andres@anarazel.de> wrote:
>> In the docs we already name the parameters using SQL like syntax, see [1].
>> How about we actually do so for at least the more common / complicated
>> functions?

> I find myself in the same situation a lot.
> I've never realized that's an implementation detail and not something
> fundamental preventing the parameters from being named in the built-in
> functions.

Yeah, it's not really hard to fix; somebody just has to do the legwork.
The attached is enough to get me to

regression=# \df regexp_split_to_table
                                          List of functions
   Schema   |         Name          | Result data type |          Argument data types          | Type
------------+-----------------------+------------------+---------------------------------------+------
 pg_catalog | regexp_split_to_table | SETOF text       | string text, pattern text             | func
 pg_catalog | regexp_split_to_table | SETOF text       | string text, pattern text, flags text | func
(2 rows)

I don't think we should go overboard on this, but +1 for labeling all the
cases where the usage isn't obvious.

            regards, tom lane

diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat
index 1dd325e0e6..ecf1299ef3 100644
--- a/src/include/catalog/pg_proc.dat
+++ b/src/include/catalog/pg_proc.dat
@@ -3551,10 +3551,12 @@
 { oid => '2765', descr => 'split string by pattern',
   proname => 'regexp_split_to_table', prorows => '1000', proretset => 't',
   prorettype => 'text', proargtypes => 'text text',
+  proargnames => '{string,pattern}',
   prosrc => 'regexp_split_to_table_no_flags' },
 { oid => '2766', descr => 'split string by pattern',
   proname => 'regexp_split_to_table', prorows => '1000', proretset => 't',
   prorettype => 'text', proargtypes => 'text text text',
+  proargnames => '{string,pattern,flags}',
   prosrc => 'regexp_split_to_table' },
 { oid => '2767', descr => 'split string by pattern',
   proname => 'regexp_split_to_array', prorettype => '_text',

On 2020-Sep-02, Tom Lane wrote:

> I don't think we should go overboard on this, but +1 for labeling all the
> cases where the usage isn't obvious.

+1

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services