Skip to main content

LogicalType

Struct LogicalType 

Source
pub struct LogicalType { /* private fields */ }
Expand description

An RAII wrapper around a duckdb_logical_type handle.

Created from a TypeId, this type ensures duckdb_destroy_logical_type is called when it is dropped. This prevents the memory leak described in Pitfall L7.

§Example

use quack_rs::types::{LogicalType, TypeId};

// Requires DuckDB runtime to be initialized (i.e., loaded as an extension).
let lt = LogicalType::new(TypeId::BigInt);
// `lt` is automatically destroyed when it goes out of scope

Implementations§

Source§

impl LogicalType

Source

pub fn new(type_id: TypeId) -> Self

Creates a new LogicalType for the given primitive TypeId.

Calls duckdb_create_logical_type internally.

§Composite types are rejected

duckdb_create_logical_type documents that it “returns an invalid logical type” for DECIMAL, ENUM, LIST, STRUCT, MAP, ARRAY and UNION — and “invalid” there means a non-null handle wrapping LogicalTypeId::INVALID, so a null check does not catch it. Left alone, that surfaces much later as an opaque duckdb_register_*_function failed or as a panic from get_type_id. Each of those types carries parameters a bare id cannot express, so each has its own constructor; see TypeId::is_composite.

§Panics
  • Panics if type_id is composite, naming the constructor to use instead. Use try_new to get a Result.
  • Panics if type_id is TypeId::Variant (duckdb-1-5-3): see try_new.
  • Panics if type_id is TypeId::IntegerLiteral or TypeId::StringLiteral: DuckDB accepts either in a function or type registration, but the first query returning one fails with an internal error that invalidates the database (checked on 1.4.4, 1.5.0 and 1.5.5).
  • Panics if duckdb_create_logical_type returns a null pointer.
§Example
use quack_rs::types::{LogicalType, TypeId};

// Requires DuckDB runtime (called from within a loaded extension).
let lt = LogicalType::new(TypeId::Timestamp);
assert!(!lt.as_raw().is_null());
Source

pub fn try_new(type_id: TypeId) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::new.

Returns an error instead of panicking when type_id is composite (see LogicalType::new), is TypeId::IntegerLiteral or TypeId::StringLiteral, when type_id is TypeId::Variant (with duckdb-1-5-3; a type made from the id alone has no STRUCT layout, and the first query that uses it crashes DuckDB or invalidates the database), when the DuckDB C API returns a null pointer, or when the running DuckDB does not support the type (TIME_NS before 1.5.0, whose C API returns an INVALID type for it; TIMESTAMPTZ_NS before 2.0.0, refused without sending the id: a DuckDB built with assertions aborts on a type id it does not know).

Source

pub fn list(element_type: TypeId) -> Self

Creates a LIST<element_type> logical type.

Lists are variable-length sequences of the given element type.

§Example
use quack_rs::types::{LogicalType, TypeId};

// Requires DuckDB runtime.
let list_of_int = LogicalType::list(TypeId::Integer);
§Panics

Panics if element_type is composite (use list_from_logical) or if duckdb_create_list_type returns null. See try_list.

Source

pub fn try_list(element_type: TypeId) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::list.

Source

pub fn list_from_logical(element: &Self) -> Self

Creates a LIST<element> logical type from an existing LogicalType.

Use this when the element type is itself a complex type (e.g. LIST(STRUCT(...))) that cannot be expressed as a simple TypeId.

§Panics

Panics if duckdb_create_list_type returns null. See try_list_from_logical.

Source

pub fn try_list_from_logical(element: &Self) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::list_from_logical.

Source

pub fn map(key_type: TypeId, value_type: TypeId) -> Self

Creates a MAP<key_type, value_type> logical type.

DuckDB maps are stored as LIST<STRUCT{key: K, value: V}>.

§Panics

Panics if either type is composite (use map_from_logical) or if duckdb_create_map_type returns null. See try_map.

Source

pub fn try_map( key_type: TypeId, value_type: TypeId, ) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::map.

Source

pub fn map_from_logical(key: &Self, value: &Self) -> Self

Creates a MAP<key, value> logical type from existing LogicalTypes.

Use this when the key or value types are complex types that cannot be expressed as simple TypeId values.

§Panics

Panics if duckdb_create_map_type returns null. See try_map_from_logical.

Source

pub fn try_map_from_logical( key: &Self, value: &Self, ) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::map_from_logical.

Source

pub fn struct_type(fields: &[(&str, TypeId)]) -> Self

Creates a STRUCT logical type from a slice of (name, type) field definitions.

§Example
use quack_rs::types::{LogicalType, TypeId};

