Skip to main content
TorchV文档中心

元数据字段与过滤

知识检索 的 metadataFilter 支持标准字段与当前租户已启用的自定义字段。自定义字段应先发现稳定的 fieldKey，再构造过滤条件。

发现自定义字段​

GET /openapi/paas/v1/knowledge/metadata/fields

使用 Authorization: Bearer tk-...，平台密钥要求 knowledge_search=READ。

Query 参数类型必填说明
namestring否按字段展示名称精确匹配
fieldKeystring否按稳定字段标识精确匹配

不传条件时列出当前租户启用的自定义字段，同时传入时两项都需匹配。不会列出停用字段。

curl --get "${BASE_URL}/openapi/paas/v1/knowledge/metadata/fields" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --data-urlencode "name=业务地区"
{
  "code": 8200,
  "message": "SUCCESS",
  "data": [
    {
      "fieldKey": "business_region",
      "name": "业务地区",
      "inputMode": "ENUM",
      "valueType": "STRING",
      "businessScopes": [],
      "options": [
        {"name": "华东", "optionValue": "east"}
      ]
    }
  ]
}

响应字段​

字段JSON 类型说明
dataarray[object]当前租户启用字段；无匹配时为空数组
data[].fieldKeystring稳定字段标识，用于构造 custom.fieldKey
data[].namestring展示名称，不应用作存储键
data[].inputModestringINPUT 自由输入，ENUM 枚举选项
data[].valueTypestringSTRING、INTEGER、DATE，决定比较值格式及操作符
data[].businessScopesarray[string]适用业务范围；空数组为全局，不代表停用
data[].optionsarray[object]启用的枚举项；非枚举字段可为空
data[].options[].namestring选项展示名称
data[].options[].optionValuestring检索时提交的稳定枚举值

inputMode 为 INPUT 或 ENUM；valueType 为 STRING、INTEGER 或 DATE。businessScopes 表示绑定的业务范围，空数组表示全局可用。options 列出启用的枚举选项，过滤时使用 optionValue，不是显示名称。

条件组结构​

{
  "logicalOperator": "AND",
  "conditions": [
    {"field": "suffix", "operator": "EQ", "value": "pdf"},
    {"field": "custom.business_region", "operator": "IN", "values": ["east"]}
  ],
  "groups": [
    {
      "logicalOperator": "OR",
      "conditions": [
        {"field": "author", "operator": "EQ", "value": "示例作者"},
        {"field": "title", "operator": "CONTAINS", "value": "产品"}
      ]
    }
  ]
}

将此对象放进检索请求的 metadataFilter。示例自定义字段需要在当前租户实际存在且启用，不能直接套用不存在的 fieldKey。

规则限制
logicalOperatorAND、OR，省略时默认 AND
嵌套深度最多 3 层，根组计为第 1 层
总条件数全部层级合计最多 20 条
单组集合conditions、groups 各最多 20 项；至少一项非空
IN、NOT_IN使用 values 数组，1～20 个值
其他比较使用字符串 value
EXISTS、NOT_EXISTS无需 value 或 values

标准字段比较值须非空，最长 256 字符；数值用整数字符串，标准时间戳用毫秒数字字符串。

过滤对象字段明细​

字段JSON 类型何时填写说明
logicalOperatorstring可省略当前组的 AND/OR 关系，默认 AND
conditionsarray[object]与 groups 至少一个非空当前层直接条件
conditions[].fieldstring每个条件必填标准字段或 custom.fieldKey
conditions[].operatorstring每个条件必填按字段类型选择下表操作符
conditions[].valuestring单值比较不传数值 JSON；数值也使用字符串
conditions[].valuesarray[string]IN / NOT_IN集合比较值
groupsarray[object]可选子条件组，递归复用本对象

过滤对象不是独立接口响应。它作为知识检索请求的一部分，成功返回检索响应；校验失败返回普通错误结构。

常用标准字段​

字段类别字段支持操作符
字符串及数组tag、title、author、suffix、pathTitle、keywordsEQ、NE、IN、NOT_IN、CONTAINS、NOT_CONTAINS、STARTS_WITH、ENDS_WITH、EXISTS、NOT_EXISTS
全文文本summaryCONTAINS、NOT_CONTAINS、EXISTS、NOT_EXISTS
整数fileSize（字节）EQ、NE、IN、NOT_IN、GT、GTE、LT、LTE、EXISTS、NOT_EXISTS
毫秒时间戳created、modified同整数
时间语义数组temporalTokens、temporalTitleTokens、temporalPathTokens、temporalContentTokens、temporalSummaryTokens同字符串；值由服务端进行时间语义归一化

以上列出常用公开字段。不要使用租户隔离、内部权限或数据库字段名自行构造过滤条件。

自定义字段​

字段格式是 custom.{fieldKey}，例如 custom.business_region。fieldKey 以小写字母开头，只含小写字母、数字和下划线，最长 64；使用发现接口返回值。

自定义类型值格式操作符
STRING字符串；枚举传 optionValueEQ、NE、IN、NOT_IN、EXISTS、NOT_EXISTS
INTEGER可解析的整数字符串上述操作符及 GT、GTE、LT、LTE
DATEyyyy-MM-dd同 INTEGER

自定义字符串暂不支持 CONTAINS、前缀或后缀匹配。自定义 DATE 使用日期字符串，和标准 created、modified 的毫秒时间戳不同。

{
  "logicalOperator": "AND",
  "conditions": [
    {"field": "custom.effective_date", "operator": "GTE", "value": "2026-09-01"},
    {"field": "created", "operator": "GTE", "value": "1788220800000"}
  ]
}

字段不存在、停用、比较值类型错误或操作符不支持时会失败。发现字段只代表定义可用；检索结果还取决于文档是否已标注对应元数据并完成索引更新。

Previous
知识检索
Next
标准知识问答（Chat）