Data model

HelixDB stores data as a labeled property graph. Nodes represent entities, directed edges represent relationships, and both carry typed properties. Optional indexes make selected properties efficient to filter, order, and search.

​

Nodes, edges, and direction

Alice is the source of the FOLLOWS edge and Bob is its target. Direction belongs to the relationship: traversing out from Alice reaches Bob, while traversing in from Bob reaches Alice. Nodes and edges are numbered from separate sequences, which is why the edge above has ID 0 even though a node already holds ID 0. An ID is only unique within its own space, so always keep track of whether an ID refers to a node or an edge. Each node and each edge carries exactly one label, assigned when it is created. There is no multi-label set, so model a secondary role as a property or as a relationship to another node rather than as an extra label.

​

Properties

Nodes and edges can carry scalar values, arrays, and nested objects: A nested value stays readable through a dotted path such as metadata.score, but only top-level properties can be indexed. Promote a nested field to the top level when you need to filter, order, or search on it.

​

Multiple relationships

HelixDB is a multigraph: the same source and target can be connected by more than one edge. Both SENT edges connect Alice to Bob, but each has its own ID and properties. Use separate edges when the relationships represent separate events or facts. An edge can also connect a node to itself, which is useful for relationships such as MERGED_INTO between records of the same kind.

​

Indexes

An index is an optional access path over a node or edge label and a top-level property. Its definition also contains family-specific settings such as uniqueness, sort direction, text analysis, or vector dimensions and distance metric. Indexes may target nodes or edges and are scoped by label and property. They do not change the canonical graph data. Creating one starts an asynchronous backfill over existing data; the index becomes visible only after validation and atomic activation. See Secondary indexes, Text indexes, and Vector indexes for creation and query examples.

​

Model data clearly

• Use noun-like node labels such as User, Document, and Product.
• Use relationship labels such as FOLLOWS, AUTHORED, and PURCHASED.
• Store relationship-specific values on the edge.
• Use separate edges for distinct events between the same entities.
• Keep properties intended for indexing at the top level.

Property and indexing rules

• Node and edge IDs are unsigned 64-bit values from separate sequences that both start at zero.
• $id and $label expose identity and label in queries. $label cannot be assigned through an ordinary property map.
• A node label can be changed by a dedicated relabel operation, which also moves the node between label indexes. An edge label is fixed for the life of the edge.
• Current secondary, text, and vector indexes require top-level properties, and object and heterogeneous-array values cannot be indexed.
• Uniqueness is available on node equality indexes only; there is no unique edge index.

​

Next steps