Runs DuckLake's maintenance operations on the catalog in one call: flushes inlined data, merges small files, rewrites heavily deleted files, and, when the lake carries a retention policy, expires old snapshots and deletes the files they released.
Details
CHECKPOINT runs, in order, the equivalents of flush_inlined_data(),
expire_snapshots(), merge_adjacent_files(), rewrite_data_files(),
cleanup_old_files(), and delete_orphaned_files(). The two retention
steps do nothing until the lake carries a policy: snapshots are expired
only when the expire_older_than option is set, and released files are
deleted only when delete_older_than is set. A lake with neither keeps
every snapshot and every file however often it is checkpointed.
A typical policy, set once with set_ducklake_option() and persisted in
the catalog:
set_ducklake_option("expire_older_than", "90 days")
set_ducklake_option("delete_older_than", "7 days")Run checkpoints periodically (e.g., after a batch of streaming inserts) to consolidate inlined data and keep query performance optimal.
Note
On Windows with a DuckDB-file catalog, the file-cleanup step of
CHECKPOINT can fail because Windows does not allow the catalog file to
be opened a second time while the lake is attached (a current DuckDB
limitation). flush_inlined_data() is unaffected; on Windows, prefer it
for routine use and run full checkpoints from a fresh session, or use a
PostgreSQL/SQLite catalog.
See also
flush_inlined_data(), set_ducklake_option(),
expire_snapshots()
Other data inlining:
flush_inlined_data(),
get_inlining_row_limit(),
set_inlining_row_limit()
Other maintenance:
backup_ducklake(),
cleanup_old_files(),
delete_orphaned_files(),
expire_snapshots(),
flush_inlined_data(),
get_table_info(),
list_ducklake_files(),
merge_adjacent_files(),
plot_table_files(),
rewrite_data_files()
Examples
lake_dir <- tempfile("checkpoint_lake_")
dir.create(lake_dir)
attach_ducklake("checkpoint_lake", lake_path = lake_dir)
create_table(mtcars, "cars")
# Run all maintenance
checkpoint_ducklake()
#> Checkpoint completed for "checkpoint_lake".
# Or specify a named lake
checkpoint_ducklake("checkpoint_lake")
#> Checkpoint completed for "checkpoint_lake".
detach_ducklake("checkpoint_lake", shutdown = TRUE)
unlink(lake_dir, recursive = TRUE)