Compress GIN posting lists, for smaller index size.

GIN posting lists are now encoded using varbyte-encoding, which allows them
to fit in much smaller space than the straight ItemPointer array format used
before. The new encoding is used for both the lists stored in-line in entry
tree items, and in posting tree leaf pages.

To maintain backwards-compatibility and keep pg_upgrade working, the code
can still read old-style pages and tuples. Posting tree leaf pages in the
new format are flagged with GIN_COMPRESSED flag, to distinguish old and new
format pages. Likewise, entry tree tuples in the new format have a
GIN_ITUP_COMPRESSED flag set in a bit that was previously unused.

This patch bumps GIN_CURRENT_VERSION from 1 to 2. New indexes created with
version 9.4 will therefore have version number 2 in the metapage, while old
pg_upgraded indexes will have version 1. The code treats them the same, but
it might be come handy in the future, if we want to drop support for the
uncompressed format.

Alexander Korotkov and me. Reviewed by Tomas Vondra and Amit Langote.

Author: hlinnaka

contrib/pgstattuple/expected/pgstattuple.out

@@ -123,6 +123,6 @@ create index test_ginidx on test using gin (b);
 select * from pgstatginindex('test_ginidx');
  version | pending_pages | pending_tuples 
 ---------+---------------+----------------
-       1 |             0 |              0
+       2 |             0 |              0
 (1 row)
 

src/backend/access/gin/README

@@ -135,15 +135,15 @@ same category of null entry are merged into one index entry just as happens
 with ordinary key entries.
 
 * In a key entry at the btree leaf level, at the next SHORTALIGN boundary,
-there is an array of zero or more ItemPointers, which store the heap tuple
-TIDs for which the indexable items contain this key.  This is called the
-"posting list".  The TIDs in a posting list must appear in sorted order.
-If the list would be too big for the index tuple to fit on an index page,
-the ItemPointers are pushed out to a separate posting page or pages, and
-none appear in the key entry itself.  The separate pages are called a
-"posting tree"; they are organized as a btree of ItemPointer values.
-Note that in either case, the ItemPointers associated with a key can
-easily be read out in sorted order; this is relied on by the scan
+there is a list of item pointers, in compressed format (see Posting List
+Compression section), pointing to the heap tuples for which the indexable
+items contain this key. This is called the "posting list".
+
+If the list would be too big for the index tuple to fit on an index page, the
+ItemPointers are pushed out to a separate posting page or pages, and none
+appear in the key entry itself.  The separate pages are called a "posting
+tree" (see below); Note that in either case, the ItemPointers associated with
+a key can easily be read out in sorted order; this is relied on by the scan
 algorithms.
 
 * The index tuple header fields of a leaf key entry are abused as follows:
@@ -163,6 +163,11 @@ algorithms.
 
 * The posting list can be accessed with GinGetPosting(itup)
 
+* If GinITupIsCompressed(itup), the posting list is stored in compressed
+  format. Otherwise it is just an array of ItemPointers. New tuples are always
+  stored in compressed format, uncompressed items can be present if the
+  database was migrated from 9.3 or earlier version.
+
 2) Posting tree case:
 
 * ItemPointerGetBlockNumber(&itup->t_tid) contains the index block number
@@ -210,6 +215,76 @@ fit on one pending-list page must have those pages to itself, even if this
 results in wasting much of the space on the preceding page and the last
 page for the tuple.)
 
