DolphinDB数据导入教程
本页概览 DolphinDB 支持的多种数据导入途径，并指向对应的导入方向与方法条目。
Source: https://dolphindb.cn/blogs/72
What this page covers
- 文章基本信息（标题、作者、发布日期）。
- 数据导入方式概览（文本、二进制、HDF5、ODBC）。
- DolphinDB 表与分区相关基础概念。
- 通过文本/CSV 文件导入的函数与示例。
- 通过二进制文件导入的函数差异与 schema 要求。
- 通过 HDF5 插件导入的流程与示例。
- 通过 ODBC 插件导入与 SQL Server 示例步骤。
技能认证特训营第二期报名活动
页面顶部的活动报名与优惠引导链接。
- 该部分用于引导报名活动。
- 该部分包含优惠相关提示或入口。
DolphinDB数据导入教程（作者与发布日期）
文章标题、作者名与发布日期信息。
- 作者为 Junxi。
- 发布日期为 2021-08-05。
数据导入方式概览
列出DolphinDB支持的四种数据导入途径。
- 支持通过文本文件导入。
- 支持通过二进制文件导入。
- 支持通过 HDF5 接口导入。
- 支持通过 ODBC 接口导入。
- 提供多种灵活的数据导入方法以导入来自多个数据源的数据。
DolphinDB数据库基本概念和特点
介绍DolphinDB中表的存储形态、分区与数据库分区机制的差异。
- 数据以结构化数据表的方式保存。
- 按存储介质可分为：内存表、本地磁盘表、分布式表。
- 内存表数据保存在内存中。
- 本地磁盘表数据保存在本地磁盘上。
- 分区是针对数据库定义的。
通过文本文件导入（loadText/ploadText/loadTextEx）
介绍文本/CSV导入相关函数及其使用场景，并展示示例脚本与性能对比。
- loadText 用于将文本文件读取为内存数据表。
- ploadText 用于并行加载数据文件作为分区表。
- loadTextEx 用于转换为数据库中的分布式表并加载元数据。
- loadText 参数包括 filename、delimiter、schema。
- loadText 可通过抽样行推断列数据类型。
- extractTextSchema 可从文本文件提取表结构生成数据类型表。
- 示例包含 loadText 与 ploadText 的性能对比数据。
- loadText 总是把所有数据导入内存，超大文件可能受内存限制。
通过二进制文件导入（readRecord!/loadRecord）
说明二进制导入函数的差异、schema要求与日期时间字段转换示例。
- readRecord! 用于导入不含字符串字段的二进制文件。
- readRecord! 不支持导入字符串类型数据。
- loadRecord 支持导入字符串类型数据（STRING 和 SYMBOL）。
- loadRecord 要求字符串在磁盘上的长度必须固定。
- readRecord! 需要先创建内存表并为每列指定名称与类型。
- loadRecord schema 通过 tuple 指定。
- temporalParse 用于转换数值形式存储的 date/time 列显示格式。
- replaceColumn! 可用转换后的日期/时间列替换原列。
通过HDF5接口导入（HDF5插件）
介绍HDF5插件方法、插件获取与加载方式，以及导入内存表/分区表的示例脚本。
- DolphinDB 支持导入 HDF5 格式数据文件。
- 通过 HDF5 插件访问 HDF5 文件。
- HDF5 插件包含 hdf5::loadHDF5 与 hdf5::loadHDF5Ex 等方法。
- 插件可通过 loadPlugin 加载（示例命令在文中给出）。
- 调用插件方法需要使用 namespace，或 use hdf5 后直接调用。
- extractHDF5Schema 可用于提取 schema 并在导入前修改字段类型。
- loadHDF5Ex 可用于 HDF5 文件超过服务器内存时的载入。
- 示例展示将数据导入 dfs 数据库并创建分区表（cycle，分区列 tradingDay）。
通过ODBC接口导入（ODBC插件与SQL Server示例）
说明ODBC插件能力、使用前置要求，并用SQL Server连接与导入分区表示例展示步骤。
- 支持通过 ODBC 连接第三方数据库并读取为内存数据表。
- 官方提供 ODBC 插件用于连接第三方数据源并迁移数据。
- ODBC 插件方法包括 odbc::connect、odbc::query、odbc::append。
- 使用前需要安装 ODBC 驱动程序。
- 示例数据源数据库类型为 SQL Server。
导入数据实例（股票日K线，分区规划与并行导入）
以约100G的股票日K线CSV目录数据为例，给出复合分区规划与按年度并行导入的实现细节与注意事项。
- 示例数据为股票市场日K线图数据，每个股票一个 CSV 文件。
- 示例数据规模约 100G，时间范围为 2008 年到 2017 年。
- 导入前需要确定分区字段与分区粒度。
- 建议分区字段为 tradingDay 与 symbol 的组合（COMPO）分区。
- 建议单分区大小为 100M~1G。
- 示例分区规划为：按交易日期范围分区 + 按股票代码范围分区。
- 示例分区数量为 1000 个分区。
- 示例并行导入策略为按年度拆分任务并并行执行。
- 示例实现使用 rpc 与 submitJob。
- 并行任务应避免同时向同一分区写入。
附录（数据文件与脚本下载项）
列出CSV、二进制、HDF5导入数据文件与案例完整脚本等条目。
- 包含 CSV 导入数据文件条目。
- 包含二进制导入例 1 数据文件条目。
- 包含二进制导入例 2 数据文件条目。
- 包含 HDF5 导入数据文件条目。
- 包含案例完整脚本条目。
Facts index
| Entity | Attribute | Value | Confidence |
|---|---|---|---|
| DolphinDB数据导入教程 | publication_date | 2021-08-05 | high |
| DolphinDB数据导入教程 | author | Junxi | high |
| DolphinDB | provides | 多种灵活的数据导入方法，帮助用户把海量数据从多个数据源导入 | low |
| DolphinDB | data_import_methods | 通过文本文件导入 | high |
| DolphinDB | data_import_methods | 通过二进制文件导入 | high |
| DolphinDB | data_import_methods | 通过HDF5接口导入 | high |
| DolphinDB | data_import_methods | 通过ODBC接口导入 | high |
| DolphinDB | data_storage_form | 数据以结构化数据表的方式保存 | high |
| DolphinDB 表类型（按存储介质） | includes | 内存表；本地磁盘表；分布式表 | high |
| 内存表 | storage_medium | 数据保存在内存中 | high |
| 内存表 | access_speed | 存取速度最快 | medium |
| 内存表 | data_persistence | 节点关闭会丢失数据 | high |
| 本地磁盘表 | storage_medium | 数据保存在本地磁盘上 | high |
| 本地磁盘表 | data_persistence | 节点关闭也不会丢失数据 | high |
| 本地磁盘表 | loadability | 可以方便地把数据从磁盘加载到内存 | high |
| 分布式表 | storage_layout | 数据分布在不同的节点的磁盘上 | high |
| 分布式表 | query_model | 通过分布式计算引擎，逻辑上仍可像本地表一样做统一查询 | high |
| DolphinDB 表类型（按是否分区） | includes | 普通表（未分区表）；分区表 | high |
| DolphinDB | partition_definition_scope | 分区是针对数据库定义的；同一个数据库下的数据表只能使用同一种分区机制 | high |
| DolphinDB | partitioning_constraint | 如果两张表要使用不同的分区机制，它们不能放在一个数据库下 | high |
| loadText | function_purpose | 将文本文件以 DolphinDB 数据表的形式读取到内存中 | high |
| ploadText | function_purpose | 将数据文件作为分区表并行加载到内存中；与loadText相比速度更快 | high |
| loadTextEx | function_purpose | 把数据文件转换为DolphinDB数据库中的分布式表，然后将表的元数据加载到内存中 | high |
| loadText | parameters | filename（文件名）、delimiter（字段分隔符，默认","）、schema（导入后字段数据类型；为一个数据表） | high |
| loadText | type_inference | 导入时随机提取一部分行以确定各列数据类型；多数文本文件无需手动指定类型 | high |
| loadText schema 参数 | when_needed | 系统自动识别的数据类型不符合预期/需求时可手动指定（示例：volume 被识别为 INT 但需要 LONG） | high |
| extractTextSchema | function_purpose | 从文本文件中提取表结构生成数据类型表；只需修改少数指定字段的数据类型即可得到理想schema | high |
| ploadText | performance_characteristic | 设计中利用多核CPU并行载入文件；并行程度取决于CPU核数量和节点localExecutors配置 | high |
| 性能示例（4核8超线程节点） | loadText_time_ms | 39728.393 ms | high |
| 性能示例（4核8超线程节点） | ploadText_time_ms | 10685.838 ms | high |
| 性能示例（4核8超线程节点） | relative_performance | 在此配置下，ploadText 性能约为 loadText 的 4 倍 | high |
| loadText | memory_behavior | 总是把所有数据导入内存；当文件体积非常庞大时内存易成为制约因素 | high |
| loadTextEx | memory_behavior | 将大的文本文件分割成小块，逐步加载到分布式数据表中 | high |
| loadTextEx 示例 | database_path | dfs://dataImportCSVDB | high |
| loadTextEx 示例 | partition_type_and_range | VALUE 分区；2018.01.01..2018.01.31 | high |
| loadTextEx 示例 | table_name_and_partition_column | 表名 "cycle"；分区列 "tradingDay" | high |
| loadTable | function_purpose_in_context | 需要使用数据时先载入分区元数据到内存（示例：loadTable("cycle")） | high |
| DolphinDB 查询执行 | data_loading_behavior | 实际执行查询时按需加载所需数据到内存 | medium |
| readRecord! | function_purpose | 导入不含有字符串类型字段的二进制文件 | high |
| readRecord! | string_support | 不支持导入字符串类型数据 | high |
| loadRecord | string_support | 支持导入字符串类型数据（包括 STRING 和 SYMBOL） | high |
| loadRecord | string_length_requirement | 要求字符串在磁盘上的长度必须固定；长度不足用ASCII值0填充，加载时去掉末尾0 | high |
| readRecord! 示例 | sample_file | binSample.bin | high |
| readRecord! 使用方式 | schema_definition | 需先创建内存表并为每列指定字段名称和数据类型，然后通过file打开文件并调用readRecord!将数据加载到该表 | high |
| temporalParse | function_purpose_in_context | 将数值形式存储的date/time列转换为日期和时间类型格式显示 | high |
| replaceColumn! | function_purpose_in_context | 用于用转换后的日期/时间列替换表中原有列 | high |
| loadRecord 示例 | sample_file | binStringSample.bin | high |
| loadRecord schema | definition_form | 通过元组（tuple）指定schema，而不是直接定义内存表 | high |
| loadRecord schema | rules | 每个字段以tuple指定名称与类型；若为字符串需指定磁盘字符串长度（含结尾0）；所有tuple按字段顺序组成元组 | high |
| writeRecord | function_purpose | 将DolphinDB对象保存为二进制文件 | high |
| DolphinDB | hdf5_support | 支持导入HDF5格式数据文件 | high |
| DolphinDB | hdf5_access_method | 通过HDF5插件访问HDF5文件 | high |
| HDF5插件 | methods | hdf5::ls; hdf5::lsTable; hdf5::hdf5DS; hdf5::loadHDF5; hdf5::loadHDF5Ex; hdf5::extractHDF5Schema | high |
| HDF5插件 | bundled_after_version | DolphinDB 1.00.0版本之后，安装目录 /server/plugins/hdf5 已经包含HDF5插件 | high |
| HDF5插件 | load_command | loadPlugin("plugins/hdf5/PluginHdf5.txt") | high |
| HDF5插件（老版本DolphinDB） | installation_note | 老版本默认不包含插件；可从对应版本分支bin目录下载并部署到节点plugins目录 | high |
| HDF5插件调用方式 | namespace_requirement | 调用插件方法需要加namespace（如hdf5::loadHDF5）；也可 use hdf5 后直接调用 | medium |
| HDF5导入示例 | file_and_dataset | 文件 candle_201801.h5；Dataset candle_201801；datasetName可通过ls或lsTable获得 | high |
| extractHDF5Schema | function_purpose_in_context | 可提取schema并修改字段类型后再导入（示例：将volume改为LONG） | high |
| loadHDF5Ex | use_case | 当HDF5文件超过服务器内存时可用于载入数据 | high |
| HDF5 loadHDF5Ex 示例 | dfs_path_and_partition_range | dfs://dataImportHDF5DB；VALUE分区；2018.01.01..2018.01.31 | high |
| HDF5 loadHDF5Ex 示例 | table_and_partition_column | 表 "cycle"；分区列 "tradingDay" | high |
| DolphinDB | odbc_support | 支持ODBC接口连接第三方数据库，将数据表读取为DolphinDB内存数据表 | high |
| DolphinDB | odbc_plugin | 官方提供ODBC插件用于连接第三方数据源并迁移数据至DolphinDB | high |
| ODBC插件 | methods | odbc::connect; odbc::close; odbc::query; odbc::execute; odbc::append | high |
| ODBC插件 | prerequisite | 使用前需要安装ODBC驱动程序（参考ODBC插件使用教程） | high |
| ODBC示例数据源 | db_type | SQL Server | high |
| ODBC示例 SQL Server | server | 172.18.0.15 | high |
| ODBC示例 SQL Server | port | 1433 | high |
| ODBC示例 SQL Server | username | sa | high |
| ODBC示例 SQL Server | password | 123456 | high |
| ODBC示例 SQL Server | database_name | SZ_TAQ | high |
| ODBC插件部署 | step | 拷贝 plugins\odbc 目录文件到 server 的 plugins/odbc 目录（若安装目录/server/plugins/odbc已包含可略过） | high |
| ODBC插件初始化示例 | load_command | loadPlugin("plugins/odbc/odbc.cfg") | high |
| ODBC连接字符串示例 | connection_string | Driver=ODBC Driver 17 for SQL Server;Server=172.18.0.15;Database=SZ_TAQ;Uid=sa;Pwd=123456; | high |
| ODBC导入示例 | dfs_database_and_range | dfs://dataImportODBC；VALUE分区；2018.01.01..2018.01.31 | high |
| ODBC导入示例 | table_created | 创建分区表 cycle，分区列 tradingDay，模板来自SQL Server中 candle_201801 的 select top 1 * | high |
| ODBC导入示例 | import_and_append | 从SQL Server查询 candle_201801 全表数据并 append! 到 DolphinDB 分区表 cycle | high |
| ODBC导入 | benefit | 通过ODBC导入数据方便快捷 | low |
| ODBC导入 + DolphinDB定时作业机制 | use_case | 可作为时序数据定时同步的数据通道 | medium |
| 导入数据实例 | data_description | 股票市场日K线图数据：每个股票一个CSV文件，共约100G，时间范围2008年-2017年，按年度分目录保存 | high |
| 分区规划 | purpose | 导入前需确定分区字段与分区粒度 | high |
| 分区字段选择建议 | recommendation | 以where/group by/context by中常用字段作为分区字段可极大提升数据检索与分析效率 | medium |
| 股票数据分区字段建议 | recommended_partition_columns | tradingDay 和 symbol 组合（COMPO）分区 | high |
| 分区大小建议 | recommended_partition_size_raw_uncompressed | 100M~1G | high |
| 分区规划示例（COMPO） | partition_design | 按交易日期范围分区（每年一个范围）+ 按股票代码范围分区（100个代码范围） | high |
| 分区规划示例（COMPO） | partition_count | 10 * 100 = 1000 个分区 | high |
| 分区规划示例（COMPO） | approx_partition_size | 每个分区大小约100M左右（未说明是否压缩，文本表述为最终每个分区大小约100M左右） | medium |
| 分区预制作时间范围 | suggested_time_range | 2008-2030年（用于后续进入的数据预先制作分区） | high |
| 股票代码分区向量构建 | design_note | 增加虚拟代码 999999 作为股票代码上限值，以覆盖未来新增代码可能超过现有最大值的情况 | high |
| 股票数据分区表创建示例 | table_name_and_partition_columns | 分区表 stockData；分区列 tradingDay 与 symbol | high |
| 导入过程中的time字段处理 | data_type_issue_and_fix | 原始time字段以整数（如“9390100000”）表示毫秒级时间；需用 datetimeParse(format(time,"000000000"),"HHmmssSSS") 转换为时间类型 | high |
| 100GB数据单线程导入 | time_cost | 单线程导入100GB数据会耗时很久 | low |
| 并行导入策略（示例） | approach | 按年度拆分导入任务，发送到各节点任务队列并行执行以提高效率 | high |
| 并行导入实现（示例） | uses_functions | rpc 与 submitJob | high |
| 后台任务观察（示例） | command | pnodeRun(getRecentJobs) | high |
| DolphinDB 分区写入并行注意事项 | write_locking_behavior | 分区是database存储数据的最小单位；对分区的写入操作是独占式；并行任务应避免同时向同一分区写入 | high |
| 案例并行写入正确性（示例说明） | no_partition_write_conflict | 本例每年数据写入由单独任务执行，数据范围不重合，因此不会发生多任务同时写入同一分区 | high |
| 附录条目 | includes | CSV导入数据文件；二进制导入例1数据文件；二进制导入例2数据文件；HDF5导入数据文件；案例完整脚本 | high |