Cache control

On this page

Advertising a result as reusable by the client.

struct CacheControl

source

type CacheControl struct {
// Ttl is the freshness lifetime in whole seconds, relative to full-result
// receipt (skew-immune; wins over Expires). Nil leaves it unset — use
// Seconds(0) for an always-revalidate ("no-cache") result.
Ttl  *int64
// Expires is an absolute RFC 3339 UTC deadline. Lifetime is expires-now at
// receipt.
Expires  string
// Scope is the reuse scope: CacheScopeCatalog (default when empty) or
// CacheScopeTransaction.
Scope  string
// NoStore is an explicit "never cache"; it overrides any freshness key.
NoStore  bool
// ETag is a strong validator (opaque quoted string) for conditional
// revalidation.
ETag  string
// LastModified is a weaker RFC 3339 UTC validator; the fallback when no
// ETag is set.
LastModified  string
// Revalidatable declares that the worker can check freshness cheaply
// without recomputing. It gates whether the client ever sends a
// conditional request.
Revalidatable  bool
// StaleWhileRevalidate is a grace window (seconds) to serve stale
// immediately while revalidating in the background.
StaleWhileRevalidate  *int64
// StaleIfError is a grace window (seconds) to serve stale if a
// revalidation RPC fails.
StaleIfError  *int64
// NotModified is the 304 equivalent — set it 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).
NotModified  bool
// PartitionScope opts in to per-PARTITION caching. Only meaningful for a
// SINGLE_VALUE_PARTITIONS table function: the client ADDITIONALLY stores
// the result split by partition value (one entry per distinct partition
// tuple), so a later =/IN-filtered scan on the partition column(s) serves
// the requested partitions from cache without calling the worker. The
// whole-scan entry is still stored, so this is purely additive.
PartitionScope  bool
// PerValue opts in to per-VALUE memoization. Only meaningful for an
// exchange-mode MAP — a scalar, or a blended table-in-out called through a
// correlated LATERAL: the client ADDITIONALLY memoizes each distinct input
// tuple's output keyed on that tuple, so the same value is served without
// calling the worker on a later chunk or a later query.
//
// It defaults to false, and that default is deliberate — leave it off
// unless one call to this function is genuinely expensive. A per-value
// serve is not free: the client pays a key probe, a decode and a result
// assembly step for every distinct value, and that only pays back when it
// costs LESS than the worker call it replaces. For a cheap map (arithmetic,
// a string tweak) it is a large net loss — roughly 50x slower than simply
// calling the worker. Only the function author knows which side of that
// line a call falls on, which is why this is an explicit advertisement
// rather than something the engine infers.
//
// Turn it on when a single call is heavy and repeats across rows: a model
// inference, a geocode, a rate-limited HTTP fetch, an expensive parse.
// Independent of the freshness keys — a result can be whole-result
// cacheable (Ttl/Expires) without per-value memoization paying off.
PerValue  bool
}

Description

CacheControl is the cacheability a table function advertises on its first result batch.

Presence of Ttl or Expires is what makes a result cacheable; NoStore overrides any freshness key. Every field is optional except Scope, which defaults to CacheScopeCatalog when empty.

Methods

method Metadata

source

func (c *CacheControl) Metadata() map[string]string

Metadata renders the CacheControl to its 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.

method Validate

source

func (c *CacheControl) Validate() error

Validate checks the scope and the non-negative duration invariants.

function Seconds

source

func Seconds(n int64) *int64

Seconds returns a pointer to n, for the duration fields of CacheControl.