vgi.cache_control

Module overview

Result-cache control metadata (vgi.cache.*).

A table function can advertise that its result is cacheable by the client (the DuckDB extension) by attaching vgi.cache.* metadata to the first data batch it emits. The vocabulary mirrors HTTP caching (RFC 9111/9110): a freshness lifetime (ttl/expires), a reuse scope, validators (ETag / Last-Modified) for conditional revalidation, and stale-serving grace windows.

The key strings are the single source of truth shared with the C++ extension (which reads them by string). :class:CacheControl renders a set of these fields to the dict[str, str] of vgi.cache.* keys that rides on batch custom_metadata.

Authors advertise cacheability either by passing a :class:CacheControl on the first out.emit(...) call:

from vgi.cache_control import CacheControl

out.emit(first_batch, cache_control=CacheControl(ttl=300))

or by passing the rendered keys directly via the metadata kwarg:

out.emit(first_batch, metadata={"vgi.cache.ttl": "300"})

Booleans render as "1" (present) and are omitted when false; timestamps are RFC 3339 UTC strings; durations are integer seconds.

class CacheControl

source

Description

Cacheability advertised by a table function on its first result batch.

Presence of ttl or expires is what makes a result cacheable; no_store overrides any freshness key. All fields are optional except scope (which defaults to catalog).

Attributes

attribute ttl

int | None

Freshness lifetime in whole seconds, relative to full-result receipt (skew-immune; wins over expires).

attribute expires

str | None

Absolute RFC 3339 UTC deadline. Lifetime is expires - now at receipt.

attribute scope

str

Reuse scope — "catalog" (default; reusable across transactions within the calling catalog identity) or "transaction" (reused only within the same transaction).

attribute no_store

bool

Explicit “never cache”; overrides any freshness key.

attribute etag

str | None

Strong validator (opaque quoted string) for conditional revalidation.

attribute last_modified

str | None

Weaker RFC 3339 UTC validator; fallback when no ETag.

attribute revalidatable

bool

The worker can check freshness cheaply without recomputing; gates whether the client ever sends a conditional request.

attribute stale_while_revalidate

int | None

Grace window (seconds) to serve stale immediately while revalidating in the background.

attribute stale_if_error

int | None

Grace window (seconds) to serve stale if a revalidation RPC fails.

attribute not_modified

bool

304-equivalent — set on a 0-row batch in reply to a conditional request to assert the client’s stored payload is still fresh (the client reuses it instead of re-streaming).

attribute partition_scope

bool

Opt in to per-partition caching. Only meaningful for a SINGLE_VALUE_PARTITIONS table function; the client ALSO caches the result split by partition value (one entry per distinct partition-value tuple) so a later =/IN-filtered scan reuses per-partition entries. Additive to the whole-scan cache.

attribute per_value

bool

Opt in to per-VALUE memoization. Only meaningful for an exchange-mode MAP (a scalar, or a blended table-in-out called via correlated LATERAL); the client ALSO memoizes each distinct input tuple’s output, so the same value serves without the worker on a later chunk or query. Default off, and leave it off unless one call is genuinely expensive. A per-value serve costs a cache probe, a decode and an assembly step per distinct value; that only pays back when it is cheaper than calling you. For an arithmetic map it is roughly 50x slower than just answering the call. Turn it on for model inference, geocoding, or a rate-limited remote fetch.

Methods

method to_metadata

source

to_metadata() -> dict[str, str]

Render to the dict[str, str] of vgi.cache.* batch-metadata keys.

Booleans render as "1" and are omitted when false; unset optional fields are omitted entirely. scope is always emitted so the client never has to infer the default.