rocksgraph 0.1.0

A Gremlin-inspired property graph query engine written in Rust, backed by RocksDB
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
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

// Copyright (c) 2026 Austin Han <austinhan1024@gmail.com>
//
// This file is part of RocksGraph.
//
// RocksGraph is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 2 of the License, or
// (at your option) any later version.
//
// RocksGraph is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with RocksGraph.  If not, see <https://www.gnu.org/licenses/>.

//! Fundamental domain types and the core data model for RocksGraph.
//!
//! This module provides the essential building blocks used throughout the engine
//! and storage layers.  Understanding how these types relate to each other is the
//! key to reading most of the codebase.
//!
//! # Type hierarchy
//!
//! ```text
//! GValue                          ← universal value flowing through a traversal
//! ├── Vertex(VertexKey)           ← i64 handle; actual data fetched on demand
//! ├── Edge(EdgeKey)               ← directed handle (primary_id + direction + …)
//! ├── Property(Property)          ← owner + PropKey + Primitive
//! ├── Scalar(Primitive)           ← bool / i32 / i64 / f32 / f64 / String / Uuid / Null
//! ├── List(Vec<GValue>)
//! ├── Map(HashMap<GValue, GValue>)
//! └── Path(Vec<(GValue, labels)>)
//!
//! Keys
//! ├── VertexKey = i64
//! ├── CanonicalEdgeKey            ← direction-free (src, label, rank, dst)
//! └── EdgeKey                     ← directed (primary_id, direction, label, rank, secondary_id)
//!
//! Identifiers
//! ├── LabelId = i32               ← numeric label id (schema registry maps Label ↔ LabelId)
//! ├── Label(SmolStr)              ← human-readable label string ("person", "knows")
//! └── PropKey = SmolStr           ← property key string ("name", "age")
//! ```
//!
//! # Lazy element loading
//!
//! `GValue::Vertex` and `GValue::Edge` carry **keys only** — they are `Copy` and cheap
//! to clone (8 / 40 bytes).  The traversal engine calls `ctx.get_vertex(key)` or
//! `ctx.get_edges(…)` to materialize the full [`Vertex`] / [`Edge`] record (with
//! properties) only when needed.  This avoids unnecessary data fetches in filter-heavy
//! traversals.
//!
//! # Module layout
//!
//! | Sub-module | Contents |
//! |---|---|
//! | [`element`] | [`Vertex`], [`Edge`], [`Property`], [`PropertyMap`](element::PropertyMap) — graph element records |
//! | [`gvalue`] | [`GValue`], [`Primitive`] — traversal value types |
//! | [`keys`] | [`VertexKey`], [`EdgeKey`], [`CanonicalEdgeKey`], [`Direction`], [`CanonicalKey`] |
//! | [`label`] | [`Label`] — human-readable label string |
//! | [`prop_key`] | [`PropKey`], [`ID`](prop_key::ID), [`LABEL`](prop_key::LABEL) — property key type and built-in keys |
//! | [`prop_codec`] | v2 property blob codec — `encode_props`, `decode_prop_by_key`, `decode_all_to_map` |
//! | [`kv_codec`] | Crate-internal key-value byte-level key/value serialization (lexicographical sorting and binary row framing) |
//! | [`error`] | [`StoreError`] — storage and runtime errors |
//!
//! Most types are re-exported at the crate root for convenience.

pub mod element;
pub mod error;
pub mod gvalue;
pub mod keys;
pub(crate) mod kv_codec;
pub mod label;
pub(crate) mod prop_codec;
pub mod prop_key;

pub use element::{Edge, Property, Vertex};
pub use error::StoreError;
pub use gvalue::{GValue, Primitive, PrimitivePredicate};
pub use keys::{
    AdjacentEdgeCursor, AdjacentEdgesOptions, BatchScenario, CanonicalEdgeKey, CanonicalKey, DegreeDirection,
    Direction, EdgeKey, LabelId, Rank, VertexKey,
};
pub use prop_key::PropKey;

// ── SmallVec inline capacities ──────────────────────────────────────────────

/// Inline capacity for step labels assigned via `as("x")`.
/// Gremlin convention is 1–2 labels per step position.
pub(crate) const STEP_LABEL_INLINE: usize = 2;

/// Inline capacity for direction lists (`OUT` / `IN` in `bothE` / `both`).
/// Always exactly two directions.
pub(crate) const DIRECTION_INLINE: usize = 2;

/// Inline capacity for order-by keys.  Most `order().by(...)` chains use 1–2 keys.
pub(crate) const ORDER_KEY_INLINE: usize = 2;

/// Inline capacity for small collections of vertex IDs, edge labels, property keys,
/// and logical sub-plans in query parameters (the user rarely supplies more than a
/// handful per `V()` / `outE()` / `.and()` / `.union()` call).
pub(crate) const SMALL_VECTOR_LENGTH: usize = 4;

/// Inline capacity for the Volcano pipeline produce buffer — determines how many
/// traversers can be emitted per single `produce()` → `next()` round-trip.
pub(crate) const PIPELINE_PRODUCE_SIZE: usize = 8;

/// Inline capacity for vertex property lists in `addV()`.
pub(crate) const VERTEX_PROPS_LENGTH: usize = 8;

#[cfg(test)]
mod tests;