+Posting tree
+------------
+
+If a posting list is too large to store in-line in a key entry, a posting tree
+is created. A posting tree is a B-tree structure, where the ItemPointer is
+used as the key.
+
+Internal posting tree pages use the standard PageHeader and the same "opaque"
+struct as other GIN page, but do not contain regular index tuples. Instead,
+the contents of the page is an array of PostingItem structs. Each PostingItem
+consists of the block number of the child page, and the right bound of that
+child page, as an ItemPointer. The right bound of the page is stored right
+after the page header, before the PostingItem array.
+
+Posting tree leaf pages also use the standard PageHeader and opaque struct,
+and the right bound of the page is stored right after the page header,
+but the page content comprises of 0-32 compressed posting lists, and an
+additional array of regular uncompressed item pointers. The compressed posting
+lists are stored one after each other, between page header and pd_lower. The
+uncompressed array is stored between pd_upper and pd_special. The space
+between pd_lower and pd_upper is unused, which allows full-page images of
+posting tree leaf pages to skip the unused space in middle (buffer_std = true
+in XLogRecData). For historical reasons, this does not apply to internal
+pages, or uncompressed leaf pages migrated from earlier versions.
+
+The item pointers are stored in a number of independent compressed posting
+lists (also called segments), instead of one big one, to make random access
+to a given item pointer faster: to find an item in a compressed list, you
+have to read the list from the beginning, but when the items are split into
+multiple lists, you can first skip over to the list containing the item you're
+looking for, and read only that segment. Also, an update only needs to
+re-encode the affected segment.
+
+The uncompressed items array is used for insertions, to avoid re-encoding
+a compressed list on every update. If there is room on a page, an insertion
+simply inserts the new item to the right place in the uncompressed array.
+When a page becomes full, it is rewritten, merging all the uncompressed items
+are into the compressed lists.  When reading, the uncompressed array and the
+compressed lists are read in tandem, and merged into one stream of sorted
+item pointers.
+
+Posting List Compression
+------------------------
+
+To fit as many item pointers on a page as possible, posting tree leaf pages
+and posting lists stored inline in entry tree leaf tuples use a lightweight
+form of compression. We take advantage of the fact that the item pointers
+are stored in sorted order. Instead of storing the block and offset number of
+each item pointer separately, we store the difference from the previous item.
+That in itself doesn't do much, but it allows us to use so-called varbyte
+encoding to compress them.
+
+Varbyte encoding is a method to encode integers, allowing smaller numbers to
+take less space at the cost of larger numbers. Each integer is represented by
+variable number of bytes. High bit of each byte in varbyte encoding determines
+whether the next byte is still part of this number. Therefore, to read a single
+varbyte encoded number, you have to read bytes until you find a byte with the
+high bit not set.
+
+When encoding, the block and offset number forming the item pointer are
+combined into a single integer. The offset number is stored in the 11 low
+bits (see MaxHeapTuplesPerPageBits in ginpostinglist.c), and the block number
+is stored in the higher bits. That requires 43 bits in total, which
+conveniently fits in at most 6 bytes.
+
+A compressed posting list is passed around and stored on disk in a
+PackedPostingList struct. The first item in the list is stored uncompressed
+as a regular ItemPointerData, followed by the length of the list in bytes,
+followed by the packed items.
+
 Concurrency
 -----------
 
@@ -260,6 +335,36 @@ page-deletions safe; it stamps the deleted pages with an XID and keeps the
 deleted pages around with the right-link intact until all concurrent scans
 have finished.)
 
+Compatibility
+-------------
+
+Compression of TIDs was introduced in 9.4. Some GIN indexes could remain in
+uncompressed format because of pg_upgrade from 9.3 or earlier versions.
+For compatibility, old uncompressed format is also supported. Following
+rules are used to handle it:
+
+* GIN_ITUP_COMPRESSED flag marks index tuples that contain a posting list.
+This flag is stored in high bit of ItemPointerGetBlockNumber(&itup->t_tid).
+Use GinItupIsCompressed(itup) to check the flag.
+
+* Posting tree pages in the new format are marked with the GIN_COMPRESSED flag.
+  Macros GinPageIsCompressed(page) and GinPageSetCompressed(page) are used to
+  check and set this flag.
+
+* All scan operations check format of posting list add use corresponding code
+to read its content.
+
+* When updating an index tuple containing an uncompressed posting list, it
+will be replaced with new index tuple containing a compressed list.
+
+* When updating an uncompressed posting tree leaf page, it's compressed.
+
+* If vacuum finds some dead TIDs in uncompressed posting lists, they are
+converted into compressed posting lists. This assumes that the compressed
+posting list fits in the space occupied by the uncompressed list. IOW, we
+assume that the compressed version of the page, with the dead items removed,
+takes less space than the old uncompressed version.
+
 Limitations
 -----------
 