// Requires DuckDB runtime.
let point = LogicalType::struct_type(&[
    ("x", TypeId::Double),
    ("y", TypeId::Double),
]);
§Panics

Panics where try_struct_type would return an error.

Source

pub fn try_struct_type( fields: &[(&str, TypeId)], ) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::struct_type.

§Errors

See try_struct_type_from_logical; also fails if a field’s TypeId is composite.

Source

pub fn struct_type_from_logical(fields: &[(&str, Self)]) -> Self

Creates a STRUCT logical type from a slice of (name, LogicalType) fields.

Use this when struct members have complex types (e.g. STRUCT(headers MAP(VARCHAR, VARCHAR), body VARCHAR)) that cannot be expressed as simple TypeId values.

§Example
use quack_rs::types::{LogicalType, TypeId};

// STRUCT(status INTEGER, headers MAP(VARCHAR, VARCHAR), body VARCHAR)
let response = LogicalType::struct_type_from_logical(&[
    ("status", LogicalType::new(TypeId::Integer)),
    ("headers", LogicalType::map(TypeId::Varchar, TypeId::Varchar)),
    ("body", LogicalType::new(TypeId::Varchar)),
]);
§Panics

Panics where try_struct_type_from_logical would return an error.

Source

pub fn try_struct_type_from_logical( fields: &[(&str, Self)], ) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::struct_type_from_logical.

§Errors

Returns an error if two field names are equal ignoring ASCII case (DuckDB rejects that type as soon as it is used), if a name contains a null byte, or if duckdb_create_struct_type returns null. Empty names are allowed, as in an unnamed STRUCT.

Source

pub fn decimal(width: u8, scale: u8) -> Self

Creates a DECIMAL(width, scale) logical type.

§Example
use quack_rs::types::LogicalType;

// DECIMAL(18, 3) — 18 total digits, 3 after the decimal point
let price = LogicalType::decimal(18, 3);
§Panics

Panics where try_decimal would return an error.

Source

pub fn try_decimal(width: u8, scale: u8) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::decimal.

§Errors

Returns an error unless 1 <= width <= 38 and scale <= width (Decimal::IsValidWidthScale). The check is made here: DuckDB makes it only from v1.5.4, and before that duckdb_create_decimal_type returns a DECIMAL(0, 0) or DECIMAL(5, 6) it cannot use.

Source

pub fn array(element_type: TypeId, size: u64) -> Self

Creates an ARRAY<element_type>[size] logical type (fixed-size array).

Unlike LIST, arrays have a fixed number of elements known at type definition time.

§Example
use quack_rs::types::{LogicalType, TypeId};

// FLOAT[3] — a 3-element array of floats (e.g., for a 3D vector)
let vec3 = LogicalType::array(TypeId::Float, 3);
§Panics

Panics where try_array would return an error.

Source

pub fn try_array( element_type: TypeId, size: u64, ) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::array.

§Errors

See try_array_from_logical; also fails if element_type is composite.

Source

pub fn array_from_logical(element: &Self, size: u64) -> Self

Creates an ARRAY<element>[size] logical type from an existing LogicalType.

Use this when the element type is itself a complex type.

§Panics

Panics where try_array_from_logical would return an error.

Source

pub fn try_array_from_logical( element: &Self, size: u64, ) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::array_from_logical.

§Errors

Returns an error if size is 0, or if DuckDB refuses the size: duckdb_create_array_type returns null for size >= 100_000 (ArrayType::MAX_ARRAY_SIZE). SQL rejects a size of 0 (“ARRAY type size must be at least 1”), and so does a DuckDB built with assertions (a null handle); a release build creates the type anyway, so it is refused here to behave the same on both.

Source

pub fn union_type(members: &[(&str, TypeId)]) -> Self

Creates a UNION logical type from a slice of (name, type) member definitions.

A UNION can hold one value of any of its member types at a time, similar to a tagged union or sum type.

§Example
use quack_rs::types::{LogicalType, TypeId};

let result = LogicalType::union_type(&[
    ("str", TypeId::Varchar),
    ("num", TypeId::BigInt),
]);
§Panics

Panics where try_union_type would return an error.

Source

pub fn try_union_type( members: &[(&str, TypeId)], ) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::union_type.

§Errors

See try_union_type_from_logical; also fails if a member’s TypeId is composite.

Source

pub fn union_type_from_logical(members: &[(&str, Self)]) -> Self

Creates a UNION logical type from a slice of (name, LogicalType) members.

Use this when members have complex types.

§Panics

Panics where try_union_type_from_logical would return an error.

Source

pub fn try_union_type_from_logical( members: &[(&str, Self)], ) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::union_type_from_logical.

