API docs by Redocly

ontology-query (0.2.0)

Download OpenAPI specification:

检索指定对象类的对象的详细数据

path Parameters
kn_id
required
string

业务知识网络ID

ot_id
required
string

对象类ID

query Parameters
branch
string
Default: "main"

分支，默认 main

include_type_info
boolean

是否包含对象类信息, 默认false，不包含

include_logic_params
boolean

包含逻辑属性的计算参数，默认false，返回结果不包含逻辑属性的字段和值

exclude_system_properties
Array of strings
Items Enum: "_instance_id" "_instance_identity" "_display"

需要排除的系统字段列表。可选值：_instance_id（实例ID）、_instance_identity（实例唯一标识）、_display（显示值）。如果指定了某个字段，则在返回的对象数据中不包含该字段。可以传递多个值，例如：?exclude_system_properties=_instance_id&exclude_system_properties=_display

ignoring_store_cache
boolean

是否忽略索引查询，默认false，不忽略，即走索引查询

header Parameters
X-HTTP-Method-Override
required
string
Value: "GET"

重载 post，实际上是 get 方法

Request Body schema: application/json
required
One of
condition_and (object) or condition_or (object) or condition_eq (object) or condition_not_eq (object) or condition_gt (object) or condition_gte (object) or condition_lt (object) or condition_lte (object) or condition_in (object) or condition_not_in (object) or condition_like (object) or condition_not_like (object) or condition_range (object) or condition_out_range (object) or condition_exist (object) or condition_not_exist (object) or condition_regex (object) or condition_match (object) or condition_match_phrase (object) or condition_knn (object) or condition_multi_match (object) (Condition)
Array of objects (Sort)

排序字段，默认使用 _score 倒序，主键字段正序

limit
required
integer

返回的数量，默认值 10。范围 1-10000

need_total
boolean

是否需要总数，默认false

properties
Array of strings

指定需要输出的属性集。默认为全部数据属性

Responses

Request samples

Content type
application/json
Example
{
  • "condition": {
    },
  • "need_total": true,
  • "limit": 10
}

Response samples

Content type
application/json
Example
{
  • "object_type": {
    },
  • "datas": [
    ],
  • "total_count": 1,
  • "search_after": [
    ]
}

行动查询

path Parameters
kn_id
required
string

业务知识网络id

at_id
required
string

行动类id

query Parameters
branch
string
Default: "main"

分支名称，默认 main

include_type_info
boolean
Default: false

是否包含行动类信息（true/false）。未传时按 false 处理。

exclude_system_properties
Array of strings
Items Enum: "_instance_id" "_instance_identity" "_display"

需要排除的系统字段列表。可选值：_instance_id（实例ID）、_instance_identity（实例唯一标识）、_display（显示值）。如果指定了某个字段，则在返回的对象数据中不包含该字段。可以传递多个值，例如：?exclude_system_properties=_instance_id&exclude_system_properties=_display

header Parameters
x-http-method-override
required
string
Value: "GET"

必须为 GET，与 POST 语义组合以实现「POST 载荷 + GET 语义」的行动查询。

Request Body schema: application/json
required
Array of objects (InstanceIdentity)

目标对象主键列表。每项为主键字段名到值的映射。可为空数组或省略，表示由服务端依据行动类绑定与条件拉取候选实例。

object

行动类「动态输入」参数取值（与行动类 parameters 中 value_from=input 的 name 对应，支持点分路径表示嵌套键）。 当行动类定义了此类参数且要求客户端提供时须传入对应非 null 取值，否则可能在业务层返回 400（例如 OntologyQuery.ActionType.InvalidParameter.DynamicParams）。

Responses

Request samples

Content type
application/json
{
  • "_instance_identities": [
    ],
  • "dynamic_params": {
    }
}

Response samples

Content type
application/json
{
  • "action_type": {
    },
  • "action_source": {
    },
  • "actions": [
    ],
  • "total_count": 1,
  • "overall_ms": 1163
}

子图查询

子图查询，可以是基于起点、方向和路径长度获取对象子图，有可以是基于路径获取对象子图，查询请求方式和返回体不同

path Parameters
kn_id
required
string

业务知识网络ID

query Parameters
branch
string

分支名称，默认 main（与实现 DefaultQuery branch 一致）

include_logic_params
boolean

包含逻辑属性的计算参数，默认false，返回结果不包含逻辑属性的字段和值

exclude_system_properties
Array of strings
Items Enum: "_instance_id" "_instance_identity" "_display"

需要排除的系统字段列表。可选值：_instance_id（实例ID）、_instance_identity（实例唯一标识）、_display（显示值）。如果指定了某个字段，则在返回的对象数据中不包含该字段。可以传递多个值，例如：?exclude_system_properties=_instance_id&exclude_system_properties=_display

