DocParser

DocParser 用于从各类文档中提取按原文顺序排列的 UTF-8 文本块及基础结构信息，支持 PDF、DOCX、PPTX、XLSX 与纯文本文件，适用于文档入库、全文检索预处理、RAG 数据准备等场景。DolphinX 的 RAG 功能依赖本插件进行文件解析，使用相关功能前请先加载本插件。目前支持以下文档格式：

格式 常见扩展名 提取内容 主要限制 资源上限
PDF .pdf PDF 文本层、页码 不支持 OCR；不支持加密 PDF。

  • 单个文件或 BLOB：100 MiB

  • PDF 页数或 PPTX 幻灯片数：2,000

  • 提取的 Unicode 字符数：50,000,000

  • 单个 XML 部件：64 MiB

  • XML 嵌套深度：256
DOCX .docx 标题、段落、列表、表格 不提取页眉和页脚；嵌套表格会展开并产生警告。
PPTX .pptx 标题、文本框、表格、幻灯片编号、演讲者备注 对象阅读顺序根据几何位置推断，复杂布局可能产生警告。
XLSX .xlsx Sheet 名称、按行排列的单元格存储值 不处理样式，不计算公式，不支持 .xls 和 .xlsm。
纯文本 .txt、.text、.log、.md、.csv、.tsv 以空行分隔的文本段落 无 BOM 的非 UTF-8 文件必须显式指定编码。

安装插件

版本要求

DolphinDB Server：3.00.6 及更高版本，支持 Linux ABI。

安装步骤

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

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

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

    installPlugin("DocParser")

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

    loadPlugin("DocParser")

接口说明

parseFile

语法 

DocParser::parseFile(path, [options])

详情

解析指定的 DolphinDB server 所在服务器的文件。

参数

path STRING 类型标量，指定需要解析的 DolphinDB server 所在服务器文件的绝对路径，不能为空。指定的文件必须存在、必须为普通文件（非加密、损坏文件），且 DolphinDB server 有权限读取。

options （可选参数）字典（Dictionary<STRING, ANY>），指定解析选项，不指定时使用默认值。键名区分大小写，键值不区分大小写。支持以下 key：
key 可选值 默认值 说明
"format"
  • "auto"
  • "pdf"
  • "docx"
  • "pptx"
  • "xlsx"
  • "text"
 "auto" 指定解析文件的格式。指定为 "auto"，插件根据文件扩展名自动选择解析器；其他值要求扩展名映射到相同格式。
"encoding"
  • "auto"
  • "UTF-8"
  • "UTF-16LE"
  • "UTF-16BE"
  • "UTF-32LE"
  • "UTF-32BE"
  • "GB18030"
 "auto"

指定纯文本编码。UTF 编码名称可以省略连字符。

  • 指定为 "auto"，插件会根据 UTF BOM 识别 UTF-8、UTF-16 和 UTF-32。
  • 没有 BOM 时，输入必须是合法 UTF-8。
  • GB18030 不会自动推断，必须显式指定。
  • 显式编码与 BOM 冲突，或者字节序列不合法时会报错。

返回值

返回一个字典（Dictionary<STRING, ANY>），包含以下 key：

key 类型 说明
"schemaVersion" STRING 返回结构版本。当前为 "1.0"。
"status" STRING "OK" 或 "PARTIAL"。
"format" STRING 实际解析格式：pdf、docx、pptx、xlsx 或 text。
"metadata" DICTIONARY 输入文件及解析器元数据。
"warnings" TABLE 非致命解析警告。没有警告时返回零行表。
"blocks" TABLE 按文档顺序排列的文本块。没有文本时返回零行表。

"status" 为 "PARTIAL" 表示文档中至少有一部分内容、页面、字符映射或可选 OOXML 部件未能提取；此时仍然是正常返回，应用程序可以使用已经提取的 "blocks"，同时记录并处理 "warnings"。

有 "warnings" 时，"status" 的值不一定是 "PARTIAL"。例如，扩展名不匹配或 PPTX 阅读顺序不确定时，会返回 "warnings"，此时 "status" 的结果仍可能是 "OK"。

metadata 字典

key 类型 说明
"fileName" STRING parseBytes 传入的逻辑文件名，或 parseFile 路径的文件名部分。
"fileSize" LONG 输入字节数。
"parserVersion" STRING 解析器实现版本。
"sourceEncoding" STRING 纯文本的实际编码；非文本格式为空值。
"pageCount" INT PDF 页数、PPTX 幻灯片数或 XLSX Sheet 数；DOCX 和纯文本为空值。

