API docs by Redocly

VEGA 引擎 · 资源 API (0.2.1)

Download OpenAPI specification:

Vega Backend Resource（数据资源）相关 API。

Resource 是数据资源主实体，归属于某个 Catalog。每个 Resource 有一种 category：

category 类型 说明
table 物理 关系表（mysql / postgresql / clickhouse / 达梦 / oracle）
index 物理 OpenSearch / Elasticsearch 索引
topic 物理 消息队列 topic（计划中）
file 物理 单文件
fileset 物理 文件集（计划中）
metric 物理 指标（计划中）
api 物理 API 数据源（计划中）
logical_view 逻辑 专业版及以上可用；由 logic_definition 定义，目前仅支持衍生视图
dataset 逻辑 文档集合（RAG 索引），documents 子资源走 [resource-data.yaml]

enabled 和 status 相互独立：enabled=false 表示该资源不可用于查询或构建； status 反映资源的生命周期和最近发现结果，取值为 active / deprecated / stale。

子资源端点指引：

端点设计遵循 [vega-backend/CLAUDE.md] 的"端点设计规则"：批量 GET / DELETE 走 path （/resources/{ids} 逗号分隔，单条退化），列表过滤走 query。

获取资源列表

分页 + 多维过滤获取 Resource 摘要。列表不返回扩展 JSON 字段 source_metadata、schema_definition、index_config、logic_definition； 需要这些字段时使用 GET /resources/{id}。

Authorizations:
OAuth2
query Parameters
name
string

按资源名称或源端标识模糊过滤，匹配任一字段中包含该值的资源

catalog_id
string

按归属 catalog 过滤

category
string
Enum: "table" "file" "fileset" "api" "metric" "topic" "index" "logical_view" "dataset"

按类别过滤

status
string
Enum: "active" "deprecated" "stale"

按状态过滤

enabled
boolean

按启用状态过滤

last_discover_status
string
Enum: "error" "missing" "new" "restored" "unchanged" "updated"

按最近一次探查状态过滤

schema
string

按所属 schema 过滤；过滤在服务端计数和分页之前完成

offset
integer <int64> >= 0
Default: 0

分页偏移量，>=0，默认 0

limit
integer <int64> [ -1 .. 1000 ]
Default: 20

每页数量，1-1000，-1 表示不分页，默认 20

sort
string
Default: "update_time"
Enum: "name" "create_time" "update_time"

排序字段

direction
string
Default: "desc"
Enum: "asc" "desc"

排序方向

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total_count": 0
}

创建资源

创建 Resource。catalog_id 必填且 catalog 必须存在；不存在返回 404 VegaBackend.Resource.CatalogNotFound。

  • id 字段可选；后端在不指定时生成。
  • category 必须为支持的取值之一。仅 dataset 与 logical_view 允许通过本 API 创建； 其他类别（table / file / fileset / api / metric / topic / index）由 discover 任务产出， 直接调用本接口创建会返回 400 VegaBackend.Resource.CategoryNotCreatable。
  • name 在 catalog 内唯一；冲突返回 409 VegaBackend.Resource.NameExists。
  • category=logical_view 仅在 EE 专业版及以上授权可创建，且必须提交 logic_type=derived 与对应的 logic_definition 对象和非空 schema_definition；字段的 name、original_name、 type 与非空 display_name 必填，type 必须等于绑定的源 Resource 字段类型。 display_name 是 View 自身的显示名，可与源字段不同，最多 255 个字符； 不提供自动继承。同一 View 内输出字段的 name 与 display_name 均不得重复； display_name 去重比较忽略首尾空白，保存时保留请求值。 重复显示名返回 400 VegaBackend.LogicalView.Duplicated.FieldDisplayName。 源资源仅支持 table/index。 source_metadata 由服务端从源资源生成，请求值不参与写入； 未安装 EE 扩展返回 501；授权版本不足返回 403 Public.Forbidden。 通过字段校验的复合视图定义暂时返回 501。
  • category=dataset 必须给非空 schema_definition；字段名/长度/重复/类型/特征均会校验， display_name 在校验与保存前去除首尾空白；省略或去空白后为空时使用字段 name， 去空白后重复则返回 400 VegaBackend.Dataset.Duplicated.FieldDisplayName。 其他违反规则的请求返回 400 VegaBackend.Dataset.*（详见错误码族）。Dataset 索引在 Resource 入库前创建，成功响应中的 index_name 是服务端分配的 vega-dataset-<uuidv7>。 新建索引的分片数和副本数遵循 OpenSearch 索引模板及集群默认配置。
