跳转至

文件上传

File 数据源用于将本机文件上传到 AIR，并配置为可查询的基础视图。支持 CSV、XLSX、XLS、TXT，以及 SAS 数据文件（.sas、.sas7bdat）。

创建 File 数据源

  1. 在“数据源”中点击“新建数据源”，选择“File”。
  2. 填写名称和描述，按需填写额外配置及投影更新设置。
  3. 点击“创建”，进入该数据源的目标文件夹。

File 数据源配置

File 数据源不需要填写外部数据库的地址和账号。文件系统或对象存储中的文件应通过对应存储数据源接入。

上传与解析文件

  1. 进入 File 数据源的文件夹，点击“文件上传”。
  2. 点击上传区域或拖入一个文件，填写表名称和描述。
  3. 点击“下一步”，按文件格式配置解析选项。
  4. 预览数据，检查字段名称、数据类型和需要的格式设置，完成配置后保存。

文件上传入口

配置项 说明
表名称 上传后生成的基础视图名称，避免与同目录已有表重名
解析的 sheet 页 Excel 文件含多个工作表时，选择要解析的 sheet
分隔符 CSV、TXT 等文本按实际格式设置
编码格式 按文件实际编码选择，避免中文乱码
第一行作为表头 首行是字段名称时启用；否则首行应作为数据读取
日期、时间格式 当页面提供这些选项时，按文件内容设置
字段配置 检查字段名、类型和描述，避免仅依赖自动推断

文件格式和大小需满足上传页面及当前部署的限制。遇到上传失败时，检查文件扩展名、实际文件格式、文件是否为空，以及页面返回的限制提示。

追加或替换已上传数据

在 File 数据源中打开目标表详情，使用“追加数据”按钮或其下拉菜单中的“替换数据”。操作前需具备目标表的修改权限，且 AIR 及执行引擎能够访问实际文件存储。

方式 用途与影响
追加数据 将本次文件作为新增数据纳入已有表，保留历史记录；不会自动去重或更新相同业务键的旧记录
替换数据 使用新上传文件替换现有数据；执行前应确认目标并备份仍需保留的数据

追加步骤

  1. 点击“追加数据”，上传本次新增文件。
  2. 在解析配置中检查格式、编码、分隔符、表头、sheet 或读取位置等是否与原表一致，预览本次文件。
  3. 打开“字段映射”，核对上传字段与目标字段的对应关系。同名字段可自动填充，保存前仍需逐项确认。
  4. 确认后提交，在表中核对本次新增记录，并通过“更新记录”检查文件名、操作类型、操作时间和操作人。

当前追加保留既有表结构及解析规则，不用于增删字段或改变解析方式。新文件必须完整匹配原表的上传字段，映射数量、原始字段名及其目标对应关系均需与已有配置兼容。格式、编码、表头、分隔符、Excel 读取位置、日期时间格式等不一致时会拒绝追加，不能将字段映射理解为任意结构转换。

同一表存在追加或预览处理时，新的冲突请求可能提示正在处理中，等待结束后再操作。旧版文件表若不具备当前支持的目录布局，也可能无法追加；应先保留数据并由管理员确认兼容方式，不要直接修改底层文件路径。

替换步骤

在下拉菜单选择“替换数据”，重新上传文件、预览并确认后保存。此操作会覆盖当前数据范围；它不是按主键合并。完成后执行小范围查询，检查结果及依赖视图和投影的状态。

更新记录与验证

在文件表详情查看“更新记录”，区分首次上传、追加和替换。记录用于追溯文件操作，不是业务数据的版本备份。提交提示或历史记录不能代替对查询结果的核对；记录写入异常时也应先核对实际数据，避免重复导入。

更新文件数据与刷新投影是不同操作。追加后至少核对新增记录、总量和重复业务键，再根据投影调度及数据时效要求检查其更新记录。不要将同一文件重复追加作为通用重试方式。

指定 HDFS 或 S3 存储

File 数据源可沿用平台默认 HDFS 存储，或引用已创建的 HDFS、S3 数据源作为文件存储。应先完成存储数据源连接，确认服务和执行引擎具备读取、写入及所需文件操作权限。

在 File 数据源的额外配置中使用以下属性：

{
  "storeFileType": "CUSTOM",
  "fileStorePath": "upload_storage/air-files"
}

upload_storage 替换为同集群中已配置的 HDFS 或 S3 数据源名称，后续段表示相对于其根目录的路径。fileStorePath 不填写完整 URI、开头或结尾斜线、空目录段、反斜线或 .. 等路径穿越内容。实际根目录及桶、连接凭据复用目标存储数据源的配置，不在 File 数据源重复填写。

storeFileType 为 DEFAULT 或未配置时使用默认 HDFS；CUSTOM 需要有效的 fileStorePath。当前自定义上传存储只接受 HDFS 和 S3，不能直接使用 Azure Blob 等其他类型。

保存后上传小文件并验证预览、查询及后续追加，确认 Spark / Kyuubi 能访问相同位置。变更存储配置不会自动搬迁历史文件，已有数据场景应先评估并迁移，避免新旧路径混用。