Checking Table Health

Icepack separates table inspection into three contracts:

• Status answers “what does the table look like right now?”
• Health answers “is anything concerning about that status?”
• Maintenance recommendation answers “should Icepack run maintenance under the configured policy?”

Use the status endpoint for dashboards and IceLens-style raw table facts. Use the health endpoint for issue summaries. Use the recommendation endpoint for scheduler decisions or manual action selection.

Live status

GET /tables/{database}/{table}/status

This endpoint inspects the table through the configured metadata inspector (the base chart/config default is PyIceberg; named deployed environment values set ICEPACK_METADATA_INSPECTOR=iceberg-go) and returns observed Iceberg table state.

curl -s https://<icepack-host>/tables/offer_service/offers/status | jq .

Status includes collection metadata, snapshot facts, file counts and sizes, derived small-file/large-file facts, manifest facts, and partition facts when available. It does not include health status, health issues, policy fields, or recommended actions.

Live status and health reads are side-effect-free (DL-515): they never write status or health snapshots to Postgres. Cached and fleet-wide reads live in the IceLens API; Icepack’s recommendation endpoint consumes IceLens cached status server-side.

Live health

GET /tables/{database}/{table}/health

This endpoint collects live status once, assesses health, and returns only the health assessment. Excerpt:

{
  "health_status": "Warning",
  "issues": [
    {
      "code": "small_files",
      "severity": "warning",
      "message": "Table has 847 files below the small-file threshold.",
      "evidence": {
        "small_file_count": 847,
        "small_file_pct": 65.97
      }
    }
  ],
  "collection": {
    "source": "live",
    "stale": false,
    "warnings": []
  },
  "error": null
}

The live health endpoint is read-only: it inspects the table and returns the assessment without persisting anything (DL-515).

Maintenance recommendation

GET /tables/{database}/{table}/maintenance/recommendation

This endpoint returns policy-aware action intent. It is the only read endpoint that returns recommended_actions. Excerpt:

{
  "recommended_actions": [
    "expire_snapshots",
    "remove_orphan_files",
    "rewrite_data_files"
  ],
  "skip_reasons": [],
  "policy": {
    "maintenance_enabled": true,
    "opt_in_mode": false,
    "maintenance_cadence_hours": 24,
    "effective_cadence_hours": 24,
    "icepack_config": {
      "maintenance_enabled": "true",
      "maintenance_cadence_hours": "24"
    }
  },
  "history": {
    "last_completed_at": null,
    "cadence_elapsed": true
  },
  "evidence": {
    "rewrite_data_files": {
      "small_file_count": 847,
      "min_input_files": 5
    }
  },
  "error": null
}

If neither IceLens cached status nor live inspection yields a usable status, the recommendation endpoint returns 200 OK with no actions, skip_reasons: ["status_unavailable"], and error populated. That lets callers distinguish “cannot evaluate” from skip_reasons: ["no_action_needed"].

Error responses

Common live-read errors:

• 404 — Table not found.
• 422 — Invalid identifier or unsupported Iceberg schema type.
• 503 — Catalog unavailable or metadata inspection failed.

Field ownership

Field family	Endpoint
Raw file, snapshot, manifest, partition, and freshness facts	/status
health_status, issues, and issue evidence	/health
Maintenance enrollment, cadence, policy, history, recommended_actions, and skip_reasons	/maintenance/recommendation

Root /metrics remains the Prometheus/OpenMetrics endpoint for Icepack operational metrics. It is not a table-status API.