Janitor overview
Janitor runs maintenance on your Lakehouse tables on a schedule. It compacts small files, removes old snapshots, and cleans up unused files, so queries stay fast and storage stays small.
You set safe defaults once. Then you create a job for each table you want to maintain, and you can run, deactivate, or change it.
What maintenance does
Janitor has three maintenance options. You turn them on or off in the defaults, and you can change them for each job.
| Option | What it does | On by default |
|---|---|---|
| OPTIMIZE | Rewrites many small data files into fewer, larger ones. Queries read fewer files and run faster. | Yes |
| EXPIRE SNAPSHOTS | Removes snapshots older than the retention period. This keeps the table history short. | Yes, 7 days |
| ORPHAN CLEANUP | Removes files in storage that no snapshot uses anymore, for example files left by a failed write. | No, 7 days |
ORPHAN CLEANUP cannot be undone. It only removes files older than the retention period. Turn it on only after you check the retention.
After EXPIRE SNAPSHOTS runs, the removed snapshots no longer appear in Time Machine. Keep the retention long enough for the history you need.
How it works
- Set the defaults on the Settings page: schedule, maintenance window, how many runs can work at the same time, and the maintenance options.
- Create a job for each table you want to maintain. A new job takes the defaults. You can change its schedule and options later.
- Wait for the schedule, or select Run to start a run now. At the scheduled time, Janitor starts a run for the job.
- Check the result in Run history. A run has steps, one for each part of the maintenance.
Only one run can work on a job at a time. By default, only one run works in the whole Lakehouse at a time, so maintenance does not overload the Lakehouse.
If maintenance is down for a while, Janitor skips the runs it missed. It starts again at the next scheduled time. To catch up, start a run with Run.
What Janitor never does
- Janitor never changes, adds, or deletes the rows in your tables.
- Janitor never drops or empties a table.
- You cannot send your own SQL through Janitor. It only runs its fixed maintenance steps.
Which tables work
Janitor works with tables in the Lakehouse table format, which keeps snapshots. Views and tables in other formats do not appear in Janitor.
Where to find it
In the sidebar, open Janitor. It has three pages:
| Page | What you do there |
|---|---|
| Maintenance Jobs | Create jobs, run them, and change their schedule and options. |
| Run history | Check the result of every run and stop a run. |
| Settings | Set the defaults and pause or resume all maintenance. |
What you can do
| Task | Page |
|---|---|
| Set the defaults | Configure default maintenance settings |
| Create jobs and change them | Create and manage maintenance jobs |
| Check and start a run, or unblock a stuck job | Run maintenance manually |
| Find out why a run failed, or stop it | View run history and stop a run |
| Stop all maintenance for a while | Pause and resume all maintenance |
Who can use Janitor
| Permission | Lets you |
|---|---|
maintenance:read | View jobs, runs, step details, and settings. Check a run with Dry run. |
maintenance:manage | Everything else: create and change jobs, start and stop runs, change settings, pause and resume. |
See Janitor permissions and input rules and Portal roles and permissions.