Import snapshot bars from CSV — ledgr_snapshot_import_bars

Imports EOD bars into snapshot_bars for a snapshot in status CREATED (snapshot mutability rule). Optionally imports instruments from CSV, or auto-generates them from bars.

Usage

ledgr_snapshot_import_bars_csv(
  con,
  snapshot_id,
  bars_csv_path,
  instruments_csv_path = NULL,
  auto_generate_instruments = TRUE,
  encoding = "UTF-8",
  validate = c("fail_fast", "none")
)

Arguments

con: A DBI connection to DuckDB.
snapshot_id: Snapshot id (must exist and be status CREATED).
bars_csv_path: Path to bars CSV.
instruments_csv_path: Optional path to instruments CSV.
auto_generate_instruments: If TRUE and instruments_csv_path is NULL, auto-generate instruments from bars.
encoding: File encoding (default "UTF-8").
validate: Validation mode (default "fail_fast").

Value

Invisibly returns TRUE on success.

Details

CSV contract:

Required columns: instrument_id, ts_utc, open, high, low, close
Optional columns: volume (defaults to NA)
Timestamp format: ISO8601 UTC with trailing Z, e.g. 2020-01-01T00:00:00Z
Encoding: UTF-8 (BOM tolerated and stripped)
Rounding: OHLCV are rounded to 8 decimals on import
Extra columns: ignored; only canonical bar columns are persisted and hashed

Errors:

LEDGR_SNAPSHOT_NOT_FOUND if snapshot_id does not exist.
LEDGR_SNAPSHOT_NOT_MUTABLE if snapshot status is not CREATED.
LEDGR_CSV_FORMAT_ERROR on CSV contract/parse violations or duplicate PKs.

CSV and OHLC errors are import/seal errors. They occur before a snapshot can be loaded into an experiment or executed by a strategy.

Low-level CSV lifecycle

Most users should prefer ledgr_snapshot_from_csv(). Use ledgr_snapshot_import_bars_csv() directly only when you need to control the create/import/seal lifecycle yourself:

create the snapshot envelope with ledgr_snapshot_create();
import bars into that CREATED snapshot;
seal it with ledgr_snapshot_seal() to validate bars and write the snapshot hash;
inspect metadata with ledgr_snapshot_info() if needed;
disconnect the write connection and reopen with ledgr_snapshot_open(..., verify = TRUE);
pass the loaded snapshot to ledgr_experiment() and ledgr_run().

bar_count and instrument_count are live counts from the sealed snapshot tables. The raw meta_json is envelope metadata on the snapshot row; seal-time metadata inside it uses n_bars and n_instruments. Snapshot identity does not come from that metadata. snapshot_hash identifies the normalized bars and instruments only.

Articles

Durable experiment stores: vignette("experiment-store", package = "ledgr") system.file("doc", "experiment-store.html", package = "ledgr")

Examples

db_path <- tempfile(fileext = ".duckdb")
con <- ledgr_db_init(db_path)
snapshot_id <- ledgr_snapshot_create(
  con,
  snapshot_id = "snapshot_20200101_000000_abcd"
)
bars_csv <- tempfile(fileext = ".csv")
utils::write.csv(data.frame(
  instrument_id = "AAA",
  ts_utc = c("2020-01-01T00:00:00Z", "2020-01-02T00:00:00Z"),
  open = c(100, 101),
  high = c(101, 102),
  low = c(99, 100),
  close = c(100, 101),
  volume = 1000
), bars_csv, row.names = FALSE)
ledgr_snapshot_import_bars_csv(con, snapshot_id, bars_csv)
snapshot_hash <- ledgr_snapshot_seal(con, snapshot_id)
snapshot_info <- ledgr_snapshot_info(con, snapshot_id)
DBI::dbDisconnect(con, shutdown = TRUE)

snapshot <- ledgr_snapshot_open(
  db_path,
  snapshot_id = snapshot_id,
  verify = TRUE
)
snapshot_hash
#> [1] "cdce2950fdab774786acf556eb1f8f76ccc2c932afc2e2a2e6e02358f13d2d94"
snapshot_info[
  ,
  c("snapshot_id", "status", "snapshot_hash", "bar_count", "instrument_count")
]
#> # A tibble: 1 × 5
#>   snapshot_id                   status snapshot_hash  bar_count instrument_count
#>   <chr>                         <chr>  <chr>              <int>            <int>
#> 1 snapshot_20200101_000000_abcd SEALED cdce2950fdab7…         2                1
ledgr_snapshot_close(snapshot)