warnings 表

字段 类型 说明
code SYMBOL

稳定、可供程序判断的警告编码。当前可能返回的警告编码：

  • "FORMAT_EXTENSION_MISMATCH"（文件扩展名与检测到的内容格式不一致）

  • "UNSUPPORTED_ELEMENT_SKIPPED"（跳过或展开了无法完整表示的页面、OOXML 部件或结构）

  • "UNICODE_MAPPING_MISSING"（PDF 字符缺少有效的 Unicode 映射）

  • "POSSIBLE_SCANNED_PDF"（PDF 包含图像但可提取文本很少，可能需要 OCR）

  • "READING_ORDER_UNCERTAIN"（PPTX 布局复杂，文本框阅读顺序只能根据位置推断）

  • "FORMULA_CACHE_MISSING"（XLSX 公式没有保存缓存结果，该单元格按空值输出）
message STRING 人类可读的详细信息。
pageNo INT 从 1 开始的 PDF 页、PPTX 幻灯片或 XLSX Sheet 编号。
sourcePart STRING OOXML 部件名称或其他来源位置。

blocks 表

字段 类型 说明
ordinal LONG 从 0 开始的全局文本块顺序。
blockType SYMBOL

文本块语义类型：

  • "pageText"（PDF 页面中可提取的非空文本）

  • "heading"（DOCX 标题，同时提供 headingLevel）

  • "paragraph"（DOCX、PPTX 或纯文本段落）

  • "listItem"（DOCX 项目符号或编号列表项）

  • "tableRow"（DOCX、PPTX 或 XLSX 表格行，单元格之间使用制表符分隔）

  • "title"（PPTX 标题占位符，或 XLSX Sheet 名称）

  • "note"（PPTX 单页演讲者备注）
text STRING 规范化后的 UTF-8 文本。
pageNo INT，可能为空 从 1 开始的 PDF 页、PPTX 幻灯片或 XLSX Sheet 编号。
headingLevel INT，可能为空 从 1 开始的 DOCX 标题级别。
groupType SYMBOL，可能为空 主要结构类型："table"、"list"、"textBox"、"note"。
groupId LONG，可能为空 本次解析结果内唯一的结构组标识。
groupOrdinal INT，可能为空 从 0 开始的组内文本块顺序。
groupLevel INT，可能为空 从 0 开始的 DOCX 列表嵌套层级；其他结构为空值。

groupType、groupId 和 groupOrdinal 要么同时存在，要么同时为空。groupId 只适合在同一次解析结果中判断两个文本块是否属于同一结构，不保证跨调用稳定。还原文档顺序时必须使用全局 ordinal，不能按 groupId 排序。

示例 

// 简单示例
options = dict(["format"], ["docx"])
result = DocParser::parseFile("/data/contracts/contract.docx", options)
blocks = result["blocks"]

// 自动识别格式和文本编码
autoResult = DocParser::parseFile("/data/readme.txt")

// 显式指定 GB18030
gbOptions = dict(["format", "encoding"], ["text", "GB18030"])
gbResult = DocParser::parseFile("/data/legacy.txt", gbOptions)

// 强制校验 PDF 内容；如果文件不是 PDF 则报错
pdfOptions = dict(["format"], ["pdf"])
pdfResult = DocParser::parseFile("/data/report.pdf", pdfOptions)

parseBytes

语法 

DocParser::parseBytes(content, fileName, [options])

详情

解析内存中的 BLOB 文档。适用于 DolphinDB server 已经读取文件内容，或者文件不在 DolphinDB server 所在服务器时。上传 PDF、DOCX、PPTX 或 XLSX 时必须保留原始二进制字节，不要先按字符串解码。

参数

content BLOB 类型标量，指定需要解析的完整原始文档字节。

fileName STRING 类型标量，指定逻辑文件名，用于返回元数据、扩展名检查和诊断；不会作为本地路径打开。

options （可选参数）字典（Dictionary<STRING, ANY>），指定解析选项，不指定时使用默认值。键名区分大小写，键值不区分大小写。支持以下 key：
key 可选值 默认值 说明
"format"
  • "auto"
  • "pdf"
  • "docx"
  • "pptx"
  • "xlsx"
  • "text"
 "auto" 指定解析文件的格式。指定为 "auto"，插件根据文件扩展名自动选择解析器；其他值要求扩展名映射到相同格式。
