来源与模型¶

本页路径均相对 /openapi/v1/workspaces/{workspaceId}/management/。配置写入的预检、planToken、Idempotency-Key 和操作状态见调用约定。

发现来源与依赖¶

方法与路径	用途
`GET catalog/?type=&q=&offset=&limit=`	搜索模型、时间序列、维度、基础指标、衍生指标、维度表和自定义表摘要；模型包含禁用项
`GET sources/?q=&offset=&limit=`	列出当前元数据版本的物理表和自定义表，取得 `ref`
`GET sources/{ref}/columns/`	读取来源、`metadataStatus`、列结构及物理表版本
`POST sources/refresh/`	刷新来源元数据，返回 `operationId`；需 `Idempotency-Key`
`POST sources/{ref}/sample/`	按列采样；需 `data` 权限
`GET impacts/{type}/{id}/`	查看引用该资源的模型、草稿及衍生指标依赖
`POST joins/validate/`	验证关联键类型、维侧唯一性及覆盖率；需 `data` 权限

ref 应从 sources/ 获取，再传入列查询或采样接口。采样请求示例为 {"columns":["amount"],"limit":10}，limit 为 1 到 25；返回 state、columns、rows。采样只用于查看数据，不能作为维度值搜索的低基数证据。刷新返回 pending 后可查询操作状态并重新读取 sources/。

关联验证请求指定左右来源及关联键，例如：

{
  "left": { "sourceRef": "<事实表来源 ref>", "key": "region_id" },
  "right": { "sourceRef": "<维度表来源 ref>", "key": "id" }
}

验证结果可能为 verified、mismatch 或 unknown。通过时返回短期有效的 evidenceToken，供模型维度表绑定使用。来源、列、工作区或密钥变化后须重新验证；超时或证据不足时不可当作通过。

语义资源与模型¶

下列资源各自提供 GET 集合/、GET 集合/{id}/、POST 集合/preview/、POST 集合/、PATCH 集合/{id}/、DELETE 集合/{id}/。模型及维度表详情使用 UID，其余使用 ID。预检、创建、修改、删除分别按通用流程调用。

集合路径	对象	用途
`time-series/`	时间序列	配置时间字段与时间范围
`dimensions/`	维度	配置维度定义、展示和筛选
`measures/`	基础指标	配置计算字段与展示属性
`derived-measures/`	衍生指标	配置公式与展示属性
`dimension-tables/`	维度表	配置维度表及其维度
`models/`	模型	配置来源、属性与绑定

模型 changes 可包含 source、setProperties、addBindings、updateBindings、removeBindings、newResources。来源使用 {"type":"physical","name":"sales"}、{"type":"custom","uid":"<自定义表 UID>"} 或 {"type":"sql","sql":"SELECT ..."}。基础指标绑定示例：

{
  "kind": "measure",
  "resourceId": 8,
  "field": "amount",
  "aggregation": "sum",
  "type": "decimal",
  "format": "float"
}

创建模型至少绑定一个基础指标；多个时间维度需指定默认时间维度。维度表须先创建，再用 joins/validate/ 取得证据，通过 addBindings 绑定到模型；newResources 不支持内联维度表绑定。维度表关联仅支持可发现的物理表或自定义表作为模型事实来源；SQL 事实来源无法验证关联，不能绑定维度表。

维度表绑定还需 joinType、joinFields，并为每对键提供 joinEvidenceTokens。更换模型来源但保留维度表绑定时，需在 updateBindings 中重新提供各绑定的关联键和证据。提交后回读模型的 ready，并以真实问法验收。

专用变更与展示顺序¶

方法与路径	用途
`POST models/{uid}/properties/preview/`、`PATCH models/{uid}/properties/`	只修改模型属性
`POST dimension-tables/preview/`、`POST dimension-tables/{uid}/dimensions/`、`DELETE dimension-tables/{uid}/dimensions/{dimensionId}/`	以 `addDimension` 或 `removeDimension` 动作预检并增删维度表成员
`GET dimensions/{id}/custom-sort/`、`POST dimensions/preview/`、`PATCH dimensions/{id}/custom-sort/`	以 `customSort` 动作预检并设置维度值的显式顺序
`GET dimension-groups/`、`POST dimension-groups/preview/`、`PUT dimension-groups/`	配置维度分组与组内顺序
`GET resource-order/`、`POST resource-order/preview/`、`PUT resource-order/`	配置模型、基础指标及衍生指标展示顺序
`GET/POST custom-tables/`、`GET/PATCH/DELETE custom-tables/{uid}/`、`POST custom-tables/preview/`	管理自定义表及字段变化
`POST custom-tables/validate-sql/`	只读 SQL 试查；需 `data` 权限

维度分组和资源顺序先 GET 取得 revision，再向各自的 preview/ 发送 {"revision":"...","changes":{...}}，最后以相同 changes、planToken 和 Idempotency-Key 调用 PUT。维度分组的 changes.groups 必须包含完整列表，最后一组为内置 other；新自定义分组的 uid 为 32 位小写 UUID hex。资源顺序的 changes 可分别提供 models（UID）、measures（ID）、derivedMeasures（ID）；未提供的类别保留原顺序。

自定义表提供常规列表、详情、预检及增删改。SQL 试查和创建或修改 SQL 的预检、提交需要 data 权限；修改字段后应回读来源列结构并验证依赖模型。