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.

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.

Show insights for the last 24 hours

pgbeam analytics insights

# Narrow or widen the window
pgbeam analytics insights --range 1h
pgbeam analytics insights --range 7d

# Machine-readable output
pgbeam analytics insights --json

Get insights (REST)

curl "https://api.pgbeam.com/v1/projects/{projectId}/insights?range=7d&limit=50" \
  -H "Authorization: Bearer $PGBEAM_TOKEN"

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.

ProjectInsights

{
  "queries": [
    {
      "query_hash": "3fa1c0b2d4e5f678",
      "query_pattern": "SELECT * FROM orders WHERE id = $1",
      "total_count": 18422,
      "total_cache_hits": 17110,
      "total_cache_misses": 1312,
      "avg_latency_ms": 2.4,
      "p99_latency_ms": 11.8
    }
  ],
  "cache": {
    "total_hits": 90233,
    "total_misses": 12904,
    "hit_rate": 0.875
  },
  "latency": {
    "avg_ms": 3.1,
    "p99_ms": 22.5
  }
}

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.

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.

Insights

On this page