MIME-Version: 1.0
References: 
 <CA+renyWs5Np+FLSYfL+eu20S4U671A3fQGb-+7e22HLrD1NbYw@mail.gmail.com>
 <1855968.1774812758@sss.pgh.pa.us>
 <CA+renyXv6+tVi2yeQNXRwRkAm=wg89k=orjU8nMRKqWf1q6mtg@mail.gmail.com>
 <2581763.1774908361@sss.pgh.pa.us>
In-Reply-To: <2581763.1774908361@sss.pgh.pa.us>
From: Paul A Jungwirth <pj@illuminatedcomputing.com>
Date: Mon, 30 Mar 2026 16:30:57 -0700
Message-ID: 
 <CA+renyUurA23jUVXM+NCQ17P49AVgCjJLdsEfStjLo+v_oKm6A@mail.gmail.com>
Subject: Re: Correct docs about GiST leaf page structure
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: pgsql-docs@lists.postgresql.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: 
 <https://www.postgresql.org/message-id/CA%2BrenyUurA23jUVXM%2BNCQ17P49AVgCjJLdsEfStjLo%2Bv_oKm6A%40mail.gmail.com>
Precedence: bulk

On Mon, Mar 30, 2026 at 3:06=E2=80=AFPM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Paul A Jungwirth <pj@illuminatedcomputing.com> writes:
> > On Sun, Mar 29, 2026 at 12:32=E2=80=AFPM Tom Lane <tgl@sss.pgh.pa.us> w=
rote:
> >> Actually I think it's more complicated than that.  A GiST opclass
> >> can choose whether to compress leaf-key entries, and if it does it
> >> can use a different representation than it does on internal pages.
> >> You can see that in action in compress/decompress functions that
> >> pay attention to the GISTENTRY.leafkey flag, which many do.
>
> > I think your changes are great. I agree about not needing two commits.
> > My only hesitation is removing the line about STORAGE. In btree_gist
> > we do declare the storage of many opclasses. But I'm not sure why. Is
> > it necessary? Does an opclass gain some advantage from it? Does core
> > use that information somehow? Especially if leaf keys might or might
> > not be the same type as internal keys, I'm not sure what value
> > declaring STORAGE can provide. (It must be for core's sake, not the
> > opclass's, right?)
>
> Excellent questions, and thanks for holding my feet to the fire about
> that ;-).  Reading more closely, the STORAGE option does indeed do
> something: it determines the declared data type of the index's column,
> as stored in pg_attribute.  And that's important because GiST uses
> that datatype while forming or deforming index tuples.  So it has to
> be accurate --- but only to the extent of having the right
> typlen/typbyval/typalign properties, because that's as much as
> index_form_tuple() and related functions really care about.  They
> don't look into the contents of the entries, except for the length
> word if it's typlen -1.
>
> My claim that the leaf key representation can be different from upper
> levels is still accurate, but both representations have to match the
> typlen/typbyval/typalign properties of whatever type is mentioned
> in STORAGE.  (I was misled by the fact that the GiST code has
> different "leafTupdesc" and "nonLeafTupdesc" tuple descriptors.
> But leafTupdesc is just the standard rd_att descriptor made from
> the index's pg_attribute entries, and nonLeafTupdesc differs from
> it only in having removed any INCLUDE attributes.)
>
> So here's a v3 that accounts for that.  I also decided that we were
> going in quite the wrong direction by cramming more info into the
> summary paragraph early in gist.sgml.  The general plan there is to
> offer about a one-sentence description of each opclass method, and
> then go into more detail as necessary in the per-method text below.
> So I moved all this info down into the compress method's section.
> This seems to me to read noticeably better.

I appreciate the explanation! Your v3 text has a lot of good info. I like i=
t.

--=20
Paul              ~{:-)
pj@illuminatedcomputing.com