---
title: "Insights"
description: "Query-level analytics for a project. Top query shapes by call count, with cache hit rate and latency for each, plus aggregate cache and latency summaries."
canonical: "https://pgbeam.com/docs/insights"
last-updated: "2026-10-08T10:00:49.000Z"
---

# Insights

> Query-level analytics for a project. Top query shapes by call count, with cache hit rate and latency for each, plus aggregate cache and latency summaries.

URL: https://pgbeam.com/docs/insights

Insights shows what your project's traffic actually looks like. It groups statements by normalized shape, ranks them by call count, and reports the cache hit rate and latency for each shape. Alongside the per-query breakdown it gives you two aggregate summaries: overall cache performance and overall latency for the window you pick. Use it to find the queries worth caching, spot a shape whose latency has crept up, and see how much the cache is saving you.

## Read insights

Open the **Observability** page for a project. It shows the cache hit rate,
average latency, and P99 latency for the selected window, then a sortable
table of the top query shapes. Switch the time range between 1h, 6h, 24h, and
7d.

## Time range and limit

Two query parameters shape the response:

Parameter

Values

Default

Description

`range`

`1h`, `6h`, `24h`, `7d`

`24h`

Time window the metrics are computed over.

`limit`

`1` to `100`

`20`

Maximum number of top query shapes to return.

The CLI exposes `--range`; the dashboard exposes the same windows as buttons.

## What you get back

The response has three parts: a list of top query shapes, a cache summary, and a latency summary.

## Top queries

Each entry in `queries` is one normalized query shape, so `WHERE id = 1` and `WHERE id = 2` count as the same shape. Entries are ranked by call count.

Field

Description

`query_hash`

Hash of the normalized SQL pattern.

`query_pattern`

The normalized SQL, truncated to 500 characters.

`total_count`

Executions in the time range.

`total_cache_hits`

Cache hits attributed to this shape.

`total_cache_misses`

Cache misses attributed to this shape.

`avg_latency_ms`

Average latency for this shape, in milliseconds.

`p99_latency_ms`

P99 latency for this shape, in milliseconds.

## Cache summary

Aggregate cache performance across all queries in the window.

Field

Description

`total_hits`

Total cache hits in the window.

`total_misses`

Total cache misses in the window.

`hit_rate`

Hit rate as a fraction from `0.0` to `1.0`.

## Latency summary

Aggregate latency across all queries in the window.

Field

Description

`avg_ms`

Average latency in milliseconds across queries.

`p99_ms`

P99 latency in milliseconds across queries.

## How to read it

A shape with a high `total_count` and a low `total_cache_hits` is a caching opportunity. Add a cache annotation and watch the hit rate climb on the next scan.

A shape whose `p99_latency_ms` is far above its `avg_latency_ms` has a tail worth investigating: a missing index, a lock, or an occasional large result.

A `hit_rate` that drops after a deploy usually means a query shape changed and the old cache entries no longer match.

## Related

Caching: the feature these hit-rate numbers measure.

Audit log: per-statement detail behind the aggregates.

Anomaly detection: alerts when a credential's traffic drifts from its baseline.