excel

在数据接入和数据清洗场景中，业务数据常以 Excel 工作簿形式交付。手动导出 CSV 或逐列处理不仅流程繁琐，也容易因表头、行范围、空值或单元格格式不一致导致数据质量问题。服务端 excel 插件提供了直接在 DolphinDB Server 中读取 .xlsx 文件的能力，其核心能力包括：

  • 读取工作簿结构：获取指定 .xlsx 文件中的所有 Sheet 名称。

  • 按列映射读取：支持指定读取的 Excel 源列，并指定结果表的列名及其在 DolphinDB 中的数据类型。

  • 读取范围控制：支持指定表头行、数据起始行和数据结束行。

  • 表头校验：可通过预期表头校验文件格式，及时发现模板变更。

DolphinDB 目前提供两种与 Excel 相关的插件，二者运行位置和使用场景不同：

  • DolphinDB Excel Add-in / Excel 客户端加载项：运行在 Microsoft Excel 客户端中，用于在 Excel 中连接 DolphinDB、执行查询、导出数据。适用于希望在 Excel 界面中交互式操作 DolphinDB 的用户。

  • DolphinDB 服务端 excel 插件：运行在 DolphinDB Server 中，用于在 DolphinDB 脚本中读取服务器本地的 .xlsx 文件，并将其转换为 DolphinDB 表。本文介绍的是该服务端插件。

下载插件前请确认使用场景：如果需要在 Excel 客户端中操作 DolphinDB，请下载 Excel Add-in；如果需要在 DolphinDB Server 中通过脚本读取 Excel 文件，请下载本文介绍的服务端 excel 插件。请注意，当前服务端 excel 插件仅支持 .xlsx 文件，不支持旧版 .xls 文件；如源文件为 .xls，需先另存或转换为 .xlsx 后再读取。

安装插件

版本要求

DolphinDB Server 版本要求：3.00.4 及以上版本

部署环境要求：Linux-x86、Linux-ABI

安装步骤

  1. 在 DolphinDB 客户端中使用 listRemotePlugins 函数查看可供安装的插件。

    login("admin", "123456")
listRemotePlugins()

  2. 使用 installPlugin 函数安装插件。

    installPlugin("excel")

  3. 使用 loadPlugin 函数加载插件。

    loadPlugin("excel")

接口说明

listSheets

语法

excel::listSheets(filePath)

详情

获取指定 Excel 工作簿中的所有 Sheet 名称。返回结果按照 Sheet 在工作簿中的顺序排列。

参数

filePath STRING 类型标量，表示 DolphinDB Server 上的 .xlsx 文件路径。路径必须指向具体文件，不能传入目录。

返回值

STRING 向量，包含工作簿中的所有 Sheet 名称。

示例

filePath = "/data/bond_trade.xlsx"
sheets = excel::listSheets(filePath)
sheets
示例结果：
["现券交易", "回购交易"]

readSheet

语法

excel::readSheet(filePath, sheet, columnSpec, [options])

详情

按照指定的列映射、行范围和读取选项读取单个 Sheet，并返回 DolphinDB 内存表。多个 Sheet 的读取和合并可通过 DolphinDB 脚本完成。

参数

filePath STRING 类型标量，表示 DolphinDB Server 上的 .xlsx 文件路径。

sheet STRING 类型标量，表示要读取的 Sheet 名称。

columnSpec 列映射表，用于定义 Excel 源列、结果表列名和 DolphinDB 目标类型。该表必须且只能包含以下三列：

列名

说明

示例
excelColumn Excel 源列。可使用列标签，也可使用从 1 开始的整数列号。 "A"、"AA"、1
name DolphinDB 结果表中的列名。 "institution"
type DolphinDB 目标类型名称，不区分大小写。 "STRING"、"double"

支持的目标类型包括：BOOL、CHAR、SHORT、INT、LONG、FLOAT、DOUBLE、STRING、SYMBOL、DATE、MONTH、TIME、MINUTE、SECOND、DATETIME、TIMESTAMP、NANOTIME、NANOTIMESTAMP、DATEHOUR。

options 可选参数，字典，类型为 dict(STRING, ANY)。用于设置表头、数据范围、空值、合并单元格和原始位置等读取规则。支持的键如下：

