# 管理语义模型 Entry

Entry 用于保存语义模型中的业务定义，例如指标或术语。每个 Entry 由类型、键、关联表和类型专属 `spec` 组成；客户端不能自行编造未受支持的类型或 Schema。

## 创建 Entry

下面的示例创建一个指标 Entry。`kind` 和 `spec` 的组合必须符合当前模型契约：

```bash
curl -X POST "$PRODUCT_API_BASE_URL/semantic-models/$MODEL_ID/entries" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "metric",
    "key": "total_rows",
    "tables": ["orders"],
    "spec": {
      "expr": "COUNT(*)",
      "unit": "rows"
    }
  }'
```

| 字段 | 类型 | 必需 | 说明 |
| --- | --- | --- | --- |
| `kind` | string | 是 | Entry 类型。当前已验证的示例包括 `metric` 和 `glossary`；具体 Schema 随类型变化。 |
| `key` | string | 是 | 模型内用于引用该定义的稳定键。 |
| `tables` | string[] | 否 | 该定义关联的表名称。不要在这里传数据目录（Catalog）表 ID。 |
| `spec` | 任意 JSON 值 | 是 | 与 `kind` 对应的定义对象。字段必须按当前类型契约提供。 |

成功响应返回 Entry：

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 501,
    "kind": "metric",
    "key": "total_rows",
    "tables": ["orders"],
    "spec": {
      "expr": "COUNT(*)",
      "unit": "rows"
    }
  }
}
```

保存 `data.id`。更新和删除使用 Entry ID 作为路径参数。

## 列出、更新和删除

| 方法与路径 | 用途 |
| --- | --- |
| `GET /semantic-models/{model_id}/entries` | 分页列出 Entry |
| `PUT /semantic-models/{model_id}/entries/{entry_id}` | 使用完整 Entry 定义更新 |
| `DELETE /semantic-models/{model_id}/entries/{entry_id}` | 删除 Entry |

列表响应使用 `items[]`、`total` 和 `next_page_token`。更新接口要求重新发送 `kind`、`key` 和 `spec`；编辑前先读取当前对象，避免遗漏原有字段。

批量导入 Entry 使用 `POST /semantic-models/{model_id}/import`，请求体为 `{"entries":[...]}`。导入成功响应中的 `imported` 表示本次写入数量，不能替代后续模型校验。

## 验证修改

创建、更新、删除或导入后，调用 `POST /semantic-models/{model_id}/validate`。`valid: true` 表示当前模型通过服务端校验；如果返回错误列表，先按 Entry 键定位问题，再修正对应 `spec`。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| `spec` 校验失败 | `kind`、键名和类型专属字段 | 从同类型的已存在 Entry 或正式 Schema 取得结构后重试。 |
| 更新后字段丢失 | 是否发送了完整 Entry 定义 | 重新读取 Entry，合并原值后再提交。 |
| 关联表不可用 | `tables` 名称和模型来源 | 确认表来源已加入模型，并重新校验模型。 |
| 批量导入部分不符合预期 | 导入结果数量和最新 Entry 列表 | 重新列出 Entry，按稳定 `key` 对比，不只检查 HTTP 状态。 |

## 下一步

- [添加和检查数据来源](sources-processing.md)
- [验证语义模型](model-lifecycle.md#校验模型)