llkv_column_map/
types.rs

1//! Core type definitions for the storage engine.
2
3// FIXME: Since upgrading to `rustc 1.90.0 (1159e78c4 2025-09-14)`, this seems
4// to be needed to workaround parenthesis errors in `LogicalFieldId`, which
5// creep up regardless of comments being added or not. This is possibly a bug
6// with Clippy or `modular_bitfield`, or a small incompatibility issue.
7#![allow(unused_parens)]
8
9use modular_bitfield::prelude::*;
10
11/// Defines the category of data a `LogicalFieldId` refers to.
12/// This enum uses 16 bits, allowing for up to 65,536 distinct namespaces.
13#[derive(Specifier, Debug, PartialEq, Eq, Clone, Copy)]
14#[bits = 16]
15pub enum Namespace {
16    /// Standard user-defined column data.
17    UserData = 0,
18    /// Internal shadow column for row IDs.
19    RowIdShadow = 1,
20    /// Highest sentinel reserved for future expansion.
21    Reserved = 0xFFFF,
22}
23
24/// Identifier for a logical table within a [`Namespace`].
25///
26/// `TableId` consumes the middle 16 bits inside [`LogicalFieldId`]. Using a
27/// `u16` keeps IDs compact and (more importantly) guarantees they always fit in
28/// that bitfield without extra checks.
29pub type TableId = u16;
30
31/// Logical column identifier within a table.
32///
33/// `FieldId` is stored inside [`LogicalFieldId::field_id`], which is a 32-bit
34/// lane.  Keep this alias in sync with that width so table metadata and
35/// runtime identifiers can round-trip without truncation.
36pub type FieldId = u32;
37
38/// Row identifier for persisted data.
39///
40/// `ColumnStore` emits row ids as Arrow `UInt64Array`s (see `core.rs`), so this
41/// alias mirrors that width to avoid casts when marshalling data in and out of
42/// the engine.
43pub type RowId = u64;
44
45/// A namespaced logical identifier for a column.
46///
47/// This 64-bit struct is designed to prevent ID collisions by partitioning the key space
48/// into distinct namespaces, table IDs, and field IDs.
49#[bitfield]
50#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Default)]
51#[repr(u64)]
52pub struct LogicalFieldId {
53    /// The specific field/column within a table (up to ~4.3 billion).
54    pub field_id: B32,
55    /// The table this field belongs to (up to 65,535).
56    pub table_id: B16,
57    /// The type of data this ID represents (up to 65,536 namespaces).
58    pub namespace: Namespace,
59}
60
61impl LogicalFieldId {
62    /// Build a logical field identifier from its namespace, table, and field components.
63    #[inline]
64    pub fn from_parts(namespace: Namespace, table_id: TableId, field_id: FieldId) -> Self {
65        LogicalFieldId::new()
66            .with_namespace(namespace)
67            .with_table_id(table_id)
68            .with_field_id(field_id)
69    }
70
71    /// Convenience constructor for user data columns.
72    #[inline]
73    pub fn for_user(table_id: TableId, field_id: FieldId) -> Self {
74        Self::from_parts(Namespace::UserData, table_id, field_id)
75    }
76
77    /// Convenience constructor for user data columns in table 0.
78    ///
79    /// Many tests use table 0 by default; this method avoids repeating the table ID literal.
80    #[inline]
81    pub fn for_user_table_0(field_id: FieldId) -> Self {
82        Self::for_user(0, field_id)
83    }
84}
llkv_column_map/types.rs

llkv_column_map/
types.rs
