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

On Sat, Jul 9, 2011 at 3:29 PM, Hitoshi Harada <umi(dot)tanuki(at)gmail(dot)com> wrote:

> It looks like the time to wrap up. I marked "Return with Feedback" on
> this patch, since response from author has not come for a while.

Hello,

I've just stumbled on the issue mentioned in this thread, which is not
fixed in 9.1. To my knowledge the box @> point index limitation is not
described anywhere in the docs (which has costed me quite some time in
debug and the redesign of several functions to work around the issue).

Wouldn't be awesome to document what are the types/operators
combinations that can be successfully used in gist indexes?

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 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. I regularly need two browser tabs open to consult
these docs, bouncing back and forth.

It's worth noting that @> is listed in the indexed operators but the
only example provided for it in 9.11 is circle @> point which is
exactly one of the combinations not working with the index. Once ops
and index support info are on the same page, the extra notes about the
supported data types would feel like at home there.

I'm new to them, but I suspect the range operators for 9.2 have the
same docs usability issue (operator and index support on two different
page).

I don't know what the operators limitations are, and you have a few
samples of my English. Modulo that, I can provide patches if you want
:)

-- Daniele