query_type
string
Enum: "" "relation_path"

查询类型，默认是子图探索，即基于起点、方向和路径长度获取对象子图；若是relation_path，则表示基于路径获取对象子图

ignoring_store_cache
boolean

是否忽略索引查询，默认false，不忽略，即走索引查询

header Parameters
x-http-method-override
required
string
Value: "GET"

重载 POST，须为 GET（与对象实例查询等接口一致，实现中强制校验）

Request Body schema: application/json
required

子图查询请求体

One of
concept_groups
Array of strings

概念分组id数组

source_object_type_id
required
string

起点对象类id

condition_and (object) or condition_or (object) or condition_eq (object) or condition_not_eq (object) or condition_gt (object) or condition_gte (object) or condition_lt (object) or condition_lte (object) or condition_in (object) or condition_not_in (object) or condition_like (object) or condition_not_like (object) or condition_range (object) or condition_out_range (object) or condition_exist (object) or condition_not_exist (object) or condition_regex (object) or condition_match (object) or condition_match_phrase (object) or condition_knn (object) or condition_multi_match (object) (Condition)
direction
required
string
Enum: "forward" "backward" "bidirectional"

探索子图的路径方向

path_length
required
integer

探索子图的路径的最大长度

include_incomplete_path
boolean
Default: false

是否包含不完整的路径。默认是false，不包含，只返回完整的路径

Array of objects (Sort)

对起点类的排序字段

limit
integer

对起点类的对象数量的限制。默认是10

need_total
boolean

是否需要(起点类)总数，默认false。

search_after
Array of any

上次查询返回的最后一个起点类对象的排序值。只对起点类生效。第一次查询不传此字段

Responses

Request samples

Content type
application/json
Example
{
  • "source_object_type_id": "comment",
  • "direction": "forward",
  • "path_length": 2,
  • "need_total": true,
  • "limit": 2
}

Response samples

Content type
application/json
Example
{
  • "objects": {
    },
  • "relation_paths": [
    ],
  • "total_count": 151043,
  • "search_after": [
    ],
  • "current_path_number": 44,
  • "overall_ms": 4204
}

基于一组对象实例组织关系子图

给定一组对象实例，按概念定义的关系，组织这些对象实例的关系子图。

path Parameters
kn_id
required
string

业务知识网络ID

query Parameters
branch
string

分支名称

include_type_info
boolean

是否包含对象类信息，默认false，不包含

include_logic_params
boolean

包含逻辑属性的计算参数，默认false，返回结果不包含逻辑属性的字段和值

ignoring_store_cache
boolean

是否忽略索引查询，默认是false，不忽略，即走索引查询

exclude_system_properties
Array of strings
Items Enum: "_instance_id" "_instance_identity" "_display"

需要排除的系统字段列表。可选值：_instance_id（实例ID）、_instance_identity（实例唯一标识）、_display（显示值）。如果指定了某个字段，则在返回的对象数据中不包含该字段。可以传递多个值，例如：?exclude_system_properties=_instance_id&exclude_system_properties=_display

Request Body schema: application/json
required

基于一组对象实例探索关系子图的请求体

required
Array of objects (InputObjectInstance)

对象实例数组

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "objects": {
    },
  • "isolated_objects": {
    },
  • "relation_paths": [
    ],
  • "overall_ms": 150
}

对象属性值查询

path Parameters
kn_id
required
string

业务知识网络ID

ot_id
required
string

对象类ID

query Parameters
branch
string

分支名称，默认 main

include_type_info
boolean

是否包含对象类信息，默认 false

exclude_system_properties
Array of strings
Items Enum: "_instance_id" "_instance_identity" "_display"

需要排除的系统字段列表。可选值：_instance_id（实例ID）、_instance_identity（实例唯一标识）、_display（显示值）。如果指定了某个字段，则在返回的对象数据中不包含该字段。可以传递多个值，例如：?exclude_system_properties=_instance_id&exclude_system_properties=_display

header Parameters
x-http-method-override
required
string
Value: "GET"

重载 post，实际上是 get 方法

Request Body schema: application/json
required

属性查询请求体

required
Array of objects (InstanceIdentity)

对象主键的数组，代表多个对象。每项为 map，key 为主键属性名，value 为对应的属性值

properties
required
Array of strings

属性列表

object

各逻辑属性所需的动态参数：外层 key 为逻辑属性名，内层为参数名到取值的 map。 当属性是指标属性时，内层结构可遵循 MetricPropertyDynamicParams（时间、分析维度等）； 算子属性则为参数名到标量或嵌套对象的映射。未传或某属性无动态需求时可省略该 key。

