statementStats

read-onlyany connectionsweeps replication groupsweeps groupcan return data values

Synopsis

statementStats([limit], [min_calls], [order_by], [query_id])

Description

Return tracked queries from pg_stat_statements under 'statements', with calls, timing, row counts, buffer usage, temporary block I/O and WAL volume, alongside an 'info' block from pg_stat_statements_info whose dealloc counter says whether entries are being evicted -- if it is climbing, this is not the slowest queries in the cluster but the slowest of those that survived eviction. query_id is a decimal string, ready to pass to explainQuery.

Returns a clear error with setup instructions if the extension is not installed.

This operation can return values that came from your data. It never changes anything and never returns rows, but read what reaches the caller before connecting it to a database whose contents are sensitive.

Parameters

limit optionalinteger: how many statements to return. Defaults to 20
min_calls optionalinteger: ignore statements called fewer times than this, to keep one-off maintenance queries out of a mean_exec_time ranking
order_by optionalstring: ranking column: total_exec_time (default), mean_exec_time, max_exec_time, calls, rows, shared_blks_read, temp_blks_written, or wal_bytes. Ranking by total time buries a statement called twice at 40s under one called ten million times at 2ms; mean_exec_time is the other question
query_id optionalstring: only statements with this queryid, as a decimal string; their query text is returned whole rather than truncated. pg_stat_statements keeps one entry per user and database, so a queryid can match more than one row

Also accepts connection, replication_group, group, role, described once under arguments every tool takes.

Output

pg_stat_statements rows with the extension's own counters. An absent extension or a missing grant is reported as {error, hint} instead.

Field	Type
info	object \| null
statements	array \| null

Scope

This reading is instance-wide -- every database on the same postmaster returns it identically, so asking each of them in turn repeats one answer. The counters here are each server's own, so members of a replication group legitimately disagree and the answer is their sum, not the primary's copy.

Example mocked data

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "statementStats",
    "arguments": {
      "limit": 2
    }
  }
}

Result

{
  "statements": [
    {
      "query_id": "-6203381990422871044",
      "query": "UPDATE shop.orders SET status = $1 WHERE id = $2",
      "calls": 18244102,
      "total_exec_ms": 9120441.2,
      "mean_exec_ms": 0.5,
      "rows": 18244102,
      "shared_blks_hit": 91220103,
      "shared_blks_read": 12033,
      "user": "app_rw",
      "database": "shop"
    },
    {
      "query_id": "3301928477102934411",
      "query": "SELECT id, status FROM shop.orders WHERE customer_id = $1 ORDER BY created_at DESC LIMIT $2",
      "calls": 4410233,
      "total_exec_ms": 3120982.7,
      "mean_exec_ms": 0.71,
      "rows": 88204660,
      "shared_blks_hit": 402211093,
      "shared_blks_read": 440112,
      "user": "app_rw",
      "database": "shop"
    }
  ],
  "info": {
    "dealloc": 0,
    "stats_reset": "2026-08-01T00:00:00Z"
  }
}

Invented values on a fictional shop database, shaped by and checked against this tool's output schema. Real output is returned as structuredContent to clients that negotiate MCP 2025-06-18 or later.