创建语义条目

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

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

调用前准备

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

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：目标工作区 ID，通过 X-Workspace-ID Header 传递。

• $MODEL_ID：要创建语义条目的知识库 ID。

路径参数

参数	类型	说明
model_id	integer	要创建语义条目的知识库 ID。

请求体

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

字段	类型	是否必填	说明
kind	string	是	条目类型；它决定 spec 的结构。
key	string	是	知识库内的稳定引用键。
tables	array[string]	否	关联的表名称，不是 Catalog 表 ID。
spec	object	是	类型专属配置对象；字段由 kind 决定。

key 在同一知识库内必须唯一；tables 不传时可省略，传入时每个名称必须是该知识库已配置的表。

spec 配置

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

控制台名称	kind	spec 必填字段	用途
维度列	dimension	column（string）	描述用于分组、筛选的字段。
事实列	fact	column（string）	描述可参与计算的事实字段。
业务指标	metric	expr（string）	定义指标计算表达式。
表关联	relationship	left_table（string）、right_table（string）、join_columns（object[]）	定义两张已配置表的关联。
列偏好	column_preference	preferred（string）、deprecated（string）	指定推荐列和不推荐列。
命名过滤	named_filter	expr（string）	定义可复用的过滤表达式。
默认约束	default_constraint	column（string）、values（string[]）	定义列的默认筛选约束；仅支持通过 API 配置。
标准问答	verified_query	question（string）、sql（string）	保存高频问题及其 SQL。
术语解释	glossary	term（string）、definition（string）	定义业务术语及其含义。
规则注入	logic_text	content（string）、injection_stages（string[]）	在指定阶段应用业务规则。
SQL 结果集	sql_resultset	sql（string）、description（string）	保存 SQL 结果集定义。

类型专属约束

kind	字段或条件	约束
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。
expand_sql.sql	string	条件必填	不超过 16 KiB；其中的 {{参数名}} 必须与 expand_sql.params 一一对应。
expand_sql.params	array[string]	条件必填	数量为 1 至 8。每个名称以字母或下划线开头，后续只能包含字母、数字或下划线；不区分大小写时不能重复，且必须在 expand_sql.sql 中使用。
retrieval	object	否	检索配置。
retrieval.enabled	boolean	否	设置为 true 时，必须同时提交 retrieval.embedding_model。
retrieval.embedding_model	string	条件必填	retrieval.enabled 为 true 时必须为非空字符串。

请求示例

curl -X POST "https://moi.matrixorigin.cn/newmoi/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(*)"
    }
  }'

成功响应

成功时返回 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.id	integer	新条目 ID。
data.kind	string	已创建的条目类型。
data.key	string	知识库内的稳定引用键。
data.tables	array[string]	关联表名称；未设置时可能省略。
data.spec	object	已保存的类型专属配置对象；字段由 data.kind 决定。
data.created_at	integer	Unix 时间戳。
data.updated_at	integer	Unix 时间戳。

错误响应

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

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
400	ErrParamInvalid	kind、key 或 spec 不符合条目类型契约。	修正完整条目定义后重试。
401	ErrUnauthorized	API Key 无效或已失效。	检查 API Key。
403	ErrForbidden	调用者没有创建条目的权限。	检查工作区和对象授权。
404	ErrNotFound	知识库不存在或不可见。	重新确认 model_id。
409	ErrConflict	同一知识库中已存在冲突的条目键。	使用其他 key 或更新现有条目。
500	ErrServer	服务未能创建条目。	保留脱敏后的响应信息后重试。

后续操作

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

最后更新于 2026 年 8 月 22 日