# boomGraph

**Repository Path**: WZFlik/boomGraph

## Basic Information

- **Project Name**: boomGraph
- **Description**: miniGraph
- **Primary Language**: C++
- **License**: AFL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-08
- **Last Updated**: 2025-12-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BoomGraph — 轻量级嵌入式图数据库

BoomGraph 是一个基于 RocksDB 构建的轻量级图数据库引擎，BoomGraph的目标是提供子图匹配等图算法能力，并通过 HTTP API 对外服务。
它不依赖外部组件，启动即用，适合嵌入到 C++ 应用中，或作为微服务提供图计算能力，支持多图隔离和自动化装载。

## 核心设计理念

BoomGraph 的存储设计遵循三个核心原则：

### 1. 列族即表，前缀即索引

* 每个节点标签（如 `Person`）对应一个 RocksDB 列族（Column Family），例如 `ADJ_Person`。
* 所有邻接关系通过 Key 的前缀编码实现高效范围查询。
* 图结构完全由邻接表表达。

### 2. 边信息内嵌于邻接结构

* 每条边的方向（IN/OUT）、关系类型、目标节点标签、目标 ID 全部编码在 Key 中。
* Value 当前为空（节省空间），为未来属性扩展预留。

### 3. 极致紧凑，快速遍历

* 同一条边在源节点的 OUT 表和目标节点的 IN 表中各存一份（对称存储称为出/入边），支持高效的方向性遍历。
* 使用整型 ID（rowid）代替字符串标签/关系名，大幅减少存储开销，内部使用前缀提取快速查询。
* 启用 RocksDB WAL 日志，确保断电后数据不丢失，重启即可恢复。



## 存储结构详解

### 主表：邻接表（按节点标签分列族）


| 列族名        | 说明                              |
| ------------ | --------------------------------- |
| `ADJ_Person` | 存储所有`Person` 节点的出边和入边 |

#### Key 编码格式（定长二进制，共 33 字节）

 [8b(start_id) + 1b(direction) + 4b(relation_id) + 4b(end_label_id) + 8b(end_id) + 8b(rowid)]

* **方向**：`0 = OUT`（从本节点出发），`1 = IN`（指向本节点）
* **关系ID / 标签ID**：由元数据表将字符串映射为整数（如 `"invest" → 2`）
* **relation_id**:relation关系id
* **end_label_id**:结束标签id
* **end_id**:结束节点id
* **rowid**:当前边的唯一id，出边入边相同
* **Value**：当前为空（未来可用于存储边属性）
* **邻接表**：往点点边表中各自插入一条


## 快速开始

### 1. 编译 RocksDB v8.11.3

```
# 克隆并编译 RocksDB（启用 RTTI）
(1).rocksdb依赖安装
You can link RocksDB with following compression libraries:

zlib - a library for data compression.
bzip2 - a library for data compression.
lz4 - a library for extremely fast data compression.
snappy - a library for fast data compression.
zstandard - Fast real-time compression algorithm.

Linux - Ubuntu plantform

Linux - CentOS / RHEL

Upgrade your gcc to version at least 7 to get C++17 support

Install gflags:

    git clone https://github.com/gflags/gflags.git
    cd gflags
    git checkout v2.2.0
    ./configure && make && sudo make install
Notice: Once installed, please add the include path for gflags to your CPATH environment variable and the lib path to LIBRARY_PATH. If installed with default settings, the include path will be /usr/local/include and the lib path will be /usr/local/lib.

Install snappy:

    sudo yum install snappy snappy-devel
Install zlib:

    sudo yum install zlib zlib-devel
Install bzip2:

    sudo yum install bzip2 bzip2-devel
Install lz4:

    sudo yum install lz4-devel
Install ASAN (optional for debugging):

    sudo yum install libasan
Install zstandard:

With EPEL:

sudo yum install libzstd-devel


(2)下载rocksdb源码

git clone https://gitee.com/WZFlik/rocksdb.git

(3)进入rocksdb源码目录并执行make编译指令
cd rocksdb
git checkout v8.11.3
make static_lib -j$(nproc) USE_RTTI=1
sudo make install-static

#若编译时报错找不到 jemalloc，请先安装jmelloc,然后在rocksdb Makefile CXXFLAG前 中添加：
CFLAGS += -I/usr/local/jemalloc/include
CXXFLAGS += -I/usr/local/jemalloc/include
```


