Replace a table with modified data and create a new snapshot

Replace a table with modified data and create a new snapshot

Usage

replace_table(.data, table_name, .quiet = TRUE)

Arguments

.data

A dplyr query object (tbl_lazy) with transformations

table_name

Table name to replace

.quiet

Logical, whether to suppress messages (default TRUE)

Value

Invisibly returns NULL

Details

This function is designed for schema changes or bulk transformations that should create a new versioned snapshot. It:

1. Collects the transformed data

2. Drops the existing table

3. Creates a new table with the updated schema/data

The drop and create run atomically: when no transaction is open, replace_table() wraps them in one of its own, so a failed create never leaves the table dropped. Wrap the call in with_transaction() (or begin_transaction()/commit_transaction()) when you want to record an author and commit message on the snapshot, or to group the replacement with other changes.

When to use replace_table():

• Bulk transformations - a dplyr pipeline that recomputes, reshapes, or filters most of the table

When to reach elsewhere:

• Schema-only changes - add_table_column(), drop_table_column(), rename_table_column(), and set_column_type() alter the table in place; nothing is collected or rewritten

• Derived columns - add_table_column() followed by a mutate() pipeline through ducklake_exec() fills the new column with an in-database UPDATE

• Targeted row changes - rows_update(), rows_upsert(), or ducklake_exec() modify only the affected rows

Both paths create a snapshot: replace_table() via DROP + CREATE, and ducklake_exec() via the in-place UPDATE/DELETE it runs, so either way the change is available for time travel.

See also

Other table operations: add_data_files(), create_table(), create_view(), drop_view(), ducklake_exec(), get_ducklake_table(), get_metadata_table(), list_ducklake_tables(), show_ducklake_query()

Examples

if (FALSE) { # \dontrun{
# Add new derived columns (atomic on its own; creates a new snapshot)
get_ducklake_table("adsl") |>
  mutate(
    AGE65FL = if_else(AGE >= 65, "Y", "N"),
    AGECAT = case_when(
      AGE < 65 ~ "<65",
      AGE >= 65 & AGE < 75 ~ "65-74",
      AGE >= 75 ~ ">=75"
    )
  ) |>
  replace_table("adsl")

# Wrap in with_transaction() to record audit metadata on the snapshot
with_transaction(
  get_ducklake_table("adsl") |>
    select(-AGE65FL, -AGECAT) |>
    replace_table("adsl"),
  author = "Data Engineer",
  commit_message = "Drop derived age columns"
)
} # }