pg.ddx.io pgsql-hackers@postgresql.org mailing list archive help / color / mirror / Atom feed From: Bruce Momjian <bruce@momjian.us>
To: Kyotaro Horiguchi <horikyota.ntt@gmail.com>
Cc: myon@debian.org
Cc: pgsql-hackers@postgresql.org
Subject: Re: "box" type description
Date: Thu, 2 Nov 2023 16:12:57 -0400
Message-ID: <ZUQCyfLJtR-Wufd5@momjian.us> (raw )
In-Reply-To: <20231102.172820.870529595012234106.horikyota.ntt@gmail.com >
References: <20210331.113240.1063412187478637420.horikyota.ntt@gmail.com >
<YGRgcxaMCFized8b@msg.df7cb.de >
<ZUJwYXGeuVkWzkDB@momjian.us >
<20231102.172820.870529595012234106.horikyota.ntt@gmail.com >
On Thu, Nov 2, 2023 at 05:28:20PM +0900, Kyotaro Horiguchi wrote:
> Thank you for continuing this. The additional changes looks
> fine.
>
> Upon reviewing the table again in this line, further potential
> improvements and issues have been found. For example:
>
> character, varchar: don't follow the rule.
> - 'char(length)' blank-padded string, fixed storage length
> + blank-padded string, fixed storage length, format 'char(length)'
So, char() and varchar() are _definition_ synonyms for characater and
character varying, so I put the way you define them at the _front_ of
the text. The "format" is the _output_ format and I put that at the end
for other types. I put numeric() at the front too since its definition
is complex. (I now see numeric should be "precision, scale" so I fixed
that.)
> interval: doesn't follow the rule.
> - @ <number> <units>, time interval
> + time interval, format '[@] <number> <units>'
> (I think '@' is not necessary here..)
Agreed, '@' is optional so removed, and I added "...".
> pg_snapshot:
>
> The description given is just "snapshot", which seems overly simplistic.
>
> txid_snapshot:
>
> The description reads "transaction snapshot". Is this really
> accurate, especially in contrast with pg_snapshot?
Uh, the docs have for txid_snapshot:
user-level transaction ID snapshot (deprecated; see
<type>pg_snapshot</type>)<
Do we want to add "deprecated" in the output.
> pg_brin_bloom_summary, pg_brin_minmax_multi_summary, pg_mcv_list and many:
>
> I'm uncertain whether these types, which lack an input syntax (but
> have an output format), qualify as pseudo-types. Nevertheless, I
> believe it would be beneficial to describe that those types differ
> from ordinary types.
Good point, now labeled as pseudo-types.
Updated patch attached.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
Attachments:
box.diff (text/x-diff, 9.8K) download
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 5a6cfbd94d..55340b00ad 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -3366,13 +3366,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
<entry><type>lseg</type></entry>
<entry>32 bytes</entry>
<entry>Finite line segment</entry>
- <entry>((x1,y1),(x2,y2))</entry>
+ <entry>[(x1,y1),(x2,y2)]</entry>
</row>
<row>
<entry><type>box</type></entry>
<entry>32 bytes</entry>
<entry>Rectangular box</entry>
- <entry>((x1,y1),(x2,y2))</entry>
+ <entry>(x1,y1),(x2,y2)</entry>
</row>
<row>
<entry><type>path</type></entry>
diff --git a/src/include/catalog/pg_type.dat b/src/include/catalog/pg_type.dat
index 92bcaf2c73..f6110a850d 100644
--- a/src/include/catalog/pg_type.dat
+++ b/src/include/catalog/pg_type.dat
@@ -32,7 +32,7 @@
# OIDS 1 - 99
{ oid => '16', array_type_oid => '1000',
- descr => 'boolean, \'true\'/\'false\'',
+ descr => 'boolean, format \'t\'/\'f\'',
typname => 'bool', typlen => '1', typbyval => 't', typcategory => 'B',
typispreferred => 't', typinput => 'boolin', typoutput => 'boolout',
typreceive => 'boolrecv', typsend => 'boolsend', typalign => 'c' },
@@ -90,7 +90,7 @@
typispreferred => 't', typinput => 'oidin', typoutput => 'oidout',
typreceive => 'oidrecv', typsend => 'oidsend', typalign => 'i' },
{ oid => '27', array_type_oid => '1010',
- descr => '(block, offset), physical location of tuple',
+ descr => 'tuple physical location, format \'(block,offset)\'',
typname => 'tid', typlen => '6', typbyval => 'f', typcategory => 'U',
typinput => 'tidin', typoutput => 'tidout', typreceive => 'tidrecv',
typsend => 'tidsend', typalign => 's' },
@@ -179,34 +179,34 @@
# OIDS 600 - 699
{ oid => '600', array_type_oid => '1017',
- descr => 'geometric point \'(x, y)\'',
+ descr => 'geometric point, format \'(x,y)\'',
typname => 'point', typlen => '16', typbyval => 'f', typcategory => 'G',
typsubscript => 'raw_array_subscript_handler', typelem => 'float8',
typinput => 'point_in', typoutput => 'point_out', typreceive => 'point_recv',
typsend => 'point_send', typalign => 'd' },
{ oid => '601', array_type_oid => '1018',
- descr => 'geometric line segment \'(pt1,pt2)\'',
+ descr => 'geometric line segment, format \'[point1,point2]\'',
typname => 'lseg', typlen => '32', typbyval => 'f', typcategory => 'G',
typsubscript => 'raw_array_subscript_handler', typelem => 'point',
typinput => 'lseg_in', typoutput => 'lseg_out', typreceive => 'lseg_recv',
typsend => 'lseg_send', typalign => 'd' },
{ oid => '602', array_type_oid => '1019',
- descr => 'geometric path \'(pt1,...)\'',
+ descr => 'geometric path, format \'(point1,...)\'',
typname => 'path', typlen => '-1', typbyval => 'f', typcategory => 'G',
typinput => 'path_in', typoutput => 'path_out', typreceive => 'path_recv',
typsend => 'path_send', typalign => 'd', typstorage => 'x' },
{ oid => '603', array_type_oid => '1020',
- descr => 'geometric box \'(lower left,upper right)\'',
+ descr => 'geometric box, format \'lower left point,upper right point\'',
typname => 'box', typlen => '32', typbyval => 'f', typcategory => 'G',
typdelim => ';', typsubscript => 'raw_array_subscript_handler',
typelem => 'point', typinput => 'box_in', typoutput => 'box_out',
typreceive => 'box_recv', typsend => 'box_send', typalign => 'd' },
{ oid => '604', array_type_oid => '1027',
- descr => 'geometric polygon \'(pt1,...)\'',
+ descr => 'geometric polygon, format \'(point1,...)\'',
typname => 'polygon', typlen => '-1', typbyval => 'f', typcategory => 'G',
typinput => 'poly_in', typoutput => 'poly_out', typreceive => 'poly_recv',
typsend => 'poly_send', typalign => 'd', typstorage => 'x' },
-{ oid => '628', array_type_oid => '629', descr => 'geometric line',
+{ oid => '628', array_type_oid => '629', descr => 'geometric line, formats \'{A,B,C}\'/\'[point1,point2]\'',
typname => 'line', typlen => '24', typbyval => 'f', typcategory => 'G',
typsubscript => 'raw_array_subscript_handler', typelem => 'float8',
typinput => 'line_in', typoutput => 'line_out', typreceive => 'line_recv',
@@ -230,7 +230,7 @@
typcategory => 'X', typinput => 'unknownin', typoutput => 'unknownout',
typreceive => 'unknownrecv', typsend => 'unknownsend', typalign => 'c' },
{ oid => '718', array_type_oid => '719',
- descr => 'geometric circle \'(center,radius)\'',
+ descr => 'geometric circle, format \'<center point,radius>\'',
typname => 'circle', typlen => '24', typbyval => 'f', typcategory => 'G',
typinput => 'circle_in', typoutput => 'circle_out',
typreceive => 'circle_recv', typsend => 'circle_send', typalign => 'd' },
@@ -271,14 +271,14 @@
typinput => 'aclitemin', typoutput => 'aclitemout', typreceive => '-',
typsend => '-', typalign => 'd' },
{ oid => '1042', array_type_oid => '1014',
- descr => 'char(length), blank-padded string, fixed storage length',
+ descr => '\'char(length)\' blank-padded string, fixed storage length',
typname => 'bpchar', typlen => '-1', typbyval => 'f', typcategory => 'S',
typinput => 'bpcharin', typoutput => 'bpcharout', typreceive => 'bpcharrecv',
typsend => 'bpcharsend', typmodin => 'bpchartypmodin',
typmodout => 'bpchartypmodout', typalign => 'i', typstorage => 'x',
typcollation => 'default' },
{ oid => '1043', array_type_oid => '1015',
- descr => 'varchar(length), non-blank-padded string, variable storage length',
+ descr => '\'varchar(length)\' non-blank-padded string, variable storage length',
typname => 'varchar', typlen => '-1', typbyval => 'f', typcategory => 'S',
typinput => 'varcharin', typoutput => 'varcharout',
typreceive => 'varcharrecv', typsend => 'varcharsend',
@@ -310,7 +310,7 @@
typsend => 'timestamptz_send', typmodin => 'timestamptztypmodin',
typmodout => 'timestamptztypmodout', typalign => 'd' },
{ oid => '1186', array_type_oid => '1187',
- descr => '@ <number> <units>, time interval',
+ descr => 'time interval, format \'number units ...\'',
typname => 'interval', typlen => '16', typbyval => 'f', typcategory => 'T',
typispreferred => 't', typinput => 'interval_in', typoutput => 'interval_out',
typreceive => 'interval_recv', typsend => 'interval_send',
@@ -345,7 +345,7 @@
# OIDS 1700 - 1799
{ oid => '1700', array_type_oid => '1231',
- descr => 'numeric(precision, decimal), arbitrary precision number',
+ descr => '\'numeric(precision, scale)\' arbitrary precision number',
typname => 'numeric', typlen => '-1', typbyval => 'f', typcategory => 'N',
typinput => 'numeric_in', typoutput => 'numeric_out',
typreceive => 'numeric_recv', typsend => 'numeric_send',
@@ -400,13 +400,13 @@
typalign => 'i' },
# uuid
-{ oid => '2950', array_type_oid => '2951', descr => 'UUID datatype',
+{ oid => '2950', array_type_oid => '2951', descr => 'UUID',
typname => 'uuid', typlen => '16', typbyval => 'f', typcategory => 'U',
typinput => 'uuid_in', typoutput => 'uuid_out', typreceive => 'uuid_recv',
typsend => 'uuid_send', typalign => 'c' },
# pg_lsn
-{ oid => '3220', array_type_oid => '3221', descr => 'PostgreSQL LSN datatype',
+{ oid => '3220', array_type_oid => '3221', descr => 'PostgreSQL LSN',
typname => 'pg_lsn', typlen => '8', typbyval => 'FLOAT8PASSBYVAL',
typcategory => 'U', typinput => 'pg_lsn_in', typoutput => 'pg_lsn_out',
typreceive => 'pg_lsn_recv', typsend => 'pg_lsn_send', typalign => 'd' },
@@ -452,12 +452,12 @@
typreceive => 'jsonpath_recv', typsend => 'jsonpath_send', typalign => 'i',
typstorage => 'x' },
-{ oid => '2970', array_type_oid => '2949', descr => 'txid snapshot',
+{ oid => '2970', array_type_oid => '2949', descr => 'transaction snapshot',
typname => 'txid_snapshot', typlen => '-1', typbyval => 'f',
typcategory => 'U', typinput => 'txid_snapshot_in',
typoutput => 'txid_snapshot_out', typreceive => 'txid_snapshot_recv',
typsend => 'txid_snapshot_send', typalign => 'd', typstorage => 'x' },
-{ oid => '5038', array_type_oid => '5039', descr => 'snapshot',
+{ oid => '5038', array_type_oid => '5039', descr => 'transaction snapshot',
typname => 'pg_snapshot', typlen => '-1', typbyval => 'f', typcategory => 'U',
typinput => 'pg_snapshot_in', typoutput => 'pg_snapshot_out',
typreceive => 'pg_snapshot_recv', typsend => 'pg_snapshot_send',
@@ -633,7 +633,9 @@
typoutput => 'tsm_handler_out', typreceive => '-', typsend => '-',
typalign => 'i' },
{ oid => '269',
- typname => 'table_am_handler', typlen => '4', typbyval => 't', typtype => 'p',
+ typname => 'table_am_handler',
+ descr => 'pseudo-type for the result of a table AM handler function',
+ typlen => '4', typbyval => 't', typtype => 'p',
typcategory => 'P', typinput => 'table_am_handler_in',
typoutput => 'table_am_handler_out', typreceive => '-', typsend => '-',
typalign => 'i' },
@@ -679,13 +681,13 @@
typtype => 'p', typcategory => 'P', typinput => 'anycompatiblemultirange_in',
typoutput => 'anycompatiblemultirange_out', typreceive => '-', typsend => '-',
typalign => 'd', typstorage => 'x' },
-{ oid => '4600', descr => 'BRIN bloom summary',
+{ oid => '4600', descr => 'pseudo-type representing BRIN bloom summary',
typname => 'pg_brin_bloom_summary', typlen => '-1', typbyval => 'f',
typcategory => 'Z', typinput => 'brin_bloom_summary_in',
typoutput => 'brin_bloom_summary_out',
typreceive => 'brin_bloom_summary_recv', typsend => 'brin_bloom_summary_send',
typalign => 'i', typstorage => 'x', typcollation => 'default' },
-{ oid => '4601', descr => 'BRIN minmax-multi summary',
+{ oid => '4601', descr => 'pseudo-type representing BRIN minmax-multi summary',
typname => 'pg_brin_minmax_multi_summary', typlen => '-1', typbyval => 'f',
typcategory => 'Z', typinput => 'brin_minmax_multi_summary_in',
typoutput => 'brin_minmax_multi_summary_out',
view thread (7+ messages) latest in thread
Message-ID: <ZUQCyfLJtR-Wufd5@momjian.us>
Permalink: ../ZUQCyfLJtR-Wufd5@momjian.us/
Also on: postgresql.org/message-id/ZUQCyfLJtR-Wufd5@momjian.us
copy link · copy postgr.es · copy git am
reply Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: bruce@momjian.us, horikyota.ntt@gmail.com, myon@debian.org
Subject: Re: "box" type description
In-Reply-To: <ZUQCyfLJtR-Wufd5@momjian.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
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