🥮 mooncakes.io
README

#core/types

Core type definitions for vcdb.

#Key Types

  • Metric: Distance metric (Cosine, L2, Dot)
  • VectorId: 64-bit vector identifier
  • AttrValue: Attribute value (Null, Bool, Int, Float, String)
  • Attrs: Map of string keys to AttrValue
  • SearchHit: Search result with id, score, and attrs
  • VectorRecord: Vector data with attrs
  • HNSWParams: HNSW algorithm parameters
  • IVFParams: IVF algorithm parameters
  • Strategy: ANN strategy selection (Bruteforce, HNSW, IVF)
  • DatabaseOptions: Database construction options
  • NumericRange: Range query constraints

#Usage

let id = @types.VectorId::from_int64(123L)
let attrs = @types.empty_attrs()
attrs.set("category", @types.String("test"))

#
AttrValue

source
pub(all) enum AttrValue {
  Null
  Bool(Bool)
  Int(Int64)
  Float(Double)
  String(String)
} derive(Eq, 
Debug)

Attribute value - supports common primitive types
impl Show for AttrValue

#
Attrs

source
pub(all) struct Attrs(Map[String, AttrValue]) derive(
Debug)

Attributes map - empty map as default
impl Show for Attrs

#
Attrs::clear

source
fn Attrs::clear(self : Attrs) -> Unit

Clear all attrs

#
Attrs::copy

source
fn Attrs::copy(self : Attrs) -> Attrs

Create a defensive copy of attrs

#
Attrs::get

source
fn Attrs::get(self : Attrs, key : String) -> AttrValue?

Get a value from attrs

#
Attrs::is_empty

source
fn Attrs::is_empty(self : Attrs) -> Bool

Check if attrs is empty

#
Attrs::keys

source
fn Attrs::keys(self : Attrs) -> Array[String]

Get all keys from attrs

#
Attrs::set

source
fn Attrs::set(self : Attrs, key : String, value : AttrValue) -> Unit

Set a value in attrs

#
Attrs::size

source
fn Attrs::size(self : Attrs) -> Int

Get size of attrs

#
Bytes16

source
pub(all) struct Bytes16 {
  b0 : Byte
  b1 : Byte
  b2 : Byte
  b3 : Byte
  b4 : Byte
  b5 : Byte
  b6 : Byte
  b7 : Byte
  b8 : Byte
  b9 : Byte
  b10 : Byte
  b11 : Byte
  b12 : Byte
  b13 : Byte
  b14 : Byte
  b15 : Byte
} derive(
Debug)

128-bit fixed-size byte array for UUID/ULID/Snowflake-extended ID representation. Stored as big-endian bytes so lexicographic order matches time order for ULID.
impl Eq for Bytes16
impl Hash for Bytes16
impl Show for Bytes16

#
Bytes16::compare

source
fn Bytes16::compare(self : Bytes16, other : Bytes16) -> Int

#
Bytes16::from_hi_lo

source
fn Bytes16::from_hi_lo(hi : Int64, lo : Int64) -> Bytes16

Construct a Bytes16 from two Int64 values (hi = bytes 0-7, lo = bytes 8-15), both interpreted as big-endian. This is the canonical way to embed a Snowflake-style or ULID timestamp+random payload into a 128-bit ID.

#
Bytes16::from_uuid_string

source
fn Bytes16::from_uuid_string(s : String) -> Bytes16?

Parse a UUID string (8-4-4-4-12 hex, with or without hyphens) into Bytes16.

#
Bytes16::new

source
fn Bytes16::new(b0 : Byte, b1 : Byte, b2 : Byte, b3 : Byte, b4 : Byte, b5 : Byte, b6 : Byte, b7 : Byte, b8 : Byte, b9 : Byte, b10 : Byte, b11 : Byte, b12 : Byte, b13 : Byte, b14 : Byte, b15 : Byte) -> Bytes16

#
Bytes16::to_hi_lo

source
fn Bytes16::to_hi_lo(self : Bytes16) -> (Int64, Int64)

Extract the two Int64 halves (big-endian) from a Bytes16.

#
Bytes16::to_uuid_string

source
fn Bytes16::to_uuid_string(self : Bytes16) -> String

