> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Kafka ClickPipes の使用時に従うべきベストプラクティスについて詳しく説明します。
# ベストプラクティス
## メッセージ圧縮
Kafka トピックでは圧縮の使用を強く推奨します。圧縮を使用すると、パフォーマンスへの影響をほとんど伴わずに、データ転送コストを大幅に削減できます。
Kafka におけるメッセージ圧縮について詳しくは、まずはこちらの[ガイド](https://www.confluent.io/blog/apache-kafka-message-compression/)をご覧になることをお勧めします。
## 制限事項
* [`DEFAULT`](/ja/reference/statements/create/table#default) はサポートされていません。
* 個々のメッセージのサイズは、最小の (XS) レプリカサイズで実行する場合、デフォルトで 16MB (非圧縮) まで、より大きいレプリカでは 32MB (非圧縮) までに制限されます。この上限を超えるメッセージは、エラーとなり拒否されます。より大きなメッセージが必要な場合は、サポートにお問い合わせください。
## 配信セマンティクス
Kafka 向け ClickPipes は、デフォルトで at-least-once 配信を保証し、Kafka コンシューマグループのオフセットを使用してインジェストの進行状況を追跡します。また、ポッド の再起動、コンシューマのリバランス、挿入の失敗があっても、各 Kafka レコードが ClickHouse に正確に 1 回だけ挿入される exactly-once セマンティクスをオプションでサポートしています。
exactly-once を実現するため、ClickPipes は 2 つの値を使用して各パーティションの進行状況を内部状態ストアに記録します。
* **High-water mark** — パーティション内のすべてのレコードが ClickHouse に挿入されたことが確認されているオフセットです。再起動時、ClickPipes はこのマーク以下のレコードをすべて破棄するため、すでに到達済みのデータが再送されることはありません。
* **Pending ranges** — ClickHouse に送信済みだが、まだ確認されていない insert block のオフセット範囲です。障害発生後、ClickPipes はこれらの範囲のみを再生します。
各 insert block は連続したオフセット範囲を対象とし、`topic:partition:firstOffset-lastOffset` 形式の決定論的な[重複排除トークン](/ja/concepts/features/operations/insert/deduplicating-inserts-on-retries)を持ちます。再生時、ClickPipes は同じオフセット範囲、したがって同じトークンを再現するため、ClickHouse は重複を拒否します。トークンはオフセット範囲のみに依存するため、再構築した block がバイト単位で同一でなくても、再生時には重複排除されます。
**重複排除ウィンドウ**
トークンによる重複排除は、ターゲットテーブルの [`replicated_deduplication_window`](/ja/reference/settings/merge-tree-settings/replicated-deduplication-window#replicated_deduplication_window) (デフォルトでは直近 10,000 個の insert block) および [`replicated_deduplication_window_seconds`](/ja/reference/settings/merge-tree-settings/replicated-deduplication-window#replicated_deduplication_window_seconds) (デフォルトでは 1 時間) の範囲内でのみ行われます。高スループットのパイプでは block 数のウィンドウがすぐに消費される可能性があるため、最悪の場合の再生遅延をカバーできるよう、ターゲットテーブルでこれら両方の設定を確認し、必要に応じて増やすことを推奨します。トークンがウィンドウから外れた後に再生されたデータは再度挿入される可能性があるため、その場合は exactly-once を保証できません。
主なトレードオフはパーツサイズです。より大きな insert block を使用すると、ClickHouse 内で生成される[パーツ](/ja/concepts/core-concepts/parts)の数が減り、各パーツは大きくなるため、マージのオーバーヘッドを低く抑えられます。ClickPipes は block を構築している間、パーティションの行をメモリ内に保持するため、到達可能なパーツサイズはパイプで利用できるメモリに依存します。メモリが不足すると小さな block を構築するため、テーブルにはより多くのパーツが蓄積されます。パイプにより多くのメモリを割り当てると、より大きな block を構築でき、生成されるパーツを減らせます。
パーティション数が内部 insert「worker」の数に近い場合、各 worker はおおむね 1 つのパーティションを処理でき、大きな block を構築するための十分なメモリのヘッドルームを確保できるため、パイプは最も効率よく動作します。worker 数と利用可能なメモリはいずれもレプリカサイズとレプリカ数に応じてスケールします。これらは **Settings** -> **Advanced Settings** -> **Scaling** で設定できます。
## 認証
Apache Kafka プロトコルのデータソースでは、ClickPipes は TLS 暗号化を使用する [SASL/PLAIN](https://docs.confluent.io/platform/current/kafka/authentication_sasl/authentication_sasl_plain.html) 認証に加え、`SASL/SCRAM-SHA-256` および `SASL/SCRAM-SHA-512` もサポートしています。ストリーミングソース (Redpanda、MSK など) によっては、互換性に応じて、これらの認証メカニズムのすべて、または一部のみが利用可能です。必要な認証方式が異なる場合は、[ぜひフィードバックをお寄せください](https://clickhouse.com/company/contact?loc=clickpipes)。
## Warpstream フェッチサイズ
ClickPipes では、一度に 1 つの ClickPipes ノードで処理されるデータ量を制限するために、Kafka の設定 `max.fetch_bytes` を使用します。一部の状況では、
Warpstream がこの設定に従わないことがあり、その結果、予期しないパイプ障害が発生する可能性があります。ClickPipes の障害を防ぐため、WarpStream エージェントを設定する際は、Warpstream 固有の設定 `kafkaMaxFetchPartitionBytesUncompressedOverride`
を 8MB (またはそれ以下) に設定することを強く推奨します。
### IAM
ClickPipes は、AWS MSK の以下の認証方式をサポートしています。
* [SASL/SCRAM-SHA-512](https://docs.aws.amazon.com/msk/latest/developerguide/msk-password.html) 認証
* [IAM 認証情報またはロールベースのアクセス](https://docs.aws.amazon.com/msk/latest/developerguide/how-to-use-iam-access-control.html) 認証
IAM 認証を使用して MSK ブローカーに接続する場合、IAM ロールには必要な権限が付与されている必要があります。
以下は、MSK の Apache Kafka API に必要な IAM ポリシーの例です。
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kafka-cluster:Connect"
],
"Resource": [
"arn:aws:kafka:us-west-2:12345678912:cluster/clickpipes-testing-brokers/b194d5ae-5013-4b5b-ad27-3ca9f56299c9-10"
]
},
{
"Effect": "Allow",
"Action": [
"kafka-cluster:DescribeTopic",
"kafka-cluster:ReadData"
],
"Resource": [
"arn:aws:kafka:us-west-2:12345678912:topic/clickpipes-testing-brokers/*"
]
},
{
"Effect": "Allow",
"Action": [
"kafka-cluster:AlterGroup",
"kafka-cluster:DescribeGroup"
],
"Resource": [
"arn:aws:kafka:us-east-1:12345678912:group/clickpipes-testing-brokers/*"
]
}
]
}
```
#### 信頼関係の設定
IAM ロール ARN を使用して MSK に認証する場合は、ロールを引き受けられるように、ClickHouse Cloud インスタンスとの信頼関係を追加する必要があります。
ロールベースのアクセスは、AWS にデプロイされた ClickHouse Cloud インスタンスでのみ機能します。
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
...
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::12345678912:role/CH-S3-your-clickhouse-cloud-role"
},
"Action": "sts:AssumeRole"
}
]
}
```
### カスタム証明書
Kafka 向け ClickPipes では、公開されていないサーバー証明書を使用する Kafka ブローカー向けに、カスタム証明書をアップロードできます。
相互 TLS (mTLS) ベースの認証では、クライアント証明書と秘密鍵のアップロードにも対応しています。
## パフォーマンス
### バッチ処理
ClickPipes はデータをバッチ単位で ClickHouse に挿入します。これは、データベース内に過剰なパーツが作成されるのを防ぐためです。パーツが増えすぎると、クラスターのパフォーマンス低下につながる可能性があります。
バッチは、次のいずれかの条件を満たすと挿入されます。
* バッチサイズが上限に達した場合 (100,000行、またはポッドメモリ 1GB あたり 28MB)
* バッチの保持時間が上限に達した場合 (5秒)
### レイテンシー
レイテンシー (Kafka メッセージが生成されてから、そのメッセージを ClickHouse で利用できるようになるまでの時間) は、さまざまな要因 (例: ブローカーのレイテンシー、ネットワークレイテンシー、メッセージのサイズ/フォーマット) に左右されます。上のセクションで説明した[バッチ処理](#batching)も、レイテンシーに影響します。想定されるレイテンシーを把握するため、通常の負荷条件でご自身のユースケースを必ずテストすることをお勧めします。
ClickPipes は、レイテンシーについて一切保証していません。低レイテンシーに関する特別な要件がある場合は、[お問い合わせください](https://clickhouse.com/company/contact?loc=clickpipes)。
### スケーリング
Kafka 向け ClickPipes は、水平および垂直の両方向にスケールできるよう設計されています。デフォルトでは、1 つのコンシューマーを含むコンシューマグループが作成されます。これは ClickPipe の作成時、またはそれ以外の任意のタイミングで **Settings** -> **Advanced Settings** -> **Scaling** から設定できます。
ClickPipes は、可用性ゾーンに分散したアーキテクチャにより高可用性を実現しています。
そのためには、少なくとも 2 つのコンシューマーまでスケールする必要があります。
実行中のコンシューマー数にかかわらず、耐障害性は設計上確保されています。
コンシューマーまたはその基盤となるインフラストラクチャに障害が発生した場合でも、
ClickPipe は自動的にコンシューマーを再起動し、メッセージ処理を継続します。
### ベンチマーク
以下は、Kafka 向け ClickPipes のおおよそのベースライン性能を把握するための参考用ベンチマークです。パフォーマンスは、メッセージサイズ、データ型、データフォーマットなど、さまざまな要因の影響を受ける点にご注意ください。実際の結果は環境によって異なる可能性があり、ここで示す内容は実際の性能を保証するものではありません。
ベンチマークの詳細:
* ClickHouse 側の insert 処理がスループットのボトルネックにならないよう、十分なリソースを備えた本番用の ClickHouse Cloud サービスを使用しました。
* ClickHouse Cloud サービス、Kafka クラスター (Confluent Cloud) 、ClickPipe は、いずれも同じリージョン (`us-east-2`) で稼働していました。
* ClickPipe は、L サイズの単一レプリカ (4 GiB の RAM と 1 vCPU) で構成しました。
* サンプルデータには、`UUID`、`String`、`Int` のデータ型が混在するネストされたデータが含まれていました。`Float`、`Decimal`、`DateTime` などの他のデータ型では、パフォーマンスが低下する可能性があります。
* 圧縮データと非圧縮データで、顕著な性能差は見られませんでした。
| レプリカサイズ | メッセージサイズ | データフォーマット | スループット |
| --------- | -------- | --------- | ------ |
| Large (L) | 1.6kb | JSON | 63mb/s |
| Large (L) | 1.6kb | Avro | 99mb/s |