键

说明
headerRow 从 1 开始的 Excel 表头行号。指定 expectedHeader 时，插件会读取并校验该行。默认值为 1。
dataStartRow 从 1 开始的数据起始行，读取结果包含该行。默认为 headerRow + 1
dataEndRow 数据结束行，读取结果包含该行。未指定时读取到有效数据末尾。
includeExcelLocation

是否在结果表最前面增加 excelSheet 和 excelRow 两列。默认值为 false。若设置为 true，在结果表最前面增加两列：

  • excelSheet：STRING 类型，数据所在的 Sheet 名称。
  • excelRow：INT 类型，数据所在的 Excel 物理行号。

注意：当开启该选项时，columnSpec 中的 name 列不能使用 excelSheet 或 excelRow 作为自定义列名，否则会引起列名冲突。
expectedHeader 与 columnSpec 等长的字符串向量，用于按照映射列精确校验表头。指定后，与 headerRow 配合使用。
mergedCellMode

合并单元格处理模式，可取

  • "topLeft"（默认值）：只保留合并区域左上角的值，其余位置为空。
  • "fill"：将左上角的值填充到被读取的整个合并区域。
  • "error"：合并区域与待读取的表头或数据区域相交时直接报错。

返回值

一张 DolphinDB 内存内存表。表结构由 columnSpec 指定；开启 includeExcelLocation 时，结果表最前面会增加 excelSheet 和 excelRow 两列。

类型转换规则

Excel 类型 目标类型 转换方式
空值 所有类型 输出对应类型的空值。
字符串 CHAR 仅当字符串长度为 1 字节时转换为字符。
字符串 STRING/SYMBOL 按字符串读出。
字符串

STRING/SYMBOL 之外的其他类型

 按照 DolphinDB 规则转换。
布尔值 所有类型 先按 BOOL 读出，再根据 DolphinDB 规则转换为对应类型。
数字（数字单元格） 所有类型 先按 DOUBLE 读出，再根据 DolphinDB 规则转换为对应类型。
数字（时间单元格） 数值类型 忽略单元格显示格式，按数字处理。
数字（时间单元格） 时间类型 解析为 TIMESTAMP 后，再根据 DolphinDB 规则转换为对应时间类型。
错误 所有类型 报错。
公式 所有类型 报错。
  • 如果文件中使用 -、N/A 等字符串表示空值，建议在 DolphinDB 脚本中先将相关列读取为 STRING 类型，再按业务规则统一处理。为便于生产环境及时发现数据异常，插件在类型转换失败时会直接报错。
  • Excel 中每个单元格可以独立设置“单元格格式”，该设置会影响底层 DOUBLE 数值在 Excel 中以时间还是数字形式展示。读取时间类型时，应确认源文件单元格格式与目标类型预期一致。

使用示例

例 1. 以下示例读取单个 Sheet，并按照列映射将 Excel 数据转换为 DolphinDB 表。

loadPlugin("excel")
go

filePath = "/data/bond_trade.xlsx"

columnSpec = table(
    ["A", "B", "C", "D"] as excelColumn,
    ["institution", "maturity", "treasuryNew", "treasuryOld"] as name,
    ["STRING", "STRING", "DOUBLE", "DOUBLE"] as type
)

options = dict(STRING, ANY)
options["headerRow"] = 3
options["dataStartRow"] = 4
options["expectedHeader"] = ["机构名称", "期限", "国债-新债", "国债-老债"]
options["mergedCellMode"] = "topLeft"
options["includeExcelLocation"] = true

result = excel::readSheet(filePath, "现券交易", columnSpec, options)
result

示例结果：

excelSheet excelRow institution maturity treasuryNew treasuryOld

现券交易

 4 机构A 1Y 100.5 20.0

现券交易

 5 机构B 3Y 80.0 10.5

例 2. 读取并合并多个 Sheet

sheets = excel::listSheets(filePath)
tables = array(ANY, 0)

for (sheetName in sheets) {
    tables.append!(excel::readSheet(filePath, sheetName, columnSpec, options))
}

result = unionAll(tables, false)

参与合并的 Sheet 应使用相同的 columnSpec，保证结果表结构一致。