Rust에서의 사용자 정의 타입

Rust SDK는 알파 단계입니다 — 릴리스 간에 호환성이 깨지는 API 변경이 발생할 수 있습니다. 함수 전용 확장, 집계 함수, 가변 인자 함수, 그리고 사용자 정의 타입(encode, decode, compare, hash)이 지원되며, sys_var, status_var, thread_worker, keyring 미리보기 기능도 지원됩니다. 컬럼 저장 ABI는 현재 C++ 전용입니다 — 이 기능이 필요하다면 C++ SDK를 사용하세요.

사용자 정의 타입을 통해 RATIONAL, VECTOR, 또는 INET과 같은 새로운 컬럼 타입을 정의할 수 있습니다. 이러한 타입은 ORDER BY, 인덱스, 및 집계 함수와 함께 작동합니다. Rust SDK는 custom_type! 매크로를 통해, 그리고 저장 크기가 컬럼 매개변수에 따라 달라지는 타입에 대해서는 parameterized_type!을 통해 이를 지원합니다(매개변수화된 타입 참조). 이 페이지는 이미 Rust에서 확장 빌드를 완료했음을 전제로 합니다. 설정(Cargo.toml, manifest.json, cargo-vsql)은 동일합니다.

사용자 정의 타입을 사용해야 하는 경우

다음과 같은 경우 사용자 정의 타입을 사용하세요:

표준 SQL 타입으로 표현할 수 없는 디스크 상의 이진 레이아웃이 필요할 때(압축된 부동소수점, 고정 폭 정수, 이진 식별자)
타입 자체가 사전식 문자열 정렬과 다른 순서 의미론을 가질 때
서버가 ORDER BY, COUNT(DISTINCT), 및 집합 연산을 위해 값들을 올바르게 인덱싱하고 해시하도록 하려 할 때

SQL 호출 가능한 함수만 필요하고 데이터를 STRING, INT, 또는 REAL 컬럼에 무리 없이 담을 수 있을 경우, 사용자 정의 타입이 필요하지 않습니다.

custom_type! 매크로

모든 사용자 정의 타입은 4개의 콜백(인코딩, 디코딩, 비교, 해시)과 기본값이 필요합니다. 전체 매크로 서명은 다음과 같습니다:

villagesql::custom_type!(
    type_name: "type_name_in_sql",
    persisted_length: N,
    max_decode_buffer_length: M,
    encode: your_encode_fn,
    decode: your_decode_fn,
    compare: your_compare_fn,
    hash: your_hash_fn,
    default: "a_valid_string_literal",
)

필드	유형	설명
`type_name`	문자열 리터럴	SQL 타입 이름. SQL에서는 대소문자 구분 없음.
`persisted_length`	`usize`	디스크 저장을 위한 고정 바이트 길이.
`max_decode_buffer_length`	`usize`	디코딩된 문자열 표현의 최대 바이트 길이.
`encode`	fn	INSERT 시에 `&str`를 이진 바이트로 변환합니다.
`decode`	fn	이진 바이트를 표시용 `String`으로 변환합니다.
`compare`	fn	`ORDER BY`, `MIN`, `MAX`에 대한 `Ordering`을 반환합니다.
`hash`	fn	`COUNT(DISTINCT)` 및 집합 연산을 위한 `usize` 해시를 반환합니다. 선택적이지만 인덱스가 있는 컬럼에는 권장됩니다.
`default`	문자열 리터럴	서버가 타입 초기화 시 인코딩할 수 있는 유효한 문자열. 정확히 `persisted_length` 바이트로 인코딩되어야 합니다. 선택적이지만 권장됩니다.

type_name, persisted_length, max_decode_buffer_length, encode, decode, compare는 필수입니다. hash와 default는 선택적이지만 권장됩니다 — hash는 올바른 COUNT(DISTINCT) 및 집합 연산을 위해 필요하며, default는 타입 초기화 검증을 위해 필요합니다.

이진 값 수신 및 반환

사용자 정의 타입을 받거나 반환하는 함수는 원시 바이트를 다룹니다. 입력 — InValue::Custom(b)는 저장된 이진 데이터를 &[u8]로 전달합니다:

fn rational_numer_impl(args: &[InValue]) -> VdfReturn {
    match args.first() {
        Some(InValue::Custom(b)) => {
            let numer = read_i64(b, 0);
            VdfReturn::int(numer)
        }
        Some(InValue::Null) | None => VdfReturn::null(),
        _ => VdfReturn::error("rational_numer: expected a RATIONAL argument"),
    }
}

