public inbox for [email protected]  

help / color / mirror / Atom feed

From: Daniele Varrazzo <[email protected]>
To: Tom Lane <[email protected]>
Cc: [email protected]
Subject: Re: GIST operators docs [was: [HACKERS] Patch: add GiST support for BOX @> POINT queries]
Date: Tue, 14 Aug 2012 18:40:58 +0100
Message-ID: <CA+mi_8b_h83fLeea6+-RTJDU8_FLAO_ZnkhkYR9cZOx-Vq0g3w@mail.gmail.com> (raw)
In-Reply-To: <[email protected]>
References: <CA+mi_8Y58Z7iLB=eZkd1u3xf1kK=1Vu3vw5TbfHcu6ug=n2Nbg@mail.gmail.com>
	<[email protected]>

On Sat, Aug 11, 2012 at 6:04 PM, Tom Lane <[email protected]> wrote:
> Daniele Varrazzo <[email protected]> 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

view thread (4+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected]
  Subject: Re: GIST operators docs [was: [HACKERS] Patch: add GiST support for BOX @> POINT queries]
  In-Reply-To: <CA+mi_8b_h83fLeea6+-RTJDU8_FLAO_ZnkhkYR9cZOx-Vq0g3w@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox