API docs by Redocly

VEGA 引擎 · 目录 API (0.2.1)

Download OpenAPI specification:

Vega Backend Catalog（数据目录）API。

Catalog 是一个数据源连接的抽象，对应一个物理数据源（MySQL / SQL Server / OpenSearch / S3 等） 或逻辑目录（虚拟视图）。资源（Resource）按 catalog 归属注册。

SQL Server 连接器（connector_type: sqlserver）

{
  "connector_type": "sqlserver",
  "connector_config": {
    "host": "sqlserver.example.com",
    "port": 1433,
    "username": "vega_reader",
    "password": "<encrypted-password>",
    "database": "sales",
    "schemas": ["dbo", "reporting"],
    "options": {
      "encrypt": true,
      "trustservercertificate": false,
      "hostnameincertificate": "sqlserver.example.com",
      "connection timeout": 30,
      "app name": "vega-backend"
    }
  }
}
  • host、port、username、password、database 必填；schemas 为空时发现当前账号可见的非系统 schema。
  • options 仅允许 encrypt、trustservercertificate、hostnameincertificate、 connection timeout 和 app name（名称不区分大小写）；其中前两项必须是 boolean。
  • 推荐使用独立只读账号，并授予目标数据库的连接、元数据查看和查询权限。例如： GRANT CONNECT TO [vega_reader]、GRANT VIEW DEFINITION TO [vega_reader]，以及 ALTER ROLE [db_datareader] ADD MEMBER [vega_reader]；不要授予 db_datawriter、db_ddladmin 或 db_owner。
  • TLS 可通过上述驱动参数启用；trustservercertificate: true 会跳过服务端证书校验，只适合受控测试环境。 未配置 encrypt 时使用 go-mssqldb v1.9.2 的 EncryptionOff 默认行为，即客户端不主动要求全程加密； 如需确定启用 TLS，应显式配置 encrypt: true 和 trustservercertificate: false。 当前未提供自定义 CA 文件配置，TLS 成功与失败路径尚待真实 SQL Server 环境验收。
  • 一个 Catalog 只连接一个 database，并在其中按 schema 发现对象；不支持跨数据库发现、CDC 和 Windows 集成认证。

本文件仅包含 catalog 自身的 CRUD 与状态相关端点。跨资源的便利端点：

  • POST /catalogs/{id}/discover（手动发现一次） → 见 discover-task.yaml
  • GET /catalogs/{ids}/resources（按 catalog 列资源） → 见 resource.yaml
  • GET /catalogs/{cid}/discover-schedules（按 catalog 列调度） → 见 discover-schedule.yaml
  • GET/PUT /catalogs/{id}/health-check-schedule（健康检查计划） → 见 catalog-health-check-schedule.yaml

每个外部接口都有一一对应的内部版本，路径前缀为 /api/vega-backend/in/v1，请求体与 响应结构与外部完全一致；区别仅在于鉴权方式：外部走 OAuth Token 校验，内部从请求头 （X-Account-ID / X-Account-Type）解析访问者。

本文档仅描述外部接口。

按连接器类型统计可见 catalog

返回当前用户具有 view_detail 权限的 catalog，按 catalog_type 与 connector_type 聚合后的数量。 catalog_type=logical 的条目没有关联连接器，其 connector_type 固定为空字符串。 该接口仅供目录树首层展示使用，不返回 catalog 详情或连接配置。

Authorizations:
OAuth2
query Parameters
name
string

按 catalog 名称模糊过滤后再聚合

Responses

Response samples

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

获取 catalog 列表

分页获取 catalog 摘要；支持按 name、tag、type、connector_type、health_check_status 过滤。 列表不返回详情专属的 connector_config 与 metadata，需要这些字段时使用 GET /catalogs/{id}。

Authorizations:
OAuth2
query Parameters
name
string

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

tag
string

按标签精确过滤

type
string
Enum: "physical" "logical"

按 catalog 类型过滤

connector_type
string

按连接器类型过滤

health_check_status
string
Enum: "healthy" "degraded" "unhealthy" "offline" "unchecked"

按健康检查状态过滤

enabled
boolean

按 catalog 启用状态过滤

offset
integer <int64> >= 0
Default: 0

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

limit
integer <int64>
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
}

创建 catalog

创建一个新的 catalog。name 全局唯一，已存在时返回 409。 connector_type 必须是已注册且 enabled 的连接器类型。

物理 Catalog 会在持久化前执行一次连接测试。默认连接失败返回 400，且不会创建 Catalog； 可传 allow_unhealthy=true 保存该 Catalog，并将其健康状态记为 unhealthy。

Authorizations:
OAuth2
query Parameters
allow_unhealthy
boolean
Default: false

是否在物理 Catalog 的连接测试失败时仍继续创建。默认 false；为 true 时创建成功， 但初始健康状态为 unhealthy。配置校验、敏感字段解密或连接器创建失败仍返回 400。

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

catalog ID；POST 时可省略由后端生成，PUT 时可省略并使用路径参数，显式提供时必须与路径参数一致；小写字母、数字、下划线、连字符，不能以下划线开头，最大长度 40

