主数据
使用场景：企业或政府内部的不同业务系统对于同一个业务字段的定义若不一致，会增加业务协同、数据治理的难度，通过构建企业主数据，保证数据一致性。
使用角色：数据开发人员。
功能描述：平台提供主数据模型构建能力，管理主数据基本信息、高级配置等信息，并可进行主数据版本管理。
前置条件：在新建主数据前要先在系统管理 > 目录管理 > 主数据领域中创建好主数据领域，供新建主数据使用。
新建
- 进入数据规范 > 主数据页面，点击页面上方的“新建主数据”按钮，即可跳转至下一界面。
- 进入新建主数据页面后，用户根据页面内容填写相关信息，填写完成后点击右下角的“保存”按钮即可。
- 基础信息：
- 模型中文名：必填，填写模型中文名称，空间内不允许重复；
- 模型英文名：必填，填写模型英文名称，空间内同一数据层级不允许重复；
- 责任人：必填，下拉选择用户作为该表责任人；
- 提供方：必填，下拉选择组织机构，即该数据表的来源组织；
- 资源标签：必填，系统默认为STG层，可修改；主数据数仓层级配置保存后不可再修改，请谨慎选择；
- 关联领域：必填，下拉选择已创建好的主数据领域；
- 业务系统：必填，下拉选择已创建好的业务系统，只有STG层的数据表可以关联业务系统；
- 描述：非必填，填写该表的业务描述信息。
系统默认会新建一个空字段，可根据信息项逐一填写，若需新增字段，可点击下方 “新增字段”或“引用字段”按钮。
字段信息：
字段中文名：必填，填写字段中文名称，同一个表内字段中文名不允许重复；
字段英文名：必填，填写字段英文名称，同一个表内字段英文名不允许重复；
字段类型：必填，下拉选择所需字段类型；
字段长度：根据填写的字段类型和实际业务需求填写合适的字段长度，部分字段类型无需填写；
字段精度：根据填写的字段类型和实际业务需求填写字段精度，即数字的小数位数，部分字段类型无需填写；
非空：默认为不勾选，勾选后则所在列的数据不能为空；
默认值：非必填，支持常量、函数变量、引用序列；若不填写则默认为空
注意- 常量：可支持任意字符，如字母、数字等
- 函数变量、引用序列：可支持以下函数，其中序列需提前创建，序列配置详见 序列管理
- 时间与日期函数：current_date、current_timestamp、localtimestamp、clock_timestamp()、now()
- 数学与随机函数：random()、round()、abs()、sqrt()、pi()
- 系统信息函数：current_user、session_user、version()
- 序列生成函数：nextval()、setval()
- 引用序列时需包含完整序列名称，如nextval('test_kj_public.xulie')，其中“test_kj”空间编码，“xulie”为序列名称，此为示例
- 非数值型常量作为默认值是，需加英文单引号，如'汉'；时间格式支持以“-”、“/”为连接符，如2025-07-22；bool类型有效文本值是'ture'、'yes'、'1'、'false'、'no'、'0'；
- 通过库表、API、FTP导入数据时，若需要对应列使用默认值，请勿将该列连线，连线后即使该列为空，数据库也会处理为null，而非填充默认值；同理SQL加工插入、数据导入时，若需使用默认值，则对应列名请勿出现在SQL语句或导入文件中
脱敏规则：支持下拉选择已配置脱敏规则，当前选择仅为手动标记为敏感，需脱敏处理确认后，则数据预览、消费时会按所选脱敏规则进行动态脱敏；不选择则视为不敏感
引用字段：支持通过引用“标准字段”以规范字段信息，除不可引用主数据字段外，其他逻辑可参见：数据表-引用字段
字段检测：主要用以发现可能需要引用标准字段进行规范的字段，点击“字段检测”按钮即可自动检测，除不可检测引用主数据字段外，其他逻辑可参见：数据表-字段检测
高级配置：
高级配置项 | 字段类型要求 | 约束限制 |
|---|---|---|
| 主键 | 不支持json、xml、text、bytea、geometry、bool字段类型 | 选择当前已创建的一个或多个表字段作为数据表主键。 使用限制如下： |
| 分区字段 | 可根据表的一列或者多列，将要插入表的记录分为若干互不重叠的分区，存储相应的数据，旨在优化查询和数据的覆写、删除，提高性能。 使用限制如下： |
修改
- 进入数据规范 > 主数据页面，选择某个主数据点击操作栏“修改”按钮，进入主数据修改页面，保存后生效。
- 已发布状态主数据不可修改，需下架后方可修改；
- 删除字段，修改字段英文名，修改分区字段、或修改原分区字段的字段类型，修改字段的字段类型且这种修改无法自动转换，将字段设为非空但已有数据存在空值等情况下，会新增版本变更记录；
- 若主数据字段信息变更，若已被其他数据表引用，不会同步变更为最新版本，而是继续引用历史版本，除非手动再次选择最新版本字段
- 当数据表存在数据时，修改字段类型等操作耗时较长，请等待后台修改完成后再写入数据，否则数据库也会等待修改完成后才会执行写入操作
- 修改数据表英文名，删除字段，会自动下线以下已关联的数据加工作业/指标加工作业/标签加工作业
- 修改数据表时若新增字段，新增列不支持使用nextval表达式设置默认值
- 高级配置修改限制
| 高级配置项 | 修改限制 |
|---|---|
| 主键 | |
| 分区字段 |
删除
- 进入数据规范 > 主数据页面，选择某个主数据点击操作栏“删除”按钮，二次确认后生效。
- 已发布状态数据表不可删除，需下架后方可删除
- 已关联数据表服务，且服务处于发布状态时不可删除，需下架服务后方可删除
- 存在关联已上线的数据加工作业/指标加工作业/标签加工作业/数据质检作业，不允许删除，需先下架已上线的作业
- 高级配置删除限制
| 高级配置项 | 删除限制 |
|---|---|
| 主键 | |
| 分区字段 |
版本管理
- 进入数据规范 > 主数据页面，选择某个主数据点击操作栏“版本管理”按钮即可跳转至版本管理页。
- 删除字段、修改字段英文名、修改分区字段、或修改原分区字段的字段类型，修改字段的字段类型且这种修改无法自动转换，将字段设为非空但已有数据存在空值等情况下，会新增版本变更记录；
- 后台生成新的版本后，会在数据表英文名后面加上_vN（N从1开始，每次新版本生成自动加1），如原数据表英文名为second_model_v1，则新生成的版本表英文名为second_model_v2。
版本使用
为保证业务连续性，以下功能会继续使用历史版本，直至用户手动干预。
- 引用主数据字段，字段变更后依旧引用历史版本；
- 主数据消费，主数据下架后，拥有访问权限用户可继续消费历史版本；
- 主数据加工，数据加工作业/指标加工作业/标签加工作业/数据质检作业继续使用历史版本数据表加工。
版本对比
“版本对比”按钮默认不可点击，需勾选任意两个版本后才可使用。版本对比页面中对字段修改内容，高亮显示两个版本差异内容；删除字段后，对应删除版本整行显示空；新增字段所对应的未新增版本整行显示空。
变更记录
点击“版本管理”页面中的“变更记录”即会出现弹窗展示当前主数据模型的版本变更详情信息，页面按版本倒序展示版本变更。
- 变更详情分为三类，“修改”记录每个字段的属性原始值和变更后的值；
- “新增”、“删除”只需记录变更字段的中文名（V1版本仅记录新增字段）。
查看详情
版本管理页面按版本号倒序排列历史版本，列表中可直接查看该主数据模型基础信息，同时支持点击版本列表后方的“查看”按钮查看历史版本信息。
关联领域&解除关联
- 关联目录
平台支持将主数据关联至主数据领域，供后续主数据发布至数据开放模块时，若关联领域也发布，则可按目录展示资产。
- 新建/修改主数据时可下拉单选“关联领域”。
- 已发布资产不允许关联领域，需下架资产再操作；
- 解除关联
主数据领域为必填项，不支持解除关联，若需要将主数据资产从数据开放模块下架，可直接将对应主数据领域下架。
空间内发布&下架
- 发布
平台支持将空间内资产发布至数据开放 > 本空间资产 >模块，若其已关联目录也已发布，则其他用户可见该资产，并可申请消费。
- 点击某个未发布资产“更多操作”，状态资产可点击“发布”按钮；或批量勾选数据表后，点击批量发布，二次确认后即可发布成功。
- 下架
通过下架资产，可将已发布至数据开放 > 本空间资产 >模块的资产下架，让其他用户不再可见，且已有消费权限的用户不再可消费。
- 点击某个已发布资产“更多操作”，点击“下架”按钮；或批量勾选数据表后，点击批量下架，二次确认后即可下架成功。
数据导入
主数据表新建完成后，可通过列表操作栏、表详情页的“数据导入”按钮，快速导入CSV、Excel数据，支持两种导入方式，由系统自行判断执行。
解析导入
解析导入主要适用于数据量较小的导入场景，可自动解析表头，乃至每一行数据错误，效率一般但支持导入策略灵活，主要流程配置如下：
- 上传文件：用户导入本地 CSV和Excel（小于2G）,Json（小于100M） 文件实现表数据写入，配置任意字段后可下载模板，模板会将已配置字段英文名作为表头，在模板中补充数据记录后即可上传。（也可直接使用含表头的CSV、Excel文件）
- 数据起始行：用于判断执行数据导入时的起始行最小值为2 (默认第1行为表头)，最大值100；Json文件默认均为1，不可修改
- 表头配置：CSV和Excel（小于2G）无需配置；Json文件需配置字段路径解析，并与目标表字段映射连线
- 导入策略：导入策略有“遇到错误回滚”和“遇到错误继续”两种
- 遇到错误回滚：即要么全部导入成功，要么全部导入失败，遇到的第一个错误行失败原因会记录供查看，此策略导入效率较高
- 遇到错误继续：即遇到错误不会停止导入，会继续下一行直至最终行，并同步记录每个错误行的失败原因供下载，但此策略导入效率较低
- 是否覆盖： 默认“否”，即不会覆盖已有数据，直接追加数据；选择“是”，则导入时会清空已有数据后再导入。
Json文件表头配置解析逻辑说明如下：整体逻辑类似API数据源-数据解析配置
- 文件要求：JSON文件只支持单个JSON数据，文件中多个JSON数据不支持
- 解析JSON：支持自动获取JSON样例数据，若获取异常可手动输入JSON样例数据
- 数据起始路径：配置起始路径后解析，则自动在下方列表生成路径下所有对象的数据相对路径，路径设置遵循JSONPath语法，但根路径不需要按JSONPath语法以$开始，多层路径以“.”连接，如school.class；
- 字段相对路径：支持手动新增、修改、删除，支持不同套嵌层级数据导入，但下层为数组的不支持导入，返回为null，如不支持data.array[0].student
- 字段映射：支持点击“自动映射“根据左侧字段相对路径进行映射，或手动连线，未连线字段将不导入
- 验证解析：点击后将从左侧样例数据中，按所配置相对路径获取对应值进行展示
复制导入
复制导入主要适用于数据量较大的导入场景，采用整体复制的模式，效率高但支持导入策略较少，主要流程配置如下：
- 上传文件：用户导入本地 CSV（大于2G） 文件实现表数据写入
- 数据起始行：用于判断执行数据导入时的起始行，默认2（即第1行为表头），最小值为1（即不包含表头），最大值100
- 表头配置：由于超大文件不会解析表头，因此需用户手动配置表头顺序，以保证数据列实际顺序可以和目标表字段列建立正确的映射关系，可手动拖拽排序
- 导入策略：仅支持“遇到错误回滚”
- 遇到错误回滚：即要么全部导入成功，要么全部导入失败，遇到的第一个错误行失败原因会记录供查看，此策略导入效率较高
- 是否覆盖： 默认“否”，即不会覆盖已有数据，直接追加数据；选择“是”，则导入时会清空已有数据后再导入。
断点续传
以上两种导入方式均支持断点续传，具体说明如下：
- 触发逻辑：点击“导入”按钮后，系统将在后台执行文件上传操作，此时会记录文件上传进度；此时若主动取消、网络问题、刷新或离开当前页面等操作造成上传中断，在未对原文件进行任何修改的情况下重新上传，将触发断点续传，从中断进度处继续上传文件
- 触发限制：上传进度将保留24小时，超过该时长则无法触发断点续传，将从头开始
主数据使用
主数据作为企业公共基础数据，平台提供了以下使用方式，具体如下：
- 引用字段，在新建数据表[含:单独建表、DDL建表、Excel建表（含数据）]时，可引用主数据以规范字段信息，引用配置基本一致，详细配置参见：引用字段
- 引用详情：主数据列表中可查看引用次数，点击次数可查看具体引用详情，便于解除引用，以完成主数据删除等操作
- 引用次数说明：仅记录当前正在引用该主数据字段的字段个数；同一张表的某一字段，引用后解除再引用，记为一次；同一张表中多个字段引用，则有几个字段引用记为几次
字段检测，在新建数据表[含:单独建表、DDL建表、Excel建表（含数据）]时，可通过“字段检测”发现应引用主数据的字段，检测逻辑基本一致，详细配置参见：字段检测
引用诊断，系统会定时基于主数据字段与数据进行扫描，以诊断当前空间内的主数据引用情况及数据一致性情况，并出具诊断明细供后续规范整改，详细逻辑参见：引用诊断
主数据资产，平台可将主数据作为主数据资产，供外部消费，以规范外部系统的主数据，保证主数据的全局唯一性、一致性，详细逻辑参见：主数据资产