Skip to content

fix: give graph labels exact CanonicalLabel identity - #1061

Open
batmnnn wants to merge 2 commits into
HelixDB:mainfrom
batmnnn:fix/canonical-graph-label-identity
Open

batmnnn wants to merge 2 commits into
HelixDB:mainfrom
batmnnn:fix/canonical-graph-label-identity

Conversation

@batmnnn

@batmnnn batmnnn commented Sep 2, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #1060.

Summary

  • Graph $label keys were SipHash-only, so colliding labels shared one Roaring bitmap. Identity is now CanonicalLabel: digest is a scan accelerator, exact identity is length-delimited UTF-8.
  • Hash-only constructors are gone. Node labels get their own prefix (0x07). Edge-label and neighbor keys carry the same canonical frame. Parse fails closed on digest mismatch and on old 10-byte hash keys.
  • Writes and lookups (topology, LabelScan, expand, count, shortest path) construct from the label string. Dual-read of hash keys is not the contract.

Test plan

  • cargo test -p db --lib label
  • cargo test -p db --lib topology
  • CI

Made with Cursor

Greptile Summary

The PR replaces hash-only graph-label identities with digest-accelerated, exact UTF-8 canonical keys across encoding, topology mutation, and graph lookup paths.

  • Adds canonical node-label, edge-label, and labeled-neighbor key formats with strict parsing.
  • Updates graph writes, label scans, expansion, counting, and shortest-path lookups to use exact label identity.
  • Leaves existing current-version databases without a migration from their old hash-only label rows.

Important Files Changed

Filename Overview
crates/db/src/encoding/v2/keys/indexes/canonical_label.rs Introduces bounded exact UTF-8 label identity, digest validation, and length-delimited encoding.
crates/db/src/encoding/v2/keys/indexes/label.rs Replaces persisted hash-only label key layouts and adds a distinct node-label key family, but old rows are intentionally unreadable.
crates/db/src/execution/interpreter/mutation/topology.rs Coalesces and writes node, edge, and neighbor memberships using exact canonical labels.
crates/db/src/search/mod.rs Routes graph-label reads and writes exclusively to canonical keys, exposing missing migrated rows in existing stores.
crates/db/src/migrations/startup/bootstrap.rs Although unchanged, its current-version Ready path demonstrates that no migration is triggered for the new persisted label format.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Existing v4 database] --> B[Writer bootstrap]
  B --> C[Version already 0x0004]
  C --> D[No label-index migration]
  D --> E[Old hash-only label rows remain]
  F[Label lookup at head] --> G[Construct canonical label key]
  G --> H[No matching row]
  E --> H
  H --> I[Existing labeled graph data omitted]
Loading

Reviews (1): Last reviewed commit: "fix: give graph labels exact CanonicalLa..." | Re-trigger Greptile

Greptile also left 1 inline comment on this PR.

Context used:

SipHash-only $label keys merged colliding labels into one bitmap.
Identity is now digest plus length-delimited UTF-8, so hash-only keys are unrepresentable.

Co-authored-by: Cursor <cursoragent@cursor.com>
Comment on lines +87 to +90
fn equality_data_key(scope: DataScope, property: &str, value: &str) -> Result<Bytes, HelixDbError> {
if property == NODE_LABEL_PROPERTY {
return node_label_data_key(scope, value);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Current stores skip label migration

When an existing version-0x0004 database contains hash-only label indexes, startup runs no migration while these lookups construct only canonical label keys, causing existing nodes and edges to disappear from label scans, labeled expansion and counts, and labeled shortest-path traversal until the indexes are rebuilt.

Knowledge Base Used:

Existing 0x0004/0x0005 stores must fail closed and rebuild CanonicalLabel indexes from graph rows instead of serving empty LabelScan.

Co-authored-by: Cursor <cursoragent@cursor.com>
@xav-db

xav-db commented Sep 9, 2026

Copy link
Copy Markdown
Member

main issue here is the storage format change, will need to take a bit longer to look at it and ensure correctness and migration support

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

2 participants