创建语义条目

创建语义配置条目，为数据表补充字段、指标、关联和业务规则等定义。

POST https://api.moi.matrixorigin.cn/v5/semantic-models/{model_id}/entries

调用前准备

先查询知识库列表取得知识库 ID。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求体

请求示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/semantic-models/$MODEL_ID/entries" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "metric",
    "key": "gmv",
    "tables": ["orders"],
    "spec": {
      "name": "GMV",
      "metric_type": "aggregate",
      "aggregation": "SUM",
      "field": "amount",
      "source_table": "orders"
    }
  }'

参数说明

路径参数

字段	类型	必填	说明
model_id	integer	是	要创建语义条目的知识库 ID。

请求体

类型后的 [] 表示数组。例如，string[] 是字符串数组。

字段	类型	必填	说明
kind	string	是	条目类型；它决定 spec 的结构。
key	string	是	知识库内的稳定引用键。
tables	array of string	否	关联的表名称，不是 Catalog 表 ID。
spec	object	是	类型专属配置对象；服务端只接受下表列出的 kind 对应结构。
key 在同一知识库内必须唯一；tables 不传时可省略，传入时每个名称必须是该知识库已配置的表。

spec 配置

在同一条目中，先选择 kind，再按下表提交对应的 spec 字段。

字段	类型	必填	说明
业务指标	metric	否	定义聚合指标或派生指标。
表描述	table_description	否	描述一张数据表。
字段描述	field_description	否	描述一个字段。
业务规则	business_rule	否	定义业务规则或术语。
过滤约束	constraint	否	定义结构化筛选条件。
表关联	relationship	否	定义两张已配置表的关联。
标准问答	standard_qa	否	保存问题及其参考 SQL。
动态查询	dynamic_query	否	保存可委派处理的 SQL 查询。

旧类型 glossary、logic_text、verified_query、dimension、fact、column_preference、named_filter、default_constraint 和 sql_resultset 不再接受。原本的术语解释和自然语言规则请改用 business_rule，并在 spec.rule 中填写完整规则。

业务指标

下面表格展开请求示例中 spec 对象；仅当 kind 为 metric 时使用。metric_type 为 derived 时使用 formula，不能传自由 SQL expr。

字段	类型	必填	说明
name	string	是	指标名称。
metric_type	string	是	指标类型。
aggregation	string	聚合指标时是	聚合方式。
field	string	聚合指标时是	要聚合的字段。
source_table	string	否	指标来源表。
formula	object	派生指标时是	派生指标的公式树。

表关联

下面表格展开 relationship 类型的 spec 对象；每一行是该对象的一个字段。

字段	类型	必填	说明
left_table	string	否	左侧表名称。
right_table	string	否	右侧表名称。
join_type	string	否	关联类型。
conditions	array of object	是	关联条件。

关联字段

下面表格展开请求示例中 spec.conditions 数组的每一项；每一行是该数组项的一个字段。

字段	类型	必填	说明
left	string	是	左侧列名称。
right	string	是	右侧列名称。
operator	string	是	比较运算符。

其他类型的必填 spec 字段如下：table_description 使用 table 和 description，field_description 使用 column，business_rule 使用 rule，constraint 使用 filter，standard_qa 使用 question，dynamic_query 使用 sql。

成功响应

成功时返回 201；保存 data.id 用于后续更新和删除。

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 501,
    "kind": "metric",
    "key": "gmv",
    "tables": ["orders"],
    "spec": {
      "name": "GMV",
      "metric_type": "aggregate",
      "aggregation": "SUM",
      "field": "amount",
      "source_table": "orders"
    },
    "created_at": 1735632000,
    "updated_at": 1735632000
  }
}

字段说明

通用字段

字段	类型	说明
code	string	成功时为 OK。
msg	string	成功时为 OK。
data	object	本次操作的返回数据。

语义条目

下面表格展开响应示例中 data 对象；每一行是该对象的一个字段。

字段	类型	说明
id	integer	新条目 ID。
kind	string	已创建的条目类型。
key	string	知识库内的稳定引用键。
tables	array of string	关联表名称；未设置时可能省略。
spec	object	类型专属配置对象；返回结构严格由 data.kind 决定，字段说明见本页“spec 配置”。
created_at	integer	Unix 时间戳。
updated_at	integer	Unix 时间戳。

条目定义

下面表格展开响应示例中 data.spec 对象；实际字段随 kind 变化。

字段	类型	说明
name	string	示例中指标条目的名称。
metric_type	string	示例中指标的类型。

错误响应

响应示例

{
  "code": "ErrParamInvalid",
  "msg": "invalid semantic entry",
  "data": null
}

字段说明

字段	类型	说明
code	string	错误代码。
msg	string	面向调用者的错误信息。
data	null	发生错误时为 null。

后续操作

使用 data.id 更新语义条目或删除语义条目。

最后更新于 2026 年 9 月 28 日