从Python Notebook调用含Markdown的SQL Notebook触发Parse Exception

问题背景 #

在Azure Databricks环境中，若SQL Notebook包含%md命令，通过Python Notebook的%run命令调用时会触发解析错误。该问题在10.4LTS和11.2版本集群均存在，与近期Databricks UI更新相关。这类SQL Notebook通常用于生成多Notebook共享的临时视图，用户希望保留Markdown文档的同时解决调用问题。

问题复现步骤 #

正常执行场景 #

• 创建SQL Notebook（命名为Test_SubNotebook）
  • 命令1：执行基础SQL，如select 'Test'
• 创建Python Notebook（命名为Test_Notebook）
  • 命令1：执行%run './Test_SubNotebook'
• 运行Test_Notebook，执行成功，显示查询结果

触发错误场景 #

• 给Test_SubNotebook添加新命令
  • 命令2：输入Markdown内容

%md
Test Markdown

• 重新运行Test_Notebook，触发ParseException错误，核心报错信息如下：

ParseException: 
mismatched input '%' expecting {'(', 'APPLY', 'CONVERT', ...}(line 1, pos 0)

== SQL ==
%md
^^^
Test Markdown

替代解决办法（无需删除Markdown） #

方案1：拆分SQL逻辑与文档说明 #

• 将生成临时视图的SQL代码单独存入.sql文件（如shared_temp_views.sql）
• 原SQL Notebook仅保留Markdown文档，通过%run ./shared_temp_views.sql调用SQL文件
• Python Notebook仍用%run './Test_SubNotebook'调用，既保留文档，又能正常执行SQL逻辑

方案2：条件执行屏蔽Markdown #

在SQL Notebook的Markdown命令位置，改用Python代码实现条件渲染，仅在交互式运行时显示文档：

# 仅当Notebook被手动运行时显示Markdown内容
if dbutils.notebook.entry_point.getDbutils().notebook().getContext().currentRunId().isEmpty():
    displayHTML("<h3>Test Markdown</h3>")

当被%run调用时（非交互式模式），这段代码不会执行，避免SQL解析器处理%md命令。

方案3：使用dbutils.notebook.run()替代%run #

在Python Notebook中，改用dbutils.notebook.run()调用目标SQL Notebook，示例代码：

# 调用子Notebook，设置超时时间（单位：秒）
dbutils.notebook.run("./Test_SubNotebook", timeout_seconds=300)

该方法以作业模式运行子Notebook，能正确识别并处理%md命令，不会触发解析错误。

内容的提问来源于stack exchange，提问作者matt.bungard