Muotai SPG 快速参考手册

核心包速查

1. SPG服务层 (14个文件)

com.aroundix.spg
├── SpgApplication.java              # 启动类
├── controller/
│   ├── GraphController.java         # 图数据API
│   └── SchemaController.java        # Schema管理API
└── service/
    ├── GraphService.java            # 图服务
    └── SchemaService.java           # Schema服务

用途: REST API层，对外提供HTTP接口

---

2. LUBE查询引擎 (249个文件)

2.1 逻辑算子 (logical/operators/)

算子	功能	对应SQL
PatternScan	图模式扫描	MATCH
Filter	条件过滤	WHERE
Select	字段选择	SELECT
Aggregate	聚合计算	GROUP BY + 聚合函数
Project	投影转换	SELECT AS
Join	图连接	JOIN
OrderAndLimit	排序分页	ORDER BY + LIMIT

2.2 物理算子 (physical/operators/)

算子	功能	说明
Start	图起点	从指定节点开始
ExpandInto	边扩展	沿边展开
AddInto	添加字段	添加计算列
Cache	缓存	缓存中间结果
Fold/Unfold	折叠/展开	处理路径

2.3 核心类位置

com.aroundix.openspg.reasoner.lube
├── logical/
│   ├── operators/               # 逻辑算子 (20+个)
│   ├── optimizer/               # 查询优化器
│   │   └── rules/              # 优化规则
│   ├── planning/               # 逻辑计划生成
│   └── validate/               # 语义验证
│       └── semantic/rules/     # 验证规则
│
├── physical/
│   ├── operators/               # 物理算子 (30+个)
│   ├── planning/
│   │   └── PhysicalPlanner.java  # 物理计划生成器 ⭐
│   └── rdg/
│       └── RDG.java              # 关系数据图抽象
│
├── parser/                      # DSL解析器
│   ├── expr/                    # 表达式解析
│   └── pattern/                 # 模式解析
│
└── common/
    ├── expr/                    # 表达式系统
    ├── pattern/                 # 模式定义
    └── rule/                    # 规则引擎

---

3. 推理引擎其他组件

com.aroundix.openspg.reasoner
├── runner/local/                # 本地执行器 ⭐
│   ├── rdg/LocalRDG.java          # 本地RDG实现
│   └── impl/LocalPropertyGraph.java  # 本地图实现
│
├── pattern/
│   └── PatternMatcher.java        # 模式匹配器 ⭐
│
├── rdg/common/                  # RDG通用实现
│   ├── KgGraphLeftJoinImpl.java   # Left Join
│   ├── KgGraphAggregateImpl.java  # 聚合
│   └── LinkEdgeImpl.java          # 边链接
│
├── catalog/                     # 元数据管理
├── loader/                      # 数据加载
├── udf/                         # 用户自定义函数
└── utils/
    ├── KgGraphSchema.java         # 图Schema工具 ⭐
    └── RunnerUtil.java            # 执行工具

---

4. Builder构建引擎 (30个文件)

com.aroundix.openspg.builder
├── core/                        # 构建核心
├── model/                       # 数据模型
└── runner/                      # Pipeline执行器

功能: 从数据源构建知识图谱

---

5. Server服务端 (20个文件)

com.aroundix.openspg.server
├── api/http/client/
│   └── HttpSchemaFacade.java    # Schema远程访问 ⭐
├── biz/                         # 业务逻辑
├── model/project/
│   └── Project.java             # 项目模型
└── service/                     # 服务实现

---

常用操作速查

添加新的逻辑算子

// 1. 定义逻辑算子
// 位置: lube/logical/operators/MyOperator.java
public class MyOperator extends StackingLogicalOperator {
    @Override
    public List<Var> fields() {
        // 返回字段列表
    }

    @Override
    public LogicalOperator withNewChildren(LogicalOperator[] newChildren) {
        // 返回新实例
    }
}

// 2. 定义物理算子
// 位置: lube/physical/operators/MyOperator.java
public class MyOperator<T extends RDG<T>> extends PhysicalOperator<T> {
    @Override
    public T execute() {
        // 执行逻辑
    }
}