expected_update_time
integer <int64> >= 1

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

name
required
string [ 1 .. 255 ] characters

catalog 名称，必填，全局唯一，最大长度 255

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

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

description
string <= 1000 characters

描述，最大长度 1000

enabled
required
boolean

是否启用；未传按 false 处理。PUT 不允许切换该字段，启停切换请使用专用 enable/disable 接口。

connector_type
required
string

连接器类型标识；必须是已注册且 enabled 的类型，SQL Server 使用 sqlserver

object or null

连接器配置；字段由 ConnectorType.field_config 决定。 PUT 时省略或 null 表示保留已存配置、敏感字段和健康状态，并跳过连接测试； 显式对象（包括 {}）按完整配置校验和替换，不合并已存字段。 POST 时物理 Catalog 仍必须提供满足连接器要求的配置。

built_in
boolean

仅 POST 创建内置 logical Catalog 时可设为 true；与非空 connector_type 同时提供返回 400。省略时为 false，PUT 时忽略。

CatalogHealthCheckScheduleRequest (object) or null

可选的健康检查计划组合创建参数。仅 physical Catalog 支持；缺失或 null 时创建 mode=inherit 的计划。提供对象时 mode 必填；仅 mode=enabled 时 cron_expr 必填； 创建失败时整个 Catalog 创建请求回滚。

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "expected_update_time": 1,
  • "name": "string",
  • "tags": [
    ],
  • "description": "string",
  • "enabled": true,
  • "connector_type": "sqlserver",
  • "connector_config": {
    },
  • "built_in": true,
  • "health_check_schedule": {
    }
}

Response samples

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

获取 catalog 详情

路径参数支持单条或批量（逗号分隔）。重复 ID 按首次出现的位置去重； entries 按请求中的 ID 顺序返回。任一 ID 不存在时，整批返回 404。

Authorizations:
OAuth2
path Parameters
id
required
string

catalog ID，多个用英文逗号分隔（如 id1,id2,id3）

Responses

Response samples

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

删除 catalog

一次只允许删除一个 catalog；路径参数包含逗号时返回 400。删除会同步移除该 catalog 下的资源、 探查计划与健康检查计划，以及全部关联的构建、探查和语义理解任务记录（包括 pending 和终态历史记录）。 构建索引不在此流程中清理。存在 running 任务时拒绝删除， 构建任务处于 stopping 时也会拒绝删除。

传入 dry_run=true 时仅执行权限、存在性和影响分析，不写入任何数据；返回该 catalog 的资源、构建任务、探查计划、健康检查计划、探查任务和语义理解任务计数； protected_resources 返回不能随 Catalog 级联删除的 dataset/logical_view 数量，blockers 返回稳定的机器可读阻断原因。can_delete 严格反映当前 DELETE 的阻断规则，调用方仍须 以不带 dry_run 的请求结果为准，因为预检与实际删除之间可能有并发变更。

Authorizations:
OAuth2
path Parameters
id
required
string

catalog ID，多个用英文逗号分隔（如 id1,id2,id3）

query Parameters
dry_run
boolean
Default: false

为 true 时模拟删除并返回影响报告；默认 false，执行真实删除。

Responses

Response samples

Content type
application/json
{
  • "catalog_id": "string",
  • "can_delete": true,
  • "blockers": [
    ],
  • "resources": 0,
  • "protected_resources": 0,
  • "build_tasks": {
    },
  • "catalog_health_check_schedules": 0,
  • "discover_schedules": 0,
  • "discover_tasks": {
    },
  • "semantic_understanding_tasks": {
    }
}

修改 catalog

全量更新指定 catalog。catalog 由路径参数 id 唯一确定（主键不可改）。

请求体的 id 字段可省略，省略时使用路径参数 id；显式提供时必须与路径参数完全一致：

  • 格式非法 → 400 VegaBackend.InvalidParameter.ID。
  • 与路径参数不一致 → 409 VegaBackend.Catalog.IDMismatch。

name 改动后若新名称已被其它 catalog 占用，返回 409 VegaBackend.Catalog.NameExists。

必须传入 expected_update_time 进行乐观并发控制。该值应取自最近一次查询响应的 update_time；若 catalog 已被其他请求更新，返回 409 VegaBackend.Catalog.UpdateConflict。

enabled 不能通过 PUT 切换；请求体中的 enabled 必须与当前 catalog 状态一致。 如需启用/禁用，使用 POST /catalogs/{id}/enable 或 POST /catalogs/{id}/disable。

connector_config 是全量更新的例外：省略或传 null 时保留已存连接配置及敏感字段， 不执行敏感字段解密、连接器创建或连接测试，健康状态及检查结果保持不变。 因此只修改名称、标签或描述不要求数据源当前可连接，也不需要 allow_unhealthy=true。 其他字段仍遵循上述全量更新约定，并继续校验 expected_update_time。

