Date: Wed, 26 Aug 2020 17:58:01 -0400
From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Michael Paquier <michael@paquier.xyz>
Cc: Tom Lane <tgl@sss.pgh.pa.us>, Bruce Momjian <bruce@momjian.us>,
	osdba <mailtch@163.com>, pgsql-docs@postgresql.org,
	jkatz@postgresql.org
Subject: Re: Document "59.2. Built-in Operator Classes" have a clerical error?
Message-ID: <20200826215801.GA30013@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20200826065618.GG2017@paquier.xyz>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk

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