通联历史数据导入教程

下载附件中的通联数据导入模块 ImportTLData 之后，需要将其同步到服务器上。当在 DolphinDB 调用模块时，会到相应路径下查找需要的模块文件。

同步路径

将模块放置于节点所在 Home 目录的 module 目录下。节点所在 Home 目录可通过 getHomeDir 函数获取， 假设 Home 目录为 /DolphinDB/server，那么可以将模块文件放置于 /DolphinDB/server/modules/ 路径下。

如何同步

前置条件

• 进行数据导入之前，首先要确保目标时间段的通联原始数据压缩文件已经保存到服务器下，需要注意的是: 原始数据要保存在执行导入任务的 DolphinDB 节点所在的服务器。
• 需要记住原始数据保存路径，后续导入时需要将其作为参数，比如原始数据保存在：/data/20231007/<具体数据 zip 文件> ，那么，作为参数的路径可设为：/data。数据导入模块会在这个路径下根据数据类型和日期查找具体的数据文件。

数据导入

通联数据导入模块提供了多个导入函数，每个导入函数的功能为导入特定类型的通联历史数据，具体函数名和介绍参照附件中的数据导入函数部分。

以下部分将详细介绍如何通过 ImportTLData 的函数进行数据导入。所有数据导入的函数定义示例请参考附件中的 example.dos 文件。

数据导入函数参数介绍

每个数据导入函数的命名格式为 loadTL<DataType>，其中 <DataType> 为具体的数据类型名称。每个数据导入函数所需参数及其含义如下所示：

返回值

数据导入示例

以导入股票逐笔委托数据为例，分别介绍如何定义导入函数和导入数据。

• 定义导入函数

// 导入模块
use ImportTLData::loadTLEntrust
// 定义数据导入函数
def loadEntrustStock(startDate, endDate, loadType){
	// 设定参数, 需根据实际情况改动
	userName = "admin" 
	password = "123456"
	dbname = "dfs://level2_tl"
	tableName = "entrust"
	filePath = "/hdd/hdd3/customer/tlData/"
	
	// 增量导入
	if(loadType == "daily"){
		idate = today()
		infoTb = loadTLEntrustStock(userName, password, idate, idate, dbname, tableName, filePath, loadType)
	}
	// 批量导入
	else if (loadType == "batch"){
		infoTb = loadTLEntrustStock(userName, password, date(startDate), date(endDate), dbname, tableName, filePath, loadType)
	}
	return infoTb
}

定义好数据导入函数之后，即可调用函数进行数据导入。

startDate = 2024.08.07
endDate = 2024.08.07
loadType = "batch"
infoTb = loadEntrustStock(startDate, endDate, loadType)

在实际导入操作中，历史数据批量导入通常采用后台任务，而每日数据增量导入采用定时任务的方式进行。以下以导入股票委托历史数据和增量数据为例依次进行介绍。

后台任务

通过 submitJob 提交后台任务导入 2023.02.01 - 2023.02.01 股票委托数据。 submitJob 函数的用法可参考：submitJob。

jobId = "loadEntrust20230201_20230201"
jobDesc = "loadEntrust20230201_20230201"
// 后台执行上文定义的 loadEntrustStock 函数
submitJob(jobId,jobDesc,loadEntrustStock{2023.02.01,2023.02.01,"batch"})

定时任务

通过 scheduleJob 提交定时任务导入每日增量股票委托数据。假设从 2025.01.01 - 2025.12.31，每周一到周五的 17:00 定时执行股票委托数据导入任务。 scheduleJob 函数的用法可参考： scheduleJob。

jobId = "loadEntrustDaily"
jobDesc = "loadEntrustDaily"
scheduleTime = 17:00m
beginDate = 2025.01.01
endDate = 2025.12.31
frequency = "W"
days = [1,2,3,4,5]
​
// 设定定时任务，定时执行上文执行的 loadEntrustStock 函数
scheduleJob(jobId,jobDesc,loadEntrustStock{NULL,NULL,"daily"},scheduleTime,beginDate,endDate,frequency,days)

通过本模块将通联各类历史数据导入 DolphinDB ，均经过如下步骤：

1. 检查系统配置。由于解压数据文件需要用到 shell 函数，因此需要在 DolphinDB 配置文件中设置 enableShellFunction=true ，如果未设置，则会报错。
2. 函数会扫描服务器上开始日期和结束日期之间交易日期的相应数据文件，如果缺失某些交易日期的数据文件，则函数会报错，报错内容为缺失的数据文件。需要注意的是：必须保证 DolphinDB 安装包的交易日历使用的是最新的版本，否则需先更新交易日历再执行数据导入任务。
3. 如果不存在共享表 tlDataLoadInfo，则创建。该表用于记录数据导入的信息，主要有三列，分别表示数据类别、数据文件的日期和报错信息。这个表的作用是：可以方便查看当前的数据导入进度和报错信息。
4. 对于每一个需要导入数据的交易日，经过如下流程：
   1. 如果 DolphinDB 中不存在相应库表，则根据相应数据类别进行建库建表。
   2. 如果原始数据只存在 zip 格式，则进行数据的解压缩操作。
   3. 如果 DolphinDB 相应数据库表中已存在即将导入的数据，则会先删除相应数据。
   4. 将原始数据载入到内存，进行数据处理后导入到 DolphinDB 相应数据库表中。
   5. 导入完成或导入报错时，执行以下操作：
      1. 将解压缩后的数据文件删除，节省磁盘空间。
      2. 更新共享表 tlDataLoadInfo，记录导入情况。

