Re: GIST operators docs [was: [HACKERS] Patch: add GiST support for BOX @> POINT queries]

Daniele Varrazzo <daniele.varrazzo@gmail.com> writes:
> The style of the docs is currently:

> - in 11.2: on the type page, a list of operators without a single word
> on their meaning, with a link to 9.11
> <http://www.postgresql.org/docs/9.1/static/indexes-types.html>
> - in 9.11 the ops explanation with no info about indexing or types
> support <http://www.postgresql.org/docs/9.1/static/functions-geometry.html>

I agree this is pretty incomplete ...

> I would suggest dropping the list in 11.2, leaving only the link
> ("several operators support indexing: see section 9.11 for a list"),
> and be explicit in 9.11 in what operator and what data type can be
> used in an index.

... but I don't think I want to fix it along those lines.  Consider
what would happen if we tried to annotate every operator supported by
btree indexes that way, for example.  It'd be very cluttering.  It'd
probably be pretty cluttering even if we restrict it to GIST cases.
I think the charter of 9.11 is to tell you what the operators *do*,
not which ones are amenable to indexing.

Over in 11.9
http://www.postgresql.org/docs/devel/static/indexes-opclass.html
there are sample queries for finding out which operators are indexable
by consulting the system catalogs directly.  I wonder whether it'd be
helpful to provide some simplified version of those queries in 11.2,
instead of or in addition to the text that's there now.

Alternatively, I could see adding tables of supported operators in
the GIST (and SPGIST and GIN) chapters of part VII, and linking to
those from 11.2.

Another idea is to extend psql's \do command to report indexability
of the operators it shows.

            regards, tom lane