Dataset Spec

表达数据集的定义语义。sourceId 支持传入数据源名称，安装器会按名称解析为运行时 ID；同步配置中的 externalDatasourceId / datasourceId / externalSourceId 同样支持名称解析。

资源类型与自然键

资源类型	自然键	说明
`Dataset`	`name`	数据集名称，全局唯一

DatasetSpecDTO

字段	类型	说明
`name`	string	名称，作为自然键
`displayName`	string	未使用。显示名称占位字段，当前写入服务不消费。
`description`	string	描述
`sourceId`	string	数据源 ID/名称，安装器按名称解析
`sourceDatabase`	string	源数据库
`sourceTableName`	string	源表名
`materializationType`	string	物化类型，见下文「物化类型」
`logicSql`	string	逻辑 SQL
`syncConfigJson`	Map<String, Object>	同步配置 JSON，内部 `externalDatasourceId` / `datasourceId` / `externalSourceId` 会解析为数据源 ID
`pipelineConfigJson`	Map<String, Object>	Pipeline 配置 JSON
`syncSchemaOnInstall`	boolean	安装完成后自动同步外部数据源 Schema
`syncDataOnInstall`	boolean	安装完成后自动触发数据集数据同步

运行态字段说明

以下字段不属于 DatasetSpecDTO，由投影层在写入 fd_dataset 时自动设置：

字段	取值	说明
`sourceType`	`DEFINITION`	来源类型，固定为 `DEFINITION`
`managementMode`	`MANAGED`	管理模式，固定为 `MANAGED`
`status`	`PUBLISHED`	业务状态，投影完成后固定为 `PUBLISHED`
`publishedVersion`	Long	当前发布版本号
`definitionResourceId`	string	关联的 Definition Resource ID

物化类型

materializationType 可选值：

取值	说明
`EXTERNAL`	外部视图
`MATERIALIZED`	物化
`LOGICAL`	逻辑视图

外部数据源引用

syncConfigJson 中若使用以下字段引用外部数据源，投影层会将其统一转换为运行态的 externalSourceId：

字段	说明
`externalDatasourceId`	外部数据源 ID/名称，优先级最高
`datasourceId`	数据源 ID/名称，兼容字段
`externalSourceId`	外部数据源 ID/名称，直接透传

转换规则：

若存在 externalDatasourceId，移除该字段并写入 externalSourceId。
否则若存在 datasourceId，移除该字段并写入 externalSourceId。
运行态通过 DataSourceApi 按名称解析为实际数据源 ID。

自动同步 (`syncSchemaOnInstall` / `syncDataOnInstall`)

投影层在 Dataset 创建或更新后，根据 spec 中的同步开关触发：

syncSchemaOnInstall 为 true 时，调用 datasetSyncApi.syncSchema(datasetId) 同步 Schema。
syncDataOnInstall 为 true 时，调用 datasetSyncApi.syncData(datasetId) 触发数据同步；若当前处于事务中，则注册 afterCommit 回调，待事务提交后执行。

消费位置

foundry-dataset-biz: DatasetDomainProjectionAdapter.project 将字段投影到 fd_dataset，并在 syncSchemaOnInstall / syncDataOnInstall 为 true 时触发同步。
安装器名称解析：sourceId 与 syncConfigJson 中的外部数据源标识均通过 DataSourceApi.getVisibleDataSourceByName 解析。

示例

datasets:
  - name: customer_orders
    description: 客户订单主数据集
    sourceId: pg_main
    sourceDatabase: sales
    sourceTableName: orders
    materializationType: MATERIALIZED
    syncConfigJson:
      externalDatasourceId: pg_oltp
      externalDatabase: oltp
      externalTable: orders
      syncEngine: PG_FDW
      syncMode: FULL
    syncSchemaOnInstall: true
    syncDataOnInstall: true