API docs by Redocly

Resource (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 数据源（计划中）
logicview 逻辑 衍生 / 复合视图，由 logic_definition 定义
dataset 逻辑 文档集合（RAG 索引），documents 子资源走 [resource-data.yaml]

status 取值：active / disabled / deprecated / stale。

可检索业务 KV（extensions，Issue #382，方案 B）

  • 与 tags 不同，extensions 为 扁平 string→string，存于 **t_entity_extension**； f_entity_id 与 t_resource.f_id 同一全局唯一 ID 空间（见设计文档不变量）。
  • 创建 / 更新：请求体可选 extensions；键出现（含 {}）即整包替换副表行； 键未出现则不修改。
  • 读取：详情与列表（include_extensions 为 true 时）返回 **extensions**。
  • 列表：include_extensions、include_extension_keys；筛选 extension_key / extension_value 数组 query（与 catalog.yaml 一致）。
  • 设计依据： catalog-resource-labels-scheme-b-design.md

持久化（与 migrations/mariadb、migrations/dm8 惯例对齐）

  • 与 Catalog 共用 t_entity_extension 表；无 f_scope 列；主键 (f_entity_id, f_key)。
  • 列名、索引、时间字段风格与 catalog.yaml / 设计文档 §3 一致；删除 resource 时同事务删除 f_entity_id 等于该 resource f_id 的全部扩展行。

子资源端点指引：

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

获取资源列表

分页 + 多维过滤获取 Resource 列表。

KV 筛选：extension_key / extension_value（数组 query）； 语义同 catalog.yaml 列表；与 catalog_id、category 等过滤 AND 组合。

Authorizations:
OAuth2
query Parameters
name
string

按名称模糊过滤，匹配名称中包含该值的资源

catalog_id
string

按归属 catalog 过滤

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

按类别过滤

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

按状态过滤

schema
string

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

offset
integer <int64> >= 0
Default: 0

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

limit
integer <int64>
Default: 20

每页数量，默认 20

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

排序字段

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

排序方向

extension_key
Array of strings <= 5 items [ items <= 128 characters ]

与 extension_value 成对；多条件 AND。等长数组；等值匹配 t_entity_extension.f_key。

extension_value
Array of strings <= 5 items [ items <= 512 characters ]

与 extension_key 成对；语义见 extension_key。

include_extensions
boolean
Default: false

为 true 时列表条目带 extensions；默认 false。

include_extension_keys
string

逗号分隔 key；在 include_extensions 为 true 时仅返回列出的 key。

Responses

Response samples

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

创建资源

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

  • id 字段可选；后端在不指定时生成。
  • category 必须为支持的取值之一。仅 dataset 与 logicview 允许通过本 API 创建； 其他类别（table / file / fileset / api / metric / topic / index）由 discover 任务产出， 直接调用本接口创建会返回 400 VegaBackend.Resource.CategoryNotCreatable。
  • name 在 catalog 内唯一；冲突返回 409 VegaBackend.Resource.NameExists。
  • category=logicview 必须给 logic_definition。
  • category=dataset 必须给非空 schema_definition；字段名/长度/重复/类型/特征均会校验， 违反返回 400 VegaBackend.Dataset.*（详见错误码族）。
  • 可选 **extensions**：与插入 t_resource 同一事务内写入 t_entity_extension。
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" "logicview" "dataset"

资源类型

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

所属 schema，由发现流程写入

source_identifier
string
object
object (EntityExtensions) <= 64 properties

扁平 KV 的 JSON object（string→string）。用于 Resource / ResourceRequest 上的 extensions 属性；语义与约束同 catalog.yaml 中 EntityExtensions。

Array of objects (Property)
object (ResourceIndexConfig)

本地索引构建配置

Array of objects (LogicDefinitionNode)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "catalog_id": "string",
  • "name": "string",
  • "tags": [
    ],
  • "description": "string",
  • "category": "table",
  • "status": "active",
  • "status_message": "string",
  • "last_discover_status": "string",
  • "schema": "string",
  • "source_identifier": "string",
  • "source_metadata": { },
  • "extensions": {
    },
  • "schema_definition": [
    ],
  • "index_config": {
    },
  • "index_name": "string",
  • "column_count": 0,
  • "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、只返回存在的那些。 每条 Resource 含 **extensions**（无副表行时为 {}）。

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，整批不删。

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

删除成功后须同事务移除 t_entity_extension 中对应 f_entity_id 的行。

Authorizations:
OAuth2
path Parameters
id
required
string

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

query Parameters
ignore_missing
boolean
Default: false

忽略不存在的 id；默认 false

Responses

Response samples

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

更新资源

更新 Resource。

  • name 在 catalog 内唯一；改名为已占用值返回 409 VegaBackend.Resource.NameExists。
  • catalog_id 和 category 不可修改，与当前 Resource 不一致时返回 400。
  • PUT 中的 status、schema、source_identifier、source_metadata 由内部流程管理；即使携带也会被忽略。
  • 必须传入 expected_update_time 进行乐观并发控制。该值应取自最近一次查询响应的 update_time；若资源已被其他请求更新，返回 409 VegaBackend.Resource.UpdateConflict。
  • extensions：请求体若包含 extensions 键（含 {}）则整包替换该 resource 的 t_entity_extension 行； 键未出现则不修改副表。
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" "logicview" "dataset"

资源类型

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

所属 schema，由发现流程写入

source_identifier
string
object
object (EntityExtensions) <= 64 properties

扁平 KV 的 JSON object（string→string）。用于 Resource / ResourceRequest 上的 extensions 属性；语义与约束同 catalog.yaml 中 EntityExtensions。

Array of objects (Property)
object (ResourceIndexConfig)

本地索引构建配置

Array of objects (LogicDefinitionNode)

Responses

Request samples

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

Response samples

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