Skip to content

Data modeling

A data model is a model that organizes data and specifies how they are related to one another. This topic describes the Nebula Graph data model and provides suggestions for data modeling with NebulaGraph.

Data structures

NebulaGraph data model uses six data structures to store data. They are graph spaces, vertices, edges, tags, edge types and properties.

  • Graph spaces: Graph spaces are used to isolate data from different teams or programs. Data stored in different graph spaces are securely isolated. Storage replications, privileges, and partitions can be assigned.
  • Vertices: Vertices are used to store entities.
  • In NebulaGraph, vertices are identified with vertex identifiers (i.e. VID). The VID must be unique in the same graph space. VID should be int64, or fixed_string(N).

    • A vertex has zero to multiple tags.


    In NebulaGraph 2.x a vertex must have at least one tag. And in NebulaGraph master, a tag is not required for a vertex.

  • Edges: Edges are used to connect vertices. An edge is a connection or behavior between two vertices.
    • There can be multiple edges between two vertices.
    • Edges are directed. -> identifies the directions of edges. Edges can be traversed in either direction.
    • An edge is identified uniquely with <a source vertex, an edge type, a rank value, and a destination vertex>. Edges have no EID.
    • An edge must have one and only one edge type.
    • The rank value is an immutable user-assigned 64-bit signed integer. It identifies the edges with the same edge type between two vertices. Edges are sorted by their rank values. The edge with the greatest rank value is listed first. The default rank value is zero.
  • Tags: Tags are used to categorize vertices. Vertices that have the same tag share the same definition of properties.
  • Edge types: Edge types are used to categorize edges. Edges that have the same edge type share the same definition of properties.
  • Properties: Properties are key-value pairs. Both vertices and edges are containers for properties.


Tags and Edge types are similar to "vertex tables" and "edge tables" in the relational databases.

Directed property graph

NebulaGraph stores data in directed property graphs. A directed property graph has a set of vertices connected by directed edges. Both vertices and edges can have properties. A directed property graph is represented as:

G = < V, E, PV, PE >

  • V is a set of vertices.
  • E is a set of directed edges.
  • PV is the property of vertices.
  • PE is the property of edges.

The following table is an example of the structure of the basketball player dataset. We have two types of vertices, that is player and team, and two types of edges, that is serve and follow.

Element Name Property name (Data type) Description
Tag player name (string)
age (int)
Represents players in the team.
The properties name and age indicate the name and age.
Tag team name (string) Represents the teams.
The property name indicates the team name.
Edge type serve start_year (int)
end_year (int)
Represents the action of a player serving a team. The action links the player to the team, and the direction is from the player to the team.
The properties start_year and end_year indicate the start year and end year of the service respectively.
Edge type follow degree (int) Represents the action of a player following another player on Twitter. The action links one player to the other player, and the direction is from one player to the other player.
The property degree indicates the rating on how well the follower liked the followee.


NebulaGraph supports only directed edges.


NebulaGraph master allows dangling edges. Therefore, when adding or deleting, you need to ensure the corresponding source vertex and destination vertex of an edge exist. For details, see INSERT VERTEX, DELETE VERTEX, INSERT EDGE, and DELETE EDGE.

The MERGE statement in openCypher is not supported.

Last update: April 25, 2024