pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feed"name" vs "alias" in datatype table
7+ messages / 5 participants
[nested] [flat]
* "name" vs "alias" in datatype table
@ 2023-11-23 20:51 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 7+ messages in thread
From: PG Doc comments form @ 2023-11-23 20:51 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: eric@aquameta.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/16/datatype.html
Description:
I think there could be some clarification of what is a "name" vs. "alias" on
the datatypes table. Right now, what's in the "Aliases" column is sometimes
postgres's internal type (e.g. `pg_catalog.int4`), and sometimes the "pretty
name", (e.g. `integer`).
How about if this table was laid out still as one row per type, but the
columns were "Names" (plural) and "Internal Name" (singular). Names would
contain both "int" and "integer" (neither of which appear in `pg_type`) and
"Internal Name" would contain "pg_catalog.int4", the "real" name. Then you
could also include arrays here, so that `text[]` would appear in the names
column and `pg_catalog._text` would appear in the "Internal Name" column.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: "name" vs "alias" in datatype table
@ 2023-11-29 13:40 Peter Eisentraut <peter@eisentraut.org>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 7+ messages in thread
From: Peter Eisentraut @ 2023-11-29 13:40 UTC (permalink / raw)
To: eric@aquameta.com; pgsql-docs@lists.postgresql.org
On 23.11.23 21:51, PG Doc comments form wrote:
> I think there could be some clarification of what is a "name" vs. "alias" on
> the datatypes table. Right now, what's in the "Aliases" column is sometimes
> postgres's internal type (e.g. `pg_catalog.int4`), and sometimes the "pretty
> name", (e.g. `integer`).
This appears not to be true. `integer` is not listed as an alias.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: "name" vs "alias" in datatype table
@ 2023-11-29 14:10 Eric Hanson <eric@aquameta.com>
parent: Peter Eisentraut <peter@eisentraut.org>
0 siblings, 1 reply; 7+ messages in thread
From: Eric Hanson @ 2023-11-29 14:10 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; +Cc: pgsql-docs@lists.postgresql.org
On Wed, Nov 29, 2023 at 7:40 AM Peter Eisentraut <peter@eisentraut.org>
wrote:
> On 23.11.23 21:51, PG Doc comments form wrote:
> > I think there could be some clarification of what is a "name" vs.
> "alias" on
> > the datatypes table. Right now, what's in the "Aliases" column is
> sometimes
> > postgres's internal type (e.g. `pg_catalog.int4`), and sometimes the
> "pretty
> > name", (e.g. `integer`).
>
> This appears not to be true. `integer` is not listed as an alias.
>
Sorry, "int" is, and it is not in pg_type.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: "name" vs "alias" in datatype table
@ 2023-11-29 15:16 Eric Hanson <eric@aquameta.com>
parent: Eric Hanson <eric@aquameta.com>
0 siblings, 1 reply; 7+ messages in thread
From: Eric Hanson @ 2023-11-29 15:16 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; +Cc: pgsql-docs@lists.postgresql.org
The larger point being, the "name" vs "alias" paradigm presented in this
table does not accurately represent PostgreSQL, and conveys an inaccurate
picture of the relationship between type names. int4 is not an "alias".
On Wed, Nov 29, 2023 at 8:10 AM Eric Hanson <eric@aquameta.com> wrote:
> On Wed, Nov 29, 2023 at 7:40 AM Peter Eisentraut <peter@eisentraut.org>
> wrote:
>
>> On 23.11.23 21:51, PG Doc comments form wrote:
>> > I think there could be some clarification of what is a "name" vs.
>> "alias" on
>> > the datatypes table. Right now, what's in the "Aliases" column is
>> sometimes
>> > postgres's internal type (e.g. `pg_catalog.int4`), and sometimes the
>> "pretty
>> > name", (e.g. `integer`).
>>
>> This appears not to be true. `integer` is not listed as an alias.
>>
>
> Sorry, "int" is, and it is not in pg_type.
>
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: "name" vs "alias" in datatype table
@ 2023-11-29 16:26 Tom Lane <tgl@sss.pgh.pa.us>
parent: Eric Hanson <eric@aquameta.com>
0 siblings, 2 replies; 7+ messages in thread
From: Tom Lane @ 2023-11-29 16:26 UTC (permalink / raw)
To: Eric Hanson <eric@aquameta.com>; +Cc: Peter Eisentraut <peter@eisentraut.org>; pgsql-docs@lists.postgresql.org
Eric Hanson <eric@aquameta.com> writes:
> The larger point being, the "name" vs "alias" paradigm presented in this
> table does not accurately represent PostgreSQL, and conveys an inaccurate
> picture of the relationship between type names. int4 is not an "alias".
I agree that this could be improved, mainly because it's far from
clear what the internal name of each type is (and there's at least
one case where the internal name is not shown at all).
I could see splitting this into three columns:
1. Preferred name (the standard's name, if it's a standard type)
2. Internal name (pg_type.typname), perhaps only if different from #1
3. Other aliases
However, the table is already pretty wide and so adding another
column might create formatting issues.
AFAICS the only candidates for "other aliases" are char, int,
and decimal. Maybe we could handle those another way than reserving
a table column for them? We could give them their own table rows,
or relegate them to footnotes.
The "serial" types need a bit more reflection too, since they
aren't truly types at all: there is no matching pg_type entry.
I'm not sure they belong here.
regards, tom lane
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: "name" vs "alias" in datatype table
@ 2023-11-29 16:42 Alvaro Herrera <alvherre@alvh.no-ip.org>
parent: Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 0 replies; 7+ messages in thread
From: Alvaro Herrera @ 2023-11-29 16:42 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Eric Hanson <eric@aquameta.com>; Peter Eisentraut <peter@eisentraut.org>; pgsql-docs@lists.postgresql.org
On 2023-Nov-29, Tom Lane wrote:
> Eric Hanson <eric@aquameta.com> writes:
> > The larger point being, the "name" vs "alias" paradigm presented in this
> > table does not accurately represent PostgreSQL, and conveys an inaccurate
> > picture of the relationship between type names. int4 is not an "alias".
>
> I agree that this could be improved, mainly because it's far from
> clear what the internal name of each type is (and there's at least
> one case where the internal name is not shown at all).
Maybe we could split this into multiple *tables*. The main one would be
what we already have except the aliases column is removed, and serial
types removed; the second table would list serial pseudo-types, without
aliases; the third one would have unofficial names (internal names and
other aliases) for types listed in the other two.
--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
"The ability of users to misuse tools is, of course, legendary" (David Steele)
https://postgr.es/m/11b38a96-6ded-4668-b772-40f992132797@pgmasters.net
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: "name" vs "alias" in datatype table
@ 2023-11-29 18:27 Eric Hanson <eric@aquameta.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 0 replies; 7+ messages in thread
From: Eric Hanson @ 2023-11-29 18:27 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Peter Eisentraut <peter@eisentraut.org>; pgsql-docs@lists.postgresql.org
On Wed, Nov 29, 2023 at 10:26 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> I could see splitting this into three columns:
>
> 1. Preferred name (the standard's name, if it's a standard type)
>
> 2. Internal name (pg_type.typname), perhaps only if different from #1
>
> 3. Other aliases
>
I like the preferred name being the preferred name and focal point, as most
users aren't going to much care about internal type names. For "int",
"decimal" and "char", how about a "shorthand" column? Wouldn't be too
wide. So:
1. Name
2. Shorthand
3. Internal name
4. Description
And maybe a paragraph at the top explaining that types have multiple names
that can be used interchangeably, but users are encouraged to use the
standard names for beauty and clarity.
I could also see splitting this into two tables. First just a) Name,
Description. Second, a paragraph about internal names and such, then b)
Name, Shorthand, Internal Name, Description. That way for quick reference
people will just see a simple table that gets 90% of readers what they need.
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2023-11-29 18:27 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-11-23 20:51 "name" vs "alias" in datatype table PG Doc comments form <noreply@postgresql.org>
2023-11-29 13:40 ` Peter Eisentraut <peter@eisentraut.org>
2023-11-29 14:10 ` Eric Hanson <eric@aquameta.com>
2023-11-29 15:16 ` Eric Hanson <eric@aquameta.com>
2023-11-29 16:26 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-11-29 16:42 ` Alvaro Herrera <alvherre@alvh.no-ip.org>
2023-11-29 18:27 ` Eric Hanson <eric@aquameta.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox