vgi 0.5.0

Build VGI workers in Rust to extend DuckDB with custom catalogs, functions, and tables over Apache Arrow IPC
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

// Copyright 2025, 2026 Query Farm LLC - https://query.farm

//! Dict-encoded enum string values used across the VGI wire protocol.
//!
//! Each is serialized as `dictionary(int16, utf8)` (see `vgi_rpc::DictString`);
//! these constants are the canonical string payloads from Python
//! `vgi/metadata.py` and `vgi/catalog/catalog_interface.py`.

use vgi_rpc::DictString;

/// Build a `DictString` from a `&str`.
pub fn dict(s: &str) -> DictString {
    DictString(s.to_string())
}

/// `FunctionType` — which registry a function lives in.
pub mod function_type {
    pub const SCALAR: &str = "scalar";
    pub const TABLE: &str = "table";
    pub const TABLE_BUFFERING: &str = "table_buffering";
    pub const AGGREGATE: &str = "aggregate";
}

/// `FunctionStability`.
pub mod stability {
    pub const CONSISTENT: &str = "CONSISTENT";
    pub const VOLATILE: &str = "VOLATILE";
    pub const CONSISTENT_WITHIN_QUERY: &str = "CONSISTENT_WITHIN_QUERY";
}

/// `NullHandling`.
///
/// Wire values are the Python `NullHandling` enum member names (`.name`), which
/// the C++ vgi extension's `ParseFunctionNullHandling` matches exactly. They
/// MUST be uppercase — lowercase values are silently ignored by the extension
/// (falling back to DEFAULT), which notably breaks scalar functions that rely
/// on SPECIAL handling to receive NULL arguments.
pub mod null_handling {
    pub const DEFAULT: &str = "DEFAULT";
    pub const SPECIAL: &str = "SPECIAL";
}

/// `OrderPreservation`.
pub mod order_preservation {
    pub const PRESERVES_ORDER: &str = "PRESERVES_ORDER";
    pub const NO_ORDER_GUARANTEE: &str = "NO_ORDER_GUARANTEE";
    pub const FIXED_ORDER: &str = "FIXED_ORDER";
}

/// `PartitionKind`.
pub mod partition_kind {
    pub const NOT_PARTITIONED: &str = "NOT_PARTITIONED";
    pub const SINGLE_VALUE_PARTITIONS: &str = "SINGLE_VALUE_PARTITIONS";
    pub const OVERLAPPING_PARTITIONS: &str = "OVERLAPPING_PARTITIONS";
    pub const DISJOINT_PARTITIONS: &str = "DISJOINT_PARTITIONS";
}

/// `OrderDependence`.
///
/// Wire values are the Python `OrderDependence` enum member names (`.name`),
/// which the C++ vgi extension's `ParseAggregateOrderDependent` matches exactly
/// (via `RequireKnownEnum`). They MUST be uppercase — a lowercase value is
/// rejected outright, failing catalog load for every function. See the sibling
/// note on [`null_handling`].
pub mod order_dependence {
    pub const ORDER_DEPENDENT: &str = "ORDER_DEPENDENT";
    pub const NOT_ORDER_DEPENDENT: &str = "NOT_ORDER_DEPENDENT";
}

/// `DistinctDependence`.
///
/// Wire values are the Python `DistinctDependence` enum member names (`.name`),
/// matched exactly by the C++ `ParseAggregateDistinctDependent` via
/// `RequireKnownEnum`. They MUST be uppercase — see [`order_dependence`].
pub mod distinct_dependence {
    pub const DISTINCT_DEPENDENT: &str = "DISTINCT_DEPENDENT";
    pub const NOT_DISTINCT_DEPENDENT: &str = "NOT_DISTINCT_DEPENDENT";
}

/// `TableInOutFunctionInitPhase` — the `init` request `phase` enum.
pub mod phase {
    pub const PROCESS: &str = "PROCESS";
    pub const INPUT: &str = "INPUT";
    pub const FINALIZE: &str = "FINALIZE";
    pub const TABLE_BUFFERING: &str = "TABLE_BUFFERING";
    pub const TABLE_BUFFERING_FINALIZE: &str = "TABLE_BUFFERING_FINALIZE";
}