Storage Serialization#

Overview#

HugeGraph uses a custom binary encoding layer (BytesBuffer) as the foundation for all persistent data written to storage backends (RocksDB, HBase, Cassandra, HStore). BytesBuffer handles vertex/edge IDs, property values, index keys, and pagination state. For a small set of non-primitive property types not covered by first-class encodings, Kryo is used as a fallback, embedded inline within BytesBuffer payloads.

BytesBuffer#

Two independent copies exist:

The struct copy was extracted from the core copy in 2025-09; both have diverged since. Key constant differences 1:

• BLOB_LEN: 5 (core) vs. 4 (struct)
• ID_LEN_MAX: core declares and enforces 16384; struct declares 32768 but its writeId enforces 16384

Wire/Storage Encoding#

BytesBuffer extends OutputStream and wraps java.nio.ByteBuffer with auto-resize 2. Max buffer capacity is 128 MB 3.

Key encoding techniques:

• Variable-length integers: writeVInt/readVInt (1–5 bytes) and writeVLong/readVLong (1–10 bytes) 4. Negative numbers are not compressed.
• Compact number IDs: Long IDs use a 2–9 byte format with a 0kkksxxx leading byte encoding sign and magnitude 5. Reserved prefixes: 0x7f = UUID, 0x7e = EdgeId.
• String IDs: Length-prefixed with 1–2 byte header; 1–63 byte strings use single-byte header (0x80 | len); up to 16384 bytes use two-byte header (0xc0 high byte) 6.
• String boundaries: Null-terminated (0x00) in string index IDs; 0x00 is disallowed inside index strings 7.
• Edge IDs: Composite encoding of owner vertex + direction + edge label + sub-label + sort values + other vertex 8.
• Properties: writeProperty(PropertyKey, Object) dispatches on DataType; BOOLEAN/BYTE/INT use VInt, LONG/DATE use VLong, FLOAT/DOUBLE are fixed-width, TEXT uses writeBytes, BLOB uses writeBigBytes, UUID is two fixed longs 9.
• Multi-value properties: The struct copy prefixes each property entry with a (cardinality << 6) | dataType byte 10; the server/core copy reads cardinality from the schema, not the byte stream 11.

Usage Layers#

Server side (BinarySerializer): All graph entities (vertices, edges, indexes, schema) are serialized/deserialized through BinarySerializer.java, which calls BytesBuffer.allocate() and BytesBuffer.wrap() throughout. This produces the binary BackendColumn.name/BackendColumn.value byte arrays stored in every backend.

Store side (hugegraph-struct copy): The store layer reads these bytes on the query/filtered-read path. SelectIterator.select() uses the struct BytesBuffer to parse server-written column values (readId, readVInt, readProperty) and re-encode filtered results. KeyUtil.idToBytes() uses the struct copy for key construction.

Pagination: PageInfo and PageState use the server/core BytesBuffer to encode cursor state (offset + backend position bytes) into Base64 page tokens passed between client and server.

Kryo Serialization#

KryoUtil provides the Kryo integration, with one thread-local Kryo instance per thread 12.

• toKryoWithType / fromKryoWithType: Used for non-primitive property types (the default branch in writeProperty) via writeClassAndObject/readClassAndObject 13. These bytes are embedded inside a writeBytes call in the BytesBuffer property stream 14.
• toKryo / fromKryo: Typed serialization without class embedding; used for specific known types.
• UUID custom serializer: Only registered serializer; writes two raw longs 15.

The Kryo version is pinned transitively through TinkerPop 3.5.1 1. There is no application-level version header in the Kryo byte stream and no fallback for incompatible data on read 1. A TODO comment in the core BytesBuffer notes intent to replace Kryo with Apache Fury 16.

⚠️ Upgrade risk: A Kryo or TinkerPop upgrade should not be assumed safe for stored generic property values without testing representative persisted data. 1

The store layer (hugegraph-struct / hstore modules) does not use Kryo; it throws IllegalArgumentException on unknown data types instead 17.

Compatibility Notes#

Known Divergence Between the Two BytesBuffer Copies#

The core and struct copies share the string-ID encoding logic (same 0x80/0xc0 prefix-bit scheme) and VInt/VLong encoding 1. However:

• Property encoding format differs: The struct copy writes a self-describing (cardinality << 6) | dataType byte before each property value; the server/core copy does not 18. This causes an active property codec mismatch when HStore operator-sinking decodes server-written property bytes — Issue #3090 tracks the fix.
• No golden test locks the struct copy's format 19. Per-copy characterization fixtures are the planned deliverable.

HStore Ingest Path#

Encoding is performed exclusively server-side. HstoreTable.insert() passes BackendColumn byte arrays through unchanged over gRPC (opaque bytes data field in StoreCommandRequest). The struct BytesBuffer is used only for read-side key construction and query-path property filtering, not for writing data 1.

External Tools#

hugegraph-loader, Hubble, and hugegraph-tools all communicate via the REST API and have no dependency on BytesBuffer or the binary row format 1.

Page Tokens#

Page tokens are ephemeral cursors with no cross-version compatibility guarantee. Clients should be prepared to restart pagination from the first page after a server upgrade 1.

Key Files#