querycache

package
v0.23.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package querycache is anfra's query cache: its data structures, its algorithm (Manager), and the Store that keeps its metadata, which anfra implements on SQLite (store/sqlite) and a platform embedding the engine may implement on its own database. A platform reaches the types through engine's aliases, and checks its store with engine/querycachetest.

A key's results are physical entries: one for each write of the result, each with its own file in canal-lake. A logical entry, one per key, points at the physical entry that answers the key now. Entry is a physical entry; the logical entry is how a store keeps which one is current, and only Lookup and Get return a current one. See docs/designs/query-cache.md.

Index

Constants

View Source
const (
	// DefaultReadGrace is how long after an entry expires its file is kept: the
	// longest a read of it can run (an export's, 30 minutes) and a margin, so a
	// read that began before expiry finishes.
	DefaultReadGrace = 35 * time.Minute
	// DefaultLeaseMargin is added to a write's deadline to make its lease.
	DefaultLeaseMargin = 5 * time.Minute
	// DefaultLease is the lease of a write whose context has no deadline.
	DefaultLease = 35 * time.Minute
)

Defaults, for a Config that leaves them unset.

View Source
const MaxDuration = 7 * 24 * time.Hour

MaxDuration is the longest a query may ask the cache to keep its result, and accept a cached one for: its cache.duration, or the repo's default.

Variables

View Source
var (
	ErrNoQuery              = errors.New("the query cache's key needs a compiler key or a SQL text, and has neither")
	ErrTwoQueries           = errors.New("the query cache's key needs a compiler key or a SQL text, and has both")
	ErrNoTenant             = errors.New("the query cache's key needs the tenant the query runs for, and has none")
	ErrNoDataSourceIdentity = errors.New("the query cache's key needs the data source's identity, and the host gave none")
)

Why NewKey makes no key. Each is a mistake of whoever built the input, not the person running the query: the query runs uncached, and the log says which.

View Source
var ErrNotPending = errors.New("not a pending write")

ErrNotPending is Commit's or Abandon's refusal of an entry that is not a pending write of the key given: committed already, or swept.

Functions

func ValidNamespace

func ValidNamespace(ns string) bool

ValidNamespace reports whether ns can prefix a file's name in canal-lake: empty, or word segments each ending in "/".

Types

type Config

type Config struct {
	Store Store
	// Namespace prefixes the names of the files its writes put in canal-lake:
	// empty for anfra, whose canal-lake is its repo's; a platform sharing one
	// canal-lake between tenants sets one per tenant. See ValidNamespace.
	Namespace string
	// ReadGrace is how long after an entry expires its file is kept, for a
	// read that began before.
	ReadGrace time.Duration
	// LeaseMargin is added to a write's deadline to make its lease.
	LeaseMargin time.Duration
	// DefaultLease is the lease of a write whose context has no deadline.
	DefaultLease time.Duration
	// Now is the clock; time.Now when nil.
	Now func() time.Time
}

Config is a Manager's store, namespace and timings. Zero timings take the defaults.

type Contents

type Contents struct {
	// Entries are the committed entries no lookup has stopped using yet, and
	// Bytes their size.
	Entries int
	Bytes   int64
	// OldestCachedAt and NewestCachedAt are those entries' oldest and newest
	// CachedAt: zero without any.
	OldestCachedAt, NewestCachedAt time.Time
	// Expired are the entries no query uses any more, expired, cleaned or
	// abandoned, which a sweep removes.
	Expired Expired
	// Writing is how many writes are pending, their lease still running.
	Writing int
}

Contents are what a store holds at a time, as anfra cache status reports it.

type Entry