출력 — VdfReturn::Binary(bytes)는 이진 바이트를 서버로 전송합니다:

fn rational_add_impl(args: &[InValue]) -> VdfReturn {
    match (args.get(0), args.get(1)) {
        (Some(InValue::Custom(a)), Some(InValue::Custom(b))) => {
            let result = add_rationals(a, b);
            VdfReturn::Binary(result)
        }
        _ => VdfReturn::null(),
    }
}

func! 선언에서 사용자 정의 타입을 참조하려면 villagesql::custom!("type_name")을 사용합니다:

villagesql::func!(
    rational_add_impl,
    "rational_add",
    [villagesql::custom!("rational"), villagesql::custom!("rational")] -> villagesql::custom!("rational"),
    deterministic: true
)

예시: 유리수 타입

SDK 리포지토리의 examples/vsql_rational은 RATIONAL 타입을 구현하는 작동하는 확장입니다. 이 타입은 유리수를 리틀 엔디안 바이트 순서로 16바이트의 i64 값 쌍(분자, 분모)으로 저장하고 산술 함수를 제공합니다. 다음은 핵심 인코딩, 디코딩, 비교, 해시 구현입니다:

use villagesql::{InValue, VdfReturn};

// Binary layout: [numerator: i64 LE][denominator: i64 LE] — 16 bytes total.
// Always stored in reduced form (GCD = 1) with a positive denominator.
const BYTES: usize = 16;

fn to_bytes(num: i64, den: i64) -> Vec<u8> {
    let mut v = Vec::with_capacity(BYTES);
    v.extend_from_slice(&num.to_le_bytes());
    v.extend_from_slice(&den.to_le_bytes());
    v
}

fn from_bytes(b: &[u8]) -> (i64, i64) {
    let num = i64::from_le_bytes(b[..8].try_into().unwrap());
    let den = i64::from_le_bytes(b[8..16].try_into().unwrap());
    (num, den)
}

// encode: "3/4" -> 16 bytes
pub fn rational_encode(s: &str) -> Result<Vec<u8>, String> {
    let (num_s, den_s) = s
        .split_once('/')
        .ok_or_else(|| format!("rational: expected 'n/d', got {:?}", s))?;
    let num: i64 = num_s.trim().parse()
        .map_err(|e| format!("rational numerator: {}", e))?;
    let den: i64 = den_s.trim().parse()
        .map_err(|e| format!("rational denominator: {}", e))?;
    let (n, d) = normalize(num as i128, den as i128)
        .ok_or_else(|| "rational: zero or overflowing denominator".to_string())?;
    Ok(to_bytes(n, d))
}

// decode: 16 bytes -> "3/4"
pub fn rational_decode(b: &[u8]) -> Result<String, String> {
    if b.len() < BYTES {
        return Err(format!("rational: expected {} bytes, got {}", BYTES, b.len()));
    }
    let (n, d) = from_bytes(b);
    Ok(format!("{}/{}", n, d))
}

// compare: for ORDER BY, MIN, MAX
pub fn rational_compare(a: &[u8], b: &[u8]) -> std::cmp::Ordering {
    let (n1, d1) = from_bytes(a);
    let (n2, d2) = from_bytes(b);
    // cross-multiply (denominators are always positive)
    let lhs = (n1 as i128) * (d2 as i128);
    let rhs = (n2 as i128) * (d1 as i128);
    lhs.cmp(&rhs)
}

// hash: for COUNT(DISTINCT) and set operations
pub fn rational_hash(b: &[u8]) -> usize {
    // FNV-1a over the 16 bytes
    let mut h: usize = 0xcbf29ce484222325u64 as usize;
    for &byte in b {
        h ^= byte as usize;
        h = h.wrapping_mul(0x100000001b3u64 as usize);
    }
    h
}

custom_type! 등록 및 산술 VDF(rational_add, rational_sub 등)는 examples/vsql_rational/src/lib.rs의 전체 소스에 있습니다. 확장이 설치된 후:

INSTALL EXTENSION vsql_rational;

CREATE TABLE fractions (
    id   INT PRIMARY KEY,
    val  RATIONAL
);

INSERT INTO fractions VALUES (1, '1/2'), (2, '3/4'), (3, '1/4');

-- ORDER BY uses rational_compare
SELECT val FROM fractions ORDER BY val;
-- → 1/4, 1/2, 3/4

