文件输入功能说明

1.1 版本说明

1.2 应用场景

用户在搭建数仓时，希望能从 FineDataLink 服务器本地或者共享目录中读取 Excel 、CSV 文件数据。

同时可以通过 FDL 将 Excel 、CSV 文件直接上传至 FDL 服务器本地。

1.3 功能说明

FineDataLink 支持「文件输入」功能。

注：通过分配数据连接权限控制每个人允许访问的 本地服务器目录，保证数据与权限安全。

• 支持 Excel 和 CSV 文件读取，允许用户从 FineDataLink 服务器本地和 FTP/SFTP 服务器上读取 Excel 和 CSV 文件数据。

• 4.0.24 及之后版本，支持批量读取同格式的 Excel 和 CSV 文件。批量读取时支持忽略错误文件，支持模糊匹配文件。支持读取 TXT 格式文本文件。

• 支持用户快速上传文件至有权限的 FDL 服务器本地目录中。详情参见本文 3.1.3 节「文件读取」说明。

• 若需要读取或者上传本地的 Excel 和 CSV 文件数据至 FineDataLink，需要新建一个「服务器本地目录」数据连接，并将要读取的文件放到%FDL%/webroot/WEB-INF/assets/local_files路径下，并且有该数据连接的使用权限。具体请参见：配置服务器本地目录数据连接

• 若需要读取远程 FTP/SFTP 服务器 Excel 和 CSV 文件数据，需要配置 FTP/SFTP数据连接，并且有该数据连接的使用权限。具体请参见：配置FTP/SFTP数据连接

• 4.0.24 版本之前，仅支持上传后缀小写的 Excel 和 CSV 文件，对于大写后缀的 Excel 和 CSV 文件上传校验不通过。若文件存在，但无法读取，请检查文件后缀是否为大写 .CSV/.XLSX，请手动修改为小写。

3.1 读取 Excel 文件

3.1.1 文件来源

需要提前配置「服务器本地数据连接」或「FTP/SFTP数据连接」且需要有该数据连接的使用权限，下拉框中才会出现选项。

3.1.2 文件类型

支持读取 Excel 文件。

注1：文件类型选择 Excel 时，支持的后缀名：.xls、.xlsx、.XLS、.XLSX

注2：Excel 需要支持满足的版本为 97~ 最新版本。

3.1.3 读取方式

分为两种，「文件读取」和「文件夹读取」。

1）文件读取

• 读取单个文件。

• 文件地址：选择要读取的文件。支持使用参数；若文件来源是「服务器本地目录」，此处填写的是相对于%FDL%/webroot/WEB-INF/assets/local_files的路径，例如：/home/ftpuser/test/${time}.xlsx（/home 在 %FDL%/webroot/WEB-INF/assets/local_files路径下）。

     也可以使用 参数赋值 进行参数设置。

• 文件来源为「服务器本地目录」且读取单个文件时，「文件地址」处支持手动上传文件至有权限的 FDL 服务器本地目录中。上传文件名限制：上传文件名不能包含「 ? * : " < > \ / | 」，不能以空格开头。上传文件大小不能超过 100M 。4.1.4 及之后版本才支持上传重名文件，上传的重名文件将替换之前的同名文件。

注：手动上传文件，文件需小于100M。

2）文件夹读取

可读取文件夹中的多个同格式文件。

注：文件夹中的 Excel 文件需要字段名相同；文件夹中的 CSV 文件需要分隔符相同。

• 文件夹地址：选取要读取的文件夹。指定文件夹方式：通过界面点击选择文件夹、手动输入文件夹地址（可设置参数，输入参数后需要手动点击选中该参数）。

• 读取子文件夹：若不勾选，读取时将忽略子文件夹中的文件；勾选时，读取时包括子文件夹中的文件。

• 文件筛选：允许配置筛选条件过滤文件夹下的多个文件，获取符合要求的部分文件进行读取。可通过「文件名」和「文件修改时间」来筛选文件。支持通过参数筛选。

「文件修改时间」理解示例：比如某文件夹中昨天的表是 A 和 B，今天新增表 C ，更新表 B 中的数据，「文件筛选」中筛选「文件修改时间」为今天的表，可筛选出表 C 和表 B（表 B 中的所有数据，非今天更新的数据）。

注1：「文件修改时间」的精确度仅到分钟，暂时无法精确到秒级别。

注2：4.1.1 及之后版本，产品内条件判断逻辑进行了统一，每个运算符的说明可参见：条件判断逻辑说明

3.1.4 sheet 名

填写要读取的 Sheet 名。为空时读取第一个 sheet。sheet 名称支持使用参数。

3.1.5 读取行列范围

指定 Excel 读取起始行和读取结束行，指定 Excel 读取起始列和读取结束列。

数字框中要求为正整数。

3.1.6 首行为字段名

勾选时，将解析到的首行数据作为字段名。

不勾选时，首行将作为实际数据解析。

3.1.7 输出字段

1）自动获取：

将根据解析结果直接读取字段类型，此时「自动获取」界面下不显示输出的字段。

2）手动获取：

• 「手动获取」界面下将展示输出字段名称、输出字段类型，支持自定义字段类型，可设置字段类型为：varchar、int、long、float、double、date、timestamp。

注：CSV 文件的情况下，不能选择 date 和 timestamp 类型。

• 字段允许追加，允许删除追加的字段，但不允许对已有字段进行删除或顺序调整。