§Errors

Returns an error if there are no members or more than MAX_UNION_MEMBERS, if two member names are equal ignoring ASCII case, if a name contains a null byte, or if duckdb_create_union_type returns null. DuckDB’s constructor checks none of these; its binder rejects all but the empty union the first time the type is used. SQL cannot write a UNION without members, and a DuckDB built with assertions refuses one, so it is refused here too.

Source

pub fn enum_type(members: &[&str]) -> Self

Creates an ENUM logical type from a list of member names.

§Example
use quack_rs::types::LogicalType;

let color = LogicalType::enum_type(&["red", "green", "blue"]);
§Panics

Panics where try_enum_type would return an error.

Source

pub fn try_enum_type(members: &[&str]) -> Result<Self, LogicalTypeError>

Fallible version of LogicalType::enum_type.

§Errors

Returns an error if a member name contains a null byte, if two members are equal (compared exactly, as DuckDB does: 'a' and 'A' are distinct members), or if duckdb_create_enum_type returns null.

Source§

impl LogicalType

Source

pub unsafe fn from_raw(ptr: duckdb_logical_type) -> Self

Creates a LogicalType from an existing raw duckdb_logical_type handle.

The returned LogicalType takes ownership of the handle and will call duckdb_destroy_logical_type when dropped.

§Safety
  • ptr must be a valid, non-null duckdb_logical_type handle returned by a duckdb_create_* function (e.g. duckdb_create_logical_type, duckdb_create_list_type, duckdb_create_struct_type, etc.).
  • The caller must not call duckdb_destroy_logical_type on the handle after passing it to this function.
  • The handle must not be used after this call except through the returned LogicalType.
§Panics

Panics if ptr is null.

Source

pub unsafe fn try_set_alias(&self, alias: &str) -> Result<(), LogicalTypeError>

Fallible version of LogicalType::set_alias. Returns an error instead of panicking if alias contains an interior null byte.

§Safety

self must wrap a valid duckdb_logical_type.

Source

pub unsafe fn get_type_id(&self) -> TypeId

Returns the TypeId of this logical type.

§Panics

Panics if DuckDB reports a type this build of quack-rs has no variant for — for example GEOMETRY or VARIANT without the duckdb-1-5-3 feature, or a type added by a newer DuckDB. Inside a callback, where the type comes from the query, prefer try_get_type_id.

§Safety

The inner handle must be valid (requires DuckDB runtime).

Source

pub unsafe fn try_get_type_id(&self) -> Option<TypeId>

Returns the TypeId of this logical type, or None if this build of quack-rs has no variant for it (see get_type_id).

§Safety

The inner handle must be valid (requires DuckDB runtime).

Source

pub unsafe fn get_alias(&self) -> Option<String>

Returns the alias of this logical type, or None if no alias is set.

§Safety

The inner handle must be valid (requires DuckDB runtime).

Source

pub unsafe fn set_alias(&self, alias: &str)

Sets an alias on this logical type.

§Safety

The inner handle must be valid (requires DuckDB runtime).

§Panics

Panics if alias contains an interior null byte.

Source

pub unsafe fn decimal_width(&self) -> u8

Returns the width (total digits) of a DECIMAL type.

§Safety

The inner handle must be a DECIMAL logical type (requires DuckDB runtime).

Source

pub unsafe fn decimal_scale(&self) -> u8

Returns the scale (digits after decimal point) of a DECIMAL type.

§Safety

The inner handle must be a DECIMAL logical type (requires DuckDB runtime).

Source

pub unsafe fn decimal_internal_type(&self) -> TypeId

Returns the internal storage type of a DECIMAL type.

§Safety

The inner handle must be a DECIMAL logical type (requires DuckDB runtime).

Source

pub unsafe fn enum_internal_type(&self) -> TypeId

Returns the internal storage type of an ENUM type.

§Safety

The inner handle must be an ENUM logical type (requires DuckDB runtime).

Source

pub unsafe fn enum_dictionary_size(&self) -> u32

Returns the number of members in an ENUM type.

§Safety

The inner handle must be an ENUM logical type (requires DuckDB runtime).

Source

pub unsafe fn enum_dictionary_value(&self, index: u64) -> String

Returns the name of the enum member at index.

§Safety

The inner handle must be an ENUM logical type and index must be within bounds (requires DuckDB runtime).

§Panics

Panics if duckdb_enum_dictionary_value returns a null pointer.

Source

pub unsafe fn list_child_type(&self) -> Self

Returns the child (element) type of a LIST type.

§Safety

The inner handle must be a LIST logical type (requires DuckDB runtime).