Authorizations:
OAuth2
Request Body schema: application/json
required
id
string <= 40 characters ^[a-z0-9][a-z0-9\-_]{0,39}$

可选；创建时不指定则后端生成；小写字母、数字、下划线、连字符，不能以下划线开头，最大长度 40

expected_update_time
integer <int64> >= 1

仅 PUT 使用的必填乐观锁版本，取自最近一次查询响应的 update_time

catalog_id
required
string

所属 catalog ID（必填）

name
required
string [ 1 .. 255 ] characters

资源名称，必填，最大长度 255

tags
Array of strings <= 5 items [ items [ 1 .. 40 ] characters ]

标签列表（可选），最多 5 个，每个标签非空且最大长度 40，不能包含特殊字符

description
string <= 1000 characters

描述，最大长度 1000

category
required
string
Enum: "table" "file" "fileset" "api" "metric" "topic" "index" "logical_view" "dataset"

资源类型

built_in
boolean

仅创建时可传；必须与所属 Catalog 的 built_in 一致，更新时不可修改

enabled
boolean
Default: true

是否允许该资源用于查询或构建。创建时省略默认 true；PUT 时该值必须与当前值一致， 启停请使用 /enable 或 /disable。与 status 独立。

status
string
Enum: "active" "deprecated" "stale"
schema
string

所属 schema，由发现流程写入

source_identifier
string

物理资源由发现流程写入，SQL 表保存连接器生成的源方言表引用； API 不允许创建物理表资源。PUT 时忽略此字段。

object

物理资源的源元数据由发现流程维护，API 不允许创建物理表资源。 请求中的值不参与 derived 逻辑视图写入；PUT 时由内部流程维护。

Array of objects (Property)

derived 逻辑视图必填且非空；每个字段的 name、original_name、type、display_name 均必填，display_name 不得为空且最多 255 个字符，可与源字段显示名不同， 同一 View 内忽略首尾空白比较后不得重复（保存原值）；输出字段 name 也必须唯一。 GET 返回已保存的 View 显示名；完整 PUT 须显式传入希望保留或更新的值。 type 须与源字段一致。 每个字段省略 features 时继承源字段全部 Feature；显式传 [] 时不公开任何 Feature； 传部分 Feature 时仅保留源字段中匹配的条目。Feature 元数据由源字段补齐， vector 的只读 config.dimension 无须提交。删除 Feature 后，Index 源视图查询不能使用 依赖该 Feature 的搜索、过滤、排序或聚合操作；Table 源的普通 SQL 字段查询不依赖 Feature。 定义内固定 filter_condition 可引用未公开的源字段，但须满足实际查询路径的过滤能力。

object (ResourceIndexConfig)

本地索引构建配置

logic_type
string
Enum: "derived" "composite"

创建和完整 PUT 更新逻辑视图时必填；须与当前定义结构一致，PUT 不可改变既有类型

object (DerivedLogicDefinition)

derived 逻辑视图的单一源和固定过滤配置；不接受旧节点数组、distinct 或未知字段

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "expected_update_time": 1,
  • "catalog_id": "string",
  • "name": "string",
  • "tags": [
    ],
  • "description": "string",
  • "category": "table",
  • "built_in": true,
  • "enabled": true,
  • "status": "active",
  • "schema": "string",
  • "source_identifier": "string",
  • "source_metadata": { },
  • "schema_definition": [
    ],
  • "index_config": {
    },
  • "logic_type": "derived",
  • "logic_definition": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "catalog_id": "string",
  • "api_name": "string",
  • "name": "string",
  • "tags": [
    ],
  • "description": "string",
  • "category": "table",
  • "built_in": true,
  • "enabled": true,
  • "status": "active",
  • "status_message": "string",
  • "last_discover_status": "string",
  • "last_discover_time": 0,
  • "schema": "string",
  • "source_identifier": "string",
  • "source_metadata": { },
  • "schema_definition": [
    ],
  • "index_config": {
    },
  • "local_status": "unavailable",
  • "index_name": "string",
  • "column_count": 0,
  • "row_count": 0,
  • "row_count_time": 0,
  • "estimated_row_count": 0,
  • "logic_type": "derived",
  • "logic_definition": {
    },
  • "creator": {
    },
  • "create_time": 0,
  • "updater": {
    },
  • "update_time": 0,
  • "operations": [
    ]
}

批量获取资源

