Thread
Commits
-
doc: Rework tables for built-in operator classes of index AMs
- 7a1cd5260aa2 14.0 landed
-
Document "59.2. Built-in Operator Classes" have a clerical error?
osdba <mailtch@163.com> — 2020-08-03T07:14:56Z
hi all: In Document "Table 59-1. Built-in GiST Operator Classes": "range_opsany range type&& &> &< >> << <@ -|- = @> @>"， exist double "@>"， Should be "<@ @>" ?
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Michael Paquier <michael@paquier.xyz> — 2020-08-03T07:49:04Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Tom Lane <tgl@sss.pgh.pa.us> — 2020-08-03T11:23:48Z
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 -
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Michael Paquier <michael@paquier.xyz> — 2020-08-04T05:56:51Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Bruce Momjian <bruce@momjian.us> — 2020-08-21T23:16:16Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Michael Paquier <michael@paquier.xyz> — 2020-08-22T01:34:14Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-08-22T03:19:07Z
On 2020-Aug-21, Bruce Momjian wrote: > 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. Now that we can point people to psql's \dAo, do we really need to have these tables at all? -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Michael Paquier <michael@paquier.xyz> — 2020-08-22T12:23:19Z
On Fri, Aug 21, 2020 at 11:19:07PM -0400, Alvaro Herrera wrote: > Now that we can point people to psql's \dAo, do we really need to have > these tables at all? Having the tables is IMO still useful as a quick reference for users that don't have immediately psql at hand when working on an application, for example imagine somebody using pgAdmin. And I would imagine that such people are not few. Another risk here is somebody using psql with a server that has a major version different than the one they are working on, leading to false assumptions? Having at least a mention to those psql shortcuts in the docs is still a good idea IMO, as said upthread: https://www.postgresql.org/message-id/20200804055651.GC2091@paquier.xyz -- Michael
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Bruce Momjian <bruce@momjian.us> — 2020-08-22T16:55:34Z
On Sat, Aug 22, 2020 at 09:23:19PM +0900, Michael Paquier wrote: > On Fri, Aug 21, 2020 at 11:19:07PM -0400, Alvaro Herrera wrote: > > Now that we can point people to psql's \dAo, do we really need to have > > these tables at all? > > Having the tables is IMO still useful as a quick reference for users > that don't have immediately psql at hand when working on an > application, for example imagine somebody using pgAdmin. And I would > imagine that such people are not few. Another risk here is somebody > using psql with a server that has a major version different than the > one they are working on, leading to false assumptions? Having at > least a mention to those psql shortcuts in the docs is still a good > idea IMO, as said upthread: > https://www.postgresql.org/message-id/20200804055651.GC2091@paquier.xyz Yeah, I kind of like the table myself too, because this topic is already so complicated. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Tom Lane <tgl@sss.pgh.pa.us> — 2020-08-22T17:27:00Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-08-22T18:59:02Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Bruce Momjian <bruce@momjian.us> — 2020-08-24T14:22:17Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-08-24T15:59:22Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Bruce Momjian <bruce@momjian.us> — 2020-08-24T16:01:00Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Michael Paquier <michael@paquier.xyz> — 2020-08-25T04:44:03Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Bruce Momjian <bruce@momjian.us> — 2020-08-25T14:06:25Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-08-25T22:10:28Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Tom Lane <tgl@sss.pgh.pa.us> — 2020-08-25T22:17:28Z
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
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Michael Paquier <michael@paquier.xyz> — 2020-08-26T06:56:18Z
On Tue, Aug 25, 2020 at 06:17:28PM -0400, Tom Lane wrote: > Alvaro Herrera <alvherre@2ndquadrant.com> writes: >> (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.) Right, STYLE=website. > 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 would imagine that rowsep=0 for a given <entry> can do that: https://tdg.docbook.org/tdg/4.5/entry.html However, it does not make a difference if I use the default style or the website style. I may be missing something with the stylesheet though? >> 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. Of course, just wanted to make sure that we agree on the layer before spending more time on that as shaping all the tables correctly is a lot of work. And GIN is the smallest one. One thing to note about the BRIN table is that we have never documented from the start any of the operators working across multiple types. For example, we only have 5 operators listed for each one of int2/int4/int8, timestamptz/timestamp or real/float, but these are listed with incorrect names and they miss a bunch of other operators able to handle combinations of (int2,int4), etc. So I have fixed the table so as all the operators are listed, grouping together ints, timestamps and reals, as \dAo says. Now there could be also an argument to stick with simplicity and list only the operators of one single type, reducing the size of the table for BRIN. But that would be incorrect with the catalogs, and the attached classifies all operators in alphabetical order. (Switching to the original list is not complicated as that would be just removing code from the attached, so I took the complicated path for now.) -- Michael
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-08-26T21:58:01Z
On 2020-Aug-26, Michael Paquier wrote: > On Tue, Aug 25, 2020 at 06:17:28PM -0400, Tom Lane wrote: > > 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 would imagine that rowsep=0 for a given <entry> can do that: > https://tdg.docbook.org/tdg/4.5/entry.html > However, it does not make a difference if I use the default style or > the website style. I may be missing something with the stylesheet > though? I have no idea there. Maybe Jon Katz (CCed) could help you to find an answer to that question. > >> 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. > > Of course, just wanted to make sure that we agree on the layer before > spending more time on that as shaping all the tables correctly is a > lot of work. And GIN is the smallest one. Thanks for doing the legwork! > One thing to note about the BRIN table is that we have never > documented from the start any of the operators working across multiple > types. For example, we only have 5 operators listed for each one of > int2/int4/int8, timestamptz/timestamp or real/float, but these are > listed with incorrect names and they miss a bunch of other operators > able to handle combinations of (int2,int4), etc. So I have fixed the > table so as all the operators are listed, grouping together ints, > timestamps and reals, as \dAo says. Well, there is a small problem here ... which is that I misled you with \dAo ... because that one lists the operators for the opfamilies, not for the opclasses. And you can't use the opfamily name in CREATE INDEX: 55432 14devel 30811=# create index on t using brin (a integer_minmax_ops); ERROR: operator class "integer_minmax_ops" does not exist for access method "brin" You have to use the opclass name: 55432 14devel 30811=# create index on t using brin (a int4_minmax_ops); CREATE INDEX Compare \dAf to \dAc. The latter shows what opclasses you can use for each datatype, while the former shows what types can be used with an index using the opfamily that the opclass belongs into. As I understand it, the cross-type operators are "loose" in the opfamily and they don't belong to any opclass. So what we could do is list the opclasses within each opfamily, and then list all the loose operators. Something like (fixed width font): Operator family Operator class Operator ------------------------------------------------------------ integer_minmax_ops int4_minmax_ops =(integer,integer) <(integer,integer) >(integer,integer) >=(integer,integer) <=(integer,integer) --------------------------------------- int2_minmax_ops =(smallint,smallint) etc ---------------------------------------- ... other opclasses ... ---------------------------------------- =(smallint,integer) <(smallint,integer) >(smallint,integer) ... rest of operators ... ------------------------------------------------------------- -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services -
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Tom Lane <tgl@sss.pgh.pa.us> — 2020-08-26T22:17:59Z
Alvaro Herrera <alvherre@2ndquadrant.com> writes: > On 2020-Aug-26, Michael Paquier wrote: >> I would imagine that rowsep=0 for a given <entry> can do that: >> https://tdg.docbook.org/tdg/4.5/entry.html >> However, it does not make a difference if I use the default style or >> the website style. I may be missing something with the stylesheet >> though? > I have no idea there. Maybe Jon Katz (CCed) could help you to find an > answer to that question. Yeah, I can't make it work as documented either. Weird --- I wonder if our stylesheets are messing that up? It *does* work in PDF output. Speaking of PDF output, we have a fair amount of work to do to make these tables render sanely in PDF. As the patch stands, it reintroduces a bunch of "exceed the available area" complaints. Partly that is because, in the interests of making the old contents fit, I'd given the operator column less space than the others: <colspec colname="col1" colwidth="2*"/> <colspec colname="col2" colwidth="2*"/> <colspec colname="col3" colwidth="1*"/> which is backwards now, of course. Perhaps you could just drop the <colspec>s again, or else twiddle their relative widths. Some other recommendations I'd make are: * Don't use the carpal-tunnel-inducing SQL standard datatype names, but just "timestamp", "timestamptz", etc. * Put a space after the comma in each operator description; this will look better and it will cue FOP that that's a good place for a line break. * I'm inclined to think that spaces before the operators' left parens would improve readabilty, too. > As I understand it, the cross-type operators are "loose" in the opfamily > and they don't belong to any opclass. So what we could do is list the > opclasses within each opfamily, and then list all the loose operators. > Something like (fixed width font): > > Operator family Operator class Operator > ------------------------------------------------------------ > integer_minmax_ops int4_minmax_ops =(integer,integer) > <(integer,integer) > >(integer,integer) > >=(integer,integer) > <=(integer,integer) Hm, do we care quite that much about explaining this difference? But you're right that we hardly need the "data type" column per se when the operator column is repeating the same info. > Thanks for doing the legwork! Indeed. regards, tom lane
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Bruce Momjian <bruce@momjian.us> — 2020-08-26T22:39:27Z
On Wed, Aug 26, 2020 at 05:58:01PM -0400, Alvaro Herrera wrote: > Well, there is a small problem here ... which is that I misled you with > \dAo ... because that one lists the operators for the opfamilies, not > for the opclasses. And you can't use the opfamily name in CREATE INDEX: > > 55432 14devel 30811=# create index on t using brin (a integer_minmax_ops); > ERROR: operator class "integer_minmax_ops" does not exist for access method "brin" > > You have to use the opclass name: > > 55432 14devel 30811=# create index on t using brin (a int4_minmax_ops); > CREATE INDEX > > Compare \dAf to \dAc. The latter shows what opclasses you can use for > each datatype, while the former shows what types can be used with an > index using the opfamily that the opclass belongs into. > > As I understand it, the cross-type operators are "loose" in the opfamily > and they don't belong to any opclass. So what we could do is list the > opclasses within each opfamily, and then list all the loose operators. > Something like (fixed width font): Stupid question, but do we think the average Postgres user can understand this issue. I am having trouble myself. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-08-26T22:58:37Z
On 2020-Aug-26, Bruce Momjian wrote: > On Wed, Aug 26, 2020 at 05:58:01PM -0400, Alvaro Herrera wrote: > > Well, there is a small problem here ... which is that I misled you with > > \dAo ... because that one lists the operators for the opfamilies, not > > for the opclasses. And you can't use the opfamily name in CREATE INDEX: > > > > 55432 14devel 30811=# create index on t using brin (a integer_minmax_ops); > > ERROR: operator class "integer_minmax_ops" does not exist for access method "brin" > > > > You have to use the opclass name: > > > > 55432 14devel 30811=# create index on t using brin (a int4_minmax_ops); > > CREATE INDEX > > > > Compare \dAf to \dAc. The latter shows what opclasses you can use for > > each datatype, while the former shows what types can be used with an > > index using the opfamily that the opclass belongs into. > > > > As I understand it, the cross-type operators are "loose" in the opfamily > > and they don't belong to any opclass. So what we could do is list the > > opclasses within each opfamily, and then list all the loose operators. > > Something like (fixed width font): > > Stupid question, but do we think the average Postgres user can > understand this issue. I am having trouble myself. The only reason I think it's worth pointing out, is that the opclass name is something you can use in CREATE INDEX, while the opfamily name cannot be used there. The original tables can be used for that purpose, but the patched tables cannot. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Tom Lane <tgl@sss.pgh.pa.us> — 2020-08-26T23:19:09Z
Alvaro Herrera <alvherre@2ndquadrant.com> writes: > On 2020-Aug-26, Bruce Momjian wrote: >> Stupid question, but do we think the average Postgres user can >> understand this issue. I am having trouble myself. > The only reason I think it's worth pointing out, is that the opclass > name is something you can use in CREATE INDEX, while the opfamily name > cannot be used there. The original tables can be used for that purpose, > but the patched tables cannot. With one eye on the PDF width issue, I propose that we not draw the distinction, but just list all the relevant operators for each opclass (its native ones, plus the applicable "loose" operators). Then we only need two columns, opclass and operators. regards, tom lane
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Michael Paquier <michael@paquier.xyz> — 2020-08-27T06:33:22Z
On Wed, Aug 26, 2020 at 07:19:09PM -0400, Tom Lane wrote: > With one eye on the PDF width issue, I propose that we not draw > the distinction, but just list all the relevant operators for each > opclass (its native ones, plus the applicable "loose" operators). > Then we only need two columns, opclass and operators. Indeed, removing the types makes sense if we list them with the operators. I have been looking at your suggestions, and adding a space before the first parenthesis where the types are listed sounds good to me, but I am not sure that it is a good idea to add spaces between each type. Looking at the pdf produced, I think that we should also drop entirely colspec for the BRIN table as it gets much small in width once the data type column is removed. I also looked at rowsep for the PDF, and I tend to prefer the version where we separate each cell for the operator, as a matter of readability. This leads me to the updated version attached. BRIN has 29 different opclasses, visibly. -- Michael
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-08-27T16:07:51Z
On 2020-Aug-27, Michael Paquier wrote: > This leads me to the updated version attached. BRIN has 29 different > opclasses, visibly. I checked both HTML and PDF and it looks good to me to commit. As a subsequent improvement we could discuss tweak the stylesheets to change the column widths in PDF, but I don't think we need to stall this patch for that, since it's a much smaller issue IMV. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Tom Lane <tgl@sss.pgh.pa.us> — 2020-08-28T01:12:39Z
Alvaro Herrera <alvherre@2ndquadrant.com> writes: > On 2020-Aug-27, Michael Paquier wrote: >> This leads me to the updated version attached. BRIN has 29 different >> opclasses, visibly. > I checked both HTML and PDF and it looks good to me to commit. I did not verify that the correct operators are listed, but visually it looks OK. One thing I've noted in working with this stuff is that (at least for me) HTML seems to default to valign=center while PDF defaults to valign=top. You can see that in these tables in the positioning of the opclass names. For myself, valign=center looks better in these cases so I'd suggest adding <colspec>s to force it that way. Or, if you like valign=top, we should do that --- but it ought to be consistent across output formats. > As a subsequent improvement we could discuss tweak the stylesheets to > change the column widths in PDF, but I don't think we need to stall this > patch for that, since it's a much smaller issue IMV. Yeah, I think some fooling with the column widths could improve the PDF results, but it's a minor point. regards, tom lane
-
Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Michael Paquier <michael@paquier.xyz> — 2020-08-28T08:02:16Z
On Thu, Aug 27, 2020 at 09:12:39PM -0400, Tom Lane wrote: > I did not verify that the correct operators are listed, but visually > it looks OK. > > One thing I've noted in working with this stuff is that (at least for me) > HTML seems to default to valign=center while PDF defaults to valign=top. > You can see that in these tables in the positioning of the opclass names. > For myself, valign=center looks better in these cases so I'd suggest > adding <colspec>s to force it that way. Or, if you like valign=top, > we should do that --- but it ought to be consistent across output formats. Yes. valign="center" does not exist, but I like your idea to use "middle" here and make things consistent between the PDF and HTML outputs. So I have used this option for the cells where this applies, and committed the patch. Thanks all for the discussion and the successive reviews. -- Michael