tableIOStats

Return per-object buffer cache hit ratios (pg_statio_all_tables): heap_blks_read versus heap_blks_hit, idx_blks_read versus idx_blks_hit, the TOAST and TOAST-index pairs, and a combined ratio, with relation size and scan counts.

read-onlyany connectionsweeps instancesweeps replication groupsweeps group

Synopsis

tableIOStats(schema, [limit], [table])

Description

Return per-object buffer cache hit ratios (pg_statio_all_tables): heap_blks_read versus heap_blks_hit, idx_blks_read versus idx_blks_hit, the TOAST and TOAST-index pairs, and a combined ratio, with relation size and scan counts. Naming a single table adds a per-index breakdown from pg_statio_all_indexes. Ratios are null, not zero, for an object that has seen no reads at all. Not to be confused with tableStats, which reports pg_stat_user_tables -- scans, tuples and vacuum state; this tool answers only whether those reads came from the buffer cache or the disk.

Parameters

schema requiredstring

limit optionalinteger

how many tables to return, most physical reads first. Defaults to 20

table optionalstring

a single table; omit to sweep the schema. Only a named table gets the per-index breakdown

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

Output

Keyed by schema-qualified table name; each value is its buffer cache hit ratios and scan counts. An absent extension or a missing grant is reported as {error, hint} in place of the map.

Scope

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": "tableIOStats",
    "arguments": {
      "schema": "shop",
      "limit": 1
    }
  }
}

Result

{
  "shop.orders": {
    "heap_blks_read": 402211,
    "heap_blks_hit": 1802201133,
    "heap_hit_percent": 99.98,
    "idx_blks_read": 12033,
    "idx_blks_hit": 902211044,
    "idx_hit_percent": 99.99,
    "seq_scan": 41,
    "idx_scan": 9832117
  }
}

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.

See also

diskUsage, databaseSize, serverSettings, currentActivity, currentLocks, databaseStats, statementStats, wraparoundStatus, progressStats, ioStats, checkpointStats, hostCapacity, bufferCacheSummary, bufferCacheContents