显式提交 connector_config 对象时，按完整配置替换，不与已存配置合并； {} 是显式空配置，仍须通过连接器配置校验，不等同于省略。 修改影响发现范围的字段后，旧 Resource 会在下一次 discover 对齐时标记为 stale。

修改物理 Catalog 配置时会先执行连接测试。默认连接失败返回 400，且不会持久化更新； 可传 allow_unhealthy=true 保存更新，并将健康状态记为 unhealthy。

Authorizations:
OAuth2
path Parameters
id
required
string

catalog ID，多个用英文逗号分隔（如 id1,id2,id3）

query Parameters
allow_unhealthy
boolean
Default: false

是否在物理 Catalog 的连接测试失败时仍继续更新。默认 false；为 true 时更新成功， 但健康状态为 unhealthy。配置校验、敏感字段解密或连接器创建失败仍返回 400。

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

catalog ID；POST 时可省略由后端生成，PUT 时可省略并使用路径参数，显式提供时必须与路径参数一致；小写字母、数字、下划线、连字符，不能以下划线开头，最大长度 40

expected_update_time
required
integer <int64> >= 1

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

name
required
string [ 1 .. 255 ] characters

catalog 名称，必填，全局唯一，最大长度 255

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

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

description
string <= 1000 characters

描述，最大长度 1000

enabled
required
boolean

是否启用；未传按 false 处理。PUT 不允许切换该字段，启停切换请使用专用 enable/disable 接口。

connector_type
required
string

连接器类型标识；必须是已注册且 enabled 的类型，SQL Server 使用 sqlserver

object or null

连接器配置；字段由 ConnectorType.field_config 决定。 PUT 时省略或 null 表示保留已存配置、敏感字段和健康状态，并跳过连接测试； 显式对象（包括 {}）按完整配置校验和替换，不合并已存字段。 POST 时物理 Catalog 仍必须提供满足连接器要求的配置。

built_in
boolean

仅 POST 创建内置 logical Catalog 时可设为 true；与非空 connector_type 同时提供返回 400。省略时为 false，PUT 时忽略。

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "expected_update_time": 1,
  • "name": "string",
  • "tags": [
    ],
  • "description": "string",
  • "enabled": true,
  • "connector_type": "sqlserver",
  • "connector_config": {
    },
  • "built_in": true
}

Response samples

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

启用 catalog

启用 catalog。接口幂等：已启用的 catalog 再次启用返回 204。 从禁用切换为启用时，health_check_status 重置为 unchecked。

Authorizations:
OAuth2
path Parameters
id
required
string

catalog ID

Responses

Response samples

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

禁用 catalog

禁用 catalog。接口幂等：已禁用的 catalog 再次禁用返回 204。 禁用不会覆盖 health_check_status，健康状态保留最近一次检查结果。

Authorizations:
OAuth2
path Parameters
id
required
string

catalog ID

Responses

Response samples

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

预检未保存的 Catalog 连接配置

使用请求中的 connector_type 与 connector_config 执行一次同步连接测试。 本接口不创建或更新 Catalog，也不持久化健康状态；适用于创建或编辑表单保存前的“测试连接”。

探测结果通过响应体 success 字段返回；目标不可达不视为 HTTP 错误：

  • 连通 → 200 { success: true, message }
  • 连不通 → 200 { success: false, message }
  • 非 2xx 仅用于请求、鉴权、参数校验或服务内部错误。

失败时 message 保留连接器返回的诊断详情（例如主机、端口、用户名、数据库名和驱动错误）， 但会替换连接器声明的密码、token 等敏感配置值，并限制异常超长的远端响应。

Authorizations:
OAuth2
Request Body schema: application/json
required
connector_type
required
string

已注册且 enabled 的连接器类型标识；SQL Server 使用 sqlserver

required
object

用于本次探测的连接器配置；字段由 ConnectorType.field_config 决定

Responses

Request samples

Content type
application/json
{
  • "connector_type": "sqlserver",
  • "connector_config": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

获取 catalog 健康状态

返回指定 catalog 的最近一次健康检查结果（状态 + 时间 + 详情）。

Authorizations:
OAuth2
path Parameters
id
required
string

catalog ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "health_check_status": "healthy",
  • "last_check_time": 0,
  • "health_check_result": "string"
}

测试 catalog 连接

以当前持久化的 connector_config 真实建立一次到数据源的连接，验证连通性。 与 health-status（异步定时检查的最近结果）不同，本端点是同步实时探测。 调用者必须拥有目标 Catalog 的 modify 权限。

探测结果通过响应体 success 字段返回；连不通不视为 HTTP 错误：

  • 连通 → 200 { success: true, message }
  • 连不通 → 200 { success: false, message }
  • 非 2xx 仅用于"请求 / 鉴权 / 服务内部"问题，与目标连通性无关。

失败时 message 保留连接器返回的诊断详情（例如主机、端口、用户名、数据库名和驱动错误）， 但会替换连接器声明的密码、token 等敏感配置值，并限制异常超长的远端响应。

Authorizations:
OAuth2
path Parameters
id
required
string

catalog ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}