Skip to contents

Set metadata for a snapshot

Source: R/transactions.R
set_snapshot_metadata.Rd

Fills in the author, commit message, and/or extra info of a snapshot in a DuckLake catalog after it was committed, by updating the ducklake_snapshot_changes metadata table directly. The most recent snapshot by default; snapshot_id names another.

Usage

set_snapshot_metadata(
  ducklake_name,
  author = NULL,
  commit_message = NULL,
  commit_extra_info = NULL,
  snapshot_id = NULL,
  conn = NULL,
  overwrite = FALSE
)

Arguments

ducklake_name

The name of the DuckLake catalog

author

Optional author name to associate with the snapshot. The ducklake.author option is not read here: labeling a snapshot after the fact is a deliberate edit, so the author is always spelled out.

commit_message

Optional commit message describing the changes

commit_extra_info

Optional extra information about the commit

snapshot_id

Optional snapshot id (see list_table_snapshots()). NULL, the default, means the most recent snapshot. An id the lake does not have is an error.

conn

Optional DuckDB connection object. If not provided, uses the default ducklake connection.

overwrite

Replace values the snapshot already carries (default FALSE). By default only empty fields are filled in, and the call stops when a supplied field already has a value.

Value

Invisibly returns TRUE on success

Details

Metadata belongs on the commit: pass author, commit_message, and commit_extra_info to with_transaction() or commit_transaction(), which record them through DuckLake's set_commit_message() as part of the transaction itself. This function is the escape hatch for a snapshot that was committed without them, such as one made interactively or by a client that could not set them.

Snapshot 0 is the lake's creation, which DuckLake writes without an author or a message. attach_ducklake() labels it for a lake it creates; for a lake created before that, or attached read-only, pinned to a snapshot, or inside a transaction at the time, pass snapshot_id = 0 here.

It writes to the catalog's metadata table outside DuckLake's transaction and conflict model, and an overwrite leaves no trace of the previous value. That is why it fills blanks only unless overwrite = TRUE. Where the snapshot history is the audit trail (GxP, 21 CFR Part 11), set metadata at commit time and leave overwrite alone. Call it outside a transaction: a DuckDB transaction can write to one attached database, and this one writes to the metadata catalog, so a lake write after it in the same transaction would fail.

See also

Other transactions: begin_transaction(), commit_transaction(), rollback_transaction(), set_ducklake_retry(), with_transaction()

Examples

lake_dir <- tempfile("meta_lake_")
dir.create(lake_dir)
attach_ducklake("meta_lake", lake_path = lake_dir)

begin_transaction()
create_table(mtcars, "cars")
commit_transaction()
#> Committed snapshot 1.

# The snapshot has no author or message yet: fill them in
set_snapshot_metadata(
  ducklake_name = "meta_lake",
  author = "Data Team",
  commit_message = "Added the cars dataset"
)
#> Updated the metadata of snapshot 1.

# A second call refuses to replace them unless told to
try(set_snapshot_metadata("meta_lake", commit_message = "Reworded"))
#> Error in set_snapshot_metadata("meta_lake", commit_message = "Reworded") : 
#>   Snapshot 1 already has commit_message set.
#> ℹ Metadata belongs on the commit: record it with `with_transaction()` or
#>   `commit_transaction()`.
#> ℹ Pass `overwrite = TRUE` to replace it; the previous value is not kept.
set_snapshot_metadata("meta_lake", commit_message = "Reworded", overwrite = TRUE)
#> Updated the metadata of snapshot 1.

# The creation snapshot has the message attach_ducklake() gave it and no
# author yet: name one
set_snapshot_metadata("meta_lake", author = "Data Team", snapshot_id = 0)
#> Updated the metadata of snapshot 0.

detach_ducklake("meta_lake", shutdown = TRUE)
unlink(lake_dir, recursive = TRUE)