Table Row Estimates

GET /admin/clients/{client_name}/table-row-estimates runs a read-only catalog query against Postgres and returns approximate row counts from pg_class.reltuples.

Use this when you want a fast “which tables are biggest?” view for dashboards, health panels, or admin tooling without issuing COUNT(*) across every table.

What It Returns

snapshot.summary rolls up total inventoried tables, non-zero tables, the estimated total rows, and the heaviest table.
snapshot.top_tables returns the largest tables first, capped by limit.
snapshot.schema_rollups aggregates row estimates by schema.
snapshot.buckets groups tables into size bands so UI charts can show distribution quickly.
snapshot.advisories highlights likely storage-pressure culprits, including Athena-managed gateway log tables and very large 10M+ row tables.

Cache Behavior

Athena caches the full response through the shared response cache used by other read-heavy routes:

In-process cache on the node
Redis when configured
Cache-Control: no-cache bypasses the cache and forces a fresh snapshot

Responses also include cache headers such as X-Athena-Cached, X-Athena-Cache-Key, X-Athena-Cache-Outcome, and X-Athena-Cache-Source.

These counts are estimates, not exact totals. PostgreSQL updates pg_class.reltuples from ANALYZE, autovacuum, and planner statistics refreshes, so freshly mutated tables can lag behind reality.

For exact totals on a single table, use the cached POST /query/count route instead.

If Postgres logs show errors like could not extend file ... No space left on device against gateway_request_log or gateway_operation_log, those are Athena gateway telemetry tables rather than internal Postgres logs. The advisories in this endpoint flag them directly and point back to gateway.log_retention_secs (default 1209600, or 14 days).

Query Parameters

schema: optional exact schema filter
limit: max number of heavy tables returned in snapshot.top_tables
include_system_schemas: include pg_catalog, information_schema, pg_toast, and temp schemas

Example

curl -X GET \
  "http://localhost:4052/admin/clients/athena_logging/table-row-estimates?limit=12" \
  -H "x-athena-admin-key: $ATHENA_KEY_12"

{
  "status": "success",
  "message": "Loaded table row estimates",
  "data": {
    "client_name": "athena_logging",
    "schema": null,
    "limit": 12,
    "include_system_schemas": false,
    "snapshot": {
      "source": "pg_class.reltuples",
      "collected_at": "2026-06-10T12:00:00Z",
      "summary": {
        "table_count": 42,
        "nonzero_table_count": 31,
        "estimated_total_rows": 9123456,
        "max_estimated_rows": 4200000,
        "max_table_name": "gateway_request_log",
        "max_qualified_table_name": "public.gateway_request_log"
      },
      "top_tables": [
        {
          "schema_name": "public",
          "table_name": "gateway_request_log",
          "qualified_table_name": "public.gateway_request_log",
          "estimated_rows": 4200000
        }
      ],
      "schema_rollups": [
        {
          "schema_name": "public",
          "table_count": 17,
          "estimated_rows": 6500000
        }
      ],
      "buckets": [
        {
          "label": "1M-9.9M",
          "min_rows": 1000000,
          "max_rows": 9999999,
          "table_count": 3
        }
      ],
      "advisories": [
        {
          "code": "gateway-log-retention",
          "severity": "warn",
          "title": "Gateway log tables are likely driving storage pressure",
          "message": "Athena writes request and operation telemetry into these tables. If disk-full errors reference them, tighten `gateway.log_retention_secs` or prune old rows before inserts stall.",
          "affected_tables": [
            {
              "schema_name": "public",
              "table_name": "gateway_request_log",
              "qualified_table_name": "public.gateway_request_log",
              "estimated_rows": 4200000
            }
          ],
          "affected_estimated_rows": 4200000,
          "share_of_estimated_total_pct": 46.0,
          "config_key": "gateway.log_retention_secs",
          "config_default_seconds": 1209600
        }
      ]
    }
  }
}

Reference

GET /admin/clients/:client_name/table-row-estimates