Skip to contents

Native workflow values

Source: R/values.R
ca_values.Rd

Inputs, results and checkpoint values are stored as DuckDB VARIANT values, queryable with field access, variant_extract() and casts. An R type descriptor stored beside each value records what SQL cannot: NULL versus a typed NA, vector versus list, data frame versus named list, and names, factor levels, time zones, row names and I() wrappers.

Details

Supported values are NULL; logical, integer, double, character and raw vectors; Date, POSIXct, difftime, factors, ordered factors and bit64::integer64; and lists and ordinary data frames composed of those. They map as:

  • length-one logical, integer, double and character values to the matching DuckDB scalar type, and longer vectors to typed lists;

  • raw vectors to BLOB, Date to DATE, POSIXct to TIMESTAMPTZ, difftime to INTERVAL, factors to VARCHAR, and integer64 to BIGINT;

  • named lists and data frames to objects, unnamed lists to arrays.

Timestamps and durations are rounded to DuckDB microsecond precision and must be finite or missing; dates must be whole finite days or missing. Double infinities and NaN survive, and factor levels must not be missing. Names of list elements and data frame columns become STRUCT fields, so they must be nonempty and unique ignoring ASCII case: A and a cannot share a container. Atomic vector names are unrestricted.

Anything else, including custom classes, matrices, environments and language objects, needs explicit conversion. The package never serializes objects for you, nor downloads extensions to convert them: store your own bytes as a raw vector and decode them in the handler, deserializing only trusted payloads. See vignette("serialized-values"). The mappings follow the declared-type approach of Rducks, which is not a dependency.

Values are read back through descriptor-typed projections rather than the driver's generic VARIANT decoder; vignette("native-values") explains why and lists the driver defects involved. Files need DuckDB storage compatibility v1.5.0. There is no package byte limit, though engine memory, disk and transport still apply.

An unsupported value raises canard_value_error, a canard_input_error carrying the conversion failure in parent. A step callback returning one has failed, and no checkpoint is saved for it.