Struct Value 

pub struct Value { /* private fields */ }

An owned, RAII-managed DuckDB value.

When dropped, the underlying duckdb_value handle is destroyed via duckdb_destroy_value. This eliminates the manual duckdb_destroy_value calls that are easy to forget and lead to memory leaks.

Creation

Obtain a Value from:

• BindInfo::get_parameter_value
• BindInfo::get_named_parameter_value
• Value::from_raw (escape hatch for raw duckdb_value handles)

Extraction

Use typed accessors to extract the underlying data:

• as_str — VARCHAR → String
• as_blob — BLOB → Vec<u8>
• as_i32 — INTEGER → i32
• as_i64 — BIGINT → i64
• as_f32 — FLOAT → f32
• as_f64 — DOUBLE → f64
• as_bool — BOOLEAN → bool

Implementations

impl Value

pub fn as_blob(&self) -> Result<Vec<u8>, ExtensionError>

Extracts the value as an owned Vec<u8> (BLOB).

DuckDB allocates the blob’s backing buffer; this method copies it into an owned Vec<u8> and frees the original with duckdb_free. The bytes are copied without UTF-8 validation.

Errors

Returns ExtensionError if the value handle is null, duckdb_get_blob returns a null data pointer for a non-empty blob, or the blob size cannot be represented by usize on the current platform.

impl Value

pub const unsafe fn from_raw(raw: duckdb_value) -> Self

Wraps a raw duckdb_value handle.

The returned Value takes ownership and will call duckdb_destroy_value on drop.

Safety

raw must be a valid duckdb_value obtained from a DuckDB API call (e.g., duckdb_bind_get_parameter). The caller must not destroy the value after passing it to this function.

pub fn as_str(&self) -> Result<String, ExtensionError>

Extracts the value as a String (VARCHAR).

Internally calls duckdb_get_varchar and frees the returned C string with duckdb_free. Returns an error if the string is not valid UTF-8 or if the value handle is null.

Embedded NUL bytes

duckdb_get_varchar returns a NUL-terminated char *, so a value whose text contains an interior NUL is truncated at the first one. DuckDB itself stores the full bytes; only this read path is limited. If the text may contain NULs, keep it in a BLOB and use as_blob.

Errors

Returns ExtensionError if the value is null or contains invalid UTF-8.

pub fn as_i32(&self) -> i32

Extracts the value as an i32 (INTEGER).

DuckDB will attempt to cast the value to INTEGER. If the value is not numeric, this returns 0.

pub fn as_i64(&self) -> i64

Extracts the value as an i64 (BIGINT).

DuckDB will attempt to cast the value to BIGINT. If the value is not numeric, this returns 0.

pub fn as_f32(&self) -> f32

Extracts the value as an f32 (FLOAT).

DuckDB will attempt to cast the value to FLOAT. If the value is not numeric, this returns 0.0.

pub fn as_f64(&self) -> f64

Extracts the value as an f64 (DOUBLE).

DuckDB will attempt to cast the value to DOUBLE. If the value is not numeric, this returns 0.0.

pub fn as_bool(&self) -> bool

Extracts the value as a bool (BOOLEAN).

DuckDB will attempt to cast the value to BOOLEAN. If the value is not convertible, this returns false.

pub fn as_i8(&self) -> i8

Extracts the value as an i8 (TINYINT).

DuckDB will attempt to cast the value to TINYINT. If the value is not numeric, this returns 0.

pub fn as_i16(&self) -> i16

Extracts the value as an i16 (SMALLINT).

DuckDB will attempt to cast the value to SMALLINT. If the value is not numeric, this returns 0.

pub fn as_u8(&self) -> u8

Extracts the value as a u8 (UTINYINT).

DuckDB will attempt to cast the value to UTINYINT. If the value is not numeric, this returns 0.

pub fn as_u16(&self) -> u16

Extracts the value as a u16 (USMALLINT).

DuckDB will attempt to cast the value to USMALLINT. If the value is not numeric, this returns 0.

pub fn as_u32(&self) -> u32

Extracts the value as a u32 (UINTEGER).

DuckDB will attempt to cast the value to UINTEGER. If the value is not numeric, this returns 0.

