Module queryapi 

The metrics query API — the data-access service boundary (SRD-86 §“The metric-reader surface”).

nmbrs-metrics is the foundational data-access library; this module exposes its query surface as a service. It provides the native result shape (Vector — multiple Series, each with sample points), the selector semantics (Matcher), and a small access contract (MetricAccess) whose signatures map 1:1 onto a MetricsQL parsed selector:

• a bare / instant selector → MetricAccess::select_instant;
• a range selector (m[w]) → MetricAccess::select_range.

Deliberately not here: aggregation, rollups, arithmetic — the “bells and whistles” of the query language. Those stay in the MetricsQL engine, layered over this access surface. Keeping the contract this thin is what lets the engine sit on any data service.

Service location (a “data service object”)

Consumers (the MetricsQL engine) locate a service at runtime rather than binding a concrete impl:

• the live in-process service wraps the session’s MetricsQuery (which is not static), so the runner install_live_accesses it per session and consumers read it via live_access;
• file / external backends (e.g. the sqlite reader) register an AccessProvider via inventory, so a consumer can provider one by scheme and open it — without the engine depending on the backend’s crate or features.

Re-exports

pub use catalog::CachedCatalog;

pub use catalog::ExemplarPoint;

pub use catalog::LabelSet;

pub use catalog::MetricCatalog;

pub use catalog::MetricFamilyMeta;

pub use catalog::MetricType;

Modules

catalog

Catalog: enumerable backend introspection for metrics.

Structs

AccessProvider

A pluggable access backend, discovered at runtime via inventory. A consumer opens a service for a scheme-specific target (e.g. a db path). The sqlite reader registers one; future backends can too, without the query engine depending on them.

ExecScopedAccess

SRD-89 §3b / SRD-90 §M6 — scope every read to its reading execution by injecting exec_id as a uniform dimensional-label matcher, so each interior backend applies it wherever exec_id lives (the in-memory tier’s label set, the sqlite tier’s exec_id column) with the same value. This replaces the per-backend special-casing (the live tier’s bespoke post-filter, a sqlite selection mode) with one mechanism: exec_id is just a label.

HybridStore

Composite read backend over an ordered tier list (finest first).

Matcher

A single label matcher in a selector — one MetricsQL label filter.

MetricsQueryAccess

The live in-process access backend. Cheap to construct (wraps the shared Arc).

QueryError

Error from a metrics access backend. Backends own their taxonomy; the engine treats these as opaque from a flow-control standpoint.

Sample

One observation: a value at a point in time (Unix epoch ms).

Series

One time series: an identifying label set plus its observed samples (ascending by timestamp). __name__ lives in labels.

Tier

One tier of a HybridStore: a backend plus its horizon advertiser.

Vector

A vector result: zero or more series, each with one or more sample points. The content distinguishes the MetricsQL result shapes —

Enums

MatchOp

How a Matcher compares a label’s value. Mirrors the four MetricsQL label-filter operators.

Traits

HorizonAware

A horizon-advertising backend: the oldest sample-time it still holds, in Unix-ms. None ⇒ unbounded (covers back as far as the query asks) — the natural answer for a durable tail tier.

MetricAccess

The metrics data-access service. Backends implement it; a query layer locates one at runtime and reads Vectors through it. See the module docs for the access/aggregation cut line.

Functions

current_read_exec_id

The reading execution’s exec_id, if a hook is installed and a scope is active. None ⇒ live reads are unscoped (A1 single-run).

install_live_access

Install the live in-process access service. Called once by the runner when the session’s MetricsQuery is built.

install_read_exec_id_hook

Install the reading-execution exec_id resolver (idempotent — first wins). The runtime calls this once with a fn that reads its task-local execution context.

live_access

The live in-process access service, if a session has installed one. Lock-free: one atomic ArcSwap load.

provider

Locate a registered AccessProvider by scheme.

uninstall_live_access

Drop the installed live-access service and everything it owns — crucially the HybridStore’s sqlite “cold tier” reader connection on metrics.db. The runner calls this at session shutdown BEFORE the SQLite reporter consolidates the WAL: PRAGMA journal_mode=DELETE needs an EXCLUSIVE lock on the db, which a still-open reader connection on the same file blocks (“database is locked”). swap + explicit drop so the holder’s Arc chain is released here rather than deferred to the next store. Idempotent; a no-op if nothing was installed.