Pinned Tables

StorageLow LatencyPinning

Stable On by default · production-ready

What it is

Pinning is an explicit contract with the storage engine: this data must stay in memory, no matter how cold it gets. A pinned table is exempt from the normal access-based eviction, so reads against it always hit RAM.

You can pin whole tables — small reference catalogs, session caches, feature flags — or pin just the rows that match a predicate. Pinning by predicate is the usual choice for large tables where only a hot subset deserves guaranteed residency.

Why it matters

Some workloads cannot tolerate the tail-latency cost of fetching cold data. A real-time bidding system that must respond in 5 ms cannot wait for a disk read on a rare miss. Pinning gives that data a hard performance floor while the rest of the database uses the normal multi-tier flow.

• Predictable latency — pinned reads always hit RAM, so the p99 looks like the p50.
• Pin the slice, not the whole table — predicate pinning keeps large tables affordable while still guaranteeing the hot rows.
• Safe by default — over-pinning is rejected up front, not resolved by silently evicting other pinned data.

How you use it

Pinning is a one-line SQL command. You can pin a whole table, pin rows that match a predicate, check what is currently pinned, and release a pin when the workload no longer needs it.

-- Pin only the critical slice of a large table.
PIN TABLE telemetry
  WHERE severity = 'CRITICAL';

-- Pin a recent window for a hot-window workload.
PIN TABLE sessions
  WHERE last_seen >= now() - INTERVAL '1 hour';

-- Pin an entire small reference table.
PIN TABLE currency_rates;

-- Inspect what's currently pinned and how much RAM it costs.
SELECT table_name, pin_predicate, bytes_pinned, segment_count
  FROM aetherius_system.pinned_objects
 ORDER BY bytes_pinned DESC;

-- Release a pin when the workload no longer needs it.
UNPIN TABLE telemetry;

After a predicate pin runs, the engine keeps only the data that actually contains matching rows in memory and leaves the rest to flow through normal residency rules.

Illustrative syntax

The PIN TABLE / UNPIN TABLE grammar and the pinned_objects columns shown here illustrate the feature shape. Confirm the exact spelling against your server version.

Pin budget

Pins are checked against a configurable ceiling (a percentage of physical RAM) before any memory is reserved. If a pin would push past the budget, the engine refuses it up front and tells you, rather than accepting it and risking an out-of-memory failure later.

Notes & caveats

Tip

Combine pinning with a warm-up: pin the predicate that matches your hot working set, then run one no-op query against it at startup so the data is resident before real traffic arrives.

Pin only what truly needs it

Pinning consumes RAM that other queries could have used. Pin only data that genuinely needs guaranteed latency; rely on the auto-managed tiers and the cache for everything else. Monitor the pinned_objects view and unpin tables whose workloads change.

Multi-Tier Residency →

The auto-managed tiering that pinning opts out of for specific data.

Caching →

For data that's hot but not hot enough to pin.

Memory Compaction →

Keeps resident memory tidy as data changes.

Configuration & Availability →

Storage defaults and feature flags.