Responses

Request samples

Content type
application/json
{
  • "_instance_identities": [
    ],
  • "properties": [
    ],
  • "dynamic_params": {
    }
}

Response samples

Content type
application/json
{
  • "datas": [
    ],
  • "overall_ms": 2588
}

执行行动类

异步提交行动执行，立即返回 execution_id。 默认启用防重复：同一知识网络、行动类、目标实例与 dynamic_params 指纹在配置窗口内 若已有进行中（pending/running）且 start_time 落在窗口内的执行，则返回 409。

path Parameters
kn_id
required
string

业务知识网络ID

at_id
required
string

行动类ID

query Parameters
branch
string

分支名称，默认 main

Request Body schema: application/json
required
Array of objects (InstanceIdentity)

目标对象唯一标识列表；扫描模式下可传空数组，由服务端按行动条件拉取实例

object

与行动类 input 参数名对应的取值（支持点分路径）。有 input 参数时必填且不能为 null。

Responses

Request samples

Content type
application/json
{
  • "_instance_identities": [
    ],
  • "dynamic_params": {
    }
}

Response samples

Content type
application/json
{
  • "execution_id": "cqq2g8h4d2fg00fvm8dg",
  • "status": "pending",
  • "message": "Action execution started",
  • "created_at": 1704067200000
}

获取行动执行状态

path Parameters
kn_id
required
string

业务知识网络ID

execution_id
required
string

执行ID

Responses

Response samples

Content type
application/json
{
  • "id": "cqq2g8h4d2fg00fvm8dg",
  • "kn_id": "kn_xxx",
  • "action_type_id": "at_xxx",
  • "action_type_name": "restart_pod",
  • "action_source_type": "tool",
  • "object_type_id": "ot_xxx",
  • "trigger_type": "manual",
  • "status": "completed",
  • "total_count": 2,
  • "success_count": 1,
  • "failed_count": 1,
  • "results": [
    ],
  • "executor_id": "user_xxx",
  • "executor": {
    },
  • "start_time": 1704067200000,
  • "end_time": 1704067206200,
  • "duration_ms": 6200
}

查询行动执行日志

path Parameters
kn_id
required
string

业务知识网络ID

query Parameters
action_type_id
string

行动类ID（可选）

status
string
Enum: "pending" "running" "completed" "failed" "cancelled"

执行状态（可选）

trigger_type
string
Enum: "manual" "scheduled"

触发类型（可选）

start_time_from
integer <int64>

开始时间范围-起始（毫秒时间戳，可选）

start_time_to
integer <int64>

开始时间范围-结束（毫秒时间戳，可选）

limit
integer
Default: 20

返回数量限制，默认20，最大1000

offset
integer
Default: 0

偏移量，默认 0；与 search_after 互斥，传了 search_after 后本参数失效

need_total
boolean
Default: false

是否需要返回总数

search_after
string

分页游标（逗号分隔字符串，如 "1704067200000,cqq2g8h4d2fg00fvm8dg"）

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total_count": 100,
  • "search_after": [
    ]
}

获取单条行动执行日志

path Parameters
kn_id
required
string

业务知识网络ID

log_id
required
string

日志ID (即执行ID)

query Parameters
results_limit
integer
Default: 100

results 分页大小，默认100，最大1000

results_offset
integer
Default: 0

results 偏移量，默认0

results_status
string
Enum: "success" "failed"

按 results 中的状态过滤（可选）

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kn_id": "string",
  • "action_type_id": "string",
  • "action_type_name": "string",
  • "action_source_type": "tool",
  • "object_type_id": "string",
  • "trigger_type": "manual",
  • "status": "pending",
  • "execution_mode": "once",
  • "target_count": 0,
  • "total_count": 0,
  • "success_count": 0,
  • "failed_count": 0,
  • "results": [
    ],
  • "results_total": 0,
  • "results_offset": 0,
  • "results_limit": 0,
  • "dynamic_params": { },
  • "executor_id": "string",
  • "executor": {
    },
  • "start_time": 0,
  • "end_time": 0,
  • "duration_ms": 0,
  • "instance_identity_hash": "string",
  • "action_type_snapshot": { },
  • "action_source": {
    }
}

取消正在执行的任务

path Parameters
kn_id
required
string

业务知识网络ID

log_id
required
string

日志ID (即执行ID)

Request Body schema: application/json
optional
reason
string

取消原因（可选）

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "execution_id": "cqq2g8h4d2fg00fvm8dg",
  • "status": "cancelled",
  • "message": "任务已取消",
  • "cancelled_count": 5,
  • "completed_count": 10
}

