Monitoring & introspection

A handful of functions tell you everything about a running xpatch table: how well it compresses, how the cache is doing, and how any single group is laid out on disk. Full signatures live in the SQL reference, all defined in pg_xpatch--0.7.0.sql; this page is about which one to reach for.

Is compression working?

SELECT total_rows, keyframe_count, delta_count,       compression_ratio, avg_compression_depth,       raw_size_bytes, compressed_size_bytesFROM xpatch.stats('documents');

compression_ratio is the headline (raw / compressed). avg_compression_depth shows how far back deltas reach on average, which tells you whether a high compress_depth is earning its keep. These read from a stats table that pg-xpatch maintains on every write, so the call stays instant even on large tables.

One-look table overview

SELECT * FROM xpatch.describe('documents');

describe() is the best first command on any xpatch table. It returns a property/value list covering the access method, whether the config is explicit or auto-detected, each column's role (group_by, order_by, delta, internal), and the storage stats in one place.

How is a group stored?

SELECT version, seq, is_keyframe, tag, delta_size_bytes, column_nameFROM xpatch.inspect('documents', 1);   -- 1 is the group value

inspect() shows one row per version per delta column: whether it is a keyframe, its tag (rows back to its base), and the compressed delta_size_bytes. This is how you see, concretely, where the space is going inside one group.

Is the cache healthy?

SELECT * FROM xpatch.cache_stats();

The content cache counters: hit_count, miss_count, eviction_count, skip_count, plus current and maximum size. Rising evictions mean the cache is undersized; rising skips mean entries exceed cache_max_entry_kb. Tuning read performance maps each symptom to a fix.

There is a matching xpatch.insert_cache_stats() for the write path (slots_in_use, total_slots, hits, misses, evictions, eviction_misses), useful if writes feel slower than expected on tables with many concurrently-written groups.

The raw bytes (advanced)

SELECT version, seq, is_keyframe, tag, delta_column, delta_sizeFROM xpatch.physical('documents');

physical() exposes the actual stored delta bytes and their metadata, across all groups or a single one. Reach for it when debugging encoding behavior or verifying what landed on disk; for everyday checks, stats() and inspect() are friendlier.