Tables

The tables endpoints expose table discovery data from the Postgres-backed table cache and live health analysis from the PyIceberg catalog (Glue/S3).

---

List tables

GET /tables

Returns the current set of tables from the table cache. The cache is periodically refreshed by a background sync worker; see cache status to check freshness.

Query parameters

Parameter	Type	Description
database	string	Filter tables to a single database.
maintenance_enabled	boolean	Filter by opt-in status (true or false).

Response — 200 OK

[
  {
    "database": "analytics",
    "table_name": "page_views"
  },
  {
    "database": "analytics",
    "table_name": "sessions"
  }
]

Each object contains:

Field	Type	Description
database	string	Database name.
table_name	string	Table name within the database.

Status codes

Code	Meaning
200	Success.

Example

# All tables
curl https://snowpack-api.internal/tables

# Only tables in the "analytics" database that are opted in
curl "https://snowpack-api.internal/tables?database=analytics&maintenance_enabled=true"

---

Cache status

GET /tables/cache-status

Returns metadata about the table cache — when it was last refreshed and how many tables it contains. Useful for monitoring staleness.

Response — 200 OK

{
  "last_synced": "2026-04-25T14:32:00.000000+00:00",
  "table_count": 247
}

Field	Type	Description
last_synced	string | null	ISO 8601 timestamp of the last successful sync, or null if never synced.
table_count	int	Number of tables currently in the cache.

Status codes

Code	Meaning
200	Success.

Example

curl https://snowpack-api.internal/tables/cache-status

---

Live table health

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

Performs a live health analysis by loading the table from the PyIceberg catalog (Glue/S3), inspecting its metadata, and computing file statistics, snapshot counts, and recommended maintenance actions. The result is also persisted to the health_snapshots Postgres table for future cached lookups.

This endpoint is slower than the cached variant (seconds vs. milliseconds) but always returns current data.

Path parameters

Parameter	Type	Description
database	string	Database name.
table	string	Table name.

Response — 200 OK

{
  "table": {
    "database": "analytics",
    "table_name": "page_views",
    "location": "s3://lakehouse/analytics/page_views",
    "format_version": 2
  },
  "file_stats": {
    "total_data_files": 1284,
    "total_delete_files": 12,
    "total_size_bytes": 53687091200,
    "avg_file_size_bytes": 41812000,
    "small_file_count": 87,
    "small_file_pct": 6.78
  },
  "snapshot_count": 34,
  "manifest_count": 18,
  "recommended_actions": ["rewrite_data_files", "expire_snapshots"],
  "needs_maintenance": true,
  "maintenance_enabled": true,
  "maintenance_cadence_hours": 24,
  "snowpack_config": {
    "maintenance_enabled": "true",
    "maintenance_cadence_hours": "24"
  },
  "total_records": 5200000,
  "snapshot_id": 7238461923847,
  "hours_since_last_snapshot": 3.2,
  "oldest_snapshot_age_hours": 168.5,
  "health_status": "Degraded",
  "error": null
}

Key response fields:

Field	Type	Description
table	object	Table identity and location.
file_stats	object	File-level metrics (counts, sizes, small file percentage).
snapshot_count	int	Total snapshots retained by the table.
manifest_count	int	Number of manifest files in current metadata.
recommended_actions	string[]	Maintenance actions the analyzer recommends.
needs_maintenance	boolean	true when any metric exceeds its threshold.
maintenance_enabled	boolean|null	Value of the snowpack.maintenance_enabled table property.
maintenance_cadence_hours	int|null	Per-table cadence override, if set.
snowpack_config	object	All snowpack.* table properties as key-value pairs.
health_status	string	Summary label: Healthy, Degraded, or Unknown.
error	string|null	Non-null if analysis encountered a non-fatal error.

Status codes

Code	Meaning
200	Success.
404	Table not found in the catalog.
422	Invalid database or table name (identifier validation).
503	Catalog unavailable or health analysis failed.

Example

curl https://snowpack-api.internal/tables/analytics/page_views/health

---

Cached table health

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

Returns the most recent health_snapshots row from Postgres for the given table. This is the fast path — responses return in roughly 1 ms because no catalog or storage access is required.

Health snapshots are written by two sources:

1. The live health endpoint (above) persists every successful analysis.
2. The background health-sync worker periodically refreshes snapshots for all tables in configured databases.

Path parameters

Parameter	Type	Description
database	string	Database name.
table	string	Table name.

Response — 200 OK

Returns the full health snapshot object as stored in Postgres. The shape mirrors the live health response.

Status codes

Code	Meaning
200	Success.
404	No health snapshot exists for this table.
503	Postgres unavailable.

Example

curl https://snowpack-api.internal/tables/analytics/page_views/health/cached