API docs by Redocly

逻辑属性求值 (0.1.3)

Download OpenAPI specification:

批量求一批对象实例的逻辑属性（指标 metric 或算子 operator）值。

逻辑属性不直接存在于数据源里，需要带参数计算，而参数往往藏在用户的自然语言里 （「最近一年」→ 时间窗、「按省份」→ 分析维度）。本接口先用大模型把 query 翻译成各属性的 dynamic_params，再批量取值，省掉调用方自己拼参数的工作。

对象类有哪些逻辑属性、各自需要什么参数，看 kn-explore.yaml 的 get_object_types 返回的 logic_properties[].parameters。

同一份文件里还有 POST /kn/query_metric：类级指标、或没绑到任何逻辑属性的 指标走它，直接按 metric_id 与 MetricDefinition 的口径取数。两条路的分工是 「实例 + 已绑逻辑属性 → logic-property-resolver，其余 → query_metric」； 已建模的指标一律不该用 run_sql 重写口径。指标清单来自 get_object_types 返回的 related_metrics。

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

LogicProperty

批量求逻辑属性值

query 的质量决定成败：参数由大模型从 query（必要时加 additional_context）里推断。查询里要含时间范围、统计维度等业务上下文， 否则会因缺参失败。

缺参返回 400，不是空结果：模型判定必需的 input 参数无法从查询推出时， 返回 400，details 里是 MISSING_INPUT_PARAMS 及逐属性的缺失说明。补上 上下文重试即可。

与之区分的是 500 DYNAMIC_PARAMS_GENERATION_FAILED：那是大模型或依赖服务 故障，不是调用方少给信息，重试或查服务状态。

结果与入参对齐：datas 与 _instance_identities 顺序一一对应，每项含 主键和本次请求的 properties。

Authorizations:
OAuth2AppKey
query Parameters
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 请求头。该提示只用于幂等，不参与身份、 权限或数据隔离判定。

kn_id
required
string

知识网络 ID。

ot_id
required
string

对象类 ID。

query
required
string

用户查询。需要包含时间范围、统计维度、业务上下文，用于生成 dynamic_params。信息不足会导致 400 缺参。

required
Array of objects

对象实例标识数组，必须从上游取，不可自拼：先调 query_object_instance 或 query_instance_subgraph，从每个对象的 _instance_identity 取值，按原顺序组成数组。

properties
required
Array of strings

要求值的逻辑属性名列表（metric 或 operator）。

additional_context
string

补充上下文，如 timezone、instant、step 或对象属性，帮助模型生成更准的 dynamic_params。

llm_model
string

覆盖用于生成动态参数的大模型；留空走系统默认大模型。

object (ResolveOptions)

高级选项。

Responses

Request samples

Content type
application/json
Example
{
  • "kn_id": "kn_medical",
  • "ot_id": "ot_company",
  • "query": "最近一年这些药企的药品上市数量和经营健康度",
  • "_instance_identities": [
    ],
  • "properties": [
    ]
}

Response samples

Content type
{
  • "datas": [
    ],
  • "debug": {
    }
}

按指标口径取数

按已建模指标自身的口径计算取数，是 OT-first 指标路径的第 3 步： search_schema / get_kn_detail 锁定对象类 → get_object_types 从 related_metrics 里选定 metric_id → 本接口计算。

与 logic-property-resolver 的分工：实例级、且已绑到逻辑属性的指标走那条 （它会先用大模型推参数）；类级指标、或未绑逻辑属性的指标走本接口，参数 由调用方显式给出，不经大模型。

time 在指标没有时间维度（related_metrics[].time_dimension 为空）时可整体 省略。给了就要自洽：**省略 instant 等同于 instant=false（序列查询）， 必须带 step**；instant=true 取单点（此时 step 被下游忽略）； start 与 end 要么都给要么都不给。step 大小写不敏感。

这些规则在本服务就地校验并返回 400，规则逐条对齐 ontology-query 的 validateMetricQueryRequest——本地比下游严会把合法调用误拒，比下游松只是 把同一个错误延后。

请求体与 ontology-query 的 MetricQueryRequestBody 同构；响应只保留结果序列， 不回带指标定义（related_metrics 里已经有了）。

Authorizations:
OAuth2AppKey
query Parameters
response_format
string
Default: "json"
Enum: "json" "toon"

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

header Parameters
x-kn-id
string

知识网络 ID 的请求头写法；请求体里给了 kn_id 时以请求体为准。

Request Body schema: application/json
required
kn_id
required
string

知识网络 ID。也可用 x-kn-id 头传。

metric_id
required
string

指标 ID，取自 get_object_types 返回的 related_metrics[].id， 或对象类逻辑属性 data_source 里引用的指标 ID。

object (MetricTimeWindow)

时间窗。指标没有时间维度时可整体省略；给了就要自洽（见接口说明）。

object

过滤条件，结构与 query_object_instance 的 condition 一致 （field / operation / value / value_from，可 and / or 嵌套）。

analysis_dimensions
Array of strings

分析维度（按维度拆分结果）。取值须来自 related_metrics[].analysis_dimensions。

Array of objects

结果排序。

object

对聚合结果过滤。

limit
integer

返回条数上限。

fill_null
boolean
Default: false

区间查询时，无数据的步长点是否补空。仅对序列查询有效，且必须同时给 time.start 与 time.end。

Responses

Request samples

Content type
application/json
Example
{
  • "kn_id": "kn_supplychain",
  • "metric_id": "metric_product_total"
}

Response samples

Content type
{
  • "kn_id": "string",
  • "metric_id": "string",
  • "datas": [
    ],
  • "overall_ms": 0
}