API 参考: 知识图谱 (Graph)

知识图谱端点。节点和边的增删查、关系遍历、全文搜索、批量同步。

图谱以 {id} (appId) 为单位隔离。底层使用 MongoDB 的 graph_nodes 和 graph_edges 集合。

列出图谱统计

GET /v1/graph

查询参数

参数	类型	说明
app_id	string	可选，按图谱 ID 过滤

请求示例

curl https://api.invoratec.cn/v1/graph \
  -H "X-API-Key: claw_xxxx"

响应

返回各图谱的节点和边统计信息。

---

获取指定图谱统计

GET /v1/graph/{id}/stats

路径参数

参数	类型	说明
id	string	图谱 ID (appId)

请求示例

curl https://api.invoratec.cn/v1/graph/my-graph/stats \
  -H "X-API-Key: claw_xxxx"

---

添加节点

POST /v1/graph/{id}/nodes

权限要求： write

使用 upsert 逻辑：如果已存在相同 externalId 的节点，自动更新。

路径参数

参数	类型	说明
id	string	图谱 ID

请求体

字段	类型	必填	说明
type	string	是	节点类型 (如 Device, Room, Employee)
name	string	是	节点名称
externalId	string	否	外部系统ID，用于去重。默认为 name 的下划线形式
properties	object	否	自定义属性键值对

请求示例

curl -X POST https://api.invoratec.cn/v1/graph/my-graph/nodes \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Device",
    "name": "冷水机-01",
    "externalId": "CW-001",
    "properties": {
      "floor": "B1",
      "power": "500kW"
    }
  }'

响应 (201 Created)

返回创建/更新后的节点文档。

错误

状态码	说明
400	type 或 name 缺失
403	缺少 write 权限

---

查询节点

GET /v1/graph/{id}/nodes

路径参数

参数	类型	说明
id	string	图谱 ID

查询参数

参数	类型	说明
object_type	string	按节点类型过滤
name	string	按名称模糊匹配
limit	integer	返回上限，默认 100

请求示例

curl "https://api.invoratec.cn/v1/graph/my-graph/nodes?object_type=Device&limit=50" \
  -H "X-API-Key: claw_xxxx"

响应

{
  "nodes": [
    {
      "appId": "my-graph",
      "objectType": "Device",
      "externalId": "CW-001",
      "name": "冷水机-01",
      "properties": { "floor": "B1", "power": "500kW" }
    }
  ],
  "total": 1
}

---

添加关系 (边)

POST /v1/graph/{id}/edges

权限要求： write

路径参数

参数	类型	说明
id	string	图谱 ID

请求体

字段	类型	必填	说明
from	string	是	起始节点名称或 externalId
to	string	是	目标节点名称或 externalId
relation	string	是	关系类型 (如 LOCATED_IN, REPORTS_TO)
properties	object	否	关系的自定义属性

请求示例

curl -X POST https://api.invoratec.cn/v1/graph/my-graph/edges \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "冷水机-01",
    "to": "机房-B1",
    "relation": "LOCATED_IN",
    "properties": { "since": "2024-01-01" }
  }'

响应 (201 Created)

返回创建的边文档。

错误

状态码	说明
400	from、to 或 relation 缺失
403	缺少 write 权限

---

全文搜索

在图谱中搜索节点，可同时返回相邻节点的信息。

POST /v1/graph/{id}/search

路径参数

参数	类型	说明
id	string	图谱 ID

请求体

字段	类型	必填	说明
query	string	否	搜索关键词
object_type	string	否	按节点类型过滤
limit	integer	否	返回上限，默认 20
includeNeighbors	boolean	否	是否返回相邻节点，默认 true

请求示例

curl -X POST https://api.invoratec.cn/v1/graph/my-graph/search \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "冷水机",
    "object_type": "Device",
    "limit": 20,
    "includeNeighbors": true
  }'

响应

返回匹配的节点列表及其相邻节点和关系。

---

关系遍历

从指定节点出发，沿关系路径遍历图谱。

POST /v1/graph/{id}/traverse

路径参数

参数	类型	说明
id	string	图谱 ID

请求体

字段	类型	必填	说明
startNode	string	是	起始节点名称
relation	string	否	限定关系类型，不填遍历所有关系
depth	integer	否	遍历深度，默认 1，最大 3
direction	string	否	方向：outgoing/incoming/both（默认 both）

请求示例

curl -X POST https://api.invoratec.cn/v1/graph/my-graph/traverse \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "startNode": "冷水机-01",
    "relation": "LOCATED_IN",
    "depth": 2,
    "direction": "both"
  }'

响应

返回遍历到的节点和关系路径。

错误

状态码	说明
400	startNode 缺失

---

批量同步

从外部系统批量导入节点和关系。使用 upsert 逻辑，可安全重复执行。

POST /v1/graph/{id}/sync

权限要求： write

路径参数

参数	类型	说明
id	string	图谱 ID

请求体

字段	类型	必填	说明
nodes	array	否	节点数组，每个元素包含 type, name, externalId, properties
edges	array	否	边数组，每个元素包含 from, to, relation, properties

请求示例

curl -X POST https://api.invoratec.cn/v1/graph/my-graph/sync \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      { "type": "Device", "name": "冷水机-01", "externalId": "CW-001", "properties": { "power": "500kW" } },
      { "type": "Room", "name": "机房-B1" }
    ],
    "edges": [
      { "from": "冷水机-01", "to": "机房-B1", "relation": "LOCATED_IN" }
    ]
  }'

响应

{
  "success": true,
  "nodesWritten": 2,
  "edgesWritten": 1
}

错误

状态码	说明
403	缺少 write 权限