Обсуждение: Call for GIST/GIN/SP-GIST opclass documentation
I just created sections in the SGML manual chapters about GIST, GIN, and SP-GIST to hold documentation about the standard opclasses provided for them: http://www.postgresql.org/docs/devel/static/gist-builtin-opclasses.html http://www.postgresql.org/docs/devel/static/gin-builtin-opclasses.html http://www.postgresql.org/docs/devel/static/spgist-builtin-opclasses.html We never had any well-defined place to discuss such opclasses before, but I think it's past time we did. I envision these sections as places to document, for example, the difference between the two jsonb gin opclasses. I put this text in about that: Of the two operator classes for type jsonb, jsonb_ops is the default. jsonb_hash_ops supports fewer operators but will work with larger indexed values than jsonb_ops can support. Is that accurate? Do we need to say more? For the moment what's there is mostly just tables of the core opclasses and the operators they support. If anyone can think of specific additions that should be there, please send in patches. (BTW, I didn't worry about btree and hash because they don't have such a wide variety of opclass behaviors.) regards, tom lane
Peter Geoghegan <pg@heroku.com> writes:
> On Tue, Apr 8, 2014 at 1:41 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Of the two operator classes for type jsonb, jsonb_ops is the
>> default. jsonb_hash_ops supports fewer operators but will work with
>> larger indexed values than jsonb_ops can support.
>>
>> Is that accurate? Do we need to say more?
> Well, I'm not sure that it's worth noting there, but as you probably
> already know jsonb_hash_ops will perform a lot better than the default
> GIN opclass, and will have much smaller indexes. FWIW I think that the
> size limitation is overblown, and performance is in fact the
> compelling reason to prefer jsonb_hash_ops, although it's probably
> incongruous to explain the issues that way in this section of the
> docs. It probably suffices that that is covered in the "JSON Types"
> section.
Well, the subtext is whether we should move that discussion to this
new section. I think there is some comparable discussion in the
full-text-indexing chapter, too.
(BTW, wasn't there some discussion of changing our minds about which
one is the default? We already have one bug report complaining about
jsonb_ops' size restriction, so that seems to be evidence in favor
of changing ...)
regards, tom lane
On Tue, Apr 8, 2014 at 2:34 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > (BTW, wasn't there some discussion of changing our minds about which > one is the default? We already have one bug report complaining about > jsonb_ops' size restriction, so that seems to be evidence in favor > of changing ...) Yes, there was. I very nearly came down on the side of making jsonb_hash_ops the default, but given that it doesn't make all operators indexable, I ultimately decided against supporting that course of action. I thought that that would be an odd limitation for the default GIN opclass to have. It was a very close call in my mind, and if you favor changing the default now, in light of the few complaints we've heard, I think that's a reasonable decision. That said, as I noted in the main -bugs thread, the case presented is fairly atypical. -- Peter Geoghegan
On Tue, Apr 8, 2014 at 1:41 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > I just created sections in the SGML manual chapters about GIST, GIN, and > SP-GIST to hold documentation about the standard opclasses provided for > them: I think that that's a good idea. I too was bothered by this omission. > Of the two operator classes for type jsonb, jsonb_ops is the > default. jsonb_hash_ops supports fewer operators but will work with > larger indexed values than jsonb_ops can support. > > Is that accurate? Do we need to say more? Well, I'm not sure that it's worth noting there, but as you probably already know jsonb_hash_ops will perform a lot better than the default GIN opclass, and will have much smaller indexes. FWIW I think that the size limitation is overblown, and performance is in fact the compelling reason to prefer jsonb_hash_ops, although it's probably incongruous to explain the issues that way in this section of the docs. It probably suffices that that is covered in the "JSON Types" section. -- Peter Geoghegan
On Tue, Apr 8, 2014 at 4:41 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > I just created sections in the SGML manual chapters about GIST, GIN, and > SP-GIST to hold documentation about the standard opclasses provided for > them: > > http://www.postgresql.org/docs/devel/static/gist-builtin-opclasses.html > http://www.postgresql.org/docs/devel/static/gin-builtin-opclasses.html > http://www.postgresql.org/docs/devel/static/spgist-builtin-opclasses.html > > We never had any well-defined place to discuss such opclasses before, > but I think it's past time we did. +1. Great idea. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company
Robert Haas wrote: > On Tue, Apr 8, 2014 at 4:41 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > > I just created sections in the SGML manual chapters about GIST, GIN, and > > SP-GIST to hold documentation about the standard opclasses provided for > > them: > > > > http://www.postgresql.org/docs/devel/static/gist-builtin-opclasses.html > > http://www.postgresql.org/docs/devel/static/gin-builtin-opclasses.html > > http://www.postgresql.org/docs/devel/static/spgist-builtin-opclasses.html > > > > We never had any well-defined place to discuss such opclasses before, > > but I think it's past time we did. > > +1. Great idea. Agreed. I find that in my browser it's a bit difficult to make out the different operators in the long list; ISTM a single space between operators isn't enough. I wonder how can we do better; sticking commas (or any other single character, really) between them is not likely to improve matters; and using one column per operator is not going to work very well. Maybe if it were possible to split a single cell in several sub-cells; or perhaps there's a way to specify two whitespace units, or a long space, or something like that. -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Training & Services
Alvaro Herrera <alvherre@2ndquadrant.com> writes: > Robert Haas wrote: >> On Tue, Apr 8, 2014 at 4:41 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: >>> http://www.postgresql.org/docs/devel/static/gist-builtin-opclasses.html >>> http://www.postgresql.org/docs/devel/static/gin-builtin-opclasses.html >>> http://www.postgresql.org/docs/devel/static/spgist-builtin-opclasses.html > I find that in my browser it's a bit difficult to make out the different > operators in the long list; ISTM a single space between operators isn't > enough. Yeah, I noticed that too, but wasn't sure what to do about it. One line per operator isn't better, but I don't know how to get a bit more horizontal space into the lists. regards, tom lane