PDF_TO_JSON
功能
将 PDF 文档解析为结构化 JSON 字符串，包含文档元数据、每页纯文本和 PyMuPDF 提取的版面结构（块、行、文字坐标等）。适合需要对 PDF 内容做程序化处理的场景，如抽取表格、段落、坐标信息等。
语法
PDF_TO_JSON(source)
PDF_TO_JSON(source, options)
| 参数 | 类型 | 说明 |
|---|
source
source | STRING | PDF 来源，支持 HTTP/HTTPS URL 或本地路径（见下方"来源格式"） |
options
options | STRING（可选） | 选项字符串，格式为 k1=v1,k2=v2,...
k1=v1,k2=v2,... ，必须是非 NULL 字面量 |
返回值：STRING 类型的 JSON 文本。
返回值结构
{
"page_count": 3,
"metadata": {
"title": "文档标题",
"author": "作者",
"subject": "主题",
"creator": "Word",
"producer": "Adobe PDF",
"creationDate": "D:20240101120000",
"modDate": "D:20240101130000",
"format": "PDF 1.7",
"encryption": null
},
"pages": [
{
"number": 1,
"text": "第一页的纯文本内容...",
"layout": {
"width": 595.0,
"height": 842.0,
"blocks": [
{
"type": 0,
"bbox": [72, 70, 523, 90],
"lines": [...]
}
]
}
}
]
}
| 字段 | 说明 |
|---|
page_count
page_count | 总页数 |
metadata
metadata | PDF 文档元数据（标题、作者、创建日期等），可能为空对象 {}
{} |
pages[].number
pages[].number | 页码（从 1 开始） |
pages[].text
pages[].text | 该页纯文本 |
pages[].layout
pages[].layout | PyMuPDF 的 JSON 版面结构，含坐标、块、行、字符信息 |
来源格式
| 格式 | 示例 | 说明 |
|---|
| HTTP/HTTPS URL | 'https://example.com/doc.pdf'
'https://example.com/doc.pdf' | 自动下载，默认超时 30 秒，默认限制 100 MB |
options 可用字段
| 字段 | 默认值 | 取值 | 说明 |
|---|
ocr
ocr | auto
auto | auto
auto / never
never / always
always | OCR 策略，见下方"OCR 策略说明" |
http_timeout_seconds
http_timeout_seconds | 30
30 | 正整数（秒） | HTTP 下载超时时间 |
max_download_bytes
max_download_bytes | 104857600
104857600 （100 MB） | 正整数（字节） | HTTP 下载大小上限，超过则报错 |
ocr_timeout_seconds
ocr_timeout_seconds | 180
180 | 正整数（秒） | OCR 处理超时时间 |
slow_operation_seconds
slow_operation_seconds | 5
5 | 正整数（秒） | 单步操作超过此时间记录 WARNING 日志 |
mode
mode | — | dummy
dummy | 测试模式，直接返回固定占位内容，不处理真实 PDF |
options 格式示例：
'ocr=never,http_timeout_seconds=60'
OCR 策略说明
| 策略 | 行为 |
|---|
auto
auto （默认） | 自动判断：检测各页词密度，若超过 50% 的页面每页词数 < 20，则认为是扫描件并触发 OCR |
never
never | 跳过 OCR，直接从 PDF 文字层提取（扫描件可能返回空文本） |
always
always | 强制对所有页面做 OCR，即使 PDF 已有文字层 |
使用示例
-- 基础用法：解析 HTTP URL 中的 PDF
SELECT PDF_TO_JSON('https://example.com/report.pdf');
-- 禁用 OCR（速度更快，仅适合有文字层的 PDF）
SELECT PDF_TO_JSON('https://example.com/report.pdf', 'ocr=never');
-- 强制 OCR（扫描件）
SELECT PDF_TO_JSON('https://example.com/scanned.pdf', 'ocr=always');
-- 调大下载限制和超时（大文件）
SELECT PDF_TO_JSON(
'https://example.com/large.pdf',
'ocr=auto,max_download_bytes=209715200,http_timeout_seconds=120'
);
-- Volume 文件（推荐生产用法：通过 get_presigned_url 获取预签名 URL）
SELECT PDF_TO_JSON(get_presigned_url(volume my_vol, 'report.pdf'));
-- 批量处理表中的 PDF URL
SELECT
doc_id,
get_json_object(PDF_TO_JSON(pdf_url), '$.page_count') AS page_count,
get_json_object(PDF_TO_JSON(pdf_url), '$.metadata.title') AS title
FROM pdf_documents;
-- 提取第一页文本
SELECT get_json_object(PDF_TO_JSON(pdf_url), '$.pages[0].text') AS first_page_text
FROM pdf_documents;
注意事项
options
options
必须是字符串字面量，不能是列名或变量；不能为空字符串 ''
''
- 多个选项用逗号分隔，不能有重复 key，不能有空 segment（如末尾多余逗号）
- OCR 依赖服务端安装
ocrmypdf
ocrmypdf
，若未安装则 OCR 会静默跳过（不报错），扫描件将直接用原始文字层提取
- 扫描件且 OCR 未安装时，
pages[].text
pages[].text
可能为空字符串
metadata
metadata
字段内容由 PDF 文件本身决定，可能为空对象 {}
{}
mode=dummy
mode=dummy
返回固定 JSON：{"page_count":1,"metadata":{},"pages":[{"number":1,"text":"Dummy PDF Text","layout":{"width":0,"height":0,"blocks":[]}}]}
{"page_count":1,"metadata":{},"pages":[{"number":1,"text":"Dummy PDF Text","layout":{"width":0,"height":0,"blocks":[]}}]}
