API docs by Redocly

实例子图查询 (0.1.3)

Download OpenAPI specification:

跨对象类展开关联，两个入口按是否已知拓扑分工：

  • query_instance_subgraph：已知路径。给一条或多条「对象类 → 关系类 → 对象类 …」的路径模板，按模板批量取数，可逐节点加过滤与排序。
  • explore_subgraph：未知拓扑。只给起点对象类、方向与最大跳数，路径由引擎 散出来。「这张订单牵连到什么」这类问题走这条。

两者打的是同一个下游端点，区别只在查询模式，返回体元素同型：路径模板模式返回 entries 数组（每条路径一个子图），探索模式返回单个子图。

不要为了用 query_instance_subgraph 去先枚举关系类再拼路径——那是把探索硬凑 成取数，跳数一多就是组合爆炸，而且容易漏路径。

与 object-instance.yaml 的分工：那边是单个对象类的平面 查询，这边是跨对象类的关联展开。对象类 ID 与关系类 ID 从 schema-search.yaml 的 search_schema 或 kn-explore.yaml 的 get_kn_detail 取。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ AppKey）。

Subgraph

按关系路径查询对象子图

relation_type_paths 可以放多条路径，每条独立查询、独立返回一个子图， 顺序与请求一致。

路径的顺序和方向是硬约束，写错会静默查出错误结果：

  • object_types 按节点出现顺序排列；n 跳路径长度为 n+1。即使某个节点没有 过滤条件，也必须占位保留其 id，否则顺序错位。
  • relation_types 按边出现顺序排列，长度为 n；第 i 条边的 source_object_type_id 必须等于 object_types[i].id， target_object_type_id 必须等于 object_types[i+1].id。
  • 边的方向由这组起终点与关系类自身定义的起终点是否一致决定：一致为正向， 相反为反向。

取主键：子图对象的主键在 _instance_identity 里，与 query_object_instance 同名同义。要把子图结果喂给 action.yaml 或 logic-property.yaml 时， 从这里取键值对，不要自己拼。

Authorizations:
OAuth2AppKey
query Parameters
kn_id
required
string

知识网络 ID。

include_logic_params
boolean
Default: false

是否返回逻辑属性的计算参数。默认 false，结果不含逻辑属性字段与值。

response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

Request Body schema: application/json
required
required
object (BKNContext)

BKN Trace 业务溯源上下文，声明这次调用属于哪一轮业务对话。REST 面必填。

两个必填子字段均为服务端签发的句柄、不可自拟：

  • conversation_id：首轮调用 Context Loader MCP 工具 bkn_start_interaction 取得
  • interaction_id：调用 Context Loader 的 MCP 工具 bkn_start_interaction 取得

这两个句柄只能经上述 MCP 溯源工具取得。BKN Trace Core 的 /api/agent-observability/v1 会话接口只接受集群内可信服务的网关凭据， 不接受 OAuth token 或 bak_ AppKey，外部调用方直接调用会得到 401 permission_denied。 Context Loader 按请求关联信息、工具名和规范化输入服务端派生 Operation 幂等标识；调用方不得提交 operation_key。网络重试应复用 bkn-request-id，或提供同一次逻辑调用稳定不变的 X-OpenBKN-Client-Invocation-Id 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

required
Array of objects (RelationTypePath)

关系路径集合。多条路径同时查询，各自返回独立子图。

Responses

Request samples

Content type
application/json
{
  • "relation_type_paths": [
    ]
}

Response samples

Content type
{
  • "entries": [
    ]
}

从起点探索关联子图

不需要预先知道拓扑：给起点对象类、方向与最大跳数，引擎沿概念定义的关系散开， 返回命中的对象与它们之间的路径。

分页与排序只切起点：limit / sort / offset / search_after 全部作用于 起点对象类的实例集合，不是路径条数、也不是返回对象总数。limit: 10 的含义 是「从至多 10 个起点出发」，每个起点散出多少条路径由拓扑决定。

path_length 必填，取 1-3，缺失或越界都在 Context Loader 侧返回 400。 下界必须拦在这里：path_length 为 0 时下游不报错，只返回空子图，会被读成 「什么都没连上」。路径数随跳数快速增长，先从 1-2 起步，不够再加。

condition 只过滤起点，不约束路径上的其他对象类。要约束中间节点就说明 路径其实是已知的，改用 query_instance_subgraph 逐节点加条件。

isolated_objects 是有效结论不是失败：它明确回答了「这些起点在给定方向与 跳数内没有关联」。不要因为它有值就重试或改问法。

取主键：与 query_instance_subgraph 一致，对象主键在 _instance_identity 里，可直接喂给 action.yaml 或 logic-property.yaml。

Authorizations:
OAuth2AppKey
query Parameters
kn_id
required
string

知识网络 ID。

include_logic_params
boolean
Default: false

是否返回逻辑属性的计算参数。默认 false。

response_format
string
Default: "json"
Enum: "json" "toon"

响应格式。toon 返回 application/toon，同构数组压成表格，省 token。

Request Body schema: application/json
required
source_object_type_id
required
string

探索起点的对象类 ID。

direction
required
string
Enum: "forward" "backward" "bidirectional"

探索方向。forward 沿关系定义的出边，backward 沿入边， bidirectional 两个方向都走。不确定关系怎么建模时用 bidirectional。

path_length
required
integer [ 1 .. 3 ]

最大跳数，取 1-3。超出返回 400。

object (Condition)

过滤条件。逻辑算子（and / or）用 sub_conditions 组合；叶子条件用 field + operation + value + value_from。value 与 value_from 必须成对出现，value_from 目前只支持 const。

可用算子以对象类的 condition_operations 为准，见 kn-explore.yaml。

concept_groups
Array of strings

概念分组 ID，把探索范围限定在这些分组内的概念上。不传则不限。

include_incomplete_path
boolean
Default: false

是否返回残缺路径——已走过至少一条边、但未走满 path_length 就无路可走 的那些。默认只返回完整路径。零边路径任何情况下都不返回。

limit
integer [ 1 .. 10000 ]
Default: 10

起点对象类的实例数量上限，不是路径条数上限。

Array of objects (SortSpec)

起点对象类的排序，按数组顺序依次比较。与 limit 配合决定「从哪些 起点出发」，不影响路径本身的顺序。元素不可为 null。

offset
integer

起点对象类的偏移翻页。与 search_after 互斥。

search_after
Array of any

起点对象类的游标翻页。与 offset 互斥。

Responses

Request samples

Content type
application/json
Example
{
  • "source_object_type_id": "ot_purchase_order",
  • "direction": "bidirectional",
  • "path_length": 2,
  • "condition": {
    },
  • "limit": 10
}

Response samples

Content type
{
  • "objects": {
    },
  • "isolated_objects": {
    },
  • "relation_paths": [
    ],
  • "current_path_number": 0,
  • "overall_ms": 0,
  • "total_count": 0,
  • "search_after": [
    ]
}