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. CREATE の前に EXPLAIN を実行してください。 statement create の前に必ずクエリを EXPLAIN してください。CFU を消費することなく、構文エラーや型エラーを検出できます。
6. 識別子をでっち上げないでください。 トピック名、テーブル名、ステートメント名、リソース名のうち、未確認のものには <placeholder> を使用してください。

参考ファイル

トピックに該当する場合に、以下を必要に応じて読み込んでください。一度にすべて読まないでください。

ファイル	読み込むタイミング
references/dialect-traps.md	Flink SQL を書く前。CC と OSS の 22 個の落とし穴をまとめた唯一の信頼できる情報源です
references/cli-reference.md	confluent CLI を実行する前。フラグの形式、引き継ぎ手順、タイミング、トークンの有効期限を確認します
references/sql-patterns-cc.md	SQL を書くとき。CC で検証済みのパターン（ウィンドウ、結合、重複排除、MATCH_RECOGNIZE、JSON、External Tables）を確認します
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 ではサポートされていません。Table API と PTF は Java で GA です。Python Table API は Open Preview で、PTF はまだ利用できません
• CREATE 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() — サポートされていません。外部テーブル／KEY_SEARCH_AGG またはイベント時刻のテンポラル結合を使用してください（upsert-kafka トピックに対する通常の結合は避けてください。テーブル全体が状態に保持されます）
• USING JAR を指定しない CREATE FUNCTION f AS '...' — 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> はシンクの 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 を参照してください。

アンチパターン

• CC の根拠として、Apache Flink のドキュメントや apache-flink タグ付きの Stack Overflow の回答を引用する
• 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 プロバイダー
• Confluent CLI リファレンス — Flink
• チュートリアル（CC のみで絞り込み）