按 ids 批量取 Resource。整体事务语义：任一 id 不存在返回 404 VegaBackend.Resource.NotFound，error_details 含具体缺失 id。 传 ignore_missing=true 可放宽为跳过缺失 id、只返回存在的那些。 重复 ID 按首次出现的位置去重；entries 按请求中的 ID 顺序返回， 跳过缺失 ID 后仍保持其余条目的相对顺序。

Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID 列表，逗号分隔（单条即长度 1 的退化情形）。

query Parameters
ignore_missing
boolean
Default: false

容忍缺失 ID，跳过而非报 404，默认 false

Responses

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

批量删除资源

按 ids 批量删除 Resource。整体事务：所有 id 通过预校验后才进入删除阶段， 任一不存在返回 404 VegaBackend.Resource.NotFound，整批不删。

若任一 Resource 存在 pending 或 running 的资源元数据刷新任务，返回 409 VegaBackend.DiscoverTask.ResourceRefreshInProgress，整批不删；需等待该任务进入终态。

可选 ?ignore_missing=true：忽略不存在的 id（视为已删除），其它 id 正常删。

可选 ?only_if_stale=true：要求所有资源在删除瞬间仍为 status=stale 且 last_discover_status=missing；否则返回 409 VegaBackend.Resource.DeleteConflict，事务回滚，整批不删，也不执行删除后的清理。 不能与 ignore_missing=true 同时使用。默认 false，不改变现有删除语义。

Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID 列表，逗号分隔（单条即长度 1 的退化情形）。

query Parameters
ignore_missing
boolean
Default: false

忽略不存在的 id；默认 false

only_if_stale
boolean
Default: false

原子校验整批资源的失效且探查缺失状态；默认 false

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "error_details": null,
  • "metadata": { }
}

更新资源

更新 Resource。

  • name 在 catalog 内唯一；改名为已占用值返回 409 VegaBackend.Resource.NameExists。
  • catalog_id 和 category 不可修改，与当前 Resource 不一致时返回 400。
  • PUT 中的 enabled 不可修改；请使用 POST /resources/{id}/enable 或 /disable。
  • PUT 中的 status、schema、source_identifier、source_metadata 由内部流程管理；即使携带也会被忽略。
  • 必须传入 expected_update_time 进行乐观并发控制。该值应取自最近一次查询响应的 update_time；若资源已被其他请求更新，返回 409 VegaBackend.Resource.UpdateConflict。
  • Dataset 已有文档时，不允许通过普通更新改变字段、Feature、embedding 模型或其他索引 结构；请求返回 409，需通过显式重建流程处理历史数据。
  • Dataset 已有物理索引时，即使没有文档，也不允许通过普通更新改变已有全文字段的 feature.config.analyzer；请求返回 409 VegaBackend.InvalidParameter.RequestBody，错误详情标明字段并提示重建 Dataset。 同值保存、仅修改描述或仅修改 default_fulltext_analyzer 不受此新增限制； Dataset 物理 mapping 当前只读取字段级 analyzer 配置，不应用资源默认 analyzer。
  • 逻辑视图更新要求 EE 专业版及以上授权；未安装 EE 扩展返回 501， 授权版本不足返回 403 Public.Forbidden。 若提交复合视图定义，也暂时返回 501；已保存的复合视图仍可读取。 derived 完整 PUT 的每个输出字段均须提交非空 display_name；保留原显示名时 应从最近一次 GET 的 schema_definition 回填，不会从源字段自动继承。
Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID 列表，逗号分隔（单条即长度 1 的退化情形）。

Request Body schema: application/json
required
id
string <= 40 characters ^[a-z0-9][a-z0-9\-_]{0,39}$

可选；创建时不指定则后端生成；小写字母、数字、下划线、连字符，不能以下划线开头，最大长度 40

expected_update_time
required
integer <int64> >= 1

仅 PUT 使用的必填乐观锁版本，取自最近一次查询响应的 update_time

catalog_id
required
string

所属 catalog ID（必填）

name
required
string [ 1 .. 255 ] characters

资源名称，必填，最大长度 255

tags
Array of strings <= 5 items [ items [ 1 .. 40 ] characters ]

标签列表（可选），最多 5 个，每个标签非空且最大长度 40，不能包含特殊字符

description
string <= 1000 characters

描述，最大长度 1000

category
required
string
Enum: "table" "file" "fileset" "api" "metric" "topic" "index" "logical_view" "dataset"

资源类型

built_in
boolean

仅创建时可传；必须与所属 Catalog 的 built_in 一致，更新时不可修改

enabled
boolean
Default: true

