rduckhts_bcf: Create VCF/BCF Table

In Rduckhts: 'DuckDB' High Throughput Sequencing File Formats Reader Extension

Create VCF/BCF Table

Description

Creates a DuckDB table from a VCF or BCF file using the DuckHTS extension. This follows the RBCFTools pattern of creating a table that can be queried.

Usage

rduckhts_bcf(
  con,
  table_name,
  path,
  region = NULL,
  index_path = NULL,
  tidy_format = FALSE,
  additional_csq_column_types = NULL,
  scan_mode = NULL,
  decompression_threads = 0,
  decode_error_policy = "null",
  overwrite = FALSE,
  samples = NULL,
  regions_var = NULL,
  include_file_offset = FALSE
)

Arguments

con	A DuckDB connection with DuckHTS loaded
table_name	Name for the created table
path	Path to the VCF/BCF file
region	Optional genomic region (e.g., "chr1:1000-2000")
index_path	Optional explicit path to index file (.csi/.tbi)
tidy_format	Logical. If TRUE, FORMAT columns are returned in tidy format
additional_csq_column_types	Optional bcftools-style 'PATTERN TYPE' overrides for CSQ/ANN/BCSQ subfield typing, separated by newlines or ';'
scan_mode	Optional scan mode. Use "auto" (default extension behavior) or "sequential" to force full-file streaming instead of index-backed count/parallel scan paths. Sequential mode is incompatible with 'region'.
decompression_threads	Integer. Number of htslib decompression worker threads per file handle. Default '0'. Use '0' to keep BCF/VCF reads single-threaded.
decode_error_policy	Character. VCF/BCF decode policy: "null" returns NULL for header-vs-payload type clashes or oversized numeric scalars, "warn" emits a DuckHTS warning and returns NULL, and "error" raises a DuckDB/R error. Missing elements count toward scalar cardinality; vector-end padding does not. A malformed FORMAT tag is withheld for every selected sample on that record. Physical read errors and OOM always fail.
overwrite	Logical. If TRUE, overwrites existing table
samples	Optional HTSlib sample selector: 'NULL' or '"-"' keeps all, '""' keeps none, comma-separated names include samples, and a leading '"^"' excludes them. Unknown names error; selected samples retain header order.
regions_var	Optional name of a session variable on 'con' that holds typed intervals, 'STRUCT(chrom VARCHAR, start BIGINT, "end" BIGINT)[]' with 0-based half-open coordinates (a VCF position 'p' is '[p - 1, p)'). The name is quoted into ‘regions := getvariable(’<name>')'; create the variable with 'SET VARIABLE' on the same connection. A 'NULL' variable value keeps the ordinary scan, an empty list selects no records, and 'region' and 'regions_var' are mutually exclusive. Typed regions need an index and are incompatible with 'scan_mode = "sequential"'. Chromosome names are literal (not region expressions); overlapping and adjacent intervals are merged natively. Limits: 1,000,000 intervals and 128 MiB. Aggregate with 'coalesce(list(...), []::STRUCT(...)[])': 'list()' over no rows is 'NULL', which means the ordinary full scan.
include_file_offset	Logical. If 'TRUE', add a 'FILE_OFFSET' column after 'FILTER': the BGZF virtual position just after each record. It increases strictly in file order and is the same for every scan mode, so ordering by it restores file order, also among records at one position. Input that is not BGZF-compressed gives 'NA'. The default keeps the existing schema.

Value

Invisible TRUE on success

Examples

library(DBI)
library(duckdb)

con <- rduckhts_connect()
bcf_path <- system.file("extdata", "vcf_file.bcf", package = "Rduckhts")
rduckhts_bcf(con, "variants", bcf_path, overwrite = TRUE)
dbGetQuery(con, "SELECT * FROM variants LIMIT 2")
dbDisconnect(con, shutdown = TRUE)

Rduckhts documentation built on Oct. 25, 2026, 1:08 a.m.