# vesoft-inc/nebula architecture

> Architecture diagram of the GitHub repository vesoft-inc/nebula, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vesoft-inc/nebula
- Repository: https://github.com/vesoft-inc/nebula

## Overview

NebulaGraph is a distributed graph database. A client submits a graph query to the Graph service; the query engine creates a per-request query context and execution instance, which plans and runs query or mutation work, requesting partitioned data operations through the storage client. Storage servers serve those operations using the KV layer, while metadata services supply schema and index information. The graph includes documented capabilities such as administration, graph algorithms, and role-based access control. Source excerpts were limited, so some subsystem links are intentionally omitted rather than inferred.

Main entry points: [`src/graph/service/QueryEngine.cpp`](https://github.com/vesoft-inc/nebula/blob/master/src/graph/service/QueryEngine.cpp) (Query Engine), [`src/clients/meta/MetaClient.cpp`](https://github.com/vesoft-inc/nebula/blob/master/src/clients/meta/MetaClient.cpp) (Metadata Client), [`src/graph/service`](https://github.com/vesoft-inc/nebula/tree/master/src/graph/service) (Query Instance), [`src/graph/executor`](https://github.com/vesoft-inc/nebula/tree/master/src/graph/executor) (Query Executors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_graph["Graph Query"]
  node_graphd["Graph Daemon<br/>[GraphDaemon.cpp]"]
  node_engine["Query Engine<br/>[QueryEngine.cpp]"]
  node_instance["Query Instance"]
  node_planner["Query Planner"]
  node_optimizer["Optimizer<br/>[Optimizer.cpp]"]
  node_executors["Query Executors"]
  node_admin["Admin Executors"]
  node_algorithms["Graph Algorithms"]
end

subgraph group_metadata["Metadata"]
  node_meta_client["Metadata Client<br/>[MetaClient.cpp]"]
  node_meta_service["Metadata Service"]
  node_schema["Schema Manager"]
  node_index["Index Manager"]
end

subgraph group_storage["Storage"]
  node_storage_client["Storage Client<br/>[StorageClient.cpp]"]
  node_storage_service["Storage Service<br/>[StorageServer.cpp]"]
  node_storage_exec["Storage Execution"]
  node_kv[("KV Store<br/>[RocksEngine.cpp]")]
end

subgraph group_shared["Query Data"]
  node_context["Query Context<br/>[QueryContext.cpp]"]
  node_expressions["Expressions<br/>[Expression.cpp]"]
  node_codec["Row Codec"]
end

node_client(("Query Client"))
node_external_search["Full-text Service"]

node_client -->|"submits query"| node_graphd
node_graphd -->|"dispatches"| node_engine
node_engine -->|"uses"| node_meta_client
node_engine -->|"creates"| node_schema
node_engine -->|"creates"| node_index
node_engine -->|"creates"| node_storage_client
node_engine -->|"creates"| node_optimizer
node_engine -->|"executes"| node_instance
node_instance -->|"plans"| node_planner
node_instance -->|"runs"| node_executors
node_instance -->|"creates"| node_context
node_executors -->|"evaluates"| node_expressions
node_executors -->|"requests data"| node_storage_client
node_admin -->|"administers"| node_meta_client
node_algorithms -->|"requests data"| node_storage_client
node_meta_client -->|"RPC"| node_meta_service
node_schema -->|"reads schema"| node_meta_client
node_index -->|"reads indexes"| node_meta_client
node_storage_client -->|"partitioned RPC"| node_storage_service
node_storage_service -->|"dispatches"| node_storage_exec
node_storage_exec -->|"reads and writes"| node_kv
node_storage_exec -->|"decodes rows"| node_codec
node_executors -.->|"full-text lookup"| node_external_search

click node_graphd "https://github.com/vesoft-inc/nebula/blob/master/src/daemons/GraphDaemon.cpp"
click node_engine "https://github.com/vesoft-inc/nebula/blob/master/src/graph/service/QueryEngine.cpp"
click node_instance "https://github.com/vesoft-inc/nebula/tree/master/src/graph/service"
click node_planner "https://github.com/vesoft-inc/nebula/tree/master/src/graph/planner"
click node_optimizer "https://github.com/vesoft-inc/nebula/blob/master/src/graph/optimizer/Optimizer.cpp"
click node_executors "https://github.com/vesoft-inc/nebula/tree/master/src/graph/executor"
click node_admin "https://github.com/vesoft-inc/nebula/tree/master/src/graph/executor/admin"
click node_algorithms "https://github.com/vesoft-inc/nebula/tree/master/src/graph/executor/algo"
click node_context "https://github.com/vesoft-inc/nebula/blob/master/src/graph/context/QueryContext.cpp"
click node_expressions "https://github.com/vesoft-inc/nebula/blob/master/src/common/expression/Expression.cpp"
click node_codec "https://github.com/vesoft-inc/nebula/tree/master/src/codec"
click node_meta_client "https://github.com/vesoft-inc/nebula/blob/master/src/clients/meta/MetaClient.cpp"
click node_schema "https://github.com/vesoft-inc/nebula/blob/master/src/common/meta/ServerBasedSchemaManager.cpp"
click node_index "https://github.com/vesoft-inc/nebula/blob/master/src/common/meta/ServerBasedIndexManager.cpp"
click node_storage_client "https://github.com/vesoft-inc/nebula/blob/master/src/clients/storage/StorageClient.cpp"
click node_storage_service "https://github.com/vesoft-inc/nebula/blob/master/src/storage/StorageServer.cpp"
click node_storage_exec "https://github.com/vesoft-inc/nebula/tree/master/src/storage/exec"
click node_kv "https://github.com/vesoft-inc/nebula/blob/master/src/kvstore/RocksEngine.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_graphd,node_engine,node_instance,node_planner,node_optimizer,node_executors,node_admin,node_algorithms,node_client toneBlue
class node_meta_client,node_meta_service,node_schema,node_index toneAmber
class node_storage_client,node_storage_service,node_storage_exec,node_kv toneMint
class node_context,node_expressions,node_codec toneRose
class node_external_search toneIndigo
```

## Components

### Graph Query

- [Graph Daemon](https://github.com/vesoft-inc/nebula/blob/master/src/daemons/GraphDaemon.cpp): `src/daemons/GraphDaemon.cpp`
- [Query Engine](https://github.com/vesoft-inc/nebula/blob/master/src/graph/service/QueryEngine.cpp): `src/graph/service/QueryEngine.cpp`
- [Query Instance](https://github.com/vesoft-inc/nebula/tree/master/src/graph/service): `src/graph/service`
- [Query Planner](https://github.com/vesoft-inc/nebula/tree/master/src/graph/planner): `src/graph/planner`
- [Optimizer](https://github.com/vesoft-inc/nebula/blob/master/src/graph/optimizer/Optimizer.cpp): `src/graph/optimizer/Optimizer.cpp`
- [Query Executors](https://github.com/vesoft-inc/nebula/tree/master/src/graph/executor): `src/graph/executor`
- [Admin Executors](https://github.com/vesoft-inc/nebula/tree/master/src/graph/executor/admin): `src/graph/executor/admin`
- [Graph Algorithms](https://github.com/vesoft-inc/nebula/tree/master/src/graph/executor/algo): `src/graph/executor/algo`

### Metadata

- [Metadata Client](https://github.com/vesoft-inc/nebula/blob/master/src/clients/meta/MetaClient.cpp): `src/clients/meta/MetaClient.cpp`
- **Metadata Service**
- [Schema Manager](https://github.com/vesoft-inc/nebula/blob/master/src/common/meta/ServerBasedSchemaManager.cpp): `src/common/meta/ServerBasedSchemaManager.cpp`
- [Index Manager](https://github.com/vesoft-inc/nebula/blob/master/src/common/meta/ServerBasedIndexManager.cpp): `src/common/meta/ServerBasedIndexManager.cpp`

### Storage

- [Storage Client](https://github.com/vesoft-inc/nebula/blob/master/src/clients/storage/StorageClient.cpp): `src/clients/storage/StorageClient.cpp`
- [Storage Service](https://github.com/vesoft-inc/nebula/blob/master/src/storage/StorageServer.cpp): `src/storage/StorageServer.cpp`
- [Storage Execution](https://github.com/vesoft-inc/nebula/tree/master/src/storage/exec): `src/storage/exec`
- [KV Store](https://github.com/vesoft-inc/nebula/blob/master/src/kvstore/RocksEngine.cpp): `src/kvstore/RocksEngine.cpp`

### Query Data

- [Query Context](https://github.com/vesoft-inc/nebula/blob/master/src/graph/context/QueryContext.cpp): `src/graph/context/QueryContext.cpp`
- [Expressions](https://github.com/vesoft-inc/nebula/blob/master/src/common/expression/Expression.cpp): `src/common/expression/Expression.cpp`
- [Row Codec](https://github.com/vesoft-inc/nebula/tree/master/src/codec): `src/codec`

### Other components

- **Query Client**
- **Full-text Service**

## Connections

- Query Client → Graph Daemon: submits query
- Graph Daemon → Query Engine: dispatches
- Query Engine → Metadata Client: uses
- Query Engine → Schema Manager: creates
- Query Engine → Index Manager: creates
- Query Engine → Storage Client: creates
- Query Engine → Optimizer: creates
- Query Engine → Query Instance: executes
- Query Instance → Query Planner: plans
- Query Instance → Query Executors: runs
- Query Instance → Query Context: creates
- Query Executors → Expressions: evaluates
- Query Executors → Storage Client: requests data
- Admin Executors → Metadata Client: administers
- Graph Algorithms → Storage Client: requests data
- Metadata Client → Metadata Service: RPC
- Schema Manager → Metadata Client: reads schema
- Index Manager → Metadata Client: reads indexes
- Storage Client → Storage Service: partitioned RPC
- Storage Service → Storage Execution: dispatches
- Storage Execution → KV Store: reads and writes
- Storage Execution → Row Codec: decodes rows
- Query Executors → Full-text Service: full-text lookup