src/backend/access/gin/ginbtree.c

@@ -325,9 +325,10 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 {
 	Page		page = BufferGetPage(stack->buffer);
 	XLogRecData *payloadrdata;
-	bool		fit;
+	GinPlaceToPageRC rc;
 	uint16		xlflags = 0;
 	Page		childpage = NULL;
+	Page		newlpage = NULL, newrpage = NULL;
 
 	if (GinPageIsData(page))
 		xlflags |= GIN_INSERT_ISDATA;
@@ -345,16 +346,17 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 	}
 
 	/*
-	 * Try to put the incoming tuple on the page. If it doesn't fit,
-	 * placeToPage method will return false and leave the page unmodified, and
-	 * we'll have to split the page.
+	 * Try to put the incoming tuple on the page. placeToPage will decide
+	 * if the page needs to be split.
 	 */
-	START_CRIT_SECTION();
-	fit = btree->placeToPage(btree, stack->buffer, stack->off,
-							 insertdata, updateblkno,
-							 &payloadrdata);
-	if (fit)
+	rc = btree->placeToPage(btree, stack->buffer, stack,
+							insertdata, updateblkno,
+							&payloadrdata, &newlpage, &newrpage);
+	if (rc == UNMODIFIED)
+		return true;
+	else if (rc == INSERTED)
 	{
+		/* placeToPage did START_CRIT_SECTION() */
 		MarkBufferDirty(stack->buffer);
 
 		/* An insert to an internal page finishes the split of the child. */
@@ -373,7 +375,6 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 
 			xlrec.node = btree->index->rd_node;
 			xlrec.blkno = BufferGetBlockNumber(stack->buffer);
-			xlrec.offset = stack->off;
 			xlrec.flags = xlflags;
 
 			rdata[0].buffer = InvalidBuffer;
@@ -415,20 +416,16 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 
 		return true;
 	}
-	else
+	else if (rc == SPLIT)
 	{
 		/* Didn't fit, have to split */
 		Buffer		rbuffer;
-		Page		newlpage;
 		BlockNumber savedRightLink;
-		Page		rpage;
 		XLogRecData rdata[2];
 		ginxlogSplit data;
 		Buffer		lbuffer = InvalidBuffer;
 		Page		newrootpg = NULL;
 
-		END_CRIT_SECTION();
-
 		rbuffer = GinNewBuffer(btree->index);
 
 		/* During index build, count the new page */
@@ -443,12 +440,9 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 		savedRightLink = GinPageGetOpaque(page)->rightlink;
 
 		/*
-		 * newlpage is a pointer to memory page, it is not associated with a
-		 * buffer. stack->buffer is not touched yet.
+		 * newlpage and newrpage are pointers to memory pages, not associated
+		 * with buffers. stack->buffer is not touched yet.
 		 */
-		newlpage = btree->splitPage(btree, stack->buffer, rbuffer, stack->off,
-									insertdata, updateblkno,
-									&payloadrdata);
 
 		data.node = btree->index->rd_node;
 		data.rblkno = BufferGetBlockNumber(rbuffer);
@@ -481,8 +475,6 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 		else
 			rdata[0].next = payloadrdata;
 
-		rpage = BufferGetPage(rbuffer);
-
 		if (stack->parent == NULL)
 		{
 			/*
@@ -508,7 +500,7 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 			data.lblkno = BufferGetBlockNumber(lbuffer);
 			data.flags |= GIN_SPLIT_ROOT;
 
-			GinPageGetOpaque(rpage)->rightlink = InvalidBlockNumber;
+			GinPageGetOpaque(newrpage)->rightlink = InvalidBlockNumber;
 			GinPageGetOpaque(newlpage)->rightlink = BufferGetBlockNumber(rbuffer);
 
 			/*
@@ -517,20 +509,20 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 			 * than overwriting the original page directly, so that we can still
 			 * abort gracefully if this fails.)
 			 */
-			newrootpg = PageGetTempPage(rpage);
-			GinInitPage(newrootpg, GinPageGetOpaque(newlpage)->flags & ~GIN_LEAF, BLCKSZ);
+			newrootpg = PageGetTempPage(newrpage);
+			GinInitPage(newrootpg, GinPageGetOpaque(newlpage)->flags & ~(GIN_LEAF | GIN_COMPRESSED), BLCKSZ);
 
 			btree->fillRoot(btree, newrootpg,
 							BufferGetBlockNumber(lbuffer), newlpage,
-							BufferGetBlockNumber(rbuffer), rpage);
+							BufferGetBlockNumber(rbuffer), newrpage);
 		}
 		else
 		{
 			/* split non-root page */
 			data.rrlink = savedRightLink;
 			data.lblkno = BufferGetBlockNumber(stack->buffer);
 
-			GinPageGetOpaque(rpage)->rightlink = savedRightLink;
+			GinPageGetOpaque(newrpage)->rightlink = savedRightLink;
 			GinPageGetOpaque(newlpage)->flags |= GIN_INCOMPLETE_SPLIT;
 			GinPageGetOpaque(newlpage)->rightlink = BufferGetBlockNumber(rbuffer);
 		}
