Azure Synapse与ADF中数据流活动Checkpoint Key属性显示条件咨询

问题背景 #

我当前使用Azure Synapse Analytics从CosmosDB提取变更源数据，配置如下：

• CosmosDB已配置Synapse Link；
• 在数据流中使用内联数据集对分析存储运行参数化查询；
• 该数据流属于Azure Synapse Analytics中的参数化管道。

遇到的问题：需要在管道中覆盖检查点键，但无法在管道内数据流活动的设置选项卡中找到覆盖Checkpoint Key的选项。

Checkpoint Key属性显示的前提条件 #

要让数据流活动设置里出现Checkpoint Key选项，必须满足以下核心条件：

• 数据流已启用增量刷新并配置检查点：只有当数据流的源转换开启了增量刷新功能，且指定了检查点列时，管道中的数据流活动才会显示该选项。
• 数据源支持增量捕获：对于CosmosDB来说，必须指向分析存储容器（通过Synapse Link挂载的），事务存储容器不支持这种增量检查点机制。
• 排除调试模式干扰：如果当前处于数据流调试会话中，部分高级属性可能不会显示，需切换到管道的正式设计视图，或者发布后再查看。

启用并覆盖Checkpoint Key的具体步骤 #

1. 在数据流中开启增量刷新
   打开目标数据流，选中CosmosDB分析存储的源转换：

   • 进入「源选项」面板，勾选「启用增量刷新」；
   • 指定检查点列（比如CosmosDB自带的_ts时间戳列，或自定义的变更序列标识列），系统会自动启用检查点功能。

2. 回到管道配置Checkpoint Key
   打开包含该数据流的管道，选中数据流活动：

   • 切换到「设置」选项卡，此时就能看到「Checkpoint Key」的输入框；
   • 输入自定义键值即可覆盖默认的检查点键（默认键由系统基于数据流和源配置生成）。

3. 参数化覆盖（适配你的场景）
   因为你的管道是参数化的，还可以把Checkpoint Key绑定到管道参数：点击输入框旁的动态内容按钮，选择已定义的管道参数，实现动态覆盖。

额外排查建议 #

• 确认源数据集确实指向CosmosDB的分析存储容器，而非事务存储；
• 如果已经配置了增量刷新仍看不到选项，尝试发布数据流和管道后刷新界面，部分属性需发布后才会加载显示。

内容的提问来源于stack exchange，提问作者Robert Hurwitz