Format Bytes16 as a UUID string (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

#
DatabaseOptions

source
pub(all) struct DatabaseOptions {
  dim : Int
  metric : Metric
  capacity : Int
  strategy : Strategy
} derive(
Debug)

Database construction options

#
DatabaseOptions::default

source
fn DatabaseOptions::default(dim : Int) -> DatabaseOptions

Create default database options

#
HNSWParams

source
pub(all) struct HNSWParams {
  m : Int
  ef_construction : Int
  ef_search : Int
  level_mult : Double
  seed : UInt64
  allow_replace_deleted : Bool
} derive(
Debug)

HNSW algorithm parameters
impl Show for HNSWParams

#
HNSWParams::default

source
fn HNSWParams::default() -> HNSWParams

Create default HNSW params

#
IVFParams

source
pub(all) struct IVFParams {
  nlist : Int
  nprobe : Int
} derive(
Debug)

IVF algorithm parameters
impl Show for IVFParams

#
IVFParams::default

source
fn IVFParams::default() -> IVFParams

Create default IVF params

#
Metric

source
pub(all) enum Metric {
  Cosine
  L2
  Dot
} derive(Eq, 
Debug)

Distance/Similarity Metric.
  • Cosine: vectors are normalized internally, score in [-1,1]
  • L2: score is negative squared distance (higher is closer)
  • Dot: raw dot product (higher is more similar)
impl Show for Metric

#
Metric::from_name

source
fn Metric::from_name(s : String) -> Metric?

Parse a Metric from its string representation.

#
Metric::to_name

source
fn Metric::to_name(self : Metric) -> String

Canonical string representation of a Metric.

#
NumericRange

source
pub(all) struct NumericRange {
  gt : Double?
  gte : Double?
  lt : Double?
  lte : Double?
} derive(
Debug)

Numeric range for range queries

#
NumericRange::between

source
fn NumericRange::between(lower : Double, upper : Double, lower_inclusive? : Bool, upper_inclusive? : Bool) -> NumericRange

#
NumericRange::empty

source
fn NumericRange::empty() -> NumericRange

#
NumericRange::gt

source
fn NumericRange::gt(value : Double) -> NumericRange

#
NumericRange::gte

source
fn NumericRange::gte(value : Double) -> NumericRange

#
NumericRange::lt

source
fn NumericRange::lt(value : Double) -> NumericRange

#
NumericRange::lte

source
fn NumericRange::lte(value : Double) -> NumericRange

#
NumericRange::matches

source
fn NumericRange::matches(self : NumericRange, value : Double) -> Bool

#
SearchHit

source
pub(all) struct SearchHit {
  id : VectorId
  score : Double
  attrs : Attrs
} derive(
Debug)

Search result: id + score + attrs
impl Show for SearchHit

#
Strategy

source
pub(all) enum Strategy {
  Bruteforce
  HNSW(HNSWParams)
  IVF(IVFParams)
} derive(
Debug)

ANN strategy selection
impl Show for Strategy

#
Strategy::default_hnsw

source
fn Strategy::default_hnsw() -> Strategy

Default HNSW strategy (most common use case).

#
Strategy::default_ivf

source
fn Strategy::default_ivf() -> Strategy

Default IVF strategy.

#
Strategy::from_name

source
fn Strategy::from_name(s : String) -> Strategy?

Parse a Strategy from its string representation (uses default params).

#
Strategy::to_name

source
fn Strategy::to_name(self : Strategy) -> String

Canonical string representation of a Strategy (name only, no params).

#
VectorId

source
pub(all) enum VectorId {
  Int64Id(Int64)
  Bytes16Id(Bytes16)
} derive(
Debug)

Vector ID — supports Int64 (legacy) and 128-bit (UUID/ULID/Snowflake-extended) for distributed environments.

Int64Id sorts before Bytes16Id in Compare so mixed collections have a stable order.
impl Eq for VectorId
impl Hash for VectorId
impl Show for VectorId

#
VectorId::as_bytes16

source
fn VectorId::as_bytes16(self : VectorId) -> Bytes16?

Get the underlying Bytes16 value. Returns None for Int64Id.

#
VectorId::as_int64

source
fn VectorId::as_int64(self : VectorId) -> Int64?

Get the underlying Int64 value as an option. Returns None for Bytes16Id.

#
VectorId::compare

source
fn VectorId::compare(self : VectorId, other : VectorId) -> Int

#
VectorId::from_bytes16

source
fn VectorId::from_bytes16(b : Bytes16) -> VectorId

Create VectorId from Bytes16 (UUID/ULID/128-bit ID).

#
VectorId::from_int

source
fn VectorId::from_int(id : Int) -> VectorId

Create VectorId from Int (backward-compatible constructor).

#
VectorId::from_int64

source
fn VectorId::from_int64(id : Int64) -> VectorId

Create VectorId from Int64 (backward-compatible constructor).

#
VectorId::from_uuid_string

source
fn VectorId::from_uuid_string(s : String) -> VectorId?

Create VectorId from a UUID string.

#
VectorId::from_wire_bytes

source
fn VectorId::from_wire_bytes(data : Bytes) -> VectorId?

Decode a VectorId from a 16-byte wire representation.

Inverse of VectorId::to_wire_bytes.
  • If bytes 8-15 are all 0x00, reconstructs as Int64Id (big-endian bytes 0-7).
  • Otherwise reconstructs as Bytes16Id.

Returns None if data length is not exactly 16 bytes.

#
VectorId::to_display_string

source
fn VectorId::to_display_string(self : VectorId) -> String

Format a VectorId as a human-readable string. Int64Id: decimal integer string. Bytes16Id: UUID string (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

#
VectorId::to_wire_bytes

source
fn VectorId::to_wire_bytes(self : VectorId) -> Bytes

Encode a VectorId as a 16-byte wire representation.

This is the canonical FFI wire format for VectorId.
  • Int64Id(v): bytes 0-7 = v as big-endian Int64, bytes 8-15 = 0x00
  • Bytes16Id(b): bytes 0-15 = b as-is

JS callers receive a Uint8Array(16) and must use VectorId::from_wire_bytes to reconstruct the VectorId.

#
VectorRecord

source
pub(all) struct VectorRecord {
  vector : Array[Double]
  attrs : Attrs
} derive(
Debug)

Result returned by get(): vector and attrs for an id

#
attr_value_to_number

source
fn attr_value_to_number(value : AttrValue) -> Double?

#
empty_attrs

source
fn empty_attrs() -> Attrs

Create empty attrs

#
hnsw_ef_construction_max

source
let hnsw_ef_construction_max : Int

#
hnsw_ef_construction_min

source
let hnsw_ef_construction_min : Int

#
hnsw_m_max

source
let hnsw_m_max : Int

#
hnsw_m_min

source
let hnsw_m_min : Int

HNSW parameter constraints

#
ivf_nlist_max

source
let ivf_nlist_max : Int

#
ivf_nlist_min

source
let ivf_nlist_min : Int

IVF parameter constraints

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io