pub fn as_u64(&self) -> u64

Extracts the value as a u64 (UBIGINT).

DuckDB will attempt to cast the value to UBIGINT. If the value is not numeric, this returns 0.

pub fn as_i128(&self) -> i128

Extracts the value as an i128 (HUGEINT).

DuckDB returns HUGEINT as { lower: u64, upper: i64 }. This method reconstructs the full i128 value.

pub fn as_str_or(&self, default: &str) -> String

Extracts the value as a String, returning default on failure.

Convenience for val.as_str().unwrap_or_else(|_| default.to_owned()).

pub fn as_str_or_default(&self) -> String

Extracts the value as a String, returning an empty string on failure.

Convenience for val.as_str().unwrap_or_default().

pub fn as_i32_or(&self, default: i32) -> i32

Extracts the value as an i32, returning default if the handle is null.

pub fn as_i64_or(&self, default: i64) -> i64

Extracts the value as an i64, returning default if the handle is null.

pub fn as_f32_or(&self, default: f32) -> f32

Extracts the value as an f32, returning default if the handle is null.

pub fn as_f64_or(&self, default: f64) -> f64

Extracts the value as an f64, returning default if the handle is null.

pub fn as_bool_or(&self, default: bool) -> bool

Extracts the value as a bool, returning default if the handle is null.

pub fn as_i8_or(&self, default: i8) -> i8

Extracts the value as an i8, returning default if the handle is null.

pub fn as_i16_or(&self, default: i16) -> i16

Extracts the value as an i16, returning default if the handle is null.

pub fn as_u8_or(&self, default: u8) -> u8

Extracts the value as a u8, returning default if the handle is null.

pub fn as_u16_or(&self, default: u16) -> u16

Extracts the value as a u16, returning default if the handle is null.

pub fn as_u32_or(&self, default: u32) -> u32

Extracts the value as a u32, returning default if the handle is null.

pub fn as_u64_or(&self, default: u64) -> u64

Extracts the value as a u64, returning default if the handle is null.

pub fn as_i128_or(&self, default: i128) -> i128

Extracts the value as an i128, returning default if the handle is null.

pub fn time_ns(nanos: i64) -> Self

Creates a TIME_NS value (time of day with nanosecond precision) from a raw nanosecond count (DuckDB 1.5.0+).

Pairs with as_time_ns and the TypeId::TimeNs column type.

pub fn as_time_ns(&self) -> i64

Extracts the value as a TIME_NS nanosecond count (DuckDB 1.5.0+).

Returns 0 if the value is not a TIME_NS.

pub fn display_string(&self) -> Option<String>

Returns the SQL literal representation of this value, as DuckDB would render it (DuckDB 1.5.0+).

Note “SQL literal”, not “text”. A VARCHAR comes back quoted and typed values carry an explicit cast:

Value	display_string()
Value::varchar("hello")	'hello'
Value::bigint(-42)	-42
Value::date(0)	'1970-01-01'::DATE
Value::timestamp(0)	'1970-01-01 00:00:00'::TIMESTAMP

Use as_str for a VARCHAR’s contents. This is for diagnostics and error messages, where it works for any value type.

Returns None if the handle is null or the rendered text is not valid UTF-8.

pub fn as_date(&self) -> i32

Extracts a DATE as days since 1970-01-01.

Returns 0 if the value is not a DATE. Decode it with datetime::date_from_days.

pub fn as_time(&self) -> i64

Extracts a TIME as microseconds since midnight.

Returns 0 if the value is not a TIME.

pub fn as_time_tz(&self) -> u64

Extracts a TIMETZ as DuckDB’s packed 64-bit representation.

Decode it with datetime::time_tz_from_bits.

pub fn as_timestamp(&self) -> i64

Extracts a TIMESTAMP as microseconds since the epoch.

Returns 0 if the value is not a TIMESTAMP.

pub fn as_timestamp_tz(&self) -> i64

Extracts a TIMESTAMPTZ as microseconds since the epoch, in UTC.

pub fn as_timestamp_s(&self) -> i64

Extracts a TIMESTAMP_S as seconds since the epoch.

pub fn as_timestamp_ms(&self) -> i64

