Обсуждение: Document "59.2. Built-in Operator Classes" have a clerical error?
hi all:
In Document "Table 59-1. Built-in GiST Operator Classes":
"range_ops any range type && &> &< >> << <@ -|- = @> @>"， exist double "@>"，
Should be "<@ @>" ?
On Mon, Aug 03, 2020 at 03:14:56PM +0800, osdba wrote: > "range_opsany range type&& &> &< >> << <@ -|- = @> @>"， exist double "@>"， > > Should be "<@ @>" ? Indeed, this needs to be improved. Another issue on the same page is that point_ops lists the same operator three times, <@. Other index pages don't seem to have any inconsistencies, fortunately. -- Michael
Вложения
Michael Paquier <michael@paquier.xyz> writes:
> On Mon, Aug 03, 2020 at 03:14:56PM +0800, osdba wrote:
>> "range_opsany range type&& &> &< >> << <@ -|- = @> @>"， exist double "@>"，
>> Should be "<@ @>" ?
> Indeed, this needs to be improved. Another issue on the same page is
> that point_ops lists the same operator three times, <@. Other index
> pages don't seem to have any inconsistencies, fortunately.
psql's handy new \dAo query clarifies things a bit:
regression=# \dAo gist range_ops
List of operators of operator families
AM | Operator family | Operator | Strategy | Purpose
------+-----------------+-------------------------+----------+---------
gist | range_ops | <<(anyrange,anyrange) | 1 | search
gist | range_ops | &<(anyrange,anyrange) | 2 | search
gist | range_ops | &&(anyrange,anyrange) | 3 | search
gist | range_ops | &>(anyrange,anyrange) | 4 | search
gist | range_ops | >>(anyrange,anyrange) | 5 | search
gist | range_ops | -|-(anyrange,anyrange) | 6 | search
gist | range_ops | @>(anyrange,anyrange) | 7 | search
gist | range_ops | <@(anyrange,anyrange) | 8 | search
gist | range_ops | =(anyrange,anyrange) | 18 | search
gist | range_ops | @>(anyrange,anyelement) | 16 | search
(10 rows)
regression=# \dAo gist point_ops
List of operators of operator families
AM | Operator family | Operator | Strategy | Purpose
------+-----------------+-------------------+----------+----------
gist | point_ops | <<(point,point) | 1 | search
gist | point_ops | >>(point,point) | 5 | search
gist | point_ops | ~=(point,point) | 6 | search
gist | point_ops | <^(point,point) | 10 | search
gist | point_ops | >^(point,point) | 11 | search
gist | point_ops | <->(point,point) | 15 | ordering
gist | point_ops | <@(point,box) | 28 | search
gist | point_ops | <@(point,circle) | 68 | search
gist | point_ops | <@(point,polygon) | 48 | search
(9 rows)
So I don't think it's a clerical error, but certainly showing these
operators this way is none too helpful. Perhaps including the input types
in this table (and its siblings elsewhere) would be a good thing.
(Looking at these, I'm reminded anew that the sort ordering used by \dAo
is still questionable ...)
regards, tom lane
On Mon, Aug 03, 2020 at 07:23:48AM -0400, Tom Lane wrote: > So I don't think it's a clerical error, but certainly showing these > operators this way is none too helpful. Perhaps including the input types > in this table (and its siblings elsewhere) would be a good thing. Ah, thanks. I did not consider the psql shortcut. I agree that including the input types would be a good idea. But just doing that may not be enough IMO as the character policy used on our website for the HTML docs makes that harder to parse. What if we switched the third column to have one line per operator with its input type, and use morerows to show the full set of indexable operators one opclass is associated with? Contrary to wait events, those tables don't change much. I am wondering as well if we should consider mentioning \dAo on all those pages, say at the bottom of each table listing the opclasses. -- Michael
Вложения
On Mon, Aug 3, 2020 at 04:49:04PM +0900, Michael Paquier wrote: > On Mon, Aug 03, 2020 at 03:14:56PM +0800, osdba wrote: > > "range_opsany range type&& &> &< >> << <@ -|- = @> @>"， exist double "@>"， > > > > Should be "<@ @>" ? > > Indeed, this needs to be improved. Another issue on the same page is > that point_ops lists the same operator three times, <@. Other index > pages don't seem to have any inconsistencies, fortunately. I decided to remove the duplicates and just add "(multiple)" after operators that have multiple system table entries; patch attached. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
Вложения
On Fri, Aug 21, 2020 at 07:16:16PM -0400, Bruce Momjian wrote: > I decided to remove the duplicates and just add "(multiple)" after > operators that have multiple system table entries; patch attached. Sounds like a good idea to me. Thanks. Another idea I had after reading your email would be to use "for multiple types", but simpler is likely better. -- Michael
Вложения
Bruce Momjian <bruce@momjian.us> writes:
> Yeah, I kind of like the table myself too, because this topic is already
> so complicated.
Agreed. I'm not very happy with the suggestion of "(multiple)" though;
I think that will just add confusion.
If you don't want to go all the way and list the operators with their
input types, maybe we should just do what the OP thought was correct
and delete the duplicate operator names. It's already the case that
the table isn't telling you exactly which input types the operators
accept, so why not be a little bit fuzzier?
regards, tom lane
On 2020-Aug-22, Tom Lane wrote: > If you don't want to go all the way and list the operators with their > input types, maybe we should just do what the OP thought was correct > and delete the duplicate operator names. It's already the case that > the table isn't telling you exactly which input types the operators > accept, so why not be a little bit fuzzier? Well, if we're going to have a table, let's have a useful table. What's wrong with using the same contents \dAo shows? It seemed reasonable enough to me. Now of course I would suggest that other client programs such as pgAdmin ought to display what \dAo shows too ;-) -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Sat, Aug 22, 2020 at 02:59:02PM -0400, Alvaro Herrera wrote: > On 2020-Aug-22, Tom Lane wrote: > > > If you don't want to go all the way and list the operators with their > > input types, maybe we should just do what the OP thought was correct > > and delete the duplicate operator names. It's already the case that > > the table isn't telling you exactly which input types the operators > > accept, so why not be a little bit fuzzier? > > Well, if we're going to have a table, let's have a useful table. What's > wrong with using the same contents \dAo shows? It seemed reasonable > enough to me. I don't think it is worth it, plus we would need to adjust the docs if system catalog layout changes. I think we just want something concise and simple, but also accurate. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
On 2020-Aug-24, Bruce Momjian wrote: > I don't think it is worth it, plus we would need to adjust the docs if > system catalog layout changes. I think we just want something concise > and simple, but also accurate. I argued for \dAo, not straight catalog output -- that was a straw man. I can't produce the docbook right now but I volunteer to show a screenshot for what I propose later this week. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Mon, Aug 24, 2020 at 11:59:22AM -0400, Alvaro Herrera wrote: > On 2020-Aug-24, Bruce Momjian wrote: > > > I don't think it is worth it, plus we would need to adjust the docs if > > system catalog layout changes. I think we just want something concise > > and simple, but also accurate. > > I argued for \dAo, not straight catalog output -- that was a straw man. > > I can't produce the docbook right now but I volunteer to show a > screenshot for what I propose later this week. Sure, I can wait. Is this the only place where it would make sense? -- Bruce Momjian <bruce@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
On Mon, Aug 24, 2020 at 12:01:00PM -0400, Bruce Momjian wrote: > Sure, I can wait. Is this the only place where it would make sense? I think so. If there are other places, it does not prevent improving what we already know needs improvement. FWIW, the layout I was thinking about is something like the patch attached. I have only patched GIN to give an idea of the shape of the tables. The PNG file attached is a screenshot of the HTML generated. I know that we try to limit the use of morerows, but it seems much better to me to use morerows for those pages here knowing the small size of the tables. We could split that into multiple tables instead, still I find the single-table approach cleaner. -- Michael
Вложения
On Tue, Aug 25, 2020 at 01:44:03PM +0900, Michael Paquier wrote: > On Mon, Aug 24, 2020 at 12:01:00PM -0400, Bruce Momjian wrote: > > Sure, I can wait. Is this the only place where it would make sense? > > I think so. If there are other places, it does not prevent improving > what we already know needs improvement. Well, my point is that if this area looks different from other places, it could look odd, so we can't always make incremental fixes to the docs, though it might be fine in this case. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
On 2020-Aug-25, Michael Paquier wrote: > I think so. If there are other places, it does not prevent improving > what we already know needs improvement. > > FWIW, the layout I was thinking about is something like the patch > attached. This looks to me enough of an improvement that I +1 it, and yes this is what I was imagining also. (With the non-website stylesheet, as in the screenshot you showed, the table looks somewhat crammed and visually unappealing; but the website stylesheet looks pleasing enough. Screenshot attached.) > I have only patched GIN to give an idea of the shape of the > tables. I suppose a commit would change all the index AMs where we document this kind of thing. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Вложения
Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> On 2020-Aug-25, Michael Paquier wrote:
>> FWIW, the layout I was thinking about is something like the patch
>> attached.
> This looks to me enough of an improvement that I +1 it, and yes this is
> what I was imagining also.
I think it's a good idea too.
> (With the non-website stylesheet, as in the screenshot you showed, the
> table looks somewhat crammed and visually unappealing; but the website
> stylesheet looks pleasing enough. Screenshot attached.)
I wonder if it would look better if we suppress the horizontal rules
between the operator names within a cell. IIRC, it's possible to do
that, though the exact incantation isn't coming to mind right now.
> I suppose a commit would change all the index AMs where we document this
> kind of thing.
Yeah, we should make all these sorts of tables consistent.
regards, tom lane