Grouped Index Tuples for PostgreSQL


Grouped Index Tuples is essentially a lossy compression scheme for B-tree indexes that takes advantage of clustering in the table. On a fully clustered table, it can achieve impressive compression by effectively storing only one index tuple per heap page instead of one per heap tuple. That can be a 100-fold reduction in index size in the best case of very narrow rows and full clustering. On a completely non-ordered table, it degrades to a normal B-tree. Smaller index size is important because it means less I/O which means more overall throughput.

Other DBMSs achieve similar effect with Clustered Indexes. Traditional clustered indexes in PostgreSQL would require moving heap tuples around, which is difficult. GIT doesn't enforce ordering of the heap, but instead gradually degrades to a normal b-tree as the table becomes less clustered.

Because the key of each index tuple and the order of tuples within a heap page is not stored, index scans need to do some extra processing with GIT. Therefore GIT is a tradeoff between CPU and I/O.


The patches below are against PostgreSQL CVS head.

The main GIT patch: groupeditems-43-pghead.patch.gz

The regression tests included in the GIT patch depend on a custom indexcontents tool that I've been using to peek into index pages. The regression tests are "white box" tests that look into the contents of the index, because I found it difficult to write a reliable black box test suite. There's a similar tool in contrib, pgstattuple, which I could've used instead, but I ended up reinventing the wheel because I found out about pgstattuple only after writing the regression tests. Here's the tool: indexcontents-20061205.tar.gz

Here's a patch to maintain cluster order on a table as new rows are inserted. This patch is independent from GIT, but I've included it here because the performance of GIT depends on clustering of the heap. maintain_cluster_order_v5.patch

A performance unit test suite that tests various simple test cases, with and without GIT: git-perfunittests-20070222.tar.gz

A crude crash recovery test suite: Modify the path to your PostgreSQL installation in the script.


After applying the GIT patch, the feature will automatically be enabled for any index that is defined as the clustered index for a table. Use "CREATE INDEX ... WITH (groupthreshold=2)" to enable the feature explicitly. You can also set the default_groupthreshold GUC parameter to enable the feature for all indexes by default.

The patch also introduces a number of new columns in pgstat_*_indexes views, to count various b-tree operations.


See git-readme.txt. The same text is also in src/backend/access/nbtree/README in the patch.

For now, I've refrained from doing any code changes that aren't absolutely necessary for GIT to work. There's a number of things that should be changed, including dramatic changes to the indexam API, to get full performance gains and to make the patch less ugly




API/Code style


Performance test results

Unit tests, CPU bound

These tests were executed on a dual-core Dell Precision 690

Results show the index size benefits and the CPU overhead of GIT.

Test nameidxpages (unpatched)idxpages (patched)patched / unpatchedduration (unpatched)duration (patched)patched / unpatched

Unit tests, I/O bound

These results show the I/O benefits of the patch

[Needs to be run again. I ran some tests with an earlier version of the patch, and they did show a gain as expected from the reduced index size, but I don't have the numbers now]

[DBT-2 numbers to be added. I'll just say that there's significant reduction in I/O initially, but it vanishes over time as the tables gets less clustered as a result of updates... The HOT patch stops the declustering of the tables, and makes the benefit permanent. ]

Heikki Linnakangas <>
Updated: 25.7.2007