MIME-Version: 1.0
References: 
 <CA+renyWs5Np+FLSYfL+eu20S4U671A3fQGb-+7e22HLrD1NbYw@mail.gmail.com>
 <1855968.1774812758@sss.pgh.pa.us>
In-Reply-To: <1855968.1774812758@sss.pgh.pa.us>
From: Paul A Jungwirth <pj@illuminatedcomputing.com>
Date: Sun, 29 Mar 2026 18:35:19 -0700
Message-ID: 
 <CA+renyXv6+tVi2yeQNXRwRkAm=wg89k=orjU8nMRKqWf1q6mtg@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%2BrenyXv6%2BtVi2yeQNXRwRkAm%3Dwg89k%3DorjU8nMRKqWf1q6mtg%40mail.gmail.com>
Precedence: bulk

On Sun, Mar 29, 2026 at 12:32=E2=80=AFPM Tom Lane <tgl@sss.pgh.pa.us> wrote=
:
>
> Paul A Jungwirth <pj@illuminatedcomputing.com> writes:
> > Our docs for GiST indexes say the compress function is only used for
> > internal pages, not leaf pages, but actually it is used everywhere.
> > Here are two patches to clean things up.
>
> > You can see that we store compressed values with the pageinspect
> > extension. For instance, multiranges are compressed to ranges. Here
> > they are in leaf pages:
>
> 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.

Ah, thanks for pointing that out!

> So I'm inclined to propose text more like the attached.  I merged
> your two patches into one (didn't seem all that useful to separate).
> Also, I dropped the adjacent sentence suggesting using the STORAGE
> option.  AFAIK that's pretty useless here: I don't think any GiST
> code pays attention to it.  At least part of the reason is that it's
> inadequate to describe the possibility that leaf and internal datums
> are different.

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?)

Yours,

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