# v0.2.2 — Paging, AUTO Mode, and Query Modification

> **Full technical details:** [v0.2.2.md-full.md](v0.2.2.md-full.md)

**Status: ✅ Released** | **Scope: Medium** (~3 weeks)

> Support for paginated top-N queries, smarter automatic refresh mode
> selection, the ability to change a stream table's query without recreating
> it, and further WAL decoder hardening.

---

## What problem does this solve?

Real applications often need *paginated* ranked results (not just the top 10,
but page 2 — results 11–20). Operators wanted the system to automatically
choose the most efficient refresh approach rather than requiring manual
configuration. And once a stream table is deployed, queries evolve —
modifying the query without a disruptive recreate became important.

---

## OFFSET Support: Paginated Top-N

v0.2.0 added `ORDER BY … LIMIT N` support for top-N queries. v0.2.2 extends
this to `OFFSET`, enabling paginated windows like:

- Page 1: `ORDER BY revenue DESC LIMIT 10 OFFSET 0`
- Page 2: `ORDER BY revenue DESC LIMIT 10 OFFSET 10`

Each page is maintained as a separate stream table, and the engine keeps
adjacent pages consistent with each other as the underlying rankings change.

*In plain terms:* if you need to display a ranked list across multiple pages
and keep all pages live and consistent, pg_trickle can now handle that.

---

## AUTO Mode: Smart Refresh Strategy Selection

Previously, users had to choose between DIFFERENTIAL (incremental, fast when
delta is small) and FULL (complete recomputation, reliable but slow). A wrong
choice means either slow refreshes or incorrect results.

**AUTO mode** — now the default — removes this decision. The scheduler
measures both the delta size and the cost of the last full refresh, and
automatically picks whichever approach will be faster. If the change batch is
small relative to the total data, DIFFERENTIAL runs. If the change batch is
large enough that DIFFERENTIAL would be slower, FULL runs.

*In plain terms:* you no longer need to tune refresh mode per stream table.
AUTO picks the right strategy automatically, and you can always override it
if you have specific requirements.

---

## ALTER QUERY: Changing a Stream Table's Defining Query

Before this release, changing the query behind a stream table required
dropping and recreating it — losing the existing data and triggering a full
refresh from scratch.

`alter_stream_table(name, query => '...')` now allows modifying the query
in place. pg_trickle validates that the new query is compatible, updates the
differential engine's representation, and schedules a reconciliation refresh
to bring the existing data in line with the new definition.

---

## WAL CDC Hardening

The WAL-based change capture path received further hardening against edge
cases: slot invalidation after a long standby period, high-frequency update
patterns that could cause buffer overflow, and transactions containing very
large numbers of row changes.

---

## IMMEDIATE Mode Parity

IMMEDIATE mode (introduced in v0.2.0) now supports the full range of SQL
patterns that standard background-refresh mode supports, closing a gap where
certain query shapes were incorrectly falling back to FULL in IMMEDIATE mode.

---

## Scope

v0.2.2 rounds out the TopK feature with pagination, makes AUTO mode the
default refresh strategy, and adds the ability to evolve stream tables
without recreating them. These improvements collectively make pg_trickle
more practical for production deployments.