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]https://www.postgresql.org/docs/current/functions-string.html#FUNCTIONS-STRING-OTHER. 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]https://www.postgresql.org/docs/current/functions-matching.html does not appear to contain a link to the documentation
about the individual pattern matching functions [1]https://www.postgresql.org/docs/current/functions-string.html#FUNCTIONS-STRING-OTHER. 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 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 being named in the built-in
functions.
--
Alex
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 being named 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 being named 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
Attachments:
label-some-parameter-names.patchtext/x-diff; charset=us-ascii; name=label-some-parameter-names.patchDownload
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