Thread: Chapter "8.8 Geometric Types" of documentation could contain more details
Chapter "8.8 Geometric Types" of documentation could contain more details
From
PG Doc comments form
Date:
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/16/datatype-geometric.html Description: Hi, I am writing to suggest a couple of clarifications to "8.8. Geometric Types" documentation chapter. 1. Documentation does not specify what precision is used when persisting point coordinates. There are hints that it's 8 bytes per coordinate, but neither can be taken for sure. Table "8.20. Geometric Types" says that a point takes 16 bytes, which strongly suggests it's 8 bytes per coordinate, but on the other hand, it could be less if a point definition also includes some unspecified metadata. Section "8.8.1. Points" says "Values of type point are specified […] where x and y are the respective coordinates, as floating-point numbers.", however it is unclear what exact type of floating-point numbers is meant. My suggestion is to clearly describe which floating-point datatype is used for point coordinates. 2. Documentation only partly clarifies what are the benefits of using polygon datatype instead of path datatype. Section "8.8.6. Polygons" says that "the essential difference is that a polygon is considered to include the area within it, while a path is not", which clarifies that they are meant to serve different purposes, but nothing more. Table "8.20. Geometric Types" says that a polygon with n vertices takes 24 bytes more than a path with n vertices, but that's all. Only chapter "9.11. Geometric Functions and Operators" really helps in understanding that some functions and operators are available to polygons but not to paths. My suggestion is to: a) point out that different operations can be performed on polygons and closed paths b) clarify what information is stored with a polygon that is not stored with a closed path (these 24 bytes) c) if there are some operations that perform better on polygons than on closed paths, clarify that as well
PG Doc comments form <noreply@postgresql.org> writes: > Hi, I am writing to suggest a couple of clarifications to "8.8. Geometric > Types" documentation chapter. Fair points. I am not really eager to say explicitly here that the set of available functions varies for the different types: that seems pretty self-evident. But your other ideas are good. I also noted while looking at this that table 8.20 is flat out wrong about the storage size of "line" values: they are 24 bytes each not 32. (This can be confirmed from pg_type.typlen or by looking at struct LINE in the source code.) How about the attached? regards, tom lane diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 6646820d6a..a693424a69 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -3369,7 +3369,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays </row> <row> <entry><type>line</type></entry> - <entry>32 bytes</entry> + <entry>24 bytes</entry> <entry>Infinite line</entry> <entry>{A,B,C}</entry> </row> @@ -3413,6 +3413,11 @@ SELECT person.name, holidays.num_weeks FROM person, holidays </tgroup> </table> + <para> + In all these types, the individual coordinates are stored as + <type>double precision</type> (<type>float8</type>) numbers. + </para> + <para> A rich set of functions and operators is available to perform various geometric operations such as scaling, translation, rotation, and determining @@ -3607,6 +3612,14 @@ SELECT person.name, holidays.num_weeks FROM person, holidays within it, while a path is not. </para> + <para> + An important implementation difference between polygons and closed + paths is that the stored representation of a polygon includes its + smallest bounding box. This speeds up certain search operations, + although computing the bounding box adds overhead while constructing + new polygons. + </para> + <para> Values of type <type>polygon</type> are specified using any of the following syntaxes:
Re: Chapter "8.8 Geometric Types" of documentation could contain more details
From
Sebastian Skałacki
Date:
Looks great to me, thanks! śr., 3 lip 2024 o 21:45 Tom Lane <tgl@sss.pgh.pa.us> napisał(a): > > PG Doc comments form <noreply@postgresql.org> writes: > > Hi, I am writing to suggest a couple of clarifications to "8.8. Geometric > > Types" documentation chapter. > > Fair points. I am not really eager to say explicitly here that the > set of available functions varies for the different types: that seems > pretty self-evident. But your other ideas are good. > > I also noted while looking at this that table 8.20 is flat out wrong > about the storage size of "line" values: they are 24 bytes each not > 32. (This can be confirmed from pg_type.typlen or by looking at > struct LINE in the source code.) > > How about the attached? > > regards, tom lane > -- Regards, Sebastian Skałacki
=?UTF-8?Q?Sebastian_Ska=C5=82acki?= <skalee@gmail.com> writes: > Looks great to me, thanks! Pushed, thanks. regards, tom lane