name	kind	category	signature	returns	r_wrapper	description	examples
duckhts_htslib_version	scalar	Diagnostics	duckhts_htslib_version()	VARCHAR	rduckhts_htslib_version	Return the runtime version reported by the htslib library loaded with DuckHTS. Rduckhts uses this value to reject a downstream linking receipt whose source/header version does not match the loaded library.	SELECT duckhts_htslib_version();
duckhts_htslib_features	scalar	Diagnostics	duckhts_htslib_features()	UINTEGER		Return the htslib runtime feature bitfield reported by hts_features(). Use duckhts_htslib_feature_string() for the corresponding build description.	SELECT duckhts_htslib_features();
duckhts_htslib_feature_string	scalar	Diagnostics	duckhts_htslib_feature_string()	VARCHAR		Return htslib's runtime build-feature description, including configured transports, compression libraries, compiler, and build flags. DuckHTS snapshots it once while loading the extension so parallel SQL calls read immutable text.	SELECT duckhts_htslib_feature_string();
duckhts_simd_backend	scalar	Diagnostics	duckhts_simd_backend()	VARCHAR	rduckhts_simd_backend	Return the current DuckHTS SIMD dispatch label. For explicit scalar or concrete backend requests this is the requested policy; for auto it is the single selected backend when all logical kernels resolve to the same backend, or mixed when per-kernel auto-dispatch resolves to multiple backends. Use duckhts_simd_kernel_info() for per-kernel details.	SELECT duckhts_simd_backend();
duckhts_simd_requested_backend	scalar	Diagnostics	duckhts_simd_requested_backend()	VARCHAR	rduckhts_simd_requested_backend	Return the current explicit SIMD backend request, usually auto unless `SELECT backend FROM duckhts_simd_set_backend('auto'|'scalar'|backend)` was called. The selected per-kernel backend may differ under auto-dispatch across x86, ARM, wasm, and scalar-only builds.	SELECT duckhts_simd_requested_backend();
duckhts_simd_backend_compiled	scalar	Diagnostics	duckhts_simd_backend_compiled(backend)	BOOLEAN	rduckhts_simd_backend_compiled	Return whether a concrete DuckHTS SIMD backend was compiled into this build. This is independent of whether the current CPU/runtime supports executing that backend; for example avx512 can be compiled but not CPU-supported on the running host.	SELECT duckhts_simd_backend_compiled('scalar'); || SELECT duckhts_simd_backend_compiled('avx512');
duckhts_simd_backend_cpu_supported	scalar	Diagnostics	duckhts_simd_backend_cpu_supported(backend)	BOOLEAN	rduckhts_simd_backend_cpu_supported	Return whether the current CPU/runtime supports a concrete DuckHTS SIMD backend, independent of whether DuckHTS compiled an implementation for it. Availability is the intersection of compiled and CPU-supported.	SELECT duckhts_simd_backend_cpu_supported('avx2'); || SELECT duckhts_simd_backend_cpu_supported('avx512');
duckhts_simd_backend_available	scalar	Diagnostics	duckhts_simd_backend_available(backend)	BOOLEAN	rduckhts_simd_backend_available	Return whether a concrete SIMD backend is usable in the current process. Availability means the backend is compiled into DuckHTS and supported by the current CPU/runtime. auto is a selection request rather than a concrete backend and is not reported as available here.	SELECT duckhts_simd_backend_available('scalar'); || SELECT duckhts_simd_backend_available('avx2'); || SELECT duckhts_simd_backend_available('avx512');
duckhts_simd_info	table	Diagnostics	duckhts_simd_info()	table	rduckhts_simd_info	Return one row per known concrete DuckHTS SIMD backend with extension-owned selectable, compiled, CPU-supported, available, selected, requested, and dispatch-mode diagnostics. Availability is the intersection of compiled and CPU/runtime-supported. selectable reports whether the backend has a selectable implementation path; explicit selection still requires available = TRUE. selected is TRUE when the current dispatch table uses that backend for at least one logical kernel. auto is a selection request and is not a concrete backend row.	SELECT * FROM duckhts_simd_info(); || SELECT backend FROM duckhts_simd_info() WHERE available;
duckhts_simd_kernel_info	table	Diagnostics	duckhts_simd_kernel_info()	table	rduckhts_simd_kernel_info	Return one row per logical DuckHTS SIMD kernel showing the concrete backend selected by the current immutable dispatch table, the selected capability, the requested backend policy, whether scalar was used as a per-kernel fallback, and the dispatch mode. This is the authoritative diagnostic for mixed auto-dispatch when different kernels resolve to different backends.	SELECT * FROM duckhts_simd_kernel_info(); || SELECT kernel, selected_backend FROM duckhts_simd_kernel_info();
duckhts_simd_set_backend	table	Diagnostics	duckhts_simd_set_backend(backend)	table(backend VARCHAR)	rduckhts_simd_set_backend	Explicitly select the DuckHTS SIMD dispatch policy for this process using a one-row table-function call and return the current dispatch label in a backend column. Use auto for per-kernel runtime dispatch or scalar for a portable baseline; unavailable platform-specific requests such as avx512 on non-AVX-512 CPUs raise an error instead of silently falling back.	SELECT backend FROM duckhts_simd_set_backend('scalar'); || SELECT backend FROM duckhts_simd_set_backend('auto');
duckhts_duckdb_type_supported	scalar_macro	Diagnostics	duckhts_duckdb_type_supported(type_name)	BOOLEAN		Return whether the currently open DuckDB runtime advertises a logical type with the given name through duckdb_types(). This is a catalog-level runtime probe for feature gating SQL/macros across DuckDB versions.	SELECT duckhts_duckdb_type_supported('VARIANT'); || SELECT duckhts_duckdb_type_supported('GEOMETRY');
duckhts_duckdb_supports_variant	scalar_macro	Diagnostics	duckhts_duckdb_supports_variant()	BOOLEAN		Return whether the currently open DuckDB runtime advertises the VARIANT logical type. Use this to gate optional SQL that depends on DuckDB VARIANT support.	SELECT duckhts_duckdb_supports_variant();
duckhts_duckdb_supports_geometry	scalar_macro	Diagnostics	duckhts_duckdb_supports_geometry()	BOOLEAN		Return whether the currently open DuckDB runtime advertises the GEOMETRY logical type. Use this to gate optional SQL that depends on DuckDB GEOMETRY support.	SELECT duckhts_duckdb_supports_geometry();
duckvep_ensembl_regions	table_macro	Variant Annotation	duckvep_ensembl_regions(core_schema, reference_chunks_table, assembly, species_id := 1)	table		Match a tiled reference sequence to one Ensembl core assembly and assign dense DuckVEP sequence-region ordinals. core_schema must contain the Ensembl seq_region and coord_system tables. reference_chunks_table must contain chrom, zero-based start, half-open end, and seq columns, normally materialized from fasta_nuc(..., include_seq := TRUE). Chunks must be contiguous from zero, their sequence lengths must match their intervals, and every FASTA contig must match exactly one same-length Ensembl region. Regions absent from the supplied FASTA are deliberately excluded. The supplied reference therefore defines the exact modeled path set: a primary-assembly FASTA produces a primary-path model, while alternate haplotypes or patches require their named sequence paths in the reference chunks. This macro does not apply Ensembl assembly_exception projections, merge X/Y PAR paths, or mark circular sequence regions; ordinary mitochondrial coordinates can be modeled, but an interval that wraps from the end of a circular sequence to its start is not accepted.	"CREATE TABLE grch38_reference_chunks AS SELECT chrom, start, ""end"", seq FROM fasta_nuc('GRCh38.primary.fa', bin_width := 1048576, include_seq := TRUE); || CREATE TABLE grch38_regions AS SELECT * FROM duckvep_ensembl_regions('ensembl_core', 'grch38_reference_chunks', 'GRCh38');"
duckvep_ensembl_transcripts	table_macro	Variant Annotation	duckvep_ensembl_transcripts(core_schema, reference_chunks_table, assembly, species_id := 1)	table		Build the validated DuckVEP transcript relation from Ensembl core tables and matching tiled FASTA sequence. This supplied builder compiles the VEP-116 Ensembl core selection; it does not build VEP --refseq or --merged transcript sets. Before dense ordinals are assigned, transcripts must be current and have a non-empty stable ID, and artifact-biotype or readthrough_tra transcripts are excluded. The result contains the exact resident-loader columns, stable/source identifiers, biotypes, versioned RefSeq accessions from MANE Select and MANE Plus Clinical attributes when present, a nested ranked-exon projection, mature miRNA cDNA attributes projected into genomic exon segments, and supported Translation SeqEdits. MANE accessions remain cold DuckDB columns while only selection flags enter the resident C model. GENCODE Basic and Primary membership is retained in transcript_flags for late filtering; this macro does not prefilter the model to either set. Prepared sequence contains the phase-adjusted CDS plus the complete transcript-oriented pre-CDS and post-CDS spliced sequence; the legacy post_cds_bases field remains as the first three post-CDS bases. Codon-table IDs come from the Ensembl seq_region_attrib relation and default to table 1 exactly as VEP 116 does; every BioPerl/VEP-supported NCBI table ID is accepted and invalid or conflicting source attributes reject the import. Single-residue initial_met, _selenocysteine, amino_acid_sub, and _stop_codon_rt edits are retained as a sparse reference-peptide overlay. Transcript-level sequence corrections, including inserted or deleted transcript bases relative to the genome, and other Translation SeqEdit shapes fail closed by withholding sequence with an explicit reason. Transcript rows remain specific to the exact selected sequence path, including separate X/Y PAR and alternate-haplotype stable IDs. The macro does not collapse alt_allele equivalence groups, use IS_PAR metadata to merge consequence rows, or lift transcripts across a circular sequence origin.	CREATE TABLE grch38_transcripts AS SELECT * FROM duckvep_ensembl_transcripts('ensembl_core', 'grch38_reference_chunks', 'GRCh38');
duckvep_ensembl_regulation_features	table_macro	Variant Annotation	duckvep_ensembl_regulation_features(funcgen_schema, regions_table)	table		Build the VEP-116-compatible interval relation for Ensembl RegulatoryFeature and MotifFeature rows on the sequence regions selected for a DuckVEP model. funcgen_schema must contain regulatory_feature, feature_type, and motif_feature; regions_table is the output of duckvep_ensembl_regions(...). Matching VEP's database and cache source, epigenetically_modified_region (EMAR) RegulatoryFeature rows are excluded before dense ordinals are assigned. The result maps source sequence-region IDs to model ordinals, validates one-based inclusive coordinates and source feature types, and preserves stable/source IDs, feature metadata, binding-matrix IDs, regulatory-build IDs, and motif scores as cold relation columns. feature_kind is the compact resident code: 1 regulatory region or 2 transcription-factor binding site. Pass the five hot columns regulation_feature_index, seq_region, feature_start, feature_end, and feature_kind to duckvep_model_load(interval_feature_query := ...); the remaining columns stay relational for late projection.	CREATE TABLE grch38_regulation AS SELECT * FROM duckvep_ensembl_regulation_features('ensembl_funcgen', 'grch38_regions');
duckvep_model_receipt	table_macro	Variant Annotation	duckvep_model_receipt(regions_table, transcripts_table, source_name, source_version, assembly, source_manifest_sha256, reference_sha256, transcript_filter, regulation_features_table := NULL)	table		Create one deterministic receipt for prepared DuckVEP region and transcript relations plus an optional prepared regulation-feature relation. The original eight positional arguments remain valid. When regulation_features_table is supplied by name, the receipt also validates its dense ordinals, region agreement, interval geometry, and feature kinds; counts regulatory regions and motif features; and includes their five resident columns in the model hash. It returns the declared provenance as source_name, source_version, assembly, source_manifest_sha256, reference_sha256, and transcript_filter; counts transcript, sequence, mature-miRNA, and peptide-edit content; and hashes every semantic resident-model field in stable ordinal order. source_manifest_sha256 should identify a canonical manifest containing every exact core and funcgen input used. The declared transcript_filter or source manifest should also record whether the reference contains only primary paths or includes alternate/patch paths and whether assembly_exception preprocessing was applied. The receipt contains no clock time, so rebuilding identical inputs yields the same model hash.	CREATE TABLE grch38_receipt AS SELECT * FROM duckvep_model_receipt('grch38_regions', 'grch38_transcripts', 'Ensembl', '116', 'GRCh38', source_manifest_sha256, reference_sha256, 'VEP 116 core selection on FASTA-covered assembly regions', regulation_features_table := 'grch38_regulation');
duckvep_model_load	table	Variant Annotation	duckvep_model_load(name, sequence_region_query, transcript_query, exon_query, mature_mirna_query := NULL, peptide_edit_query := NULL, interval_feature_query := NULL, reference_fasta := NULL, transcript_coverage_complete := FALSE)	table(loaded BOOLEAN)		Load one immutable consequence model into the current DuckDB database instance under a caller-chosen name. The resident kernel is source-neutral: callers may prepare any transcript catalog that satisfies this model contract. Three required query strings read committed, non-temporary DuckDB relations: sorted UINTEGER sequence-region ordinals; dense transcript rows with genomic span, strand, gene ordinal, flags, optional CDS span/sequence/codon table; and transcript-ordered exon rows with genomic and cDNA spans plus phase. Each exon cDNA span must be contiguous in transcript order and the same length as its genomic exon span. Transcript models that insert or delete bases relative to the genome therefore need a future explicit mapping and are not accepted by this interface. The optional mature_mirna_query reads transcript_index UINTEGER, mature_mirna_start UBIGINT, and mature_mirna_end UBIGINT ordered by transcript and start. The optional peptide_edit_query reads transcript_index UINTEGER, protein_position UINTEGER, and alternate_amino_acid VARCHAR ordered uniquely by transcript and protein position. The optional interval_feature_query reads regulation_feature_index UINTEGER, seq_region UINTEGER, feature_start UINTEGER, feature_end UINTEGER, and feature_kind UTINYINT ordered by region, start, and index; kind 1 is RegulatoryFeature and kind 2 is MotifFeature. Loading keeps those hot columns in a compact SoA and builds a separate cgranges seed index, while identifiers and funcgen metadata remain ordinary DuckDB columns. The transcript projection accepts 11 base columns, 12 columns with the legacy post_cds_bases BLOB of up to three bases, or 13 columns ending in complete transcript-oriented pre_cds_sequence and post_cds_sequence BLOBs. Complete flanks enable VEP start/stop predicates for length-changing edits that cross a CDS start or end. reference_fasta enables reference-validated, VEP-style 3-prime HGVS shifting. When supplied, the sequence-region query must return seq_region UINTEGER, sequence_length UBIGINT, and seq_region_name VARCHAR; loading requires an existing FASTA index and verifies every declared name and exact length without creating or modifying the index. The named model pins open read descriptors for the validated FASTA, .fai, and optional .gzi. Linux workers reopen those descriptors through /proc/self/fd, Windows retains the resolved source under deny-write sharing, and other POSIX workers use independent resolved-source handles with identity checks rather than shared /dev/fd seek state. Each annotation worker owns its mutable faidx handle, reuses contained sorted reference requests, and rejects detectable replacement or in-place source mutation around a cache-miss fetch. Sequence-region ordinals are exact model paths: loading performs no contig-synonym, PAR, patch, haplotype, assembly_exception, or circular-origin projection. Callers must apply any declared path mapping before loading or constructing events. Explicit NULL for any optional query or reference parameter is equivalent to omission. The default is a partial transcript model: a variant with no loaded transcript is unresolved, not intergenic. Setting transcript_coverage_complete := TRUE requires sequence_length UBIGINT and permits supported intergenic results after coordinate bounds checks. Loading validates and narrows the model once and returns one TRUE row. Several named models may coexist.	SELECT loaded FROM duckvep_model_load('grch38', 'SELECT seq_region, sequence_length, seq_region_name FROM grch38_regions ORDER BY seq_region', 'SELECT transcript_index, seq_region, transcript_start, transcript_end, strand, gene_index, transcript_flags, cds_start, cds_end, cds_sequence, codon_table, pre_cds_sequence, post_cds_sequence FROM grch38_transcripts ORDER BY seq_region, transcript_start, transcript_index', 'SELECT transcript_index, exon.exon_start, exon.exon_end, exon.exon_cdna_start, exon.exon_cdna_end, exon.phase, exon.end_phase FROM grch38_transcripts, LATERAL unnest(exons) AS u(exon) ORDER BY transcript_index, exon.exon_cdna_start', mature_mirna_query := 'SELECT transcript_index, region.mature_mirna_start, region.mature_mirna_end FROM grch38_transcripts, LATERAL unnest(mature_mirna_regions) AS u(region) ORDER BY transcript_index, region.mature_mirna_start', peptide_edit_query := 'SELECT transcript_index, edit.protein_position, edit.alternate_amino_acid FROM grch38_transcripts, LATERAL unnest(peptide_edits) AS u(edit) ORDER BY transcript_index, edit.protein_position', interval_feature_query := 'SELECT regulation_feature_index, seq_region, feature_start, feature_end, feature_kind FROM grch38_regulation ORDER BY seq_region, feature_start, regulation_feature_index', reference_fasta := '/data/Homo_sapiens.GRCh38.dna.primary_assembly.fa', transcript_coverage_complete := TRUE);
duckvep_model_drop	scalar	Variant Annotation	duckvep_model_drop(name)	BOOLEAN		Remove a named resident DuckVEP consequence model and release its transcript and regulation-feature interval indexes, sequences, and cached worker state. Returns FALSE when the name is absent or the model is in use by an annotation vector.	SELECT duckvep_model_drop('grch38');
duckvep_allele_geometry	scalar	Variant Annotation	duckvep_allele_geometry(position, reference, alternate)	STRUCT(kind_code UTINYINT, interbase BOOLEAN, anchor_side_code UTINYINT, raw_start0 UBIGINT, raw_end0 UBIGINT, feature_start0 UBIGINT, feature_end0 UBIGINT, edit_start0 UBIGINT, edit_end0 UBIGINT, insertion_boundary0 UBIGINT, reference_difference_offset USMALLINT, reference_difference_length USMALLINT, alternate_difference_offset USMALLINT, alternate_difference_length USMALLINT)		Interpret one literal biallelic allele with the same lossless geometry authority used by DuckVEP. position is positive and one-based; REF and ALT are non-empty A/C/G/T/N strings of at most 65,535 bases and must differ after ASCII case folding. kind_code is stable: 0 SNV, 1 insertion, 2 deletion, 3 length-changing replacement, and 4 multi-base substitution. anchor_side_code is 0 for no retained anchor, 1 for a left anchor, and 2 for a right anchor. All coordinate fields are non-null zero-based half-open intervals except insertion_boundary0, which is non-null only for an interbase insertion. Difference offsets and lengths are non-null indices into the uploaded REF and ALT. The result separates the uploaded REF span, VEP-116 VariationFeature span, and fully minimized semantic reference edit. A pure insertion has equal feature/edit start and end plus insertion_boundary0. This function does not split multiallelic records or left-align alleles: run duckhts_bcftools_norm(..., split_multiallelic := TRUE) first when canonical exact keys or cross-source joins require normalization. Use feature_start0/feature_end0 for VEP consequence feature overlap, edit_start0/edit_end0 for affected-reference supplementary providers, and an explicit insertion-flank policy when interbase is TRUE; the uploaded raw REF span is not a biological affected interval.	SELECT (duckvep_allele_geometry(100, 'A', 'ATG')).*;
duckvep_annotate	table	Variant Annotation	duckvep_annotate(events_table, model_name, hgvs := FALSE, upstream_distance := 5000, downstream_distance := 5000, rich := FALSE)	table		Annotate a narrow canonical event relation against one resident DuckVEP model through one fixed-schema, pipe-friendly surface. events_table names a coordinate-ordered relation with event_index UBIGINT, seq_region UINTEGER, positive one-based position, reference VARCHAR, alternate VARCHAR, end_position UBIGINT, structural_type VARCHAR, copy_change VARCHAR, mate_seq_region UINTEGER, and mate_position UBIGINT. One row represents one ALT allele. Keep genotype, phase-set, confidence-interval, raw-ALT, orientation, and other provenance in the source relation; join selected annotations back by event_index instead of multiplying wide payloads by transcript count. Literal reference/alternate rows are small variants; an explicit structural type, supported symbolic ALT, or span without literal alleles is structural; a complete mate coordinate pair is a breakend. Following VEP 116, expanded gVCF <NON_REF>, bare *, and . ALT rows emit no annotation. The distinct <*> catch-all allele remains an overlap allele: coding positions receive coding_sequence_variant, start/stop codon positions receive the corresponding retained consequence, and HGVS fields remain NULL. VEP 116 also compares the literal three-character <*> spelling with REF length, so a long-REF catch-all allele that completely contains a feature can receive an ablation term; exclude <*> rows after ALT expansion if catch-all consequences are not wanted. A literal ALT from a mixed gVCF record remains a small variant even when the source relation retains record-level INFO/END; keep that END as provenance rather than treating it as an SV type. Contradictory or incomplete geometry fails instead of being guessed, including disagreement between supported symbolic ALT and explicit structural_type values. For VCF span SVs, prepare position as POS + 1 after removing the left anchor; insertion position is the interbase site after POS. DEL implies LOSS and DUP/TDUP imply GAIN when copy_change is NULL. Filtering the globally coordinate-ordered event stream preserves the order required by each native transcript and regulation-feature sweep; the macro does not hide a sort. The event seq_region is an exact ordinal in the loaded model; annotation does not strip contig prefixes or project PAR, patch, alternate-haplotype, or circular-origin coordinates. X/Y PAR and alternate-path transcript rows therefore remain path-specific exactly as prepared. Each event is annotated independently: genotype and phase-set columns are not combined into haplotypes. The stable compact contract includes SO/region masks, IMPACT/status/reason codes, one-based cDNA/CDS/protein positions, amino-acid bytes, NMD prediction/escape codes, and overlap-object ordinals. protein_position is the affected one-based protein residue/codon ordinal used by codon-level evidence such as PS1/PM5. rich := TRUE adds Consequence, IMPACT, region, amino-acid, NMD, overlap-object, duckvep_status, and duckvep_reason text from the same native pass while retaining every compact field; FALSE or explicit NULL leaves those presentation columns NULL. hgvs := TRUE fuses independent-event HGVSc/HGVSn/HGVSp into the small-variant path without repeating candidate discovery; it composes with rich := TRUE in one pass; structural and breakend HGVS remain NULL. DuckHTS audit status/reason fields distinguish an unresolved computation from a genuinely absent consequence and are not Ensembl CSQ fields. Zero disables either directional transcript window. Decode consequence_mask only after filtering by joining duckvep_so_terms(); join transcript_index, gene_index, or regulation_feature_index to the prepared model relations for stable identifiers, biotype, MANE/GENCODE/CCDS flags, and other presentation metadata. This typed rich projection does not claim the complete serialized VEP CSQ vocabulary: exon/intron ordinals, codon strings, distance text, CANONICAL/APPRIS/TSL, existing variation, and supplementary predictors require their declared model or annotation relations.	SELECT * FROM duckvep_annotate('canonical_events', 'grch38'); || SELECT event_index, transcript_index, transcript_hgvs, protein_hgvs FROM duckvep_annotate('canonical_events', 'grch38', hgvs := TRUE, upstream_distance := 5000, downstream_distance := 0); || SELECT event_index, transcript_index, consequence, impact, protein_position, nmd_prediction FROM duckvep_annotate('canonical_events', 'grch38', rich := TRUE);
duckvep_so_terms	table	Variant Annotation	duckvep_so_terms()	table		Return the generated Sequence Ontology metadata behind DuckVEP's stable consequence-mask bits: bit index, single-bit mask, term, impact code and label, VEP severity rank, and evaluator tier. Filter and aggregate compact annotation rows numerically first, then expand only selected mask bits with (annotation.consequence_mask & term.consequence_mask) <> 0. The relation is generated from the same pinned VEP-116 class-model metadata as the native consequence engine; it is not a second hand-maintained term inventory.	SELECT a.event_index, t.consequence FROM duckvep_annotate('canonical_events', 'grch38') a JOIN duckvep_so_terms() t ON (a.consequence_mask & t.consequence_mask) <> 0;
read_bcf	table	Readers	read_bcf(path, region := NULL, index_path := NULL, tidy_format := FALSE, additional_csq_column_types := NULL, scan_mode := 'auto', decompression_threads := 0, decode_error_policy := 'null')	table	rduckhts_bcf	Read VCF and BCF variant data with typed INFO, FORMAT, typed CSQ/ANN/BCSQ subfields, optional tidy sample output, optional bcftools-style CSQ type overrides, explicit scan_mode control ('auto' or full-file 'sequential'), optional htslib decompression worker threads via decompression_threads (default 0 for single-threaded reads), and decode_error_policy ('null', 'warn', or 'error') for corrupt BCF header-vs-payload decode mismatches. Comma-separated indexed regions use htslib's native multi-region iterator and emit a record once when requested regions overlap.	SELECT CHROM, POS, REF, ALT FROM read_bcf('vcf_file.bcf') LIMIT 5;
read_bcf_v2	table	Readers	read_bcf_v2(path, region := NULL, index_path := NULL, tidy_format := FALSE, additional_csq_column_types := NULL, scan_mode := 'auto', decompression_threads := 0, decode_error_policy := 'null', samples := NULL, samples_file := NULL, exclude_samples := NULL, exclude_samples_file := NULL, force_samples := FALSE, include_info := TRUE, include_format := TRUE, include_vep := TRUE, info_fields := NULL, format_fields := NULL, vep_fields := NULL)	table		Experimental clone of read_bcf(...) for non-destructive benchmarking of current-schema scan optimizations. It preserves the read_bcf wide/tidy output schema by default, streams full-file scans by default instead of auto-iterating indexed contigs, accepts the same scan_mode and decode_error_policy ('null', 'warn', or 'error') contract as read_bcf, and shares read_bcf's native deduplicating multi-region iterator. It sets htslib VCF text max_unpack from DuckDB projection pushdown so unprojected INFO/FORMAT text can be skipped earlier, keeps INFO/FORMAT/GT decode buffers and parsed VEP/CSQ records in local scan state across output chunks, repeats VEP-derived values correctly across tidy sample rows, supports v2-only htslib sample pushdown via comma-separated samples/exclude_samples strings or samples_file/exclude_samples_file lists, can bind only requested INFO/FORMAT/VEP fields through include_info/include_format/include_vep and comma-separated info_fields/format_fields/vep_fields controls, rejects format_fields when no samples are selected, treats tidy_format := true with include_format := false as one row per variant because no SAMPLE_ID/FORMAT columns are bound, and counts VCF text rows without parsing when no columns are projected.	SELECT CHROM, POS, REF, ALT FROM read_bcf_v2('vcf_file.bcf') LIMIT 5;
read_bcf_appender	table	Readers	read_bcf_appender(path, target_table, region := NULL, tidy_format := TRUE, overwrite := TRUE, include_file_offset := FALSE, region_threads := 1, decompression_threads := 0, decode_error_policy := 'null')	table		Experimental side-effecting benchmark helper that reads BCF/VCF with htslib and appends a narrow scalar tidy table through DuckDB's chunk appender API. The target table is created in the default schema with columns CHROM, POS, REF, ALT, SAMPLE_ID, and FORMAT_GT; set include_file_offset := TRUE to add FILE_OFFSET as a file-order token. Comma-separated regions use htslib's native deduplicating multi-region iterators. region_threads controls at most 16 worker handles claiming primary-contig jobs iteratively: every contig keeps its complete requested interval set in one native iterator, so repeated, overlapping, or record-spanning intervals produce the same target schema and row multiset for every thread count. Header contig count does not create worker threads or open handles, and a request limited to one contig uses one iterator. Parallel row arrival is unordered; use ORDER BY FILE_OFFSET when file order matters. decompression_threads configures htslib workers per open region-worker handle, so total helper threads can scale as region workers times decompression workers. The operation runs inside an internal transaction and surfaces malformed-record errors as DuckDB errors; decode_error_policy controls corrupt BCF FORMAT/GT header-vs-payload mismatches with 'null', 'warn', or 'error'. target_table must be an unqualified SQL identifier. This is intended to compare appender-based materialization against read_bcf(...) query pipelines, not as a full replacement for the typed read_bcf surface.	SELECT * FROM read_bcf_appender('vcf_file.bcf', 'bcf_app', region := '1:1-1000000'); || SELECT count(*) FROM bcf_app;
read_bam	table	Readers	read_bam(path, standard_tags := FALSE, auxiliary_tags := FALSE, region := NULL, index_path := NULL, reference := NULL, sequence_encoding := 'string', quality_representation := 'string', cigar_representation := 'string', scan_mode := 'auto', decompression_threads := 2)	table	rduckhts_bam	Read SAM, BAM, and CRAM alignments with optional typed SAMtags and auxiliary tag maps. Use sequence_encoding := 'nt16' to return SEQ as UTINYINT[], quality_representation := 'phred' to return QUAL as UTINYINT[], and cigar_representation := 'binary' to return packed BAM CIGAR operations as UINTEGER[] instead of SAM text. scan_mode := 'sequential' forces a full-file streaming scan instead of index-backed count/parallel paths and is incompatible with region. decompression_threads controls per-file htslib worker threads and defaults to 2; use 0 to disable worker threads.	SELECT QNAME, FLAG, RNAME, POS FROM read_bam('range.bam') LIMIT 5;
duckhts_bcf_convert_parquet_sql	scalar_macro	Converters	duckhts_bcf_convert_parquet_sql(path, output, columns := []::VARCHAR[], region := NULL, index_path := NULL, tidy_format := FALSE, additional_csq_column_types := NULL, decompression_threads := 0, where_sql := NULL, compression := 'zstd', row_group_size := 100000, partition_by := []::VARCHAR[], include_metadata := TRUE, header_text := NULL, metadata := map([]::VARCHAR[], []::VARCHAR[]), metadata_json_file := NULL, overwrite := FALSE, write_format_version := '1')	VARCHAR	rduckhts_bcf_convert_parquet	Build a DuckDB COPY statement that converts read_bcf(...) output to Parquet with DuckHTS key-value metadata, preserved or corrected VCF header text, user metadata from metadata := map(...), selected columns, filters, and partition columns. Optional metadata_json_file is caller-managed and requires DuckDB's json extension to be available when the builder is called; use metadata maps for CRAN/offline-safe workflows. Clients execute the returned SQL string; the R wrapper is a thin DBI helper that does this execution.	SELECT duckhts_bcf_convert_parquet_sql('cohort.vcf.gz', 'cohort.parquet', columns := ['CHROM','POS','REF','ALT'], metadata := map(['project'], ['cohort-a']));
duckhts_bam_convert_parquet_sql	scalar_macro	Converters	duckhts_bam_convert_parquet_sql(path, output, columns := []::VARCHAR[], region := NULL, index_path := NULL, reference := NULL, standard_tags := FALSE, auxiliary_tags := FALSE, sequence_encoding := NULL, quality_representation := NULL, cigar_representation := NULL, decompression_threads := 2, where_sql := NULL, compression := 'zstd', row_group_size := 100000, partition_by := []::VARCHAR[], include_metadata := TRUE, header_text := NULL, metadata := map([]::VARCHAR[], []::VARCHAR[]), metadata_json_file := NULL, overwrite := FALSE, write_format_version := '1')	VARCHAR	rduckhts_bam_convert_parquet	Build a DuckDB COPY statement that converts read_bam(...) output to Parquet with DuckHTS key-value metadata, preserved or corrected SAM header text, user metadata from metadata := map(...), selected columns, filters, and partition columns. Optional metadata_json_file is caller-managed and requires DuckDB's json extension to be available when the builder is called; use metadata maps for CRAN/offline-safe workflows. Clients execute the returned SQL string; the R wrapper is a thin DBI helper that does this execution.	SELECT duckhts_bam_convert_parquet_sql('sample.bam', 'sample.parquet', columns := ['QNAME','FLAG','RNAME','POS']);
duckhts_gff_convert_parquet_sql	scalar_macro	Converters	duckhts_gff_convert_parquet_sql(path, output, columns := []::VARCHAR[], region := NULL, index_path := NULL, header := NULL, header_names := []::VARCHAR[], auto_detect := NULL, column_types := []::VARCHAR[], attributes_map := FALSE, attributes_list := FALSE, attributes_pairs := FALSE, strict := FALSE, where_sql := NULL, compression := 'zstd', row_group_size := 100000, partition_by := []::VARCHAR[], include_metadata := TRUE, header_text := NULL, metadata := map([]::VARCHAR[], []::VARCHAR[]), metadata_json_file := NULL, overwrite := FALSE, write_format_version := '1')	VARCHAR	rduckhts_gff_convert_parquet	Build a DuckDB COPY statement that converts read_gff(...) output to Parquet with DuckHTS key-value metadata, preserved or corrected GFF/tabix header text, user metadata from metadata := map(...), selected columns, filters, and partition columns. Optional metadata_json_file is caller-managed and requires DuckDB's json extension to be available when the builder is called; use metadata maps for CRAN/offline-safe workflows. Clients execute the returned SQL string; the R wrapper is a thin DBI helper that does this execution.	SELECT duckhts_gff_convert_parquet_sql('annotations.gff3.gz', 'annotations/', columns := ['seqname','feature','start','end'], partition_by := ['feature']);
duckhts_tabix_convert_parquet_sql	scalar_macro	Converters	duckhts_tabix_convert_parquet_sql(path, output, columns := []::VARCHAR[], region := NULL, index_path := NULL, header := NULL, header_names := []::VARCHAR[], auto_detect := NULL, column_types := []::VARCHAR[], where_sql := NULL, compression := 'zstd', row_group_size := 100000, partition_by := []::VARCHAR[], include_metadata := TRUE, header_text := NULL, metadata := map([]::VARCHAR[], []::VARCHAR[]), metadata_json_file := NULL, overwrite := FALSE, write_format_version := '1')	VARCHAR	rduckhts_tabix_convert_parquet	Build a DuckDB COPY statement that converts read_tabix(...) output to Parquet with DuckHTS key-value metadata, preserved or corrected tabix header text, user metadata from metadata := map(...), selected columns, filters, and partition columns. Optional metadata_json_file is caller-managed and requires DuckDB's json extension to be available when the builder is called; use metadata maps for CRAN/offline-safe workflows. Clients execute the returned SQL string; the R wrapper is a thin DBI helper that does this execution.	SELECT duckhts_tabix_convert_parquet_sql('regions.tsv.gz', 'regions.parquet', header_names := ['chrom','pos','value'], auto_detect := TRUE);
read_pileup	table	Coverage	read_pileup(path, region := NULL, index_path := NULL, min_mapq := 0, flag_mask := 1796)	table	rduckhts_pileup	Construct a region-scoped BAM pileup with one row per covered position, emitting chrom, 1-based position, depth, observed bases, and Phred+33 qualities after SAM flag and MAPQ filtering. This is a compact htslib pileup view, not samtools mpileup text parity.	SELECT chrom, pos, depth FROM read_pileup('range.bam', region := 'CHROMOSOME_I:1-200') LIMIT 5;
read_fasta	table	Readers	read_fasta(path, region := NULL, index_path := NULL, gzi_path := NULL, sequence_encoding := 'string', scan_mode := 'auto')	table	rduckhts_fasta	Read FASTA records or indexed FASTA regions as sequence rows. Use sequence_encoding := 'nt16' to return SEQUENCE as UTINYINT[] (htslib nt16 4-bit codes) instead of VARCHAR. For bgzipped FASTA, gzi_path may point to an explicit .gzi sidecar when it is not colocated with the FASTA. scan_mode := 'sequential' forces full-file streaming/counting instead of index-backed count paths and is incompatible with region.	SELECT NAME, length(SEQUENCE) FROM read_fasta('ce.fa');
read_bed	table	Readers	read_bed(path, region := NULL, index_path := NULL, scan_mode := 'auto')	table	rduckhts_bed	Read BED3-BED12 interval files with canonical typed columns and optional tabix-backed region filtering. scan_mode := 'sequential' forces full-file streaming/counting instead of index-backed count paths and is incompatible with region.	"SELECT chrom, start, ""end"", name FROM read_bed('targets.bed') LIMIT 5;"
fasta_nuc	table	Readers	fasta_nuc(path, bed_path := NULL, bin_width := NULL, region := NULL, index_path := NULL, gzi_path := NULL, bed_index_path := NULL, include_seq := FALSE)	table	rduckhts_fasta_nuc	Compute bedtools nuc-style nucleotide composition for supplied BED intervals or generated fixed-width bins over a FASTA reference. For bgzipped FASTA, gzi_path may point to an explicit .gzi sidecar when it is not colocated with the FASTA.	"SELECT chrom, start, ""end"", pct_gc FROM fasta_nuc('ce.fa', bin_width := 1000) LIMIT 5;"
duckhts_cgranges_create	scalar	Intervals	duckhts_cgranges_create(name)	BOOLEAN		Create an empty session-scoped cgranges registry entry that can be populated with intervals and finalized for overlap queries.	SELECT duckhts_cgranges_create('targets_idx');
duckhts_cgranges_add	scalar	Intervals	duckhts_cgranges_add(name, chrom, start, end[, label])	BOOLEAN		Append an interval to a session-scoped cgranges registry entry before finalization. Labels may be BIGINT-like, DOUBLE, VARCHAR, or BOOLEAN.	SELECT duckhts_cgranges_add('targets_idx', 'chr1', 10, 20, 'exon1');
duckhts_cgranges_index	scalar	Intervals	duckhts_cgranges_index(name)	BOOLEAN		Finalize a populated cgranges registry entry and build its immutable overlap index for subsequent queries.	SELECT duckhts_cgranges_index('targets_idx');
duckhts_cgranges_destroy	scalar	Intervals	duckhts_cgranges_destroy(name)	BOOLEAN		Destroy a session-scoped cgranges registry entry and release its indexed interval storage when it is not in active use.	SELECT duckhts_cgranges_destroy('targets_idx');
duckhts_cgranges_from_query	scalar	Intervals	duckhts_cgranges_from_query(name, query, chrom_col, start_col, end_col[, label_col])	BOOLEAN		Execute a SQL query on an extension-owned DuckDB connection, append its interval rows into a session-scoped cgranges registry entry, and leave the populated index ready for explicit finalization with duckhts_cgranges_index(...).	"SELECT duckhts_cgranges_from_query('targets_idx', 'SELECT chrom, start, ""end"", name FROM targets', 'chrom', 'start', 'end', 'name');"
duckhts_cgranges_from_table	scalar	Intervals	duckhts_cgranges_from_table(name, table_name, chrom_col, start_col, end_col[, label_col])	BOOLEAN		Reserved convenience constructor for bulk cgranges population from a table name. The current implementation is intentionally deferred and directs callers to duckhts_cgranges_from_query(...).	SELECT duckhts_cgranges_from_table('targets_idx', 'targets', 'chrom', 'start', 'end', 'name');
duckhts_cgranges_has_overlap	scalar	Intervals	duckhts_cgranges_has_overlap(name, chrom, start, end[, mode])	BOOLEAN		Vectorized scalar predicate for streaming provider rows through a finalized session-scoped cgranges index. Returns TRUE when the query interval overlaps at least one indexed interval, or when mode = 'contain' and it fully contains at least one indexed interval; NULL inputs return NULL.	"SELECT * FROM read_bed('queries.bed') WHERE duckhts_cgranges_has_overlap('targets_idx', chrom, start, ""end"");"
duckhts_cgranges_count_overlaps	scalar	Intervals	duckhts_cgranges_count_overlaps(name, chrom, start, end[, mode])	BIGINT		Vectorized scalar overlap counter for streaming provider rows through a finalized session-scoped cgranges index. Returns the number of indexed intervals that overlap the query interval, or with mode = 'contain' the number fully contained by it; NULL inputs return NULL.	"SELECT chrom, start, ""end"", duckhts_cgranges_count_overlaps('targets_idx', chrom, start, ""end"") AS n_targets FROM read_bed('queries.bed');"
duckhts_cgranges_overlaps_list	scalar	Intervals	duckhts_cgranges_overlaps_list(name, chrom, start, end[, mode])	STRUCT(interval_ordinal BIGINT, label VARCHAR, label_type VARCHAR, interval_chrom VARCHAR, interval_start INTEGER, interval_end INTEGER)[]		Vectorized scalar overlap expander for streaming provider rows through a finalized session-scoped cgranges index. Returns a LIST of hit STRUCTs that can be expanded with UNNEST, preserving provider columns while emitting one row per matching indexed interval. Because scalar return types are fixed, labels are returned as text with label_type describing the original cgranges label kind; NULL inputs return NULL.	"SELECT q.*, hit.interval_chrom, hit.interval_start, hit.interval_end, hit.label FROM read_bed('queries.bed') AS q CROSS JOIN UNNEST(duckhts_cgranges_overlaps_list('targets_idx', q.chrom, q.start, q.""end"")) AS u(hit);"
duckhts_cgranges_overlaps	table	Intervals	duckhts_cgranges_overlaps(name, chrom, start, end, mode := 'overlap', query_row_id := NULL)	table		Query a finalized session-scoped cgranges registry entry and return one row per overlapping or containing indexed interval, preserving the original label type and interval coordinates.	SELECT * FROM duckhts_cgranges_overlaps('targets_idx', 'chr1', 100, 150);
duckhts_cgranges_overlaps_bulk	table	Intervals	duckhts_cgranges_overlaps_bulk(name, query, chrom_col, start_col, end_col, mode := 'overlap', query_row_id_col := NULL)	table		Run a SQL query that yields overlap probes, stream those rows through a finalized session-scoped cgranges registry entry, and return one row per matching indexed interval. The probe query runs on the extension-owned helper connection, so it must reference regular tables/views rather than connection-local temp tables. When query_row_id_col is omitted, query_row_id defaults to the 1-based probe row ordinal.	"SELECT * FROM duckhts_cgranges_overlaps_bulk('targets_idx', 'SELECT probe_id, chrom, start, ""end"" FROM probes', 'chrom', 'start', 'end', query_row_id_col := 'probe_id');"
read_fastq	table	Readers	read_fastq(path, interleaved := FALSE, mate_path := NULL, sequence_encoding := 'string', quality_representation := 'string', input_quality_encoding := 'phred33', scan_mode := 'auto')	table	rduckhts_fastq	Read single-end, paired-end, or interleaved FASTQ files with optional legacy quality decoding. By default, FASTQ qualities are interpreted as modern Phred+33 input. Use sequence_encoding := 'nt16' to return SEQUENCE as UTINYINT[] and quality_representation := 'phred' to return QUALITY as UTINYINT[] instead of VARCHAR. input_quality_encoding accepts 'phred33', 'auto', 'phred64', or 'solexa64'. scan_mode := 'sequential' forces raw streaming/counting instead of index-backed count paths.	SELECT NAME, MATE FROM read_fastq('r1.fq', mate_path := 'r2.fq') LIMIT 5;
read_bigwig	table	Readers	read_bigwig(path, region := NULL, blocks_per_iteration := 64)	table	rduckhts_bigwig	Read stored BigWig signal intervals as CHROM, START0, END0, and VALUE. Coordinates are zero-based half-open. region uses htslib's one-based inclusive syntax; comma-separated requests are merged per contig and emit each stored interval once. Full scans claim nonempty contigs across DuckDB workers, and multi-region scans claim merged ranges. Each worker owns its mutable file handle and iterator. blocks_per_iteration controls libBigWig iterator batching, not the number of DuckDB workers. Local, native remote, and browser wasm reads all use DuckHTS's htslib hFILE transport rather than a second libcurl stack.	SELECT * FROM read_bigwig('scores.bw', region := 'chr1:100000-101000,chr2:200000-201000');
duckhts_fastq_qc	aggregate	Quality Control	duckhts_fastq_qc(sequence, quality [, max_cycles])	STRUCT		Aggregate canonical sequence and Phred+33 quality strings directly into exact read/base/Q20/Q30/Q40, nucleotide, quality-sum, and per-cycle sufficient statistics. The nested cycles list supports mean-quality, nucleotide-content, GC, and read-length curves without expanding one SQL row per base. Rows with any NULL input are ignored. Per-cycle state defaults to at most 1,048,576 cycles; pass a constant max_cycles per aggregate group to choose a larger explicit limit, up to 16,777,216.	SELECT duckhts_fastq_qc(SEQUENCE, QUALITY) AS qc FROM read_fastq('reads.fastq.gz'); || WITH q AS (SELECT duckhts_fastq_qc(SEQUENCE, QUALITY) AS qc FROM read_fastq('reads.fastq.gz')) SELECT cycle.* FROM q, UNNEST(qc.cycles) AS u(cycle);
detect_quality_encoding	table	Metadata	detect_quality_encoding(path, max_records := 10000)	table	rduckhts_detect_quality_encoding	Inspect a FASTQ file's observed quality ASCII range and report compatible legacy encodings with a heuristic guessed encoding.	SELECT * FROM detect_quality_encoding('reads.fq.gz');
read_gff	table	Readers	read_gff(path, header_names := NULL, header := FALSE, column_types := NULL, auto_detect := FALSE, attributes_map := FALSE, attributes_list := FALSE, attributes_pairs := FALSE, strict := FALSE, region := NULL, index_path := NULL, scan_mode := 'auto')	table	rduckhts_gff	Read GFF annotations with optional raw scalar and richer list/pair parsed attribute columns, strict GFF3 structural validation, and indexed region filtering. Comma-separated indexed regions use htslib's native multi-region iterator and emit a row once when requested regions overlap. scan_mode := 'sequential' forces full-file streaming/counting instead of index-backed count paths and is incompatible with region.	"SELECT seqname, feature, start, ""end"" FROM read_gff('gff_file.gff.gz') LIMIT 5;"
read_gtf	table	Readers	read_gtf(path, header_names := NULL, header := FALSE, column_types := NULL, auto_detect := FALSE, attributes_map := FALSE, attributes_list := FALSE, attributes_pairs := FALSE, region := NULL, index_path := NULL, scan_mode := 'auto')	table	rduckhts_gtf	Read GTF annotations with optional raw scalar and richer list/pair parsed attribute columns and indexed region filtering. Comma-separated indexed regions use htslib's native multi-region iterator and emit a row once when requested regions overlap. scan_mode := 'sequential' forces full-file streaming/counting instead of index-backed count paths and is incompatible with region.	"SELECT seqname, feature, start, ""end"" FROM read_gtf('annotations.gtf.gz') LIMIT 5;"
read_tabix	table	Readers	read_tabix(path, header_names := NULL, header := FALSE, column_types := NULL, auto_detect := FALSE, region := NULL, index_path := NULL, scan_mode := 'auto')	table	rduckhts_tabix	Read generic tabix-indexed text data with optional header handling and type inference. Comma-separated indexed regions use htslib's native multi-region iterator and emit a row once when requested regions overlap. scan_mode := 'sequential' forces full-file streaming/counting instead of index-backed count paths and is incompatible with region.	SELECT * FROM read_tabix('meta_tabix.tsv.gz') LIMIT 5;
fasta_index	table	Readers	fasta_index(path, index_path := NULL)	table	rduckhts_fasta_index	Build a FASTA index (.fai) and return a single row with columns success (BOOLEAN) and index_path (VARCHAR).	SELECT * FROM fasta_index('ce.fa');
bgzip	table	Compression	bgzip(path, output_path := NULL, threads := 4, level := -1, keep := TRUE, overwrite := FALSE)	table	rduckhts_bgzip	Compress a plain file to BGZF and return the created output path and byte counts.	SELECT * FROM bgzip('regions.bed');
bgunzip	table	Compression	bgunzip(path, output_path := NULL, threads := 4, keep := TRUE, overwrite := FALSE)	table	rduckhts_bgunzip	Decompress a BGZF-compressed file and return the created output path and byte counts.	SELECT * FROM bgunzip('regions.bed.gz');
bam_index	table	Indexing	bam_index(path, index_path := NULL, min_shift := 0, threads := 4)	table	rduckhts_bam_index	Build a BAM or CRAM index and report the written index path and format.	SELECT * FROM bam_index('range.bam');
bcf_index	table	Indexing	bcf_index(path, index_path := NULL, min_shift := NULL, threads := 4)	table	rduckhts_bcf_index	Build a TBI or CSI index for a VCF or BCF file and report the written index path and format.	SELECT * FROM bcf_index('formatcols.vcf.gz');
tabix_index	table	Indexing	tabix_index(path, preset := 'vcf', index_path := NULL, min_shift := 0, threads := 4, seq_col := NULL, start_col := NULL, end_col := NULL, comment_char := NULL, skip_lines := NULL)	table	rduckhts_tabix_index	Build a tabix index for a BGZF-compressed text file using a preset or explicit coordinate columns.	SELECT * FROM tabix_index('gff_file.gff.gz', preset := 'gff');
bam_bin_counts	table	Coverage	bam_bin_counts(path, bin_width, chrom := NULL, reference := NULL, index_path := NULL, mapq := 0, require_flags := 0, exclude_flags := 0, rmdup := 'none', stats := NULL)	table	rduckhts_bam_bin_counts	Count BAM or CRAM read starts into fixed-width bins. Returns one row per bin across the selected contig span, including zero-count bins, with total, forward, and reverse counts; `rmdup := 'streaming'` applies the WisecondorX-style larp/larp2 consecutive-position deduplication, `rmdup := 'flag'` drops SAM duplicate-flagged reads, and `stats := 'gc'`, `'mq'`, or `'gc,mq'` adds per-bin pre/post-filter GC and MAPQ sufficient statistics, including reference GC when `reference` is provided.	SELECT * FROM bam_bin_counts('fixture_mixed.cram', 5000, reference := 'fixture_ref.fa', rmdup := 'streaming', stats := 'gc,mq');
duckhts_bam_bed_coverage	table	Coverage	duckhts_bam_bed_coverage(path, bed_path, reference := NULL, index_path := NULL, bed_index_path := NULL, mapq := 0, min_baseq := 0, min_read_len := 0, require_flags := 0, exclude_flags := 1796, min_depth := 1, max_depth := 1000000, decompression_threads := 0, fragment_mode := FALSE, strand_outputs := TRUE, processing_threads := 0)	table	rduckhts_bam_bed_coverage	Compute samtools coverage-like regional summaries for BAM or CRAM input over a BED target set, returning one row per BED interval with DuckHTS-specific pre/post-filter read counts, covered bases, percentage covered, mean depth, mean baseQ, mean mapQ, and strand-specific post-filter summaries in read mode. Indexed BAM/CRAM input is required in the current implementation. decompression_threads controls htslib worker threads for BAM/CRAM decoding; use 0 to disable them.	"SELECT chrom, start, ""end"", numreads_post, covbases_post, coverage_post FROM duckhts_bam_bed_coverage('fixture_mixed.bam', 'fixture_mixed_regions.bed');"
duckhts_mosdepth	table	Coverage	duckhts_mosdepth(prefix, path, chrom := NULL, by := NULL, fasta := NULL, read_groups := NULL, no_per_base := FALSE, threads := 2, processing_threads := 2, flag := 1796, include_flag := 0, fast_mode := FALSE, fragment_mode := FALSE, use_median := FALSE, mapq := 0, min_frag_len := -1, max_frag_len := -1, precision_digits := 2, quantize := NULL, thresholds := NULL, index_path := NULL, overwrite := FALSE)	table	rduckhts_mosdepth	Write native mosdepth-compatible coverage outputs for indexed BAM or CRAM input. Produces mosdepth-style summary, global distribution, per-base BED.gz + CSI, optional window/BED region outputs, optional quantized BED.gz + CSI, and optional threshold counts for `by`; `fast_mode` defaults to FALSE to match upstream mosdepth, default mode performs CIGAR-aware coverage with mate-overlap correction, `fragment_mode` switches coverage to full-fragment insert spans for proper pairs, `use_median` switches `by` outputs from mean to median, `read_groups` filters by comma-separated RG IDs, `min_frag_len` and `max_frag_len` filter on absolute template length, `fasta` is required for CRAM when htslib needs a reference, `precision_digits` controls decimal places in the text outputs, and `processing_threads` enables parallel contig processing (0 = sequential, >0 = number of worker threads).	SELECT * FROM duckhts_mosdepth('sample', 'range.cram', fasta := 'ce.fa', by := '1000', fragment_mode := TRUE, read_groups := '1', use_median := TRUE, min_frag_len := 50, max_frag_len := 500, quantize := ':1:4:', thresholds := '1,10,20', precision_digits := 4, overwrite := TRUE);
duckhts_samtools_idxstats	table	Metadata	duckhts_samtools_idxstats(path, output := NULL, index_path := NULL, threads := 0, overwrite := FALSE)	table	rduckhts_samtools_idxstats	Write samtools idxstats-compatible TAB-delimited output for BAM, CRAM, or SAM input. Indexed BAM uses `hts_idx_get_stat(...)` for the fast path; CRAM, SAM, and unindexed BAM fall back to a full scan while preserving samtools-style contig rows plus the final `*` row.	SELECT * FROM duckhts_samtools_idxstats('range.bam', output := 'range.idxstats.txt', overwrite := TRUE);
read_hts_header	table	Metadata	read_hts_header(path, format := NULL, mode := NULL)	table	rduckhts_hts_header	Inspect HTS headers in parsed, raw, or combined form across supported formats. Raw VCF/BCF mode includes the final `#CHROM` sample header line so the returned text is suitable for Parquet metadata and future VCF/BCF regeneration.	SELECT record_type, id FROM read_hts_header('formatcols.vcf.gz') LIMIT 10;
read_hts_index	table	Metadata	read_hts_index(path, format := NULL, index_path := NULL)	table	rduckhts_hts_index	Inspect high-level HTS index metadata such as sequence names and mapped counts.	SELECT seqname, index_type FROM read_hts_index('vcf_file.bcf');
read_hts_index_spans	table	Metadata	read_hts_index_spans(path, format := NULL, index_path := NULL)	table	rduckhts_hts_index_spans	Expand index metadata into span and chunk rows suitable for low-level index inspection.	SELECT seqname, chunk_beg_vo, chunk_end_vo FROM read_hts_index_spans('vcf_file.bcf') LIMIT 5;
read_hts_index_raw	table_macro	Metadata	read_hts_index_raw(path, format := NULL, index_path := NULL)	table	rduckhts_hts_index_raw	Return the raw on-disk HTS index blob together with basic identifying metadata.	SELECT length(raw) FROM read_hts_index_raw('formatcols.vcf.gz');
variantkey	scalar	Variants	variantkey(chrom, pos, ref, alt)	UBIGINT		Encode a normalized biallelic variant as an official VariantKey-compatible 64-bit unsigned integer. This DuckHTS wrapper accepts 1-based VCF/DuckHTS POS to match bcftools `%VKX` / `+add-variantkey`, internally converts to the upstream 0-based field, and preserves the official hashed nonreversible mode for large, ambiguous, and symbolic REF/ALT strings. Only CHROM, POS, REF, and ALT are encoded; END, SVLEN, mate breakend coordinates, and other SV metadata are not.	SELECT variantkey_hex(variantkey('1', 324684, 'C', 'G'));
variantkey_hex	scalar	Variants	variantkey_hex(vk)	VARCHAR		Render a VariantKey as its lowercase 16-character hexadecimal string representation.	SELECT variantkey_hex(variantkey('1', 324684, 'C', 'G'));
parse_variantkey_hex	scalar	Variants	parse_variantkey_hex(hex)	UBIGINT		Parse a 16-character hexadecimal VariantKey string back into its UBIGINT code. Invalid or non-hex strings return NULL.	SELECT parse_variantkey_hex('08027a2588b00000');
encode_variantkey	scalar	Variants	encode_variantkey(chrom_code, pos0, refalt_code)	UBIGINT		Encode the raw upstream VariantKey fields directly: chromosome code, 0-based position, and 31-bit REF+ALT code.	SELECT variantkey_hex(encode_variantkey(1, 324683, 145752064));
extract_variantkey_chrom	scalar	Variants	extract_variantkey_chrom(vk)	UTINYINT		Extract the raw upstream VariantKey chromosome code.	SELECT extract_variantkey_chrom(parse_variantkey_hex('08027a2588b00000'));
extract_variantkey_pos	scalar	Variants	extract_variantkey_pos(vk)	UINTEGER		Extract the raw upstream VariantKey 0-based position field.	SELECT extract_variantkey_pos(parse_variantkey_hex('08027a2588b00000'));
extract_variantkey_refalt	scalar	Variants	extract_variantkey_refalt(vk)	UINTEGER		Extract the raw upstream 31-bit VariantKey REF+ALT code.	SELECT extract_variantkey_refalt(parse_variantkey_hex('08027a2588b00000'));
decode_variantkey	scalar	Variants	decode_variantkey(vk)	STRUCT		Decode a VariantKey into its raw upstream numeric fields: chrom_code, pos0, and refalt_code.	SELECT (decode_variantkey(parse_variantkey_hex('08027a2588b00000'))).pos0;
reverse_variantkey	scalar	Variants	reverse_variantkey(vk)	STRUCT		Decode a VariantKey into a STRUCT with chrom, chrom_code, 1-based pos, upstream 0-based pos0, ref, alt, refalt_code, and reversible. For hashed nonreversible keys, reversible is FALSE and ref/alt are returned as NULL because DuckHTS v1 does not ship the optional NRVK lookup sidecar.	SELECT (reverse_variantkey(parse_variantkey_hex('08027a2588b00000'))).ref;
variantkey_range	scalar	Variants	variantkey_range(chrom, pos_min, pos_max)	STRUCT		Return the inclusive minimum and maximum VariantKey bounds for a chromosome plus 1-based VCF position range, suitable for numeric range filtering on precomputed VariantKeys.	SELECT variantkey_hex((variantkey_range('1', 100, 100)).min), variantkey_hex((variantkey_range('1', 100, 100)).max);
regionkey	scalar	Intervals	regionkey(chrom, start, end, strand := 0)	UBIGINT		Encode a genomic interval as an official RegionKey-compatible 64-bit unsigned integer. Start and end use 0-based half-open interval semantics, matching BED-style coordinates; strand accepts -1, 0, or 1.	SELECT regionkey_hex(regionkey('X', 1007, 1807, 1));
regionkey_hex	scalar	Intervals	regionkey_hex(rk)	VARCHAR		Render a RegionKey as its lowercase 16-character hexadecimal string representation.	SELECT regionkey_hex(regionkey('X', 1007, 1807, 1));
parse_regionkey_hex	scalar	Intervals	parse_regionkey_hex(hex)	UBIGINT		Parse a 16-character hexadecimal RegionKey string back into its UBIGINT code. Invalid or non-hex strings return NULL.	SELECT parse_regionkey_hex('b80001f78000387a');
encode_regionkey	scalar	Intervals	encode_regionkey(chrom_code, start, end, strand_code)	UBIGINT		Encode the raw upstream RegionKey fields directly: chromosome code, 0-based start, 0-based end, and strand code (0 = unknown, 1 = +, 2 = -).	SELECT regionkey_hex(encode_regionkey(23, 1007, 1807, 1));
extract_regionkey_chrom	scalar	Intervals	extract_regionkey_chrom(rk)	UTINYINT		Extract the raw upstream RegionKey chromosome code.	SELECT extract_regionkey_chrom(parse_regionkey_hex('b80001f78000387a'));
extract_regionkey_startpos	scalar	Intervals	extract_regionkey_startpos(rk)	UINTEGER		Extract the raw upstream RegionKey 0-based start position.	SELECT extract_regionkey_startpos(parse_regionkey_hex('b80001f78000387a'));
extract_regionkey_endpos	scalar	Intervals	extract_regionkey_endpos(rk)	UINTEGER		Extract the raw upstream RegionKey 0-based end position.	SELECT extract_regionkey_endpos(parse_regionkey_hex('b80001f78000387a'));
extract_regionkey_strand	scalar	Intervals	extract_regionkey_strand(rk)	UTINYINT		Extract the raw upstream RegionKey strand code (0 = unknown, 1 = +, 2 = -).	SELECT extract_regionkey_strand(parse_regionkey_hex('b80001f78000387a'));
decode_regionkey	scalar	Intervals	decode_regionkey(rk)	STRUCT		Decode a RegionKey into its raw upstream numeric fields: chrom_code, start, end, and strand_code.	SELECT (decode_regionkey(parse_regionkey_hex('b80001f78000387a'))).strand_code;
reverse_regionkey	scalar	Intervals	reverse_regionkey(rk)	STRUCT		Decode a RegionKey into a STRUCT with chrom, chrom_code, start, end, strand, and strand_code.	SELECT (reverse_regionkey(parse_regionkey_hex('b80001f78000387a'))).strand;
extend_regionkey	scalar	Intervals	extend_regionkey(rk, size)	UBIGINT		Extend a RegionKey interval by a fixed number of bases on both sides, clamping to the official 28-bit RegionKey position range.	SELECT reverse_regionkey(extend_regionkey(regionkey('X', 10000, 20000, -1), 1000));
duckhts_contig_key	scalar	Variants	duckhts_contig_key(contig)	VARCHAR		Return a conservative contig join key by removing one non-empty leading chr prefix case-insensitively and normalizing M/MT to MT. X and Y are uppercased; all other suffixes are preserved. This does not map numeric sex chromosomes, accessions, patches, or alternate loci.	SELECT duckhts_contig_key('chr1'), duckhts_contig_key('chrM');
are_overlapping_regions	scalar	Intervals	are_overlapping_regions(chrom_a, start_a, end_a, chrom_b, start_b, end_b)	BOOLEAN		Return TRUE when two explicit 0-based half-open intervals overlap on the same canonical chromosome.	SELECT are_overlapping_regions('1', 2, 4, '1', 3, 7);
are_overlapping_region_regionkey	scalar	Intervals	are_overlapping_region_regionkey(chrom, start, end, rk)	BOOLEAN		Return TRUE when a 0-based half-open interval overlaps the supplied RegionKey interval.	SELECT are_overlapping_region_regionkey('X', 1008, 1800, parse_regionkey_hex('b80001f78000387a'));
are_overlapping_regionkeys	scalar	Intervals	are_overlapping_regionkeys(rka, rkb)	BOOLEAN		Return TRUE when two RegionKeys overlap.	SELECT are_overlapping_regionkeys(regionkey('X', 1007, 1807, 1), parse_regionkey_hex('b80001f78000387a'));
bcftools_liftover	scalar	Variants	bcftools_liftover(chrom, pos, ref, alt, chain_path, dst_fasta_ref, src_fasta_ref, max_snp_gap, max_indel_inc, lift_mt, end_pos, no_left_align)	STRUCT	rduckhts_liftover	Row-oriented liftover kernel intended to mirror bcftools +liftover semantics as closely as possible while returning one STRUCT per input row with fields: src_chrom, src_pos, src_ref, src_alt, dest_chrom, dest_pos, dest_end, dest_ref, dest_alt, mapped, reverse_complemented, swap, reject_reason, and note. Set no_left_align := true to skip post-liftover left-alignment of lifted indels (mirrors --no-left-align in bcftools +liftover).	SELECT (bcftools_liftover(chrom, pos, ref, alt, 'hg19ToHg38.over.chain.gz', 'hg38.fa', 'hg19.fa', 1, 250, false, NULL::BIGINT, false)).dest_pos FROM variants;
duckdb_liftover	table_macro	Variants	duckdb_liftover(table_name, chrom_col, pos_col, ref_col := NULL, alt_col := NULL, chain_path := NULL, dst_fasta_ref := NULL, src_fasta_ref := NULL, max_snp_gap := 1, max_indel_inc := 250, lift_mt := false, end_pos_col := NULL, no_left_align := false)	table	rduckhts_liftover	DuckDB-specific wrapper over bcftools_liftover that takes either a table name or a derived-table expression plus column-name strings for chrom/pos/ref/alt and returns the lifted table. The no_left_align parameter mirrors --no-left-align in bcftools +liftover.	SELECT * FROM duckdb_liftover('variants', 'chrom', 'pos', ref_col := 'ref', alt_col := 'alt', chain_path := 'hg19ToHg38.over.chain.gz', dst_fasta_ref := 'hg38.fa'); || SELECT * FROM duckdb_liftover('(SELECT chrom, pos, ref, alt FROM variants) AS v', 'chrom', 'pos', ref_col := 'ref', alt_col := 'alt', chain_path := 'hg19ToHg38.over.chain.gz', dst_fasta_ref := 'hg38.fa');
bcftools_norm_row	scalar	Variants	bcftools_norm_row(chrom, pos, ref, alt, fasta_ref, end_pos := NULL, svlen := NULL, fasta_index_path := NULL, gzi_path := NULL)	STRUCT		Normalize one variant row with bcftools/vt-style left-alignment semantics against a FASTA reference. The alt argument may be either a comma-delimited VARCHAR or a VARCHAR[] list. The returned STRUCT contains pos_normed, end_pos_normed, ref_normed, alt_normed (always VARCHAR[]), normed (TRUE/FALSE/NULL), and norm_status. Symbolic <DEL> rows can use end_pos, and symbolic <DUP> rows can use svlen. gVCF <NON_REF>/<*> reference-block alleles pass through with GVCFReferenceBlock, and mixed real-plus-gVCF-symbolic alleles normalize the real alleles while preserving symbolic alleles and caller-supplied reference-block END in site-preserving output.	SELECT nr.pos_normed, nr.ref_normed, nr.alt_normed FROM (SELECT bcftools_norm_row('chr1', 100, 'AC', 'A', 'ref.fa', NULL::BIGINT, NULL::BIGINT, NULL, NULL) AS nr);
duckhts_bcftools_norm	table_macro	Variants	duckhts_bcftools_norm(table_name, fasta_ref, chrom_col := 'chrom', pos_col := 'pos', ref_col := 'ref', alt_col := 'alt', split_multiallelic := FALSE, end_pos_col := NULL, svlen_col := NULL, fasta_index_path := NULL, gzi_path := NULL)	table	rduckhts_bcftools_norm	DuckDB table macro wrapper over bcftools_norm_row that normalizes variants from a table or derived-table expression while preserving the original columns. The input ALT column may be either VARCHAR or VARCHAR[]. The result appends pos_normed, end_pos_normed, ref_normed, alt_normed, normed, and norm_status; with split_multiallelic := TRUE, multiallelic sites are split before normalization and alt_normed becomes VARCHAR plus alt_index. This is a vt/vcfnorm-style row/table transform, not a full-record VCF/BCF rewrite: genotype, PL/GP/DS, and PS fields are preserved as caller columns unless a separate full-record writer/remapper layer is used.	SELECT * FROM duckhts_bcftools_norm('variants', 'ref.fa'); || SELECT * FROM duckhts_bcftools_norm('(SELECT CHROM AS chrom, POS AS pos, REF AS ref, ALT AS alt FROM read_bcf(''cohort.vcf.gz'')) AS v', 'ref.fa', split_multiallelic := TRUE);
bcftools_score	table	Variants	bcftools_score(bcf_path, summary_path_or_list, use := NULL, columns := 'PLINK', columns_file := NULL, q_score_thr := NULL, summaries_list_file := NULL, log_path := NULL, use_variant_id := FALSE, counts := FALSE, samples := NULL, force_samples := FALSE, regions := NULL, regions_file := NULL, regions_overlap := 1, targets := NULL, targets_file := NULL, targets_overlap := 0, apply_filters := NULL, include := NULL, exclude := NULL)	table	rduckhts_score	Compute polygenic scores from one genotype BCF/VCF and one or more summary-statistics files with bcftools +score-compatible GT/DS/HDS/AP/GP/AS dosage semantics, sample subsetting, and region/target/FILTER-string controls. The second argument accepts a scalar path or a DuckDB LIST/array of paths; TSV/SSF summaries produce one PRS column per file in a single genotype scan, while GWAS-VCF summaries still produce one PRS column per FORMAT sample. Use summaries_list_file with a NULL second argument to read paths from a file or directory; list-file entries are interpreted as written, matching upstream `bcftools +score --summaries` behavior, while directory inputs scan supported regular summary files in lexicographic order and ignore index sidecars. Use log_path to write per-PRS loaded/matched/allele-mismatch/duplicate-marker audit counts.	SELECT * FROM bcftools_score('cohort.bcf', 'gwas.tsv.gz', columns := 'PLINK') LIMIT 5; || SELECT * FROM bcftools_score('cohort.bcf', ['score1.tsv.gz', 'score2.tsv.gz'], columns := 'GWAS-SSF') LIMIT 5; || SELECT * FROM bcftools_score('cohort.bcf', NULL, columns := 'GWAS-SSF', summaries_list_file := 'scores.list', log_path := 'score.log') LIMIT 5;
bcftools_munge_row	scalar	Variants	bcftools_munge_row(chrom, pos, a1, a2, id, p, z, or, beta, n, n_cas, n_con, info, frq, se, lp, ac, neff, neffdiv2, het_i2, het_p, het_lp, dire, fasta_ref, iffy_tag := 'IFFY', mismatch_tag := 'REF_MISMATCH', ns := NULL, nc := NULL, ne := NULL)	STRUCT		Normalize one summary-statistics row into GWAS-VCF-style fields (chrom/pos/ref/alt/effect metrics), resolving REF/ALT orientation against a FASTA reference and applying swap-aware sign/frequency/count transforms. The output flag `alleles_swapped` means REF/ALT orientation was swapped to match the FASTA reference.	SELECT (bcftools_munge_row('chr1', 12345, 'A', 'G', 'rs1', 0.01, NULL, NULL, 0.12, 1000, NULL, NULL, NULL, 0.3, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, 'ref.fa')).ref;
duckdb_munge	table_macro	Variants	duckdb_munge(table_name, preset := '', column_map := map([''], ['']), column_map_file := '', fasta_ref := NULL, iffy_tag := 'IFFY', mismatch_tag := 'REF_MISMATCH', ns := NULL, nc := NULL, ne := NULL)	table	rduckhts_munge	DuckDB macro wrapper over bcftools_munge_row that maps source columns (via preset or explicit map) and returns normalized GWAS-VCF-style rows with lean outputs and explicit `alleles_swapped` semantics. Output columns: chrom, pos, id, ref, alt, alleles_swapped, filter, ns, ez, nc, es, se, lp, af, ac, ne (16 columns). For METAL meta-analysis output with SI/I2/CQ/ED columns, use duckdb_munge_metal.	SELECT * FROM duckdb_munge('gwas_table', preset := 'PLINK', fasta_ref := 'ref.fa'); || SELECT * FROM duckdb_munge('(SELECT * FROM gwas_table) AS s', column_map := map(['CHR','BP','A1','A2','SNP'], ['chrom','pos','ea','nea','id']), fasta_ref := 'ref.fa');
duckdb_munge_metal	table_macro	Variants	duckdb_munge_metal(table_name, preset := '', column_map := map([''], ['']), column_map_file := '', fasta_ref := NULL, iffy_tag := 'IFFY', mismatch_tag := 'REF_MISMATCH', ns := NULL, nc := NULL, ne := NULL)	table	rduckhts_munge	Extended munge macro with METAL meta-analysis output columns. Same as duckdb_munge but additionally emits: si (imputation info, from INFO input), i2 (Cochran's I² heterogeneity, from HET_I2), cq (Cochran's Q -log10 p, from HET_LP or -log10(HET_P)), and ed (effect direction string, from DIRE; +/- flipped on allele swap). The R wrapper rduckhts_munge() auto-dispatches to this macro when metal keys (INFO, HET_I2, HET_P, HET_LP, DIRE) are present in the resolved column map.	SELECT * FROM duckdb_munge_metal('metal_results', preset := 'METAL', fasta_ref := 'ref.fa'); || SELECT * FROM duckdb_munge_metal('meta', column_map := map(['CHR','BP','A1','A2','SNP','HET_I2','DIRE'], ['chr','pos','ea','nea','snp','HetISq','Direction']), fasta_ref := 'ref.fa');
hts_union_query	scalar_macro	Readers	hts_union_query(reader, pattern, params := '')	VARCHAR	rduckhts_bam_multi, rduckhts_bcf_multi, rduckhts_fastq_multi, rduckhts_fasta_multi, rduckhts_bed_multi, rduckhts_tabix_multi, rduckhts_gff_multi, rduckhts_gtf_multi	Generate a UNION ALL BY NAME query string that reads every file matching a glob pattern through the named reader function. The result includes a 'filename' column identifying the source file for each row. Assign to a variable with SET VARIABLE and execute via query(getvariable(...)). Optional params string is appended to each reader call. In R, use the typed rduckhts_*_multi() helpers instead, which accept file vectors with optional per-file parameters and create DuckDB tables directly.	SET VARIABLE q = hts_union_query('read_bam', 'samples/*.bam'); SELECT * FROM query(getvariable('q')); || SET VARIABLE q = hts_union_query('read_bcf', 'cohort/*.vcf.gz', 'tidy_format := true'); SELECT * FROM query(getvariable('q'));
hts_region_union_query	scalar_macro	Readers	hts_region_union_query(reader, path, regions, params := '')	VARCHAR		Generate a UNION ALL BY NAME query string that reads one HTS file through separate per-region table-function scans. The result adds filename, duckhts_region_shard_id, and duckhts_region_shard columns so benchmark queries can compare region-sharded execution and explicit ordered writes. Pass regions as a DuckDB list of region strings; params is appended to each reader call and should not include region. The generated UNION ALL does not deduplicate records; adjacent or overlapping shards can duplicate BAM alignments or BCF/VCF records that span shard boundaries, so add explicit shard-local filters or downstream deduplication when exact once-only semantics are required.	SET VARIABLE q = hts_region_union_query('read_bam', 'sample.bam', ['chr1:1-1000000','chr1:1000001-2000000']); SELECT * FROM query(getvariable('q')); || SET VARIABLE q = hts_region_union_query('read_bcf', 'cohort.vcf.gz', string_split('22:16000000-16999999,22:17000000-17999999', ','), 'tidy_format := true'); SELECT * FROM query(getvariable('q'));
seq_revcomp	scalar	Sequence UDFs	seq_revcomp(sequence)	VARCHAR		Compute the reverse complement of a DNA sequence using A, C, G, T, and N bases. Overloaded: accepts either a VARCHAR text sequence (returns VARCHAR) or a UTINYINT[] of htslib nt16 codes as produced by read_bam(sequence_encoding := 'nt16') (returns UTINYINT[]); the nt16 overload is bit-identical to the text path after decoding, so BAM pipelines can reverse-complement without leaving the nt16 encoding.	SELECT seq_revcomp('ACGTN'); || SELECT seq_revcomp(SEQ) FROM read_bam('reads.bam', sequence_encoding := 'nt16');
seq_canonical	scalar	Sequence UDFs	seq_canonical(sequence)	VARCHAR		Return the lexicographically smaller of a sequence and its reverse complement. Overloaded: accepts either a VARCHAR text sequence (returns VARCHAR) or a UTINYINT[] of htslib nt16 codes as produced by read_bam(sequence_encoding := 'nt16') (returns UTINYINT[]); the nt16 overload compares by decoded base order and is bit-identical to the text path after decoding.	SELECT seq_canonical('ACGTN'); || SELECT seq_canonical(SEQ) FROM read_bam('reads.bam', sequence_encoding := 'nt16');
seq_hash_2bit	scalar	Sequence UDFs	seq_hash_2bit(sequence)	UBIGINT		Encode a short DNA sequence as a 2-bit unsigned integer hash. Overloaded to also accept a UTINYINT[] of htslib nt16 codes (from read_bam(sequence_encoding := 'nt16')); non-ACGT codes yield NULL, bit-identical to the text path.	SELECT seq_hash_2bit('ACGT');
seq_encode_4bit	scalar	Sequence UDFs	seq_encode_4bit(sequence)	UTINYINT[]		Encode an IUPAC DNA sequence as a list of 4-bit base codes, preserving ambiguity symbols including N.	SELECT seq_encode_4bit('ACGTRYSWKMBDHVN');
seq_decode_4bit	scalar	Sequence UDFs	seq_decode_4bit(codes)	VARCHAR		Decode a list of 4-bit IUPAC DNA base codes back into a sequence string.	SELECT seq_decode_4bit(seq_encode_4bit('ACGTRYSWKMBDHVN'));
seq_gc_content	scalar	Sequence UDFs	seq_gc_content(sequence)	DOUBLE		Compute GC fraction for a DNA sequence as a value between 0 and 1. Overloaded: accepts either a VARCHAR text sequence or a UTINYINT[] of htslib nt16 codes as produced by read_bam(sequence_encoding := 'nt16'); the nt16 overload classifies codes directly and is bit-identical to the text path, so BAM pipelines can compute GC without decoding sequences back to text.	SELECT seq_gc_content('ACGT'); || SELECT seq_gc_content(SEQ) FROM read_bam('reads.bam', sequence_encoding := 'nt16');
seq_kmers	table	Sequence UDFs	seq_kmers(sequence, k, canonical := FALSE)	table		Expand a sequence into positional k-mers with optional canonicalization.	SELECT * FROM seq_kmers('ACGT', 2);
sam_flag_bits	scalar	SAM Flag UDFs	sam_flag_bits(flag)	STRUCT		Decode a SAM flag into a struct of boolean bit fields using explicit SAM-oriented names such as `is_paired`, `is_proper_pair`, `is_next_segment_unmapped`, and `is_supplementary`.	SELECT (sam_flag_bits(99)).is_proper_pair;
sam_flag_has	scalar	SAM Flag UDFs	sam_flag_has(flag, mask)	BOOLEAN		Test whether any bits from the provided SAM flag mask are set in a flag value.	SELECT sam_flag_has(99, 2);
is_forward_aligned	scalar	SAM Flag UDFs	is_forward_aligned(flag)	BOOLEAN		Test whether a mapped segment is aligned to the forward strand. Returns `NULL` for unmapped segments because SAM flag `0x10` does not define genomic strand when `0x4` is set.	SELECT is_forward_aligned(0);
cigar_has_soft_clip	scalar	CIGAR Utils	cigar_has_soft_clip(cigar)	BOOLEAN		Test whether a CIGAR string contains any soft-clipped segment (`S`). Overloaded to also accept a UINTEGER[] binary CIGAR (as produced by read_bam(cigar_representation := 'binary')); the binary overload is bit-identical to the text path.	SELECT cigar_has_soft_clip('5S90M5S');
cigar_has_hard_clip	scalar	CIGAR Utils	cigar_has_hard_clip(cigar)	BOOLEAN		Test whether a CIGAR string contains any hard-clipped segment (`H`). Overloaded to also accept a UINTEGER[] binary CIGAR (as produced by read_bam(cigar_representation := 'binary')); the binary overload is bit-identical to the text path.	SELECT cigar_has_hard_clip('5H95M');
cigar_left_soft_clip	scalar	CIGAR Utils	cigar_left_soft_clip(cigar)	BIGINT		Return the left-end soft-clipped length from a CIGAR string, or zero if the alignment does not start with `S`. Overloaded to also accept a UINTEGER[] binary CIGAR (as produced by read_bam(cigar_representation := 'binary')); the binary overload is bit-identical to the text path.	SELECT cigar_left_soft_clip('5S90M5S');
cigar_right_soft_clip	scalar	CIGAR Utils	cigar_right_soft_clip(cigar)	BIGINT		Return the right-end soft-clipped length from a CIGAR string, or zero if the alignment does not end with `S`. Overloaded to also accept a UINTEGER[] binary CIGAR (as produced by read_bam(cigar_representation := 'binary')); the binary overload is bit-identical to the text path.	SELECT cigar_right_soft_clip('5S90M5S');
cigar_query_length	scalar	CIGAR Utils	cigar_query_length(cigar)	BIGINT		Return the query-consuming length from a CIGAR string, counting `M`, `I`, `S`, `=`, and `X`. Overloaded to also accept a UINTEGER[] binary CIGAR (as produced by read_bam(cigar_representation := 'binary')); the binary overload is bit-identical to the text path.	SELECT cigar_query_length('5S90M5I');
cigar_aligned_query_length	scalar	CIGAR Utils	cigar_aligned_query_length(cigar)	BIGINT		Return the aligned query length from a CIGAR string, counting `M`, `=`, and `X` but excluding clips and insertions. Overloaded to also accept a UINTEGER[] binary CIGAR (as produced by read_bam(cigar_representation := 'binary')); the binary overload is bit-identical to the text path.	SELECT cigar_aligned_query_length('5S90M5I');
cigar_reference_length	scalar	CIGAR Utils	cigar_reference_length(cigar)	BIGINT		Return the reference-consuming length from a CIGAR string, counting `M`, `D`, `N`, `=`, and `X`. Overloaded to also accept a UINTEGER[] binary CIGAR (as produced by read_bam(cigar_representation := 'binary')); the binary overload is bit-identical to the text path.	SELECT cigar_reference_length('90M5D');
cigar_has_op	scalar	CIGAR Utils	cigar_has_op(cigar, op)	BOOLEAN		Test whether a CIGAR string contains at least one instance of the requested operator. Overloaded to also accept a UINTEGER[] binary CIGAR (as produced by read_bam(cigar_representation := 'binary')); the binary overload is bit-identical to the text path.	SELECT cigar_has_op('5S90M5S', 'S');
is_paired	scalar	SAM Flag UDFs	is_paired(flag)	BOOLEAN		Test whether the SAM flag indicates that the template has multiple segments in sequencing (`0x1`).	SELECT is_paired(99);
is_proper_pair	scalar	SAM Flag UDFs	is_proper_pair(flag)	BOOLEAN		Test whether the SAM flag indicates that each segment is properly aligned according to the aligner (`0x2`).	SELECT is_proper_pair(99);
is_unmapped	scalar	SAM Flag UDFs	is_unmapped(flag)	BOOLEAN		Test whether the read itself is unmapped according to the SAM flag.	SELECT is_unmapped(4);
is_next_segment_unmapped	scalar	SAM Flag UDFs	is_next_segment_unmapped(flag)	BOOLEAN		Test whether the next segment in the template is flagged as unmapped (`0x8`).	SELECT is_next_segment_unmapped(9);
is_reverse_complemented	scalar	SAM Flag UDFs	is_reverse_complemented(flag)	BOOLEAN		Test whether `SEQ` is stored reverse complemented (`0x10`); for mapped reads this corresponds to reverse-strand alignment.	SELECT is_reverse_complemented(16);
is_next_segment_reverse_complemented	scalar	SAM Flag UDFs	is_next_segment_reverse_complemented(flag)	BOOLEAN		Test whether `SEQ` of the next segment in the template is stored reverse complemented (`0x20`).	SELECT is_next_segment_reverse_complemented(32);
is_first_segment	scalar	SAM Flag UDFs	is_first_segment(flag)	BOOLEAN		Test whether the read is marked as the first segment in the template.	SELECT is_first_segment(64);
is_last_segment	scalar	SAM Flag UDFs	is_last_segment(flag)	BOOLEAN		Test whether the read is marked as the last segment in the template.	SELECT is_last_segment(128);
is_secondary	scalar	SAM Flag UDFs	is_secondary(flag)	BOOLEAN		Test whether the alignment is marked as secondary.	SELECT is_secondary(256);
is_qc_fail	scalar	SAM Flag UDFs	is_qc_fail(flag)	BOOLEAN		Test whether the read failed vendor or pipeline quality checks.	SELECT is_qc_fail(512);
is_duplicate	scalar	SAM Flag UDFs	is_duplicate(flag)	BOOLEAN		Test whether the alignment is flagged as a duplicate.	SELECT is_duplicate(1024);
is_supplementary	scalar	SAM Flag UDFs	is_supplementary(flag)	BOOLEAN		Test whether the alignment is marked as supplementary.	SELECT is_supplementary(2048);
