DuckLake database utility functions — ducklake_db

A set of utility functions for working with ducklake_db.

Usage

as_ducklake_db_t(
  x,
  class_name = character(),
  key_cols = NULL,
  alternate_key_cols = NULL,
  map_cols = NULL,
  partition_cols = NULL
)

read_sql(file)

serialize_metadata(metadata)

deserialize_metadata(comment)

convert_list_cols(x, cols, fn)

list_to_kv_df(x)

kv_df_to_list(x)

create_table_binding(
  table_name,
  mode = c("write_once", "upsert", "append", "overwrite")
)

create_method_binding(fun, with_private = FALSE, with_super = FALSE)

Arguments

class_name: Optional class name to prepend before "ducklake_db_t". Used to create more specific subclasses.
key_cols: Optional character vector. Used for data.table's data.table::setkey and used by ducklake_db to determine which columns to use for upsert operations. Together with alternate_key_cols, these are used to define uniqueness constraints.
alternate_key_cols: Optional character vector. These are used in conjunction with key_cols to define uniqueness constraints, but are not used for upsert operations. Example: numeric primary key whose distinctness is identical to a character primary key column, but upsert operations should be based on the character key, leaving the character<->numeric mapping intact.
map_cols: Optional character vector. Used to coerce columns to DuckDB's MAP type, used to store named unnested lists from R.
partition_cols: Optional character vector. Used to specify columns for hive style partitioning of the data files.
file: Name of a SQL file in the installed package.
metadata: Named list of atomic vectors.
comment: Character scalar, or NA for a table without metadata.
cols: The list columns to convert.
fn: The function to apply to each element of the list columns
table_name: The name of the table to bind to.
mode: The mode of the binding, which determines the behavior when committing data. Options are: "write_once" (default, only allows writing if table doesn't exist), "upsert", "append", and "overwrite".
fun: The underlying function to bind as an R6 method, which must have a self argument
with_private: Whether to also pass the R6 reference to private as an argument
with_super: Whether to also pass the R6 reference to super as an argument

Functions

as_ducklake_db_t(): Coerce to ducklake_db_t subclass. It coerces an object to a data.table and adds attributes that ducklake_db relies on for database-like operations. See the paramaters for details.
read_sql(): Read one of the package's inst/*.sql files, for passing to $get_query() – which interpolates it, so the placeholders in the file are filled from the named arguments given alongside it.
serialize_metadata(): Serialize a named list of atomic vectors into the single string that ducklake_db stores as a comment on the catalog table. Each entry becomes one line, key: "value1", "value2".
deserialize_metadata(): Recover the named list written by serialize_metadata(). Values are type-converted, so that a numeric attribute survives the round-trip as a number rather than as a string.
convert_list_cols(): Convert list columns by applying fn
list_to_kv_df(): Convert a named list to a data.frame with "key" and "value" columns.
kv_df_to_list(): Convert a data.frame with "key" and "value" columns to a named list.
create_table_binding(): Create a binding function for a table, which can be used to fetch or commit data to that table. The active binding either returns the table (missing argument), or upserts to it (assignment operation)
create_method_binding(): Helper function to bind a function as a method to an R6 generator. Simply passes the R6 method's arguments as-is to the underlying "pure" function, passing the R6 reference to self, but not to private.