管理语义模型 Entry¶

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

创建 Entry¶

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

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：

{
  "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 状态。

下一步¶

最后更新于 2026 年 8 月 14 日