1. 概述
1.1 版本说明
| FineReport 版本 | 插件版本 | 功能变动 |
|---|---|---|
| 10.0.18 | V1.6 |
|
| V1.7 |
| |
| V1.9 |
| |
| V2.1 |
| |
| V2.2 |
|
1.2 应用场景
当用户需要将数据从一个数据库抽取到另一个数据库时，就可以使用离线同步节点。
2. 示例
2.1 创建任务
在数据平台中创建一个任务，创建完成后双击进入任务设计页面，如下图所示：
2.2 拖入离线同步节点
拖入离线同步节点，如下图所示：
2.3 配置数据来源
1）双击「离线同步」进入它的详细设置页面，配置数据来源，如下图所示：
数据源类型：数据来源有：Oracle、SQLite、SQL Server、PostgreSQL、DB2、ClickHouse、HSQL、MySQL、Presto、Rest API、服务器数据集
数据连接：选择对应的数据连接
SQL语句：输入取数的 SQL 语句，此处的 SQL 语句可以引用 ETL 任务中的参数，参数的定义和使用方式可参见：自定义参数
2）点击「数据预览」用户可查看当前语句对应的数据表内容，但预览数据行数不超过5行，可能会与实际数据存在差异。如下图所示：
2.4 配置数据去向
配置数据的去向，如下图所示：
数据源类型：选择目标数据库用来存放抽取过来的数据，当前可选择的数据库类型有：MySQL、SQL Server、Oracle、PostgreSQL、SQLite
数据连接：选择数据去向对应的数据连接。
目标表：可选择「已存在表」和「自动建表」，详细请参见本文 2.4.1 和 2.4.2 节。
写入方式：数据写入目标数据库表的方式，可以选择直接写入或者先清空表再写入。
比对字段：允许指定一个或多个字段作为比对字段，来更新目标表中的数据，实现增量写入。该项必须设置，否则无法下一步。
更新策略：上面「比对字段」选择之后( 选择框里不为空 )，就会显示改设置项，可以根据选择的字段，选择数据的更新策略，是覆盖、忽略还是直接报错。
写入方式、比对字段、更新策略 3 个设置项的详细介绍如下：
1）写入方式
| 写入方式 | |
|---|---|
| 直接将数据写入目标表 | 直接将数据写入到目标表中： 如果是目标表中没有的数据，直接插入就好 如果是更新的数据，还需要根据「比对字段」和「更新策略」来决定是覆盖、忽略还是报错 |
| 清空目标表，再写入数据 | 直接先把目标表清空掉，然后再写入数据 |
2）比对字段和更新策略
| 目标表 | 比对字段 | 更新策略 |
|---|---|---|
| 如果目标表设置了主键 | 目标表有主键，也就是对数据唯一性有约束 有增量数据要写到目标表中时，就要判断是插入目标表中没有的新数据，还是更新目标表中已有的数据，判断就要用到「比对字段」
点击「比对字段」后，主键字段会自动选中
主键字段可以取消，但是建议保留，在此基础上还可以选择其他字段：
这样有更新的数据过来后，就可以根据这些比对字段来实现数据更新，但是要结合更新策略来判断，是覆盖掉、忽略掉还是直接报错 注：目标表有主键，比对字段必须要选，选择框里不能空着 | 只要设置了比对字段，就会显示「更新策略」这个选项 因为目标表有主键时，必须要选择比对字段 所以在点击「比对字段」后，更新策略必定出现 可选项有 3 个，分别如下：
增量数据和目标表中比对字段有相同的，也就是更新操作，那么直接将这些相同字段对应的记录覆盖到目标表中去
增量数据和目标表中比对字段有相同的，那么直接忽略掉这些相同字段对应的记录，只插入目标表中没有的数据
增量数据和目标表中比对字段有相同的，那么停止写入并报错
|
| 如果目标表没有主键 | 目标表没有主键，也就是对数据唯一性没有约束 那么此时点击「比对字段」后，可以不选择字段，如果不选，不会显示更新策略，那么增量数据都是直接插入到目标表里，没有更新数据这一说
当然也可以选择比对字段，这时就会出现更新策略，可以区别是插入目标表中没有的新数据，还是更新目标表中已有的数据
| 不选比对字段，不出现更新策略 选择了比对字段，更新策略同上 |
注1：数据量较大情况下，“直接将数据写入目标表”会比“清空目标表,再写入数据”执行效率更高，因为后者方案需要先清空目标表数据，再将来源表的数据全量抽取至目标表中；前者方案，直接利用目标表的主键，将来源表数据和目标表数据进行比对，若数据有变化即更新，若数据无变化则不更新，相比后者方案，更新的数据会更少，所以抽数速度更快。
注2：如果字段映射里目标表中缺少比对字段，那么写入数据时就会找不到比对字段。所以字段映射时必须包含比对字段。
注3：若目标表中的字段包含约束，则写入的字段需要满足约束。
注4：当选择比对字段为主键时，若目标表中未写入的字段存在约束，那么写入数据会出现失败，这种场景仅在 MySQL 和 Postgre SQL 中出现。
2.4.1 目标表选择「已存在表」
在目标数据库中选择一张已存在的数据表作为目标表，要注意的是目标表的表结构要与抽取过来的数据表表结构一致。
如下图示例，选择「已存在表」，并从目标数据库中选择出目标表target1
2.4.2 目标表选择「自动建表」
系统为用户在目标数据库中创建一张表作为目标表，且自动创建的目标表与抽取过来的数据表表结构一致。
选择「自动建表」，并给新建的表命名即可。如下图所示：
注1：表名称可以为数字、字母、下划线、不允许为中文、特殊字符。
注2：表名称不允许与已存在的表重名，若重名系统则会提示：数据库内存在同名表。
右侧还有个「查看建表语句」，点开后可以查看建表语句，您可以复制粘贴到 SQL 脚本那边新建表，好处是可以对字段数据类型，约束什么的进行调整。
如果自动建表生成的表不满足您的要求，可以使用这个方法来修改一些地方。
2.5 配置字段映射
1）配置好数据来源和数据去向后，点击「下一步」，如下图所示：
2）进入字段映射界面。系统会自动将字段名和字段类型相同的字段匹配做映射，若用户需要匹配的字段名不同，可以手动调整匹配关系。如下图所示：
点击「确定」，离线同步设置完成。
注：如果字段映射里目标表中缺少比对字段，那么写入数据时就会找不到比对字段。所以字段映射时必须包含比对字段。
2.6 运行离线同步
鼠标右击离线同步节点，选择「运行节点」。若运行日志无报错，即运行成功。如下图所示：
3. 功能变动
3.1 数据源类型下拉框支持手动编辑
设置「数据来源」和「数据去向」的数据源类型时，数据库表只能通过下拉框选择，当库内表数量过多时，会导致很难快速找到要用的表。
针对上述问题，插件 1.6 版本对下拉框进行了优化，现在下拉框可直接编辑，输入内容后可模糊搜索数据库表，如下图所示：
3.2 字段映射界面增加刷新按钮
针对源表的字段、字段类型发生改变时，字段映射界面无法获取最新的源表字段问题。
插件 1.6 版本在字段映射界面新增刷新按钮：重新获取，点击按钮后重新获取源头字段和源头字段的类型，并初始化字段映射界面。
3.3 字段映射界面可删除字段
有时候用户希望能够选择性地使用获取到的来源字段，插件 1.7 版本在字段映射界面新增「编辑映射」入口实现改功能。
点击「编辑映射」后，可在编辑页面勾选需要删除的字段，然后点击右上角「删除映射行」，二次确认后再点击「确定」删除相应字段。
但是还没结束，不要忘了点击右下角「确定」，保存设置，如下图所示：
说明：
由于提供了左表删除字段的功能，所以当左表字段大于右表字段时，不会再有 toast 报错，直接显示出来左右表字段。
字段映射对应逻辑不变，默认按照字段顺序对应，如果右表字段比左表少，则对应的字段位置为空。
进入字段映射界面时，不管是否删除了一些字段，目标表字段下拉框里，都可以选择到全量的字段，也就是已删除的字段仍然能够选到。
如果配置完字段映射，目标表的字段名发生了改变，则重新进入字段映射界面时，目标表字段位置为空，如果字段名未改变，只是字段类型、长度发生了变化，则直接展示最新的字段类型、长度。
3.4 字段映射可选择映射方式
字段映射配置界面上方有个下拉框，用户可自定义当前节点的字段映射方式，共有两种：「同名映射」和「同行映射」，默认为「同名映射」。
两种映射方式的匹配逻辑如下：
| 映射方式 | 匹配逻辑 |
|---|---|
| 同名映射 | 按照目标表字段与来源表字段字符重合的情况匹配，整体逻辑为： 1）根据来源字段，在目标表中寻找同名（字符完全相同）字段对其进行匹配 2）没有同名字段时：
3）如果在目标表中找不到同名或者包含目标表字段字符的字段，则右侧映射字段显示为空 |
| 同行映射 | 源头字段和目标表字段按顺序匹配：同行则建立映射关系 |
使用时一些需要注意的点：
1）映射时删除了一些来源表字段，那么切换映射方式后，还是会根据剩下来的这些字段进行调整。
2）手动将映射方式从默认项「同名映射」切换到「同行映射」，点击「重新获取」字段，获取的字段将按照「同行映射」的方式自动匹配。
3）以下两种场景会出现目标表无字段可匹配源头表的情况，在这两种情况下，右侧目标表字段可展示为空：
同名映射：目标表不存在包含源头表字段的字段。
同行映射：源头表字段数量大于目标表字段数量。
4）映射时，如果右侧目标表有空字段，会出现提示图标，悬浮在其上方提示：目标表字段存在空值，如下图所示：
3.5 数据来源支持服务器数据集
直接上传或者配置固定路径下 CSV、Excel 文件作为数据来源是比较常见的。为了满足用户直接从文件读取数据的需求，2.2 版本数据来源支持服务器数据集。
使用方式：
1）按照文档 服务器数据集 在设计器中新建数据集。
2）ETL 任务的「离线同步」节点中，将数据源类型设置为「服务器数据集」，然后选择对应的「数据集类型」，再选择该类型下的那个「数据集」即可。
具体的配置流程参见文档：数据源类型为Excel
注1：暂不支持读取 SQL 数据集，TSV 数据集会自动识别为 CSV 数据集。
注2：添加 CSV 数据集需要安装插件，详情参见文档：CSV数据集。
注3：存储过程可以生成多个数据集，默认只取第一个数据集。
注4：文件数据集地址中包含参数，那么参数可以被解析使用，例如：
用户定义了文件的 URL 为：https://fanruan-market.oss-cn-shanghai.aliyuncs.com/fine_data_prep_test/${today}.xls ，如果 ${today} 在 ETL 任务内被定义过，那么支持正常解析。