Source

pub unsafe fn map_key_type(&self) -> Self

Returns the key type of a MAP type.

§Safety

The inner handle must be a MAP logical type (requires DuckDB runtime).

Source

pub unsafe fn map_value_type(&self) -> Self

Returns the value type of a MAP type.

§Safety

The inner handle must be a MAP logical type (requires DuckDB runtime).

Source

pub unsafe fn struct_child_count(&self) -> u64

Returns the number of child fields in a STRUCT type.

§Safety

The inner handle must be a STRUCT logical type (requires DuckDB runtime).

Source

pub unsafe fn struct_child_name(&self, index: u64) -> String

Returns the name of the struct field at index.

§Safety

The inner handle must be a STRUCT logical type and index must be within bounds (requires DuckDB runtime).

§Panics

Panics if duckdb_struct_type_child_name returns a null pointer.

Source

pub unsafe fn struct_child_type(&self, index: u64) -> Self

Returns the type of the struct field at index.

§Safety

The inner handle must be a STRUCT logical type and index must be within bounds (requires DuckDB runtime).

Source

pub unsafe fn union_member_count(&self) -> u64

Returns the number of members in a UNION type.

§Safety

The inner handle must be a UNION logical type (requires DuckDB runtime).

Source

pub unsafe fn union_member_name(&self, index: u64) -> String

Returns the name of the union member at index.

§Safety

The inner handle must be a UNION logical type and index must be within bounds (requires DuckDB runtime).

§Panics

Panics if duckdb_union_type_member_name returns a null pointer.

Source

pub unsafe fn union_member_type(&self, index: u64) -> Self

Returns the type of the union member at index.

§Safety

The inner handle must be a UNION logical type and index must be within bounds (requires DuckDB runtime).

Source

pub unsafe fn array_size(&self) -> u64

Returns the fixed size of an ARRAY type.

§Safety

The inner handle must be an ARRAY logical type (requires DuckDB runtime).

Source

pub unsafe fn array_child_type(&self) -> Self

Returns the child (element) type of an ARRAY type.

§Safety

The inner handle must be an ARRAY logical type (requires DuckDB runtime).

Source

pub unsafe fn register( &self, con: duckdb_connection, ) -> Result<(), ExtensionError>

Registers this type in the catalog of con, making it usable in SQL.

This is how an extension ships a named type — CREATE TYPE from the C API. Once registered, the alias can be used anywhere a type name can:

SELECT 'happy'::mood;
CREATE TABLE t(m mood);

duckdb.h: “Registers a custom type within the given connection. The type must have an alias.” Set one with try_set_alias first; a type without an alias has no name to register under and DuckDB rejects it.

The duckdb_create_type_info third argument is passed as null: DuckDB declares the handle but exposes no constructor for it in the C API, so null is the only value an extension can supply.

§Errors

Returns an error if the type is or contains ANY or INVALID (checked here, since DuckDB reports it the same way as a taken name), or if DuckDB rejects the registration — no alias, or a name that already exists in the catalog.

§Safety

con must be a valid, open duckdb_connection.

§Example
use quack_rs::types::LogicalType;

let mood = LogicalType::enum_type(&["sad", "ok", "happy"]);
// SAFETY: `con` is the connection DuckDB handed the entry point.
unsafe {
    mood.set_alias("mood");
    mood.register(con)?;
}
Source

pub const fn as_raw(&self) -> duckdb_logical_type

Returns the underlying raw duckdb_logical_type handle.

§Safety note

Do not call duckdb_destroy_logical_type on the returned handle; that is handled by this type’s Drop implementation.

Source

pub const fn into_raw(self) -> duckdb_logical_type

Consumes this LogicalType and returns the raw handle without destroying it.

The caller is responsible for calling duckdb_destroy_logical_type on the returned handle.

Trait Implementations§

Source§

impl Debug for LogicalType

Source§

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

Prints the decoded type rather than the handle address — the type id is the only thing anyone inspects a LogicalType to learn.

This calls into DuckDB, so it deliberately avoids anything that could panic while formatting: a Debug impl that panics inside a panic message aborts the process. A type id from a newer DuckDB than this build knows renders as its numeric value rather than panicking the way get_type_id would.

The null check is belt-and-braces — every constructor, from_raw included, already asserts the handle is non-null — but a formatting impl is the last place worth being clever about a single comparison.

Source§

impl Drop for LogicalType

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

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. Read more
Source§

impl From<TypeId> for LogicalType

Source§

fn from(type_id: TypeId) -> Self

Creates a LogicalType from a TypeId.

This is equivalent to calling LogicalType::new.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.