From 42b8df1f669fedc8328524173f1799379c80bab4 Mon Sep 17 00:00:00 2001 From: "Paul A. Jungwirth" Date: Fri, 16 Jan 2026 12:31:06 -0800 Subject: [PATCH v1 2/2] Correct GiST documentation about compressed values in leaf pages Our docs stated that the GiST compress support function is only used to store values in internal pages, not leaf pages. But actually we use compress for all pages (if supplied). This error may go back to the 1997 paper "Concurrency and Recovery in Generalized Search Trees", which states that internal pages should hold a predicate and leaf pages should hold the key itself (page 2). But the original paper from 1995 has the predicate everywhere. I also updated the README to call out this difference. --- doc/src/sgml/gist.sgml | 5 ++--- src/backend/access/gist/README | 3 +++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/src/sgml/gist.sgml b/doc/src/sgml/gist.sgml index 1871f742721..c527757a7ef 100644 --- a/doc/src/sgml/gist.sgml +++ b/doc/src/sgml/gist.sgml @@ -273,9 +273,8 @@ CREATE INDEX ON my_table USING GIST (my_inet_column inet_ops); index will depend on the penalty and picksplit methods. Two optional methods are compress and - decompress, which allow an index to have internal tree data of - a different type than the data it indexes. The leaves are to be of the - indexed data type, while the other tree nodes can be of any C struct (but + decompress, which allow an index to store keys of + a different type than the data it indexes. The index tuples can be of any C struct (but you still have to follow PostgreSQL data type rules here, see about varlena for variable sized data). If the tree's internal data type exists at the SQL level, the STORAGE option diff --git a/src/backend/access/gist/README b/src/backend/access/gist/README index 52b14119ff6..c8fc749dcf2 100644 --- a/src/backend/access/gist/README +++ b/src/backend/access/gist/README @@ -59,6 +59,9 @@ The original algorithms were modified in several ways: it is now a single-pass algorithm. * Since the papers were theoretical, some details were omitted and we had to find out ourself how to solve some specific problems. +* We store the (potentially-compressed) predicate at all node levels. The + 1997 paper above (but not the 1995 one) states that leaf pages should store + the original key. Because of the above reasons, we have revised the interaction of GiST core and PostgreSQL WAL system. Moreover, we encountered (and solved) -- 2.47.3