创建语义条目

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

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": "total_rows",
    "tables": ["orders"],
    "spec": {
      "expr": "COUNT(*)"
    }
  }'

参数说明

路径参数

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

请求体

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

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

spec 配置

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

字段	类型	必填	说明
维度列	dimension	否	描述用于分组、筛选的字段。
事实列	fact	否	描述可参与计算的事实字段。
业务指标	metric	否	定义指标计算表达式。
表关联	relationship	否	定义两张已配置表的关联。
列偏好	column_preference	否	指定推荐列和不推荐列。
命名过滤	named_filter	否	定义可复用的过滤表达式。
默认约束	default_constraint	否	定义列的默认筛选约束；仅支持通过 API 配置。
标准问答	verified_query	否	保存高频问题及其 SQL。
术语解释	glossary	否	定义业务术语及其含义。
规则注入	logic_text	否	在指定阶段应用业务规则。
SQL 结果集	sql_resultset	否	保存 SQL 结果集定义。
relationship 的对象数组包含以下固定字段：

业务指标

下面表格展开请求示例中 spec 对象；仅当 kind 为 metric 时使用。

字段	类型	必填	说明
expr	string	是	指标的计算表达式。

表关联

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

字段	类型	必填	说明
left_table	string	否	左侧表名称。
right_table	string	否	右侧表名称。
join_columns	array of object	否	连接列对；数组不能为空。

关联字段

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

字段	类型	必填	说明
left	string	是	左侧列名称。
right	string	是	右侧列名称。

类型专属约束

字段	类型	必填	说明
relationship	join_columns	否	数组不能为空；每项必须包含非空的 left 和 right（string）。
column_preference	preferred、deprecated	否	两个值均不能为空，且不区分大小写时不能相同。
default_constraint	values	否	至少包含一个非空字符串；可选 operator 为 =、!=、<>、IN 或 NOT IN。
logic_text	injection_stages	否	数组不能为空；每项只能为 planner_policy、sql_generation、sql_followup、sql_regenerate、sql_decomposition、executor_rule 或 renderer_rule。
sql_resultset	sql、description	否	sql 不超过 16 KiB；description 不超过 1000 个字符。

sql_resultset 可选配置

字段	类型	必填	说明
resolve_mode	string	否	只能为 semantic 或 passthrough。设置为 passthrough 时不能设置 expand_sql。
max_rows	integer	否	不能小于 0。
max_bytes	integer	否	不能小于 0。
timeout_seconds	integer	否	范围为 0 至 60。
expand_sql	object	否	SQL 展开配置。设置时必须同时提交 expand_sql.sql 和 expand_sql.params。
retrieval	object	否	检索配置。

展开 SQL

下面表格展开请求示例中 expand_sql 对象；每一行是该对象的一个字段。

字段	类型	必填	说明
sql	string	条件必填	不超过 16 KiB；其中的 {{参数名}} 必须与 expand_sql.params 一一对应。
params	array of string	条件必填	数量为 1 至 8。每个名称以字母或下划线开头，后续只能包含字母、数字或下划线；不区分大小写时不能重复，且必须在 expand_sql.sql 中使用。

检索配置

下面表格展开请求示例中 retrieval 对象；每一行是该对象的一个字段。

字段	类型	必填	说明
enabled	boolean	否	设置为 true 时，必须同时提交 retrieval.embedding_model。
embedding_model	string	条件必填	retrieval.enabled 为 true 时必须为非空字符串。

成功响应

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

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 501,
    "kind": "metric",
    "key": "total_rows",
    "tables": ["orders"],
    "spec": {
      "expr": "COUNT(*)"
    },
    "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	json.RawMessage 类型专属配置对象；返回结构严格由 data.kind 决定，字段与本页“spec 配置”及其 relationship、sql_resultset 子字段完全相同。
created_at	integer	Unix 时间戳。
updated_at	integer	Unix 时间戳。

条目定义

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

字段	类型	说明
expr	string	示例中指标条目的计算表达式。

错误响应

响应示例

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

字段说明

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

后续操作

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

最后更新于 2026 年 9 月 9 日