-- Arithmetic with rational_add
SELECT rational_add('1/3', '1/6');
-- → 1/2

-- Extract numerator and denominator
SELECT rational_numer(val), rational_denom(val) FROM fractions;

-- Convert to floating-point approximation
SELECT rational_to_real('1/3');
-- → 0.3333333333333333

rational_to_real(r RATIONAL) -> REAL은 분자를 분모로 나누어 RATIONAL 값을 64비트 부동소수점 근사치로 변환합니다. 표시나 비교를 위해 근사 소수를 필요로 하지만 열에 손실형 표현을 저장하고 싶지 않을 때 유용합니다.

매개변수화된 타입

매개변수화된 타입은 저장 크기를 알기 위해 CREATE TABLE 시점에 읽는 값이 필요합니다 — VECTOR(3)의 3 같은 값입니다. custom_type!은 이를 표현할 수 없습니다: 그 persisted_length는 모든 컬럼에 대해 하나의 고정 상수입니다. parameterized_type!은 매개변수화된 대응물로, 저장 길이가 고정되는 대신 int_to_params와 resolve_params를 통해 선언된 매개변수로부터 컬럼마다 계산됩니다.

villagesql::parameterized_type!(
    type_name: "type_name_in_sql",
    max_persisted_length: N,
    max_decode_buffer_length: M,
    encode: your_encode_fn,
    decode: your_decode_fn,
    compare: your_compare_fn,
    int_to_params: your_int_to_params_fn,
    resolve_params: your_resolve_params_fn,
    params_type: YourParamsType,
    params_parse: your_params_parse_fn,
    params_to_strings: your_params_to_strings_fn,
    hash: your_hash_fn,
    default: "a_valid_string_literal",
)

필드	유형	설명
`type_name`	문자열 리터럴	SQL 타입 이름. SQL에서는 대소문자 구분 없음.
`max_persisted_length`	`i64`	모든 유효한 매개변수화에 걸친 디스크 상 바이트 길이의 상한.
`max_decode_buffer_length`	`usize`	디코딩된 문자열 표현의 최대 바이트 길이.
`encode`	fn	INSERT 시에 `&str`와 `&mut MaybeParams<P>`를 이진 바이트로 변환합니다.
`decode`	fn	이진 바이트와 `&P`를 표시용 `String`으로 다시 변환합니다.
`compare`	fn	`&P`가 주어졌을 때 `ORDER BY`, `MIN`, `MAX`에 대한 `Ordering`을 반환합니다.
`int_to_params`	fn	`TYPE(N)` 정수 구문을 정규 매개변수 문자열로 변환합니다.
`resolve_params`	fn	파싱된 `Params`를 검증하고 `Resolved`(저장 크기, 선택적으로 다시 작성된 매개변수)를 반환합니다.
`params_type`	타입	파싱된 매개변수 구조체입니다. 예: `PadintParams`.
`params_parse`	fn	`Params`를 `params_type`으로 파싱합니다. 고유한 매개변수 조합마다 최대 한 번 실행됩니다 — SDK가 결과를 캐시합니다.
`params_to_strings`	fn	`params_parse`의 역방향입니다: `params_type`을 정규 `(key, value)` 쌍으로 다시 씁니다.
`hash`	fn	`&P`가 주어졌을 때 `usize` 해시를 반환합니다. 선택적이지만 인덱스가 있는 컬럼에는 권장됩니다.
`default`	문자열 리터럴	서버가 타입 초기화 시 인코딩할 수 있는 유효한 문자열. 선택적이지만 권장됩니다.

type_name, max_persisted_length, max_decode_buffer_length, encode, decode, compare, int_to_params, resolve_params, params_type, params_parse, params_to_strings는 필수입니다. hash와 default는 선택적입니다. intrinsic_default_fn(기본값이 매개변수에 따라 달라질 때 &P로부터 기본값을 계산하는 함수) 또한 선택적이며 default와 상호 배타적입니다. 다음은 padint입니다 — 고정된 8바이트에 저장되는 i64이며, width 매개변수가 0으로 채워지는 표시 폭을 제어합니다:

pub struct PadintParams {
    pub width: u32,
}

pub fn padint_parse(params: Params) -> PadintParams {
    let width = params.get("width").and_then(|s| s.parse().ok()).unwrap_or(1);
    PadintParams { width }
}