// 3. 更新物理规划器
// 位置: lube/physical/planning/PhysicalPlanner.java
private static <T extends RDG<T>> PhysicalOperator<T> plan(...) {
    if (input instanceof MyOperator) {
        return planMyOperator((MyOperator) input, context);
    }
    // ...
}

添加新的REST API

// 1. 定义DTO
// 位置: muotai-spg-api/dto/MyRequest.java
@Data
public class MyRequest {
    private String param1;
    private Integer param2;
}

// 2. 添加Controller
// 位置: muotai-spg-biz/controller/MyController.java
@RestController
@RequestMapping("/api/v1/my")
public class MyController {
    @PostMapping("/action")
    public R<String> myAction(@RequestBody MyRequest request) {
        return R.ok(myService.doAction(request));
    }
}

// 3. 实现Service
// 位置: muotai-spg-biz/service/impl/MyServiceImpl.java
@Service
public class MyServiceImpl implements MyService {
    @Override
    public String doAction(MyRequest request) {
        // 业务逻辑
    }
}

执行KGDSL查询

// 使用GraphService执行查询
@Autowired
private GraphService graphService;

public Object executeQuery(String kgdsl) {
    GraphQueryRequest request = new GraphQueryRequest();
    request.setQuery(kgdsl);
    request.setProjectId(projectId);

    return graphService.executeQuery(request);
}

// KGDSL示例
String kgdsl = """
    MATCH (u:User)-[r:KNOWS]->(f:User)
    WHERE u.age > 18
    RETURN u.name, f.name, r.since
    LIMIT 10
    """;

---

关键文件位置

配置文件

muotai-spg-biz/src/main/resources/
├── application.yml              # 主配置
├── bootstrap.yml                # 启动配置
└── mapper/                      # MyBatis映射
    └── *.xml

数据库实体

muotai-spg-api/src/main/java/com/aroundix/spg/api/entity/
├── KgOntologyEntity.java        # 本体实体
├── KgOntologyRelease.java       # Schema版本
├── KgProjectInfo.java           # 项目信息
└── KgPropertyConstraint.java    # 属性约束

核心引擎入口

物理计划生成:
  lube/physical/planning/PhysicalPlanner.java

逻辑计划优化:
  lube/logical/optimizer/LogicalOptimizer.java

DSL解析:
  parser/KGDSLParser.java

本地执行:
  runner/local/rdg/LocalRDG.java

模式匹配:
  pattern/PatternMatcher.java

---

依赖版本

依赖	版本	用途
Spring Boot	3.4.5	应用框架
Java	17	运行环境
Scala	2.12.18	推理引擎
MyBatis-Plus	3.5.x	数据访问
ANTLR4	4.13.x	DSL解析
Nacos	2.x	服务注册

---

编译命令

# 编译整个模块
mvn clean compile -pl muotai-spg

# 只编译Java代码
mvn compile -pl muotai-spg/muotai-spg-biz

# 编译Scala代码
mvn scala:compile -pl muotai-spg/muotai-spg-biz

# 跳过测试打包
mvn clean package -DskipTests -pl muotai-spg

# 构建Docker镜像
mvn clean package docker:build -pl muotai-spg/muotai-spg-biz

---

常见问题

Q: 编译错误 "找不到符号: 方法 pattern()"

A: Lombok getter方法调用错误

// ❌ 错误
patternScan.pattern()

// ✅ 正确
patternScan.getPattern()

Q: Scala类找不到

A: 需要先编译Scala代码

mvn scala:compile

Q: 查询执行缓慢

A: 检查执行计划并优化

1. 启用查询优化器
2. 添加适当索引
3. 使用Cache算子
4. 批量处理

---

目录索引

• 完整文档: MUOTAI-SPG-MODULE-STRUCTURE.md
• 核心模块: core-modules-guide.md
• 数据库设计: MUOTAI-SPG-DATABASE-DESIGN-GUIDE.md
• DSL解析: dsl-parsing-locations.md

---

快速参考版本: v1.0最后更新: 2025-12-19