confluent-cloud-flink-sql

Confluent Cloud Flink SQL

对于任何 Confluent Cloud Flink SQL 工作，都必须遵守 CC-Flink 与 OSS-Flink 的方言边界，并采用 CLI 驱动的验证循环。Apache Flink OSS 训练数据是个陷阱——CC 会拒绝或悄然错误处理大量其他情况下有效的 Flink SQL 语法。

范围说明：本技能的参考资料围绕 OSS 与 CC 的方言边界构建，重点介绍两种方言都支持、但行为不同的语法陷阱。目前尚未收录没有 OSS 对应项的 CC 专属 DDL（例如 CREATE MATERIALIZED TABLE、CREATE MODEL/AI_COMPLETE、CREATE AGENT、USE CATALOG）。对于这些语法，请直接查阅 CC Flink SQL 参考，不要期待这里会有相关陷阱条目。

不可妥协的要求

1. CC Flink ≠ Apache Flink。 请对照以下资料验证每个 API、SQL 语法和运行时行为：
   • Confluent Cloud Flink 文档
   • CC Flink SQL 参考
   • Confluent Terraform 提供程序
   • 在用户的计算池上运行实时 confluent flink shell
2. 验证时不得使用模拟。 集成声明必须通过真实的 confluent CLI 运行来验证。单元测试可以使用模拟，但任何称为“端到端验证”的测试都不可以。
3. 将决策记录在持久位置。 编写任何新文件前，先询问用户希望在哪里跟踪方言陷阱和验证记录（例如项目中的 docs/flink-dialect-traps.md）；不要假设项目采用 docs/ 目录结构。
4. 仓库中绝不能包含密钥。 CREATE CONNECTION 参数必须通过 Terraform 注入，绝不能硬编码。从第一天起就将 .tfvars、.tfstate*、*.secret* 加入 Git 忽略列表。
5. 先 EXPLAIN，再 CREATE。 执行 statement create 前，始终先对查询运行 EXPLAIN，以便在不消耗 CFU 的情况下捕获解析或类型错误。
6. 不要编造标识符。 对于尚未验证的任何主题、表、语句或资源名称，请使用 <placeholder>。

参考文件

仅在主题相关时按需加载，不要一开始就全部读取：

文件	加载时机
references/dialect-traps.md	编写任何 Flink SQL 之前——包含 22 个 CC 与 OSS 的陷阱，是唯一可信来源
references/cli-reference.md	运行 confluent CLI 之前——标志参数格式、续接操作步骤、时序、令牌过期
references/sql-patterns-cc.md	编写 SQL 时——经 CC 验证的模式：窗口、联接、去重、MATCH_RECOGNIZE、JSON、外部表
references/formats-and-serialization.md	配置表格式时——7 种受支持的格式、id 编码、消费标志
references/troubleshooting-cc.md	排查错误时——CC 专属错误、原因与修复方法
references/reserved-words.md	遇到解析错误时——必须使用反引号括起的标识符

危险信号

如果发现自己写了以下任何内容，请停下来并查阅 references/dialect-traps.md：

• DataStream API（Java/Scala）——CC 不支持。Java 中的 Table API + PTF 已正式发布；Python Table API 处于公开预览阶段，尚不支持 PTF
• CREATE CATALOG ... ——catalog = CC 环境，不能创建
• SET 'execution.checkpointing.*' ——由 CC 管理，不能设置
• CREATE TABLE ... WITH ('connector' = 'kafka', ...) ——表会自动映射到主题
• 'value.format' = 'json' ——必须使用 'json-registry'（或其他基于 SR 的格式）
• WITH cte AS (...) INSERT INTO ... ——CC 要求将 CTE 放在 INSERT INTO 之后
• GROUP BY TUMBLE(ts, INTERVAL ...) ——必须使用 TVF 形式：TUMBLE(TABLE t, DESCRIPTOR(ts), ...)
• LATERAL TABLE(UNNEST(...)) ——会导致解析错误；请使用 CROSS JOIN UNNEST(...)
• PROCTIME() ——不支持；请使用 External Tables/KEY_SEARCH_AGG 或事件时间时态联接（避免与 upsert-kafka 主题进行常规联接——它会在状态中保留整张表）
• CREATE FUNCTION f AS '...' 不带 USING JAR ——CC UDF 必须使用已上传的制品
• Savepoint / STOP WITH SAVEPOINT ——CC 不提供
• --sql-file 标志 ——不存在；请使用 --sql "$(cat file.sql)"
• DROP TABLE ——在 CC 上会删除物理 Kafka 主题及其中的数据，而不仅是元数据；运行前请确认