查询指标数据（BKN 原生指标）

查询已落库的 object_type 作用域 atomic 指标（定义见 bkn-backend MetricDefinition）。

定义内过滤 vs 查询时过滤

执行时将以下条件 按 AND 合并（不是覆盖）后下推到 Vega/resource：

  1. MetricDefinition.calculation_formula.condition（定义内口径，稳定 KPI）
  2. 本请求体 condition（查询时下钻 / 临时收窄）
  3. 由 time 或 time_dimension.default_range_policy 推导的时间范围条件（instant / 趋势查询时）

合并规则：语义上等价于 AND(definition.condition, request.condition, timeCondition)，任一侧为空则省略。 实现上为两层嵌套（先合并 definition 与 request，再与时间条件 AND），下推 filter 可能出现 sub_conditions 嵌套，而非扁平三元组。

analysis_dimensions 与 group_by

  • calculation_formula.group_by：定义内的固定分组基线，每次查询都会参与 group_by。
  • analysis_dimensions（请求体）：在指标 analysis_dimensions 白名单内的追加下钻维度，按请求顺序接在 group_by 之后；未知维度名忽略。
  • 趋势查询（time.instant 为 false 或省略，且提供 time.step）会额外追加时间分桶维度。

建模 CRUD 与能力矩阵见 bkn-metrics.yaml；对象类级总量指标应使用本接口，而非对象实例页的 logic-property 执行入口。

path Parameters
kn_id
required
string

业务知识网络ID

metric_id
required
string

指标 ID（BKN MetricDefinition.id）

query Parameters
branch
string

分支，默认 main

fill_null
boolean
Default: false

趋势（区间）查询时，将各序列值对齐到 [time.start, time.end] 的完整分桶时间轴，缺失分桶以 null 填充；与 mdl-uniquery 指标数据查询的 fill_null 一致，为 URL 查询参数（非 body）。仅当 instant 为 false 或省略时有效。

Request Body schema: application/json
required
object
condition_and (object) or condition_or (object) or condition_eq (object) or condition_not_eq (object) or condition_gt (object) or condition_gte (object) or condition_lt (object) or condition_lte (object) or condition_in (object) or condition_not_in (object) or condition_like (object) or condition_not_like (object) or condition_range (object) or condition_out_range (object) or condition_exist (object) or condition_not_exist (object) or condition_regex (object) or condition_match (object) or condition_match_phrase (object) or condition_knn (object) or condition_multi_match (object) (Condition)
analysis_dimensions
Array of strings
Array of objects (MetricQueryOrderBy)
object (HavingCondition)

having值数据过滤

object (Metrics)

同环比、占比分析

limit
integer >= 1

仅返回前 limit 条 Data 序列（MetricData.datas）

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
Example
{
  • "model": {
    },
  • "datas": [
    ],
  • "step": "",
  • "is_variable": false,
  • "is_calendar": false
}

指标试算（不落库）

运行时字段（time / condition / analysis_dimensions 等）与 POST .../metrics/{metric_id}/data 的 MetricQueryRequestBody 合并语义完全一致； 区别仅在于 definition 侧取自请求体 metric_config（含 calculation_formula.condition），而非落库定义。

path Parameters
kn_id
required
string
query Parameters
branch
string
fill_null
boolean
Default: false

与「查询指标数据」接口相同；URL 查询参数，非 body。

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

试算请求体中的 metric_config：与 MetricDefinition 中参与执行的字段 JSON 同构；id、name、kn_id、branch、tags 等可省略。 不包含服务端管理字段（creator、create_time、updater、update_time、module_type）。

object
condition_and (object) or condition_or (object) or condition_eq (object) or condition_not_eq (object) or condition_gt (object) or condition_gte (object) or condition_lt (object) or condition_lte (object) or condition_in (object) or condition_not_in (object) or condition_like (object) or condition_not_like (object) or condition_range (object) or condition_out_range (object) or condition_exist (object) or condition_not_exist (object) or condition_regex (object) or condition_match (object) or condition_match_phrase (object) or condition_knn (object) or condition_multi_match (object) (Condition)
analysis_dimensions
Array of strings
Array of objects (MetricQueryOrderBy)
object (HavingCondition)

having值数据过滤

object (Metrics)

同环比、占比分析

limit
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "metric_config": {
    },
  • "time": { },
  • "condition": {
    },
  • "analysis_dimensions": [
    ],
  • "order_by": [
    ],
  • "having": {
    },
  • "metrics": {
    },
  • "limit": 1
}

Response samples

Content type
application/json
{
  • "model": {
    },
  • "datas": [
    ],
  • "step": "string",
  • "is_variable": true,
  • "is_calendar": true
}