通用处理逻辑

本文主要介绍导入通联数据到 DolphinDB 库表的数据处理逻辑。通联不同类别的原始数据存在以下特征：

• 部分原始数据在不同时间段会有所变更，比如增加新数据列、旧数据列不再使用等。
• 对于同一数据类别，如股票逐笔委托数据，上交所和深交所分别提供 csv 数据文件。

考虑到以上情况，模块中的数据处理函数做了如下设计：

• 对于每一个数据类别，考虑数据字段的历史变更，设计兼容的表结构。
• 对于同时含有上交所和深交所数据的数据类别，合并它们相同含义的表字段，并在表结构中分别添加它们的独特字段，并添加字段 Market 用于辨识市场类别，以此将上交所和深交所的相同类别数据导入到同一张表中。

快照数据处理逻辑

由于通联的股票和债券的快照数据分成两部分，一个是快照主体数据，一个是最优买卖价前50笔委托，分别存储在不同的 csv 文件中。因此，股票和债券的快照数据处理逻辑除了遵循上文介绍的通用处理逻辑之外，还需要根据不同交易所进行以下处理：

• 如果最优买价和最优卖价前 50 笔委托数据存储在不同文件，则根据交易时间和股票 ID 进行左连接操作，合并成一张表。
• 根据交易时间和股票 ID ，将快照主体数据和最优买卖价前 50 笔委托数据进行左连接操作，合并成一张表。
• 对于当天的每一支股票， 判断 TotalVolumeTrade 字段是否递增（该字段表示截止当前快照时间点的成交总量），如果不满足递增条件，说明快照数据存在问题，则报错。

通联各类历史数据文件根据一定规则命名，而且在不同时间段可能存在表结构的变化。因此，要把这些不同时间段的同一类数据导入到 DolphinDB 同一张表中，需要考虑到所有变化，并设计出兼容所有数据的库表结构。本部分详细介绍通联原始数据文件在不同时间段的文件名与含义，以及与 DolphinDB 数据库表的映射关系。其中文件名涉及到日期表示的以 20231007 为例：

以下列出了通联数据中股票逐笔委托、行情快照、逐笔成交表的详细字段名、字段类型和字段含义。

股票委托(dfs://level2_tl : entrust)

股票快照(dfs://level2_tl : snapshot)

股票成交(dfs://level2_tl : trade)

可以。

假设要将 2023.01.01 - 2023.11.01 这一时间段内的股票委托数据、股票快照数据、股票成交数据、指数数据、盘后数据以及 equity 分钟线数据同时导入 DolphinDB 。由于每个任务导入不同的数据表，不会产生冲突，因此修改参数之后就可以直接通过后台任务并发执行多个数据导入任务。

需要注意的是，在并发导入过程中应注意内存情况，避免产生内存溢出。

依情况而定。

DolphinDB 按分区存储数据。当一个写入任务涉及多个分区时，系统会首先锁定这些分区。如果在该任务完成之前，其他写入任务也涉及这些分区，由于锁定状态，这些任务会因分区冲突而报错 S00002，从而导致任务失败。

尽管数据导入任务已根据不同时间段划分，但仍可能出现因同时写入同一分区而导致冲突的情况。接下来，我们将介绍每个库的分区类型，并探讨如何设计并发任务以避免分区冲突。

分区类型

避免分区冲突

根据以上每个数据库的分区类型可以得知，dfs://level2_tl 和 dfs://level2_tlExtra 的时间分区粒度为日，所以不用担心分区冲突问题，只需保证多个并发任务之间的时间段不产生重合即可。

dfs://level2_tlEquity1_5Min 以月分区。为了避免分区冲突，应保证每个任务的导入时间段不产生月份重合。假设任务 A 的导入时间段为 2023.01.01 - 2023.01.15 ，任务B的导入时间段为 2023.01.16 - 2023.02.15 ，会产生分区冲突。应该改为：任务 A 的导入时间段为 2023.01.01 - 2023.01.31 ，任务 B 的导入时间段为 2023.02.01 - 2023.02.15。

以此类推，dfs://level2_tlEquity15_60Min 以年分区，为了避免分区冲突，应保证每个任务的导入时间段不产生年份重合，假设任务 A 的导入时间段为 2023.01.01 - 2023.05.15 ，任务B的导入时间段为 2023.05.16 - 2024.04.15，会产生分区冲突，应该改为：任务 A 的导入时间段为 2023.01.01 - 2023.12.31 ，任务 B 的导入时间段为 2024.01.01 - 2024.04.15。

前台任务

以深交所交易统计数据导入为例，通过以下代码获取数据导入任务的运行信息：

infoTb = loadSZTradeStat(startDate, endDate, loadType)

这里的 infoTb 为一张表。该表只有一列 msg ，每一行记录深交所交易统计数据导入过程中的每一条运行信息：

后台任务和定时任务

• 获取后台任务的状态

  getRecentJobs()

• 通过以上函数返回的结果查询所需的 jobId ，再通过以下函数获取相应的运行信息
  • getJobMessage(jobId) ：以字符串形式返回运行信息
  • getJobReturn(jobId) ：以表的形式返回运行信息