### 2. 编译 BoomGraph

手动编译： 进入项目根目录
  ```
 
  1.执行make分发指令
  make dist

  2.在项目根目录下会生成 发行包boomGraph-xxxx.tar.gz


  ```


### 3. 启动服务
解压包，进入boomGraph包目录

```
1.导入到指定图名
./boomGraph -f /path/to/csv -g mygraph

2.重启指定图名
./boomGraph -g mygraph

3.重启随机图名
./boomGraph 

4.帮助
./boomGraph -h

5.修改启动端口和ip

 boomGraph启动时默认监听0.0.0.0:8080 
使用 boomGraph -i xxx.xxx.xxx.xxx -p 9090

6.完整示例
./boomGraph -f /path/to/csv -g mygraph -i xxx.xxx.xxx.xxx -p 9090

7.帮助
./bin/boomGraph  -h 
示例：
a stand alone graph storage.
Usage:
  BoomGraph [OPTION...]

  -f, --file arg   Path to CSV file,the file and the graph name must be 
                   specified together.
  -g, --graph arg  Name of the graph,the file and the graph name must be 
                   specified together.
  -i, --ip arg     listen ip default 0.0.0.0
  -p, --port arg   listen port default 8080
  -h, --help       Print help

```

CSV 格式示例 (`data.csv`)：

| 起始节点id | 起始节点标签 | 边标签    | 终点id | 终点标签 |
| ---------- | ------------ | --------- | ------ | -------- |
| startId    | startLabel   | edgeLabel | endId  | endLabel |

## HTTP API 示例

### 连通分量

```
curl -X POST "http://localhost:8080/api/v1/algorithms/wcc" \
  -H "Content-Type: application/json" \
  -d '{
    "n_labels": ["Person", "Company"],
    "r_labels": ["invest"]
  }'
```
返回结果
```
{
  "code": 0,
  "data": {
    "component_count": 64 # 返回分量数量
  }
}

```


### 子图匹配查询
```
curl -X POST "http://localhost:8080/api/v1/algorithms/subgraph-matching" \
-H "Content-Type: application/json" \
-d '{
  "nodes": [
    {"var": "p1", "labels": ["Person"]},
    {"var": "c1", "labels": ["Company"]},
    {"var": "c2", "labels": ["Company"]},
    {"var": "p2", "labels": ["Person"]}
  ],
  "edges": [
    {"source": "p1", "target": "c1", "labels": ["invest"], "direction": "OUT"},
    {"source": "c1", "target": "c2", "labels": ["debt"], "direction": "OUT"},
    {"source": "p2", "target": "c2", "labels": ["invest"], "direction": "IN"}
  ]
}'

```
返回结果：
```
  {
  "code": 0,
  "data": {
    "count": 61124 # 返回同态子图总数
  }
}

```

## 项目依赖

* C++17
* cpp-httplib（HTTP server监听）
* nlohmann/json（JSON 解析）
* RocksDB v8.11.3（存储引擎）

## 适用场景

* 嵌入式图分析（风控、知识图谱、社交网络）
* 小规模图数据（百万级边以内）
* 需要快速部署、无外部依赖的图服务
* 教学或研究：理解图数据库底层存储原理

## 未来计划

* [ ]  点边分离
* [ ]  支持边/节点属性存储
* [ ]  支持并发查询与事务
## 致谢

本项目受 Neo4j 的邻接索引思想和 JanusGraph 的存储模型启发，但追求更轻、更快、更简单。

**BoomGraph — 让图查询，一触即发。**

```