"encoding"
  • "auto"
  • "UTF-8"
  • "UTF-16LE"
  • "UTF-16BE"
  • "UTF-32LE"
  • "UTF-32BE"
  • "GB18030"
 "auto"

指定纯文本编码。UTF 编码名称可以省略连字符。

  • 指定为 "auto"，插件会根据 UTF BOM 识别 UTF-8、UTF-16 和 UTF-32。
  • 没有 BOM 时，输入必须是合法 UTF-8。
  • GB18030 不会自动推断，必须显式指定。
  • 显式编码与 BOM 冲突，或者字节序列不合法时会报错。

返回值

返回一个字典（Dictionary<STRING, ANY>），包含以下 key：

key 类型 说明
"schemaVersion" STRING 返回结构版本。当前为 "1.0"。
"status" STRING "OK" 或 "PARTIAL"。
"format" STRING 实际解析格式：pdf、docx、pptx、xlsx 或 text。
"metadata" DICTIONARY 输入文件及解析器元数据。
"warnings" TABLE 非致命解析警告。没有警告时返回零行表。
"blocks" TABLE 按文档顺序排列的文本块。没有文本时返回零行表。

"status" 为 "PARTIAL" 表示文档中至少有一部分内容、页面、字符映射或可选 OOXML 部件未能提取；此时仍然是正常返回，应用程序可以使用已经提取的 "blocks"，同时记录并处理 "warnings"。

有 "warnings" 时，"status" 的值不一定是 "PARTIAL"。例如，扩展名不匹配或 PPTX 阅读顺序不确定时，会返回 "warnings"，此时 "status" 的结果仍可能是 "OK"。

metadata 字典

key 类型 说明
"fileName" STRING parseBytes 传入的逻辑文件名，或 parseFile 路径的文件名部分。
"fileSize" LONG 输入字节数。
"parserVersion" STRING 解析器实现版本。
"sourceEncoding" STRING 纯文本的实际编码；非文本格式为空值。
"pageCount" INT PDF 页数、PPTX 幻灯片数或 XLSX Sheet 数；DOCX 和纯文本为空值。

warnings 表

字段 类型 说明
code SYMBOL

稳定、可供程序判断的警告编码。当前可能返回的警告编码：

  • "FORMAT_EXTENSION_MISMATCH"（文件扩展名与检测到的内容格式不一致）

  • "UNSUPPORTED_ELEMENT_SKIPPED"（跳过或展开了无法完整表示的页面、OOXML 部件或结构）

  • "UNICODE_MAPPING_MISSING"（PDF 字符缺少有效的 Unicode 映射）

  • "POSSIBLE_SCANNED_PDF"（PDF 包含图像但可提取文本很少，可能需要 OCR）

  • "READING_ORDER_UNCERTAIN"（PPTX 布局复杂，文本框阅读顺序只能根据位置推断）

  • "FORMULA_CACHE_MISSING"（XLSX 公式没有保存缓存结果，该单元格按空值输出）
message STRING 人类可读的详细信息。
pageNo INT 从 1 开始的 PDF 页、PPTX 幻灯片或 XLSX Sheet 编号。
sourcePart STRING OOXML 部件名称或其他来源位置。

blocks 表

字段 类型 说明
ordinal LONG 从 0 开始的全局文本块顺序。
blockType SYMBOL

文本块语义类型：

  • "pageText"（PDF 页面中可提取的非空文本）

  • "heading"（DOCX 标题，同时提供 headingLevel）

  • "paragraph"（DOCX、PPTX 或纯文本段落）

  • "listItem"（DOCX 项目符号或编号列表项）

  • "tableRow"（DOCX、PPTX 或 XLSX 表格行，单元格之间使用制表符分隔）

  • "title"（PPTX 标题占位符，或 XLSX Sheet 名称）

  • "note"（PPTX 单页演讲者备注）
text STRING 规范化后的 UTF-8 文本。
pageNo INT，可能为空 从 1 开始的 PDF 页、PPTX 幻灯片或 XLSX Sheet 编号。
headingLevel INT，可能为空 从 1 开始的 DOCX 标题级别。
groupType SYMBOL，可能为空 主要结构类型："table"、"list"、"textBox"、"note"。
groupId LONG，可能为空 本次解析结果内唯一的结构组标识。
groupOrdinal INT，可能为空 从 0 开始的组内文本块顺序。
groupLevel INT，可能为空 从 0 开始的 DOCX 列表嵌套层级；其他结构为空值。