验证循环

验证任何 CC Flink SQL 声明的规范流程：

0. 在 flink shell 中对查询执行 EXPLAIN ——可免费发现语法和类型错误。
1. 编写一个最小复现用例。
2. 在运行任何会创建或修改实际资源的操作之前，展示执行计划并等待用户明确确认。说明：语句名称和 SQL、目标计算池/数据库/环境，以及所有副作用（DDL 会创建 Kafka 主题和 Schema Registry 主体；每次运行都会消耗 CFU）。未获准前，不要进入第 3 步。
3. 运行：confluent flink statement create <name> --sql "$(cat repro.sql)" --compute-pool <id> --database <cluster> --environment <env> --wait
4. 观察结果。消费下游数据：confluent kafka topic consume <topic> --cluster <id> --from-beginning --value-format <matching-format> 2>/dev/null | grep -v '^%' ——将 <matching-format> 与 sink 的 value.format 匹配（参见 references/formats-and-serialization.md；json-registry 对应 jsonschema，avro-registry 对应 avro，proto-registry 对应 protobuf，raw 对应 string）
5. 记录命令和输出，供日后参考。

需要升级处理的状态（不得默默采用替代方案）：

• 语句处于 PENDING 状态超过 60 秒 → confluent flink statement exception list <name> --cloud <provider> --region <region>
• UDF 部署提示“jar not found” → confluent flink artifact list --cloud <provider> --region <region>
• 架构不匹配 → DESCRIBE <table>，并与生产者架构进行差异比较
• 出站流量被拒绝 → 检查 CREATE CONNECTION + USING CONNECTIONS 子句

完整的标志架构和时间预期请参阅 references/cli-reference.md。

反模式

• 将 Apache Flink 文档或标记为 apache-flink 的 Stack Overflow 答案作为 CC 权威依据
• 未经 CC 验证就使用 LLM 记忆中的“Flink SQL 语法”
• 在声称端到端验证的内容中模拟 confluent CLI
• 首次运行根模块时使用 terraform apply -auto-approve
• 提交 .tfvars、.tfstate*、.terraform/、*.secret*
• 忽略 Flink 语句异常——应明确报错；查看 statement exception list
• 在 CREATE CONNECTION 或 UDF 源代码中硬编码密钥

教程

developer.confluent.io/tutorials/#flink 混合了 OSS 和 CC 教程。

筛选规则： 仅使用前置条件中列出“Confluent Cloud”或使用 confluent flink shell 的教程。对从教程中复制的任何 SQL 应用方言陷阱表——许多教程面向 OSS Flink 或 Kafka Streams，不能直接兼容 CC。

真相来源层级

1. references/dialect-traps.md（此技能）——权威且整合的来源
2. 各项目的 CLAUDE.md——引用此技能，并补充项目特定背景
3. 各项目的陷阱记录（如果用户希望保留）——创建前先询问存放位置

如果在会话中发现新的陷阱，请告知用户，让他们决定是否将其记录到项目自己的笔记中。不要编辑此技能已安装的文件（references/dialect-traps.md 或其他文件）——提出修改建议，由用户（或向此技能的代码仓库单独提交 PR）来应用。

参考资料

• Confluent Cloud Flink 文档
• Confluent Cloud Flink SQL 参考
• Confluent Terraform Provider
• Confluent CLI 参考 — Flink
• 教程（仅筛选 CC）