Extracts a TIMESTAMP_MS as milliseconds since the epoch.

pub fn as_timestamp_ns(&self) -> i64

Extracts a TIMESTAMP_NS as nanoseconds since the epoch.

pub fn as_interval(&self) -> DuckInterval

Extracts an INTERVAL.

pub fn as_uuid(&self) -> u128

Extracts a UUID as its textual 128 bits, matching VectorReader::read_uuid and uuid.

DuckDB undoes its internal top-bit flip itself here, so this is the value the UUID renders as — not the raw HUGEINT a UUID vector holds.

pub fn as_decimal(&self) -> Decimal

Extracts a DECIMAL as its width, scale and unscaled value.

The represented number is value / 10^scale.

pub fn as_u128(&self) -> u128

Extracts a UHUGEINT as a u128.

pub fn list_len(&self) -> usize

Number of elements in a LIST value.

Returns 0 for non-LIST values.

pub fn list_child(&self, index: usize) -> Option<Self>

Element index of a LIST value, or None if out of range.

The returned Value owns its handle.

pub fn list_items(&self) -> Vec<Self>

Collects a LIST value into a Vec of owned Values.

Example

let files: Vec<String> = paths
    .list_items()
    .iter()
    .filter_map(|v| v.as_str().ok())
    .collect();

pub fn struct_child(&self, index: usize) -> Option<Self>

Field index of a STRUCT value, or None if the handle is null or the index is out of range.

Field names come from the value’s LogicalType, not from the value itself; DuckDB’s C API exposes children by position.

pub fn map_len(&self) -> usize

Number of key/value pairs in a MAP value.

pub fn map_key(&self, index: usize) -> Option<Self>

Key at index of a MAP value, or None if out of range.

pub fn map_value(&self, index: usize) -> Option<Self>

Value at index of a MAP value, or None if out of range.

pub fn boolean(value: bool) -> Self

Creates a BOOLEAN value.

pub fn bigint(value: i64) -> Self

Creates a BIGINT value.

pub fn double(value: f64) -> Self

Creates a DOUBLE value.

pub fn date(days: i32) -> Self

Creates a DATE value from days since 1970-01-01.

pub fn timestamp(micros: i64) -> Self

Creates a TIMESTAMP value from microseconds since the epoch.

pub fn varchar(value: &str) -> Self

Creates a VARCHAR value.

The length is passed explicitly, so no CString conversion can fail and DuckDB stores every byte — but note that as_str reads back through a NUL-terminated C string and will truncate at an interior NUL.

pub fn uuid(bits: u128) -> Self

Creates a UUID value from its textual 128 bits, matching VectorWriter::write_uuid and as_uuid.

DuckDB applies its internal top-bit flip itself here, so these are the bits the value renders as — not the raw HUGEINT a UUID vector holds.

pub fn null_value() -> Self

Creates a SQL NULL value.

pub fn type_id(&self) -> Option<TypeId>

Returns the TypeId this value actually holds.

Every as_* accessor reinterprets the value as a chosen physical type without checking: reading a VARCHAR with as_i64 returns garbage rather than an error. This is the check that makes those accessors safe to use on a value whose type you did not choose — a named parameter, a bound constant, a config option.

Returns None for a null handle, and for a type id introduced by a newer DuckDB than this build of quack-rs knows.

Example

use quack_rs::types::TypeId;
use quack_rs::value::Value;

match value.type_id()? {
    TypeId::BigInt => Some(value.as_i64()),
    TypeId::Integer => Some(i64::from(value.as_i32())),
    _ => None,
}

pub const fn is_null(&self) -> bool

Returns true if the underlying handle is null.

pub const fn as_raw(&self) -> duckdb_value

Returns the raw duckdb_value handle without consuming the Value.

The Value still owns the handle and will destroy it on drop.

pub const fn into_raw(self) -> duckdb_value

Consumes the Value and returns the raw duckdb_value handle.

The caller takes ownership and is responsible for calling duckdb_destroy_value when done.

Trait Implementations

impl Debug for Value

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Prints the value’s type and, where DuckDB can render it, its contents.

Like LogicalType’s impl this calls into DuckDB, so it avoids every path that could panic while formatting.

impl Drop for Value

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.