Checking Table Health

Snowpack exposes two endpoints for inspecting the health of an Iceberg table. Use the live endpoint when you need a real-time assessment. Use the cached endpoint when you need a fast, low-cost lookup — for example in dashboards or automated checks.

Live health check

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

This endpoint loads the table directly from the PyIceberg catalog (backed by AWS Glue and S3), analyzes its metadata, and returns a full health report. The call typically takes a few seconds depending on the size of the table’s metadata.

curl -s https://<snowpack-host>/tables/offer_service/offers/health | jq .

The live endpoint also saves the result as a health snapshot in Postgres, so subsequent cached lookups reflect the latest state.

Cached health check

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

This endpoint returns the most recent health snapshot from Postgres. It is near-instant (~1ms) because it performs a single database read with no catalog or S3 interaction. Health snapshots are collected automatically by the health-sync CronJob every 15 minutes.

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

Error responses:

404 — No health snapshot exists for this table. This happens when the table has not yet been assessed by health-sync, or when it is not included in healthSync.databases in the Helm values.
503 — Postgres is unavailable. The API cannot serve cached data when the database connection is down.

Response format

Both endpoints return a JSON object with the same shape. Here is an annotated example:

{
  "table": {
    "database": "offer_service",
    "table_name": "offers",
    "location": "s3://lakehouse-dev/offer_service/offers",
    "format_version": 2
  },
  "file_stats": {
    "total_data_files": 1284,
    "total_delete_files": 12,
    "total_size_bytes": 8741625856,
    "avg_file_size_bytes": 6807340,
    "small_file_count": 847,
    "small_file_pct": 65.97
  },
  "snapshot_count": 142,
  "manifest_count": 38,
  "total_records": 52491000,
  "snapshot_id": 7289345612038475000,
  "hours_since_last_snapshot": 1.2,
  "oldest_snapshot_age_hours": 720.5,
  "health_status": "Unhealthy",
  "needs_maintenance": true,
  "maintenance_enabled": true,
  "maintenance_cadence_hours": 6,
  "recommended_actions": [
    "rewrite_data_files",
    "expire_snapshots",
    "rewrite_manifests"
  ],
  "snowpack_config": {
    "maintenance_enabled": "true",
    "maintenance_cadence_hours": "6"
  },
  "error": null
}

Field reference

file_stats — Statistics about the table’s data files:

Field	Description
`total_data_files`	Total number of data files across all partitions.
`total_delete_files`	Number of position-delete files pending compaction.
`total_size_bytes`	Combined size of all data files in bytes.
`avg_file_size_bytes`	Mean data file size. Iceberg targets ~128 MB per file; values far below this indicate a small-file problem.
`small_file_count`	Number of data files smaller than the small-file threshold (default: 32 MB).
`small_file_pct`	Percentage of data files classified as small. A high percentage (above ~30%) typically triggers a `rewrite_data_files` recommendation.

Top-level fields:

Field	Description
`snapshot_count`	Number of Iceberg snapshots retained. Excess snapshots inflate metadata size and slow planning.
`manifest_count`	Number of manifest files. Redundant manifests slow file planning in queries.
`total_records`	Approximate row count across all data files.
`snapshot_id`	The current snapshot ID of the table.
`hours_since_last_snapshot`	Hours elapsed since the most recent snapshot was created.
`oldest_snapshot_age_hours`	Age of the oldest retained snapshot in hours.
`health_status`	Summary label: `Healthy`, `Unhealthy`, or `Unknown`.
`needs_maintenance`	`true` when at least one threshold is breached and maintenance is warranted.
`maintenance_enabled`	Whether the table has opted into automated maintenance via the `snowpack.maintenance_enabled` table property. `null` if the property is not set.
`maintenance_cadence_hours`	Per-table cadence override, or `null` if using the cluster default.
`recommended_actions`	Ordered list of maintenance actions Snowpack recommends, based on current thresholds.
`snowpack_config`	All `snowpack.*` table properties with the prefix stripped. Useful for debugging opt-in status and overrides.
`error`	`null` on success. Contains an error message if the health analysis failed for this table.