Skip to content
Snowpack

Quick Start

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

1. Opt your table in

In a Spark SQL session, enable Snowpack maintenance for your table:

ALTER TABLE lakehouse_dev.my_database.my_table
  SET TBLPROPERTIES ('snowpack.maintenance_enabled' = 'true');

Replace my_database.my_table with your actual database and table name. This tells Snowpack that the table is eligible for maintenance.

2. Request the database allowlist addition

Ask the Data Platform team to add your database to the orchestrator allowlist. This is a one-time change to the Helm values — once the database is listed, every opted-in table in that database will be picked up by the automated CronJob.

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

3. Check table health

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

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

The response includes metrics like small file count, snapshot count, and whether the table needs_maintenance. Use the /health/live endpoint instead if you need real-time data directly from the catalog (slower, but always current).

4. Submit a manual maintenance job

Trigger maintenance for specific actions:

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

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://snowpack-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 opted-in tables, checks their health, and submits maintenance jobs on a schedule.

For deeper coverage, see the Guides section.