type Entry struct {
	ID EntryID
	// Namespace prefixes its file's name in canal-lake (LakeKey): empty, or
	// segments each ending in "/", such as "3f9a1c0e/". A platform sharing
	// one canal-lake between tenants groups each one's files by it.
	Namespace string
	Key       Key
	// CachedAt is when its rows were read from the warehouse: when its write
	// began, as the warehouse reads a query's rows as it starts. Zero while its
	// write is pending: a pending entry is one with no CachedAt.
	CachedAt time.Time
	// ExpiresAt is when it stops being used. While pending, its lease: the
	// latest its write can commit and be used, set from the run's deadline so a
	// write can't outlive it, and swept like any expiry once it runs out.
	// Abandoning a write, or a clean, ends it at once, so its result is never
	// used (docs/designs/query-cache.md#a-writes-lease).
	ExpiresAt time.Time
	RowCount  int64
	SizeBytes int64
	// Columns is the result's header, as the executor gave it, kept as given.
	Columns []byte
	// AQL and SQL are what ran, for inspecting an entry.
	AQL, SQL string
}

Entry is a physical entry: one write of a key's result, with its own file in canal-lake. Its times are whole milliseconds, as a store keeps them. Whether it answers the key now is the store's to say: Lookup and Get return only an entry that does; Sweepable returns ones that don't.

func (Entry) LakeKey

func (e Entry) LakeKey() string

LakeKey is the entry's file in canal-lake: its namespace and its id, such as 1234, or 3f9a1c0e/1234 in a namespace. From a file to its entry is its id; from an entry to its file, this.

type EntryID

type EntryID int64

EntryID identifies a physical entry, and orders writes: the greater is the newer, and wins a commit. A store never reuses one.

type Expired

type Expired struct {
	Entries int
	Bytes   int64
}

Expired is what Expire expired: how many committed entries, and their size.

type Key

type Key string

Key is a query's key in the cache: anfra-node's cache key, hashed with what the compiler doesn't see (the data source's identity, the result's bounds).

func NewKey

func NewKey(in KeyInput) (Key, error)

NewKey is the key of the query in: the hash of every field, so that two inputs differing in any one have different keys.

type KeyInput

type KeyInput struct {
	// CompilerKey is anfra-node's key for an AQL query (v1:…): the compiled
	// query, data restrictions and user attributes resolved into it. Its
	// format version stands for anfra-node's version.
	CompilerKey string
	// SQL is a SQL query's text, which has no compiler key. Exactly one of
	// CompilerKey and SQL is set.
	SQL string

	// Tenant is whom the query runs for: tenants never share an entry.
	Tenant string
	// DataSource is the data source's identity: who the warehouse sees
	// (datasource.DataSource.Identity).
	DataSource string
	// DBType is the data source's type, the SQL dialect.
	DBType string
	// TruncateRows is the most rows the query answers, as canal-query stores
	// the rows it streamed (negative: all of them).
	TruncateRows int
}

