# 创建语义条目

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

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

## 调用前准备

先[查询知识库列表](list-knowledge-bases.md)取得知识库 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` 时必须为非空字符串。 |

## 请求示例

```bash
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` 用于后续更新和删除。

```json
{
  "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 时间戳。 |

## 错误响应

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

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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` [更新语义条目](update-semantic-entry.md)或[删除语义条目](delete-semantic-entry.md)。