是否允许该资源用于查询或构建。创建时省略默认 true；PUT 时该值必须与当前值一致， 启停请使用 /enable 或 /disable。与 status 独立。

status
string
Enum: "active" "deprecated" "stale"
schema
string

所属 schema，由发现流程写入

source_identifier
string

物理资源由发现流程写入，SQL 表保存连接器生成的源方言表引用； API 不允许创建物理表资源。PUT 时忽略此字段。

object

物理资源的源元数据由发现流程维护，API 不允许创建物理表资源。 请求中的值不参与 derived 逻辑视图写入；PUT 时由内部流程维护。

Array of objects (Property)

derived 逻辑视图必填且非空；每个字段的 name、original_name、type、display_name 均必填，display_name 不得为空且最多 255 个字符，可与源字段显示名不同， 同一 View 内忽略首尾空白比较后不得重复（保存原值）；输出字段 name 也必须唯一。 GET 返回已保存的 View 显示名；完整 PUT 须显式传入希望保留或更新的值。 type 须与源字段一致。 每个字段省略 features 时继承源字段全部 Feature；显式传 [] 时不公开任何 Feature； 传部分 Feature 时仅保留源字段中匹配的条目。Feature 元数据由源字段补齐， vector 的只读 config.dimension 无须提交。删除 Feature 后，Index 源视图查询不能使用 依赖该 Feature 的搜索、过滤、排序或聚合操作；Table 源的普通 SQL 字段查询不依赖 Feature。 定义内固定 filter_condition 可引用未公开的源字段，但须满足实际查询路径的过滤能力。

object (ResourceIndexConfig)

本地索引构建配置

logic_type
string
Enum: "derived" "composite"

创建和完整 PUT 更新逻辑视图时必填；须与当前定义结构一致，PUT 不可改变既有类型

object (DerivedLogicDefinition)

derived 逻辑视图的单一源和固定过滤配置；不接受旧节点数组、distinct 或未知字段

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "expected_update_time": 1,
  • "catalog_id": "string",
  • "name": "string",
  • "tags": [
    ],
  • "description": "string",
  • "category": "table",
  • "built_in": true,
  • "enabled": true,
  • "status": "active",
  • "schema": "string",
  • "source_identifier": "string",
  • "source_metadata": { },
  • "schema_definition": [
    ],
  • "index_config": {
    },
  • "logic_type": "derived",
  • "logic_definition": {
    }
}

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "error_details": null,
  • "metadata": { }
}

刷新资源元数据

对指定物理资源触发一次元数据刷新。服务端创建 resource_id 为该资源 ID 的 DiscoverTask 并立即返回 task id；实际刷新由 worker 异步执行。刷新不会改变 Resource 的 enabled 值。可选 count_only 仅刷新精确数量及采集时间，不刷新元数据。 精确计数支持 MariaDB/MySQL、PostgreSQL 表与普通视图、PostgreSQL 物化视图及 OpenSearch 索引； logical_view 复用已注册的视图查询服务，按完整视图定义及固定过滤条件获取源端精确总数。 Dataset 数据量在读取时实时计算，不支持后台 count_only；单资源不支持的 category 在创建任务前返回 400，不入库、不调度、不调用连接器。 每个资源使用 5 分钟 ctx 兜底，暂不设置数据库服务端执行时限。 统计写回仅更新资源独立的数量及采集时间字段，不改变 source_metadata、update_time 或 updater。

同一 Resource 已有 pending 或 running 的刷新任务时，返回 409 VegaBackend.DiscoverTask.ResourceRefreshInProgress。full_sync 遇到不支持按资源标识刷新 的 category，或支持计数的资源在执行时已从源端消失，任务会进入 failed，请通过 GET /discover-tasks/{id} 查看详情。

Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID

Request Body schema: application/json
optional
strategy
string
Default: "full_sync"
Enum: "full_sync" "count_only"

count_only 对已有源表、源视图、索引或 logical_view 执行精确计数；Dataset 等不支持的单资源在创建任务前返回 400

Responses

Request samples

Content type
application/json
{
  • "strategy": "full_sync"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

启用资源

仅将 Resource 的 enabled 设为 true，不改变 status、last_discover_status 或任何发现元数据。已启用时幂等返回 204。

Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "error_details": null,
  • "metadata": { }
}

禁用资源

仅将 Resource 的 enabled 设为 false，不改变 status、last_discover_status 或任何发现元数据。已禁用时幂等返回 204。

Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "error_details": null,
  • "metadata": { }
}