KeyInput is what a query's key is made of: anfra-node's key, and what the compiler doesn't see. Each field is either something that decides access, which the key guarantees, or something that changes the rows under the same access, which it holds as best it can. What changes neither (comments, timeouts, SSL, pooling, the result's maximums) is not here (docs/designs/query-cache.md#keys).

type Lake

type Lake interface {
	// Drop removes the files of these lake keys. A key with no file is no
	// error: a write that failed has none, and a sweep may be repeated.
	Drop(ctx context.Context, lakeKeys []string) error
}

Lake is what the cache needs of canal-lake besides reading and writing an entry, which go through the executor: dropping entries' files.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager is the query cache's algorithm, over a Store, sweeping through a Lake: which entry a query accepts, a write's lease and commit, cleaning, and sweeping. It holds no state of its own: it is as cheap to make as its store, for each invocation.

func NewManager

func NewManager(c Config) (*Manager, error)

NewManager makes a Manager. A namespace canal-lake can't take is an error.

func (*Manager) Begin

func (m *Manager) Begin(ctx context.Context, key Key, tags []Tag, aql, sql string) (*Write, error)

Begin starts a write of key's result, with the key's tags and what runs. Its lease is its context's deadline and a margin, so the write can't outlive it; a context without one gets the default lease. Its file in canal-lake is named by the namespace and its id (LakeKey).

func (*Manager) Clean

func (m *Manager) Clean(ctx context.Context, tags []Tag) (Expired, error)

Clean expires the entries of the keys with all of tags, or of every key without tags, and ends their writes' leases: after it, no result read before it is used (docs/designs/query-cache.md#cleaning). Their files go with the next sweep.

func (*Manager) Lookup

func (m *Manager) Lookup(ctx context.Context, key Key, maxAge time.Duration, notBefore time.Time) (Entry, bool, error)

Lookup is the entry a query accepts: the key's current entry, unexpired, younger than maxAge, the query's cache duration, and cached at notBefore or later, when notBefore isn't zero. So a query asking for fresher data than an entry was written for never gets older data than it accepts, and a later page of a run never gets data older than its first page (docs/designs/query-cache.md#which-entry-a-query-accepts). None when maxAge is not positive: the query doesn't read the cache.

func (*Manager) Sweep

func (m *Manager) Sweep(ctx context.Context, lake Lake, limit int) (Swept, error)

Sweep removes up to limit entries expired for longer than the read grace, whatever their namespace, as each names its own file: their files from canal-lake first, through lake, then their rows. In that order a row may name a file already gone, but no file is left that no row names. Pending writes are among them once their lease has run out.

type State

type State string

State is the query cache's state: one for each thing the reader does about it.

const (
	// StateReady: the cache can be used. Nothing to do.
	StateReady State = "ready"
	// StateIncompatible: a newer anfra changed the store in a way this one
	// can't read. Update anfra. Only a store that processes of different
	// versions share can be in it.
	StateIncompatible State = "incompatible"
	// StateUnavailable: the store can't be used, for a reason Problem gives.
	StateUnavailable State = "unavailable"
	// StateDisabled: the cache is turned off, for a reason Reason gives.
	StateDisabled State = "disabled"
)

type Store

type Store interface {
	// Lookup is the key's current entry, if it is unexpired at now. The age
	// rule, against the query's own duration, is the caller's.
	Lookup(ctx context.Context, key Key, now time.Time) (Entry, bool, error)
	// Get is the entry id, as Lookup would return it: current and unexpired at
	// now. For a Planner that found it by other means.
	Get(ctx context.Context, id EntryID, now time.Time) (Entry, bool, error)

	// Begin records a pending write (Namespace, Key, AQL and SQL set, and
	// ExpiresAt as its lease) and its key's tags, and gives it its id, which
	// with its namespace names its file (LakeKey). No Lookup returns it.
	Begin(ctx context.Context, e Entry, tags []Tag) (EntryID, error)
	// Commit finishes a pending write at now, in one transaction: fills it
	// (CachedAt, ExpiresAt, RowCount, SizeBytes, Columns), makes it the key's
	// current entry unless a greater id is already current, and expires the
	// key's other committed entries at now. A write that lost to a greater id,
	// or whose lease ended by now (abandoned, cleaned, or past its lease),
	// commits expired at now. ErrNotPending when e is not a pending write of
	// its key.
	Commit(ctx context.Context, e Entry, now time.Time) error
	// Abandon ends a pending write's lease at now: one that failed or was
	// cancelled. ErrNotPending when it is not pending.
	Abandon(ctx context.Context, id EntryID, now time.Time) error

	// Sweepable is up to limit entries a sweep may remove, oldest first: those
	// expired before cutoff, pending or committed.
	Sweepable(ctx context.Context, cutoff time.Time, limit int) ([]Entry, error)
	// Delete removes entries; and a key's logical entry and tags with its last
	// entry. The caller drops their files first.
	Delete(ctx context.Context, ids []EntryID) error
	// Expire expires at now every unexpired entry of the keys that have all of
	// tags, or of every key when tags is empty: what a clean does.
	// A pending write among them has its lease ended, so it commits expired:
	// after a clean, no result read before it is used, which is what someone
	// cleaning after fixing data relies on. It answers the committed entries
	// it expired, and their size.
	Expire(ctx context.Context, tags []Tag, now time.Time) (Expired, error)
}

Store keeps the cache's metadata. Each method is one step of the cache's algorithm, and its transaction is the store's to keep. Times are given, never read from a clock, so the rules can be tested. engine/querycachetest says what each method must do; a store passes it, whatever its tables.

A store is one cache: anfra's, one per repo. A platform serving several tenants binds a store to one for each invocation, and keeps the tenant in its own rows; nothing here names it.

type Summarizer

type Summarizer interface {
	Summarize(ctx context.Context) Summary
}

Summarizer reports the query cache's state, as anfra status shows it, without changing anything. anfra's host implements it over the repo's store; a platform, over its own.

type Summary

type Summary struct {
	State State `` /* 397-byte string literal not displayed */
	// Store is where the store is, when a person can act on it: anfra's file.
	// Absent when the cache is disabled, or the host doesn't say.
	Store   string `` /* 137-byte string literal not displayed */
	Problem string `json:"problem,omitempty" doc:"what's wrong with the cache, when it is incompatible or unavailable"`
	Reason  string `json:"reason,omitempty" doc:"what turns the cache off, when it is disabled"`
	// Hint is what to do about the problem, for status to add to its hints.
	Hint string `json:"-"`
}

Summary is the query cache's state, read without changing anything.

type Swept

type Swept struct {
	Entries int
	Bytes   int64
}

Swept is what a sweep removed: how many entries, and their size.

type Tag

type Tag struct {
	Kind  TagKind
	Value string
}

Tag is what a key's entries are selected by for cleaning: the data source, dataset and models a query read. A tag is never read by a lookup.

type TagKind

type TagKind string

TagKind is what a tag selects entries by.

const (
	TagDataSource TagKind = "data_source"
	TagDataset    TagKind = "dataset"
	TagModel      TagKind = "model"
)

type Write

type Write struct {
	// contains filtered or unexported fields
}

Write is a write of a key's result in progress: its rows go to canal-lake under LakeKey, and Commit or Abandon ends it.

func (*Write) Abandon

func (w *Write) Abandon(ctx context.Context) error

Abandon ends the write without a result: its query failed or was cancelled. Its lease ends now, so it is swept, and never used. It runs whether or not ctx is done, since a cancelled query is a reason to abandon its write. A write already committed or swept is no error.

func (*Write) Commit

func (w *Write) Commit(ctx context.Context, rowCount, sizeBytes int64, columns []byte, duration time.Duration) (Entry, error)

Commit ends the write: its rows are in canal-lake, rowCount of them in sizeBytes, their header columns, kept for duration. Its rows were read when it began, so that is its CachedAt, and it expires duration after. It becomes the key's current entry unless a newer one is, or its lease ended (it was cleaned, or ran past its deadline): then it is committed expired, and never used. ErrNotPending when it was swept or committed already.

func (*Write) ID

func (w *Write) ID() EntryID

ID is the write's entry.

func (*Write) LakeKey

func (w *Write) LakeKey() string

LakeKey is the file in canal-lake the write's rows go to.

Directories

Path Synopsis
Package local is a local repo's query cache, as anfra's own process holds it: the repo's store, opened at first use, its canal-lake, started at first use, and the cache's state as anfra status reports it (a querycache.Summarizer).
Package local is a local repo's query cache, as anfra's own process holds it: the repo's store, opened at first use, its canal-lake, started at first use, and the cache's state as anfra status reports it (a querycache.Summarizer).
store
sqlite
Package sqlite is anfra's query cache store (querycache.Store), on SQLite: one file per repo, under anfra's home.
Package sqlite is anfra's query cache store (querycache.Store), on SQLite: one file per repo, under anfra's home.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL