Metrics Overview & Data Model

Overview

If you want to build custom dashboards or alert rules against Arthur's observability data, you write SQL directly against Arthur's TimescaleDB metrics store — a PostgreSQL 16 database with the TimescaleDB extension. Specifically: you write TimescaleDB SQL queries against Arthur's pre-aggregated metrics tables to build custom dashboards and alert rules, using standard PostgreSQL syntax plus TimescaleDB time-series functions.

Before you write your first query, there are two things you must understand:

1. This is not DuckDB. Arthur uses DuckDB for custom aggregation pipelines (a separate concern). The metrics store is PostgreSQL + TimescaleDB. Syntax that works in DuckDB — such as approx_quantile() — will fail here. Use the functions documented on this page.
2. Metrics are pre-aggregated into 5-minute intervals. Raw inference data is rolled up automatically. Your queries operate on these aggregates, not on individual inferences.

From here, see Basic Metric Query Patterns for common SQL patterns, Advanced SQL Patterns & Sketch Functions for quantile queries and joins, Alert Rule Queries for alert-specific SQL, and Best Practices & Troubleshooting for performance tips and error fixes.

The Metrics Data Model

Arthur continuously aggregates inference data into 5-minute buckets. Each row in the metrics store represents one metric, for one model, over one 5-minute window, optionally broken down by one or more dimension values.

Core Concepts

Metric Types

Numeric metrics store a single aggregated scalar value per bucket. Examples include:

• Request counts
• Mean prediction scores
• Accuracy, F1, precision, recall
• Mean feature values
• Drift scores (numeric)

Sketch metrics store a compressed probabilistic data structure (a KLL float sketch) that lets you compute approximate quantiles (p50, p95, p99, etc.) over the aggregation window. Examples include:

• Latency distributions
• Token count distributions
• Feature value distributions where you need percentiles

⚠️

Important: You cannot AVG() or SUM() a sketch column directly. You must use the kll_float_sketch_* functions described in Advanced SQL Patterns & Sketch Functions.

Dimensions as JSONB

Dimensions let you filter and group metrics by arbitrary key-value metadata. Because dimensions are stored as JSONB, you use PostgreSQL's JSONB operators to access them:

-- Filter to a specific dimension value
WHERE dimensions->>'environment' = 'production'

-- Filter where a dimension key exists
WHERE dimensions ? 'model_version'

-- Group by a dimension value
GROUP BY dimensions->>'model_version'

Available Tables and Views

Arthur exposes two primary views for querying metrics. Always query these views rather than the underlying hypertables directly — the views automatically select the most recent schema version of each metric.

metrics_numeric_latest_version

Use this view for all numeric (scalar) metrics.

metrics_sketch_latest_version

Use this view for all sketch (distributional) metrics.

💡

Tip: To discover which metric names are available for a given model, run the discovery queries in Basic Metric Query Patterns.