groupType、groupId 和 groupOrdinal 要么同时存在，要么同时为空。groupId 只适合在同一次解析结果中判断两个文本块是否属于同一结构，不保证跨调用稳定。还原文档顺序时必须使用全局 ordinal，不能按 groupId 排序。

示例

纯文本 BLOB 示例：

content = blob("第一段\n\n第二段")
options = dict(["format", "encoding"], ["text", "UTF-8"])
result = DocParser::parseBytes(content, "note.txt", options)

fileName 只表示逻辑名称，因此下面的调用不会访问 /client/path/：

result = DocParser::parseBytes(content, "/client/path/report.pdf")

formats

语法 

DocParser::formats()

详情

查询本插件支持的文档格式。

参数

无

返回值

返回一张表，包含以下字段：

字段 类型 说明
format SYMBOL 本插件支持的文档格式；options.format 可使用的格式名称。
extensions STRING 识别的文件扩展名，多个扩展名以逗号分隔。
mimeTypes STRING 对应的 MIME 类型。
features STRING 该格式支持的提取能力。

示例 

DocParser::formats()

返回一张表：

format extensions mimeTypes features
pdf .pdf application/pdf text,page
docx .docx application/vnd.openxmlformats-officedocument.wordprocessingml.document text,heading,list,table,structureGroup
pptx .pptx application/vnd.openxmlformats-officedocument.presentationml.presentation text,page,title,table,textBox,note,structureGroup
xlsx .xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet text,sheet,title,table,rawValue,structureGroup
text .txt,.text,.log,.md,.csv,.tsv text/plain text,encoding

version

语法 

DocParser::version()

详情

查询本插件版本、编译环境及依赖版本。

参数

无

返回值

返回一个字典（Dictionary<STRING, ANY>），包含以下 key：

key 说明
"pluginVersion" DocParser 插件版本。
"schemaVersion" 解析结果结构版本。
"architecture" 构建目标架构。
"compiler" 编译器版本。
"cppAbi" 插件使用的 libstdc++ C++ ABI。
"dependencies" PDFium、libzip、pugixml、ICU 和 zlib 的版本字典。

如果 PDFium 无法加载，DocParser::version() 不会因此整体失败，而会在 PDFium 版本字段中报告不可用状态。

使用示例

// 自动识别格式和文本编码解析 pptx 文件
result = DocParser::parseFile("/home/test/test.pptx")
blocks = result["blocks"]

// 传入 options 指定 format 为 text
options = dict(["format"], ["text"])
result = DocParser::parseFile("/home/test/test.txt", options)
blocks = result["blocks"]

// 显式指定 GB18030
gbOptions = dict(["format", "encoding"], ["text", "GB18030"])
gbResult = DocParser::parseFile("/home/test/test.txt", gbOptions)

// 强制校验文件，若非 PDF 则报错
pdfOptions = dict(["format"], ["pdf"])
pdfResult = DocParser::parseFile("/home/test/test.txt", pdfOptions)
// Error: [DocParser:INVALID_OPTION] options.format 'pdf' does not match file extension '.txt'

错误码

参数错误或致命解析失败时抛出 DolphinDB 运行时异常，不返回部分字典。异常消息统一以下面的格式开头：

[DocParser:<错误码>] 详细信息
错误码 常见原因
INVALID_ARGUMENT 参数数量、数据类型或数据形式错误。
INVALID_OPTION 未知选项、非法选项值，或对二进制文档指定了文本编码。
FILE_NOT_FOUND 文件不存在、不是普通文件，或者 server 进程无权读取。
FILE_TOO_LARGE 文件或 BLOB 超过 100 MiB。
UNSUPPORTED_FORMAT ZIP/OOXML 内容不是受支持的 DOCX、PPTX 或 XLSX。
CORRUPT_DOCUMENT 签名、ZIP、XML、关系、校验和或文档结构损坏。
PASSWORD_REQUIRED PDF 或 OOXML 文档已加密；当前不支持输入密码。
ENCODING_REQUIRED 文本没有 Unicode BOM，并且不是合法 UTF-8。
INVALID_ENCODING 文本字节不符合指定编码，或者与 BOM 冲突。
LIMIT_EXCEEDED 页数、ZIP 条目、XML 深度、输出量或解析时间超过限制。
OUT_OF_MEMORY 内存分配失败。
INTERNAL_ERROR PDFium 等运行时依赖异常，或出现未预期的解析错误。