注：追加的字段名称，不允许为空，不能包含空格，不能与其他有效字段名重复。

• 追加的字段如果前 N 行没有数据，则对应行值为 NULL 。

3.2 读取 CSV 文件

文件来源、读取方式、首行为字段名、输出字段介绍请参见本文 3.1 节内容。

3.2.1 文件类型

文件类型选择 CSV 时，支持读取类 csv 文件类型。

例如：支持的文件后缀名：csv、CSV、txt、TXT、tsv、log、dt（csv 和 xml 混合格式）/dbf 等。

3.2.2 读取文件后缀

当用户选择「文件读取」方式时，新增该选项。说明如下：

• 不区分大小写。

• 根据用户输入的文件后缀读取文件地址中的该类型文件，跳过路径下非该格式文件。

• 支持写多种格式，以逗号为分隔符；支持读取类 CSV 文件，例如：txt/tsv/log/dt（csv和xml混合格式）/dbf 等。

3.2.3 列分隔符

根据指定的分隔符，分隔数据为多列。配置的分隔符需要与文件中实际的分隔符保持一致才可正常解析。

可指定或自定义分隔符。

分隔符可选择：英文逗号,、制表符\t、英文分号;、管道符|、空格、ASCII字符、自定义

• 可以手动输入自定义分隔符，可以输入多个字符作为分隔符，可以是中文字符。

• 可以手动输入十进制的 ASCII 编码，指定 ASCII 字符作为特殊的列分隔符，支持的十进制ASCII编码为0～32。

• 文本限定符、列分隔符、行分隔符彼此不可重复。

3.2.4 行分隔符

可指定 CSV 中的行分隔符：

CR+LF：在 Windows 系统中使用。

LF：在 Unix、Linux 等系统中使用。

CR：在早期的 Mac OS 系统中使用。

文本限定符、列分隔符、行分隔符彼此不可重复。

3.2.5 文本限定符

用于标识数据值的开始和结束，以避免数据中包含的特殊字符干扰 CSV 文件的解析。

可选择：双引号、单引号、ASCII 字符（支持的十进制ASCII编码为0～32）。

文本限定符、列分隔符、行分隔符彼此不可重复。

3.2.6 编码

指定 CSV 文件编码。编码可选择 GBK、BIG5、ISO-8859-1、UTF-8、UTF-16、EUC_JP、EUC_KR、CP850、GB2312

3.2.7 读取起始行

CSV 文件可以从第 N 行开始取数。

• 必填。默认值为 1，不允许输入 1 以下的数字。

• 实际读取时，将从配置的起始行开始进行读取。

• 多文件读取的情况下，对于每个文件，此配置都将生效。

• 同时指定「起始行为字段名」时，将以读取起始行开始，取该行作为字段名行。

3.3 自定义

可读取 xml、json 等文件类型。

默认获取为文本数据，一个文件一行数据，列名默认为「文件输入」，解析内容功能由后续XML解析、JSON解析等算子实现。如下图所示：

文件来源、读取方式、文件地址请参见本文 3.1 节。

3.3.1 读取文件后缀

读取方式选择「文件读取」时，新增该选项：

• 不区分大小写。

• 支持写多种格式，以逗号为分隔符。

• 文件后缀不能重复。

3.3.2 编码

编码可选择 GBK、BIG5、ISO-8859-1、UTF-8、UTF-16、EUC_JP、EUC_KR、CP850、GB2312。如下图所示：

3.3 数据预览

「数据预览」界面如下图所示：

说明如下：

• 预览数据量默认最多20行；使用前5000行数据中出现的字段与首行列数（如果指定了首行为字段名称）取并集，作为预览时展示的字段，且仅取数采样前5000条数据，但请不要担心，在输出数据时为全量输出。

• 如果首行字段为合并单元格的情况，将合并单元格进行拆分后，以「字段名称+数字」的方式对拆分后的字段命名，如三个单元格合并后的首行单元格为「姓名」，则命名为姓名、姓名1、姓名2..:

• 如果CSV首行字段有重名情况，以「字段名称+数字」的方式对重复字段命名，如重复字段为姓名，则重复字段命名为姓名1、姓名2...。

• 未勾选首行包含字段名时，字段名称以「column+数字」的方式对解析出的字段依次命名，如colum、column1、column2...。

FDL 工程的定时任务中使用了「文件输入」算子，其中文件类型选择 CSV，读取方式为文件夹读取：

• 若设置了文件筛选条件，升级到 4.1.4 及之后版本后，filename 包含.txt、.TXT、.csv、.CSV，与升级前配置的筛选条件为且关系。

• 若没有设置文件筛选条件，升级到 4.1.4 及之后版本后，filename 默认包含.txt、.TXT、.csv、.CSV。
  

单元格格式与读取后字段的关系说明：

1）CSV字段类型问题

CSV读取后，输出只有字符串和数字两种类型，数字需要保证不丢精度。对于时间类型，如2022-11-10类型的时间，解析为字符串；时间戳类型的时间解析成数字。

2）合并单元格读取问题

对于合并的单元格，拆分单元格读取，复制值到每个拆分后的单元格进行读取。

3）字段为空的情况

如果标题字段存在空值，则将空值以「column+数字」的方式补充。

如果数字字段存在空值，填NULL

4）不支持 Excel 的多选Sheet读取。

5）不支持文件名通配符。

6）不支持读取设密码的Excel文件。