Encoding
This document describes how Actionbase encodes and stores data internally. This information is primarily for contributors and those who need to understand the low-level storage format.
For high-level concepts, see Core Concepts.
Row Types
Section titled “Row Types”Actionbase stores edge data using multiple row types in the datastore backend. Each row type serves a specific query purpose.
| Row Type | Type Code | Purpose | Query Type |
|---|---|---|---|
| Edge State | -3 | Current edge state | Get |
| Edge Index | -4 | Index entries | Scan |
| Edge Count | -2 | Edge counts | Count |
Edge State (Type Code: -3)
Section titled “Edge State (Type Code: -3)”Stores the current state of edges for Get queries.
Key Structure
Section titled “Key Structure”[4-byte hash] + [1-byte + source] + [1-byte + table code] + [1-byte + type code(-3)] + [1-byte + target]Value Structure
Section titled “Value Structure”| Field | Type | Description |
|---|---|---|
| active | Boolean | Edge active status |
| version | Long | Edge version |
| properties | Map | Property values with version per property |
| createdAt | Long | Creation timestamp |
| deletedAt | Long | Deletion timestamp |
Edge Index (Type Code: -4)
Section titled “Edge Index (Type Code: -4)”Stores index entries for Scan queries. Uses Narrow Row format for high-cardinality indexes.
Key Structure
Section titled “Key Structure”[4-byte hash] + [1-byte + directed source] + [1-byte + table code] + [1-byte + type code(-4)] +[1-byte + direction] + [1-byte + index code] + [(1-byte + N) * # index values] + [1-byte + directed target]Value Structure
Section titled “Value Structure”| Field | Type | Description |
|---|---|---|
| version | Long | Edge version |
| properties | Map | Property values |
Edge Count (Type Code: -2)
Section titled “Edge Count (Type Code: -2)”Stores counters for Count queries. Uses the datastore backend’s increment operation.
Key Structure
Section titled “Key Structure”[4-byte hash] + [1-byte + directed source] + [1-byte + table code] + [1-byte + type code(-2)] + [1-byte + direction]Value Structure
Section titled “Value Structure”| Field | Type | Description |
|---|---|---|
| count | Long | Edge count |
Row Key Encoding
Section titled “Row Key Encoding”All row keys follow a common pattern:
[4-byte hash] + [1-byte + source] + [1-byte + table code] + [1-byte + type code] + [additional fields...]| Component | Size | Purpose |
|---|---|---|
| Hash | 4 bytes | xxhash32 for region distribution |
| Type Code | 1 byte | Identifies data type (-2, -3, -4) |
| Source/Target | Variable | Prefixed with 1-byte length |
The hash prefix ensures even distribution across HBase regions, preventing hotspots.
Value Encoding
Section titled “Value Encoding”Actionbase uses byte headers to maintain type information:
Format
Section titled “Format”[1-byte type information] + [actual value]Type Information
Section titled “Type Information”| Aspect | Description |
|---|---|
| Type Code | Distinguishes NULL, STRING, INT, FLOAT, JSON, etc. |
| Sort Order | Includes ASC/DESC for index ordering |
| Encoding | Values encoded according to sort order |
Version Tracking
Section titled “Version Tracking”| Row Type | Version Scope |
|---|---|
| EdgeState | Version per property |
| EdgeIndex | Version per edge |
Key Design Principles
Section titled “Key Design Principles”Hash Prefix
Section titled “Hash Prefix”The 4-byte xxhash32 prefix ensures:
- Even distribution across storage regions
- Prevention of write hotspots
- Balanced read/write load
Negative Type Codes
Section titled “Negative Type Codes”Type codes use negative values (-2, -3, -4) to:
- Separate from user data
- Enable efficient key range scanning
- Provide clear type identification
Length-Prefixed Strings
Section titled “Length-Prefixed Strings”All variable-length fields use 1-byte length prefix:
- Enables efficient parsing
- Supports binary-safe encoding
- Allows prefix-based scanning