Store statistics

A store's statistics come in two kinds. Basic statistics are always present and independent of what the samples contain: the sample count and the total byte size. Configured statistics are opt-in per store — a store owner names the scalar keys worth rolling up, and datavo maintains a store-level figure for each.

Every figure is maintained by delta as the store grows, so reading them is a small per-store lookup, never a scan (see db_scaling.md).

Scalar metrics

A metric is {metric_id, display_name, source_key, type} where type is numeric or categorical, and source_key is a scalar (single-value-per-sample) key such as duration_ms.cls or speaker.txt:

• a numeric metric maintains a total (the sum of the key's values) and a present-count (how many samples carry the key);
• a categorical metric maintains a distinct-count (how many distinct values) and a present-count.

A numeric metric MAY declare a unit from a fixed set datavo understands (milliseconds, seconds, bytes, hertz, decibels, count); the total is stored in that base unit and the UI and CLI pick the best scale to show it (milliseconds as hours, bytes as GB). A metric on a non-scalar key, or a numeric metric on a key whose values are not numeric, is refused (HTTP 400).

client.create_store_metric(
    "my_store",
    StoreMetricCreateRequest(
        metric_id="snr",
        display_name="Signal-to-noise",
        source_key="snr.cls",
        type="numeric",
        unit="decibels",
    ),
)
client.list_store_metrics("my_store")            # configured metrics + present-gated defaults
client.get_store_metric("my_store", "snr")
client.update_store_metric("my_store", "snr", StoreMetricUpdateRequest(display_name="SNR"))
client.remove_store_metric("my_store", "snr")

Configuring metrics is a store-owner action (the store's owner), the same authority that archives it.

Default metrics

A store that holds a well-known scalar key gets the matching metric with no configuration, present-gated on the key actually being in the store:

Key	Metric	Type
duration_ms.cls	Total hours	numeric
speaker.txt	Speakers	categorical
a transcript key (graphemes.txt / grapheme.txt / transcript.txt / text.txt)	Transcripts	categorical
session_id.cls	Sessions	categorical

A default appears in list_store_metrics marked is_default. An owner MAY edit its display name or remove it like any other metric; a removed default stays removed even as the store grows again.

Reading the figures

get_store_stats returns the basic statistics plus a metrics list — each configured and present-gated default metric with its maintained value (total for numeric, distinct_count for categorical, and present_count for both):

stats = client.get_store_stats("my_store")
stats.sample_count                               # basic
for metric in stats.metrics:
    metric.display_name, metric.type, metric.total, metric.distinct_count, metric.unit

The store overview in the UI renders one card per metric, including the Sessions count.