---
updatedAt: 2026-05-19T06:49:20.000Z
agentTools:
  projectIndex: https://docs.arthur.ai/llms.txt
---

# 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](https://docs.arthur.ai/docs/metrics-basic-queries) for common SQL patterns, [Advanced SQL Patterns & Sketch Functions](https://docs.arthur.ai/docs/metrics-advanced-queries) for quantile queries and joins, [Alert Rule Queries](https://docs.arthur.ai/docs/metrics-alert-queries) for alert-specific SQL, and [Best Practices & Troubleshooting](https://docs.arthur.ai/docs/metrics-best-practices) 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

| Concept         | Description                                                                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Metric name** | A string identifier such as `prediction_count`, `accuracy`, or `feature_drift.my_feature`                                              |
| **Metric type** | Either `numeric` (a scalar `DOUBLE PRECISION` value) or `sketch` (a serialized KLL float sketch for quantile estimation)               |
| **Timestamp**   | A `TIMESTAMPTZ` aligned to 5-minute boundaries (e.g., `2024-01-15 14:00:00+00`, `2024-01-15 14:05:00+00`)                              |
| **Dimensions**  | A `JSONB` column containing key-value pairs that slice the metric — for example `{"environment": "production", "model_version": "v2"}` |
| **Model ID**    | A `UUID` identifying the Arthur model this metric belongs to                                                                           |

### 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](https://docs.arthur.ai/docs/metrics-advanced-queries).

### 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:

```sql
-- 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.

| Column           | Type               | Description                                                        |
| ---------------- | ------------------ | ------------------------------------------------------------------ |
| `model_id`       | `UUID`             | The Arthur model this metric belongs to                            |
| `metric_name`    | `TEXT`             | The metric identifier                                              |
| `timestamp`      | `TIMESTAMPTZ`      | Start of the 5-minute aggregation window                           |
| `value`          | `DOUBLE PRECISION` | The aggregated numeric value                                       |
| `dimensions`     | `JSONB`            | Key-value dimension slices (may be `{}` for undimensioned metrics) |
| `metric_version` | `INTEGER`          | Schema version (the view filters to the latest)                    |

### `metrics_sketch_latest_version`

Use this view for all **sketch** (distributional) metrics.

| Column           | Type          | Description                                     |
| ---------------- | ------------- | ----------------------------------------------- |
| `model_id`       | `UUID`        | The Arthur model this metric belongs to         |
| `metric_name`    | `TEXT`        | The metric identifier                           |
| `timestamp`      | `TIMESTAMPTZ` | Start of the 5-minute aggregation window        |
| `value`          | `BYTEA`       | Serialized KLL float sketch                     |
| `dimensions`     | `JSONB`       | Key-value dimension slices                      |
| `metric_version` | `INTEGER`     | Schema version (the view filters to the latest) |

> 💡 **Tip:** To discover which metric names are available for a given model, run the discovery queries in [Basic Metric Query Patterns](https://docs.arthur.ai/docs/metrics-basic-queries).