pub fn padint_to_strings(p: &PadintParams) -> Vec<(String, String)> {
    vec![("width".to_string(), p.width.to_string())]
}

pub fn padint_int_to_params(n: i64) -> Result<String, String> {
    if n < 1 {
        return Err(format!("padint: width must be >= 1, got {n}"));
    }
    Ok(format!("width={n}"))
}

pub fn padint_resolve_params(params: Params) -> Result<Resolved, String> {
    let width: i64 = params
        .get("width")
        .ok_or_else(|| "padint: missing 'width' param".to_string())?
        .parse()
        .map_err(|e| format!("padint: bad width: {e}"))?;
    // Fixed 8-byte i64 storage; the decode buffer must fit the widest
    // rendering, which is the larger of an i64's digits and the padded width.
    Ok(Resolved::new(8, width.max(20)))
}

pub fn padint_encode(s: &str, params: &mut MaybeParams<PadintParams>) -> Result<Vec<u8>, String> {
    let n: i64 = s.trim().parse().map_err(|e| format!("padint: {e}"))?;
    if !params.is_known() {
        // Bare constant with no column to anchor it: infer width from digits.
        let digits = s.trim().trim_start_matches('-').len().max(1);
        params.set(PadintParams { width: u32::try_from(digits).unwrap_or(u32::MAX) });
    }
    Ok(n.to_le_bytes().to_vec())
}

pub fn padint_decode(b: &[u8], p: &PadintParams) -> Result<String, String> {
    let n = i64::from_le_bytes(b[..8].try_into().unwrap());
    Ok(format!("{n:0width$}", width = p.width as usize))
}

pub fn padint_compare(a: &[u8], b: &[u8], _p: &PadintParams) -> std::cmp::Ordering {
    i64::from_le_bytes(a[..8].try_into().unwrap()).cmp(&i64::from_le_bytes(b[..8].try_into().unwrap()))
}

villagesql::parameterized_type!(
    type_name: "padint",
    max_persisted_length: 8,
    max_decode_buffer_length: 32,
    encode: padint_encode,
    decode: padint_decode,
    compare: padint_compare,
    int_to_params: padint_int_to_params,
    resolve_params: padint_resolve_params,
    params_type: PadintParams,
    params_parse: padint_parse,
    params_to_strings: padint_to_strings,
    default: "0",
)

매개변수화된 사용자 정의 타입 인수를 받는 함수는 일반 InValue::Custom(bytes)가 아니라 InValue::CustomWithParams { bytes, params }를 봅니다 — params는 컬럼에 선언된 key=value 쌍에 대한 읽기 전용, 무복사 뷰인 [TypeParams]입니다.

extension! 블록과 타입

함수와 타입을 모두 등록할 때, extension! 블록은 두 개의 섹션을 가집니다:

villagesql::extension! {
    funcs: [
        // VDFs declared with func!
    ],
    types: [
        // Custom types declared with custom_type!
    ]
}

함수만 포함하는 확장은 types:를 생략합니다. 타입만 포함하는 확장은 funcs: []를 유지하며 그 밖의 것은 생략하지 않습니다.

다음 단계

Rust API 참조

InValue, VdfReturn, 및 모든 매크로에 대한 완전한 참조.

Rust에서 확장 빌드

시작하기 — Cargo 설정, 첫 번째 함수, 패키징 및 테스트.

C++ 사용자 정의 타입

C++에서의 사용자 정의 타입 — make_type<>, 인코딩/디코딩/비교/해시, ALTER TABLE 규칙.

확장 아키텍처

사용자 정의 타입이 해석, 캐시, 저장되는 방식.

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

사용자 정의 타입을 사용해야 하는 경우

custom_type! 매크로

이진 값 수신 및 반환

예시: 유리수 타입

매개변수화된 타입

extension! 블록과 타입

다음 단계

Rust API 참조

Rust에서 확장 빌드

C++ 사용자 정의 타입

확장 아키텍처

​사용자 정의 타입을 사용해야 하는 경우

​custom_type! 매크로

​이진 값 수신 및 반환

​예시: 유리수 타입

​매개변수화된 타입

​extension! 블록과 타입

​다음 단계

Rust API 참조

Rust에서 확장 빌드

C++ 사용자 정의 타입

확장 아키텍처

사용자 정의 타입을 사용해야 하는 경우

custom_type! 매크로

이진 값 수신 및 반환

예시: 유리수 타입

매개변수화된 타입

extension! 블록과 타입

다음 단계