DolphinDB文本数据加载教程

What this page covers

• 文本导入函数概览与用途（loadText/ploadText/loadTextEx/textChunkDS）。
• 导入时字段名与数据类型的自动识别机制与限制。
• 通过 schema 参数指定导入的列名、类型、格式与列下标。
• skipRows 跳过文件前若干行的行为与注意点。
• 并行导入：单文件多线程与多文件并行写入数据库的示例与约束。
• 写入数据库前的 transform 预处理机制与示例。
• 编码、数值解析与 CSV 引号处理等其它注意事项。

技能认证特训营第二期报名推广 cta

页面顶部包含培训营报名推广信息与报名链接。

• 该部分提供一个报名入口链接。
• 该部分属于培训营相关的推广信息。

DolphinDB文本数据加载教程（标题/作者/日期） product_overview

该部分给出教程标题、作者署名与发布时间信息。

• 作者署名为 Junxi。
• 发布时间为 2021-08-05。

文本导入函数概览与性能主张 product_overview

该部分列出 4 个文本导入/处理函数及其用途，并包含导入性能对比主张与教程范围说明。

• DolphinDB 提供 4 个用于导入文本数据的函数。
• loadText 用于将文本文件导入为内存表。
• ploadText 用于并行导入文本文件为分区内存表。
• loadTextEx 用于将文本文件导入数据库。
• textChunkDS 用于将文件切分为数据源并配合 mr 处理。

1. 自动识别数据格式 how_it_works

该部分说明导入时字段名与数据类型的自动识别机制、限制提示，并展示 loadText 示例与 schema 查看。

• 导入文本时可自动识别字段名与数据类型。
• 若首行列名不以数字开头，系统将其视为表头字段名。
• 类型推断基于小样本，可能出现列类型误识别。
• 当前不支持 UUID 与 IPADDR 的自动识别。
• schema() 可用于查看表结构（字段名与数据类型）。

2. 指定数据导入格式（schema参数） how_it_works

该部分说明可通过 schema 参数指定列名、类型、格式与列下标，并给出 schema 表结构要求与示例。

• schema 参数可使用一个表来描述导入列的规则。
• schema 表可包含 name、type、format、col 四列。
• name 与 type 为必填且必须是前两列。
• format 与 col 为可选列，出现顺序不受限。
• col 表示要导入的列下标，并要求升序。

2.1 提取文本文件的schema how_it_works

该部分介绍 extractTextSchema 获取字段名称与类型，并说明可基于结果修改解析类型。

• extractTextSchema 可获取文本文件的 schema（字段名与数据类型）。
• 若自动解析类型不符合预期，可修改得到的 schema 表。
• 可使用 SQL 语句对 schema 表进行修改。

2.2 指定字段名称和类型 how_it_works

该部分说明可通过修改 schema 并在 loadText 中指定 schema 参数来控制导入字段名与类型，并提到日期时间解析处理方式。

• 当自动识别不符合需求时，可显式指定 schema 参数。
• schema 参数可用于设置每列的字段名与数据类型。
• 日期/时间列需要结合 type 与 format 进行控制（在后续小节展开）。

2.3 指定日期和时间类型的格式 how_it_works

该部分通过示例说明日期时间列需要同时指定 type 与 format，才能按期望解析与导入。

• 若日期/时间列解析类型不符合预期，需要在 schema.type 中指定目标类型。
• 日期/时间列需要在 schema.format 中指定解析格式（如 “MM/dd/yyyy”）。
• 仅设置类型但不设置 format 可能无法按预期解析日期/时间。
• schema.format 用于指导日期/时间字符串的解析规则。

2.4 导入指定列 how_it_works

该部分说明可通过 schema.col 只导入指定列，列号从 0 开始，且不能在导入时改变列顺序。

• 可使用 schema.col 指定仅导入部分列。
• 列下标从 0 开始。
• 导入时不能改变原文件列顺序。
• 如需调整列顺序，可先导入再使用 reorderColumns!。

2.5 跳过文本数据的前若干行（skipRows） how_it_works

该部分说明 skipRows 用于跳过前 n 行（最大 1024），以及对列名识别的影响，并给出保留列名的做法。

• skipRows 可在导入时跳过文件前 n 行。
• skipRows 的最大值为 1024。
• 该参数被文中所述的 4 个加载函数支持。
• 若首行是列名，使用 skipRows 会跳过列名行并导致默认列名（如 col0）。
• 为保留列名可先用 extractTextSchema 提取 schema，再在 loadText 中同时使用 schema 与 skipRows。

3. 并行导入数据 how_it_works

该部分介绍单文件多线程载入内存与多文件并行导入数据库两种并行场景，并给出示例数据与性能结果。

• ploadText 使用多线程将单个文本文件载入内存并生成分区内存表。
• 并行度与 CPU 核数及节点 localExecutors 配置相关。
• 示例生成约 4GB 的文本文件用于性能对比。
• 示例中 loadText 用时为 12629.492 ms。
• 示例中 ploadText 用时为 2669.702 ms。
• 示例中 ploadText 约为 loadText 的 4.5 倍性能。
• loadTextEx 可将文本导入分布式数据库、本地磁盘数据库或内存数据库。
• 分区表不允许多个线程同时写入同一分区。

4. 导入数据库前的预处理（transform） how_it_works

该部分说明 loadTextEx 提供 transform 参数，可在写入数据库前对未分区内存表进行预处理，并给出类型转换与空值填充的示例。

• 仅 loadTextEx 提供 transform 参数用于写入前预处理。
• transform 接受一个恰好单参数的函数。
• transform 的输入是未分区内存表，输出也为未分区内存表。
• 自定义 transform 中建议使用就地修改函数（带 “!”）以提升性能。
• 示例中 transform 后 time 列以 TIME 类型存储，而非文本中的 INT。
• 示例中 transform 后 tradingDay 列以 MONTH 类型存储，而非文本中的 DATE。
• 可用偏函数将多参数内置函数转换为可用的单参数 transform。

5. 使用Map-Reduce自定义数据导入 how_it_works

该部分介绍使用 textChunkDS 与 mr 进行按 chunk 的 Map-Reduce 导入与自定义处理，并包含并行写入约束与首尾 chunk 加载示例。

• 支持使用 Map-Reduce 方式按行切分并自定义导入。
• 可用 textChunkDS 切分文件并用 mr 写入数据库。
• 在写入前可进行灵活处理。
• 示例按每 300MB 切分，约 1GB 文件得到 4 个分块。
• 若分块可能写入同一分区，应设置 mr parallel=false 以避免并发写同分区异常。
• 可通过选择 ds.head() 与 ds.tail() 并 union 来只加载大文件首尾分块。

6. 其它注意事项 limitations

该部分涵盖编码（UTF-8 要求与转换函数）、数值解析规则，以及 CSV 字段双引号处理等注意点。

• 由于字符串使用 UTF-8，待加载文件需要为 UTF-8 编码。
• 提供 convertEncode、fromUTF8、toUTF8 用于导入后编码转换。
• 数值解析可识别普通数字、千分位、带小数与科学计数法形式。
• 解析数值时会忽略数字周围的字母与符号。
• 若字段中不含数字，则解析为 NULL。
• 处理 CSV 被双引号包裹的字段时会自动去除外围双引号。

附录：示例数据文件链接 misc

该部分提供教程示例数据文件 candle_201801.csv 的下载链接。

• 示例数据文件为 candle_201801.csv。
• 该文件链接指向 GitHub（通过知乎跳转链接引用）。

Facts Index