Skip to content
Icepack

Quick Start

This guide walks you through opting a table into Icepack and running your first maintenance job. You will need Spark SQL access and curl.

1. Confirm your database is in scope

Icepack maintains tables by default. If your table’s database is on the orchestrator allowlist, the table is already eligible — no per-table action is needed. Ask the Data Platform team whether your database is allowlisted, or request that it be added (a one-time change to the Helm values).

Until the database is allowlisted, you can still run maintenance manually (steps 4-5).

2. (Optional) Opt a table out

If you do not want a table maintained automatically, opt it out explicitly:

ALTER TABLE lakehouse_dev.my_database.my_table
  SET TBLPROPERTIES ('icepack.maintenance_enabled' = 'false');

Use compaction_skip = 'true' instead to hard-exclude a table from all maintenance (for example, during a migration).

3. Check table health

Verify that Icepack can see your table and inspect its current health:

Terminal window
curl https://icepack-api.internal/tables/my_database/my_table/health/cached

The response includes health_status and any health issues. Use /tables/my_database/my_table/status when you need raw metrics like file counts or snapshot counts, and use /tables/my_database/my_table/health when you need a fresh live assessment.

To ask Icepack which actions it would run under current policy:

Terminal window
curl https://icepack-api.internal/tables/my_database/my_table/maintenance/recommendation

4. Submit a manual maintenance job

Trigger maintenance for specific actions:

Terminal window
curl -X POST https://icepack-api.internal/tables/my_database/my_table/maintenance \
  -H "Content-Type: application/json" \
  -d '{"actions": ["expire_snapshots", "remove_orphan_files", "rewrite_data_files"]}'

The API returns 202 Accepted with a job ID:

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending"
}

You can request any combination of the five maintenance actions. See Key Concepts for the full list and execution order.

5. Monitor the job

Poll the job endpoint to track progress:

Terminal window
curl https://icepack-api.internal/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890

The response includes the current status (pending, running, completed, failed, or cancelled) and details for each action.

Once your database is allowlisted, the orchestrator CronJob handles all of this automatically — it discovers eligible tables, calls the maintenance recommendation endpoint, and submits maintenance jobs on a schedule.

For deeper coverage, see the Guides section.