Skip to content
Icepack

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.

Terminal window
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.

Cached status

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

This endpoint returns the latest successful status payload from Postgres. It is near-instant because it performs a database read with no catalog or S3 interaction. The response sets source: "cached", recomputes stale, and may include last_error when a newer status collection failed.

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

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 also saves the status payload and health assessment in Postgres, so later cached reads can reuse the same table state.

Cached health

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

This endpoint returns the latest health assessment from Postgres. It is the right path for dashboards and periodic checks that do not need a fresh metadata scan.

Terminal window
curl -s https://<icepack-host>/tables/offer_service/offers/health/cached | jq .

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 status cannot be collected and no usable cached status exists, 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 cached-read errors:

  • 404 — No cached status or health assessment exists for this table yet.
  • 503 — Postgres is unavailable.

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 familyEndpoint
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.