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 scopeImplementations§
Source§impl LogicalType
impl LogicalType
Sourcepub fn new(type_id: TypeId) -> Self
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_idis composite, naming the constructor to use instead. Usetry_newto get aResult. - Panics if
type_idisTypeId::Variant(duckdb-1-5-3): seetry_new. - Panics if
type_idisTypeId::IntegerLiteralorTypeId::StringLiteral:DuckDBaccepts 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_typereturns 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());Sourcepub fn try_new(type_id: TypeId) -> Result<Self, LogicalTypeError>
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).
Sourcepub fn list(element_type: TypeId) -> Self
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.
Sourcepub fn try_list(element_type: TypeId) -> Result<Self, LogicalTypeError>
pub fn try_list(element_type: TypeId) -> Result<Self, LogicalTypeError>
Fallible version of LogicalType::list.
Sourcepub fn list_from_logical(element: &Self) -> Self
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.
Sourcepub fn try_list_from_logical(element: &Self) -> Result<Self, LogicalTypeError>
pub fn try_list_from_logical(element: &Self) -> Result<Self, LogicalTypeError>
Fallible version of LogicalType::list_from_logical.
Sourcepub fn map(key_type: TypeId, value_type: TypeId) -> Self
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.
Sourcepub fn try_map(
key_type: TypeId,
value_type: TypeId,
) -> Result<Self, LogicalTypeError>
pub fn try_map( key_type: TypeId, value_type: TypeId, ) -> Result<Self, LogicalTypeError>
Fallible version of LogicalType::map.
Sourcepub fn map_from_logical(key: &Self, value: &Self) -> Self
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.
Sourcepub fn try_map_from_logical(
key: &Self,
value: &Self,
) -> Result<Self, LogicalTypeError>
pub fn try_map_from_logical( key: &Self, value: &Self, ) -> Result<Self, LogicalTypeError>
Fallible version of LogicalType::map_from_logical.
Sourcepub fn struct_type(fields: &[(&str, TypeId)]) -> Self
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.
Sourcepub fn try_struct_type(
fields: &[(&str, TypeId)],
) -> Result<Self, LogicalTypeError>
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.
Sourcepub fn struct_type_from_logical(fields: &[(&str, Self)]) -> Self
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.
Sourcepub fn try_struct_type_from_logical(
fields: &[(&str, Self)],
) -> Result<Self, LogicalTypeError>
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.
Sourcepub fn decimal(width: u8, scale: u8) -> Self
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.
Sourcepub fn try_decimal(width: u8, scale: u8) -> Result<Self, LogicalTypeError>
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.
Sourcepub fn array(element_type: TypeId, size: u64) -> Self
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.
Sourcepub fn try_array(
element_type: TypeId,
size: u64,
) -> Result<Self, LogicalTypeError>
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.
Sourcepub fn array_from_logical(element: &Self, size: u64) -> Self
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.
Sourcepub fn try_array_from_logical(
element: &Self,
size: u64,
) -> Result<Self, LogicalTypeError>
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.
Sourcepub fn union_type(members: &[(&str, TypeId)]) -> Self
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.
Sourcepub fn try_union_type(
members: &[(&str, TypeId)],
) -> Result<Self, LogicalTypeError>
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.
Sourcepub fn union_type_from_logical(members: &[(&str, Self)]) -> Self
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.
Sourcepub fn try_union_type_from_logical(
members: &[(&str, Self)],
) -> Result<Self, LogicalTypeError>
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.
Sourcepub fn enum_type(members: &[&str]) -> Self
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.
Sourcepub fn try_enum_type(members: &[&str]) -> Result<Self, LogicalTypeError>
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
impl LogicalType
Sourcepub unsafe fn from_raw(ptr: duckdb_logical_type) -> Self
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
ptrmust be a valid, non-nullduckdb_logical_typehandle returned by aduckdb_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_typeon 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.
Sourcepub unsafe fn try_set_alias(&self, alias: &str) -> Result<(), LogicalTypeError>
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.
Sourcepub unsafe fn get_type_id(&self) -> TypeId
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).
Sourcepub unsafe fn try_get_type_id(&self) -> Option<TypeId>
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).
Sourcepub unsafe fn get_alias(&self) -> Option<String>
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).
Sourcepub unsafe fn decimal_width(&self) -> u8
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).
Sourcepub unsafe fn decimal_scale(&self) -> u8
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).
Sourcepub unsafe fn decimal_internal_type(&self) -> TypeId
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).
Sourcepub unsafe fn enum_internal_type(&self) -> TypeId
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).
Sourcepub unsafe fn enum_dictionary_size(&self) -> u32
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).
Sourcepub unsafe fn enum_dictionary_value(&self, index: u64) -> String
pub unsafe fn enum_dictionary_value(&self, index: u64) -> String
Sourcepub unsafe fn list_child_type(&self) -> Self
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).
Sourcepub unsafe fn map_key_type(&self) -> Self
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).
Sourcepub unsafe fn map_value_type(&self) -> Self
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).
Sourcepub unsafe fn struct_child_count(&self) -> u64
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).
Sourcepub unsafe fn struct_child_name(&self, index: u64) -> String
pub unsafe fn struct_child_name(&self, index: u64) -> String
Sourcepub unsafe fn struct_child_type(&self, index: u64) -> Self
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).
Sourcepub unsafe fn union_member_count(&self) -> u64
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).
Sourcepub unsafe fn union_member_name(&self, index: u64) -> String
pub unsafe fn union_member_name(&self, index: u64) -> String
Sourcepub unsafe fn union_member_type(&self, index: u64) -> Self
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).
Sourcepub unsafe fn array_size(&self) -> u64
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).
Sourcepub unsafe fn array_child_type(&self) -> Self
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).
Sourcepub unsafe fn register(
&self,
con: duckdb_connection,
) -> Result<(), ExtensionError>
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)?;
}Trait Implementations§
Source§impl Debug for LogicalType
impl Debug for LogicalType
Source§fn fmt(&self, f: &mut Formatter<'_>) -> Result
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
impl Drop for LogicalType
Source§impl From<TypeId> for LogicalType
impl From<TypeId> for LogicalType
Source§fn from(type_id: TypeId) -> Self
fn from(type_id: TypeId) -> Self
Creates a LogicalType from a TypeId.
This is equivalent to calling LogicalType::new.