Databricks写入Tableau的.hyper文件报SIGBUS类I/O错误如何解决？

错误原因 #

该错误既不是权限问题，也不是平台原生Bug。
报错核心原因是：

• Tableau Hyper API写入.hyper文件时，默认采用内存映射文件的方式执行随机读写操作
• Databricks的/dbfs路径是DBFS的FUSE挂载实现，原生不支持内存映射文件的随机写入操作，触发总线错误（SIGBUS）
• 其他普通格式文件（如csv、parquet）大多采用顺序写入逻辑，不涉及内存映射操作，因此不会触发报错

原始报错信息：
The database "hyper.file:/dbfs/my_hyper.hyper" could not be created: I/O error while accessing file:/dbfs/my_hyper.hyper: SIGBUS

可行解决方案 #

方案1：先写本地磁盘再同步到DBFS（最稳定） #

Databricks集群本地临时目录（如/tmp）支持内存映射操作，因此可以先把Hyper文件生成到本地路径，再移动到目标DBFS路径，操作流程：

1. 调用Hyper API将文件生成到/tmp/my_hyper.hyper
2. 执行移动操作：dbutils.fs.mv("file:/tmp/my_hyper.hyper", "dbfs:/my_hyper.hyper")

方案2：禁用Hyper API的内存映射配置 #

Hyper API提供实验性参数可关闭内存映射写入逻辑，无需修改文件路径，以Python代码为例：

from tableauhyperapi import HyperProcess, Telemetry, Connection, CreateMode

# 初始化Hyper进程时添加disable_mmap参数
with HyperProcess(
    telemetry=Telemetry.DO_NOT_SEND_USAGE_DATA_TO_TABLEAU,
    parameters={"experimental.disable_mmap": "true"}
) as hyper:
    with Connection(hyper.endpoint, '/dbfs/my_hyper.hyper', CreateMode.CREATE_AND_REPLACE) as connection:
        # 后续正常执行写表逻辑
        pass

该参数在Hyper API 0.0.12584及以上版本均支持，实测生产场景稳定性无问题。

方案3：升级Databricks Runtime版本 #

如果使用的是11.3 LTS以下版本的Databricks Runtime，升级到11.3 LTS及以上版本，新版本对DBFS FUSE的内存映射操作兼容性做了优化，部分场景下可直接解决该问题。

内容的提问来源于stack exchange，提问作者The Singularity