@@ -550,16 +542,24 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 		START_CRIT_SECTION();
 
 		MarkBufferDirty(rbuffer);
+		MarkBufferDirty(stack->buffer);
 
+		/*
+		 * Restore the temporary copies over the real buffers. But don't free
+		 * the temporary copies yet, WAL record data points to them.
+		 */
 		if (stack->parent == NULL)
 		{
-			PageRestoreTempPage(newlpage, BufferGetPage(lbuffer));
 			MarkBufferDirty(lbuffer);
-			newlpage = newrootpg;
+			memcpy(BufferGetPage(stack->buffer), newrootpg, BLCKSZ);
+			memcpy(BufferGetPage(lbuffer), newlpage, BLCKSZ);
+			memcpy(BufferGetPage(rbuffer), newrpage, BLCKSZ);
+		}
+		else
+		{
+			memcpy(BufferGetPage(stack->buffer), newlpage, BLCKSZ);
+			memcpy(BufferGetPage(rbuffer), newrpage, BLCKSZ);
 		}
-
-		PageRestoreTempPage(newlpage, BufferGetPage(stack->buffer));
-		MarkBufferDirty(stack->buffer);
 
 		/* write WAL record */
 		if (RelationNeedsWAL(btree->index))
@@ -568,7 +568,7 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 
 			recptr = XLogInsert(RM_GIN_ID, XLOG_GIN_SPLIT, rdata);
 			PageSetLSN(BufferGetPage(stack->buffer), recptr);
-			PageSetLSN(rpage, recptr);
+			PageSetLSN(BufferGetPage(rbuffer), recptr);
 			if (stack->parent == NULL)
 				PageSetLSN(BufferGetPage(lbuffer), recptr);
 		}
@@ -582,6 +582,11 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 		if (stack->parent == NULL)
 			UnlockReleaseBuffer(lbuffer);
 
+		pfree(newlpage);
+		pfree(newrpage);
+		if (newrootpg)
+			pfree(newrootpg);
+
 		/*
 		 * If we split the root, we're done. Otherwise the split is not
 		 * complete until the downlink for the new page has been inserted to
@@ -592,6 +597,8 @@ ginPlaceToPage(GinBtree btree, GinBtreeStack *stack,
 		else
 			return false;
 	}
+	else
+		elog(ERROR, "unknown return code from GIN placeToPage method: %d", rc);
 }
 
 /*