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

On Sat, Aug 11, 2012 at 6:04 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> 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.

Agreed it would be cluttering for btree, but btree operators are
pretty well known and surprise-free, whereas the geometric/interval
ones are quite exotic and the interaction between types not obvious.

> It'd
> probably be pretty cluttering even if we restrict it to GIST cases.

There would be more information, but I don't think a useful page is an
impossible task. What I have in mind is a notes column and free
descriptive text below the table as in
<http://docs.python.org/library/stdtypes.html#index-15>.

> I think the charter of 9.11 is to tell you what the operators *do*,
> not which ones are amenable to indexing.

In the context of using intervals or geometric types to build indexes
one must design his system with this knowledge. He can only use the
operators that support indexes, the others are out of the game.

> 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.

That would be probably fine too. The other propositions (extending
psql's \do and a query to be copypasted into psql) are still a form of
help but require another tool to be used out of the Fine Manual.

-- Daniele