> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # ClickStack - パフォーマンスチューニング > ClickStack のパフォーマンスチューニング - ClickHouse オブザーバビリティスタック export const Image = ({img, alt, size}) => { return {alt} ; }; export const galaxyOnClick = eventName => () => { try { if (typeof window !== "undefined" && window.galaxy && eventName) { window.galaxy.track(eventName, { interaction: "click" }); } } catch (e) {} }; export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => { if (link) { return Beta ; } return
Beta feature.  Learn more.
; };
## はじめに
このガイドでは、ClickStack における最も一般的で効果的なパフォーマンス最適化に焦点を当てます。これらは、実環境における大半のオブザーバビリティ ワークロードを最適化するのに十分であり、通常は 1 日あたり数十テラバイト規模までのデータ量に対応できます。 最適化は、最も簡単で効果の大きい手法から始めて、より高度で専門的なチューニングへ進むよう、意図した順序で紹介しています。まずは前半の最適化から適用してください。それだけでも大幅な改善が得られることがよくあります。データ量が増え、ワークロードの要求が厳しくなるにつれて、後半の手法を検討する価値はますます高まります。
## ClickHouse の概念
このガイドで説明する最適化を適用する前に、ClickHouse のいくつかの基本的な概念を理解しておくことが重要です。 ClickStack では、各**データソースは 1 つ以上の ClickHouse テーブルに直接対応**します。OpenTelemetry を使用している場合、ClickStack は logs、traces、metrics データを格納する一連のデフォルトテーブルを作成し、管理します。カスタムスキーマを使用していたり、独自のテーブルを管理していたりする場合は、これらの概念にすでに馴染みがあるかもしれません。一方、単に OpenTelemetry Collector 経由でデータを送信しているだけであれば、これらのテーブルは自動的に作成され、以下で説明するすべての最適化はこれらのテーブルに対して適用されます。 | Data type | Table | | -------------------------------- | --------------------------------------------------------------------------------------------------- | | Logs | [otel\_logs](/ja/clickstack/ingesting-data/schemas#logs) | | Traces | [otel\_traces](/ja/clickstack/ingesting-data/schemas#traces) | | Metrics (gauges) | [otel\_metrics\_gauge](/ja/clickstack/ingesting-data/schemas#gauge) | | Metrics (sums) | [otel\_metrics\_sum](/ja/clickstack/ingesting-data/schemas#sum) | | Metrics (histogram) | [otel\_metrics\_histogram](/ja/clickstack/ingesting-data/schemas#histogram) | | Metrics (Exponential histograms) | [otel\_metrics\_exponentialhistogram](/ja/clickstack/ingesting-data/schemas#exponential-histograms) | | Metrics (summary) | [otel\_metrics\_summary](/ja/clickstack/ingesting-data/schemas#summary-table) | | Sessions | [hyperdx\_sessions](/ja/clickstack/ingesting-data/schemas#sessions) | ClickHouse では、テーブルは[データベース](/ja/reference/statements/create/database)に属します。デフォルトでは `default` データベースが使用されますが、これは [OpenTelemetry collector で変更できます](/ja/clickstack/managing/config#otel-collector)。 **logs と traces に注目** ほとんどの場合、パフォーマンスチューニングの対象となるのは logs テーブルと traces テーブルです。metrics テーブルもフィルタリング向けに最適化できますが、そのスキーマは Prometheus スタイルのワークロード向けに意図的に設計されており、通常は標準的なチャート表示のために変更する必要はありません。一方、logs と traces はより幅広いアクセスパターンをサポートするため、チューニングの効果が最も得られやすい対象です。session データはユーザー体験が固定されているため、スキーマを変更する必要はほとんどありません。 最低限、次の ClickHouse の基本事項を理解しておく必要があります。 | Concept | Description | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tables** | ClickStack のデータソースが、基盤となる ClickHouse テーブルにどのように対応しているか。ClickHouse のテーブルでは主に [MergeTree](/ja/reference/engines/table-engines/mergetree-family/mergetree) エンジンが使用されます。 | | **Parts** | データが不変のパーツとしてどのように書き込まれ、時間の経過とともにどのようにマージされるか。 | | **Partitions** | パーティションは、テーブルのデータパーツを整理された論理単位にグループ化します。これにより、管理、クエリ、最適化がしやすくなります。 | | **Merges** | クエリ対象となるパーツ数を減らすために、パーツ同士をマージする内部プロセス。クエリ性能を維持するうえで不可欠です。 | | **グラニュール** | ClickHouse がクエリ実行時に読み取りや pruning を行う最小のデータ単位。 | | **Primary (ordering) keys** | `ORDER BY` キーが、ディスク上のデータ配置、圧縮、クエリ pruning にどのように影響するか。 | これらの概念は、ClickHouse のパフォーマンスの中核を成します。データがどのように書き込まれるか、ディスク上でどのように構成されるか、そしてクエリ時に ClickHouse がどれだけ効率的に不要なデータの読み取りをスキップできるかは、これらによって決まります。このガイドで扱うあらゆる最適化、たとえば マテリアライズドカラム、スキップ索引、主キー、projections、materialized view は、こうした基本的な仕組みの上に成り立っています。 チューニングを始める前に、以下の ClickHouse ドキュメントを確認しておくことをお勧めします。 * [ClickHouse でのテーブル作成](/ja/get-started/quickstarts/creating-tables) - テーブルの簡単な入門です。 * [Parts](/ja/concepts/core-concepts/parts) * [Partitions](/ja/concepts/core-concepts/partitions) * [Merges](/ja/concepts/core-concepts/merges) * [主キー/索引](/ja/concepts/core-concepts/primary-indexes) * [ClickHouse がデータを保存する方法: parts と グラニュール](/ja/guides/clickhouse/data-modelling/sparse-primary-indexes) - ClickHouse でデータがどのように構成され、どのようにクエリされるかを詳しく説明した、より高度なガイドです。グラニュール と主キーも詳しく扱っています。 * [MergeTree](/ja/reference/engines/table-engines/mergetree-family/mergetree)- コマンドや内部仕様の理解に役立つ高度な MergeTree リファレンスガイドです。 以下で説明する最適化はすべて、標準のClickHouse SQLを使って、[ClickHouse Cloud SQL Console](/ja/integrations/connectors/sql-clients/sql-console)または [clickhouse client](/ja/concepts/features/interfaces/cli) から基になるテーブルに直接適用できます。
## 最適化 1. 頻繁にクエリされる属性をマテリアライズする
ClickStack ユーザーにとって、最初に行うべき最もシンプルな最適化は、`LogAttributes`、`ScopeAttributes`、`ResourceAttributes` 内で頻繁にクエリされる属性を特定し、マテリアライズドカラムを使ってそれらをトップレベルのカラムに昇格させることです。 この最適化だけでも、ClickStack のデプロイメントを 1 日あたり数十テラバイト規模までスケールさせるのに十分な場合が多く、より高度なチューニング手法を検討する前に適用すべきです。
### 属性をマテリアライズする理由
ClickStack は、Kubernetes のラベル、サービスのメタデータ、カスタム属性などのメタデータを `Map(String, String)` カラムに格納します。これは柔軟性が高い一方で、マップのサブキーをクエリする際にはパフォーマンス上の重要な影響があります。 Map カラムから単一のキーをクエリする場合、ClickHouse はディスクからマップカラム全体を読み込む必要があります。マップに多数のキーが含まれていると、専用のカラムを読み込む場合に比べて不要な IO が発生し、クエリも遅くなります。 頻繁にアクセスされる属性をマテリアライズすると、挿入時に値を抽出して独立したカラムとして保存できるため、このオーバーヘッドを回避できます。 マテリアライズドカラムの特長: * 挿入時に自動的に計算される * INSERT ステートメントで明示的に設定できない * 任意の ClickHouse 式をサポートする * String から、より効率的な数値型や日付型へ型変換できる * スキップ索引と主キーを利用できる * マップ全体へのアクセスを避けることでディスク読み取りを削減できる ClickStack は、マップから抽出されたマテリアライズドカラムを自動的に検出し、ユーザーが元の属性パスを引き続きクエリしている場合でも、クエリ実行時に透過的にそれらを使用します。
### 例
Kubernetes のメタデータが `ResourceAttributes` に格納される、トレース向けのデフォルトの ClickStack スキーマを見てみましょう。 ```sql theme={null} CREATE TABLE IF NOT EXISTS otel_traces ( `Timestamp` DateTime64(9) CODEC(Delta(8), ZSTD(1)), `TraceId` String CODEC(ZSTD(1)), `SpanId` String CODEC(ZSTD(1)), `ParentSpanId` String CODEC(ZSTD(1)), `TraceState` String CODEC(ZSTD(1)), `SpanName` LowCardinality(String) CODEC(ZSTD(1)), `SpanKind` LowCardinality(String) CODEC(ZSTD(1)), `ServiceName` LowCardinality(String) CODEC(ZSTD(1)), `ResourceAttributes` Map(LowCardinality(String), String) CODEC(ZSTD(1)), `ScopeName` String CODEC(ZSTD(1)), `ScopeVersion` String CODEC(ZSTD(1)), `SpanAttributes` Map(LowCardinality(String), String) CODEC(ZSTD(1)), `Duration` UInt64 CODEC(ZSTD(1)), `StatusCode` LowCardinality(String) CODEC(ZSTD(1)), `StatusMessage` String CODEC(ZSTD(1)), `Events.Timestamp` Array(DateTime64(9)) CODEC(ZSTD(1)), `Events.Name` Array(LowCardinality(String)) CODEC(ZSTD(1)), `Events.Attributes` Array(Map(LowCardinality(String), String)) CODEC(ZSTD(1)), `Links.TraceId` Array(String) CODEC(ZSTD(1)), `Links.SpanId` Array(String) CODEC(ZSTD(1)), `Links.TraceState` Array(String) CODEC(ZSTD(1)), `Links.Attributes` Array(Map(LowCardinality(String), String)) CODEC(ZSTD(1)), `__hdx_materialized_rum.sessionId` String MATERIALIZED ResourceAttributes['rum.sessionId'] CODEC(ZSTD(1)), INDEX idx_trace_id TraceId TYPE bloom_filter(0.001) GRANULARITY 1, INDEX idx_rum_session_id __hdx_materialized_rum.sessionId TYPE bloom_filter(0.001) GRANULARITY 1, INDEX idx_res_attr_key mapKeys(ResourceAttributes) TYPE bloom_filter(0.01) GRANULARITY 1, INDEX idx_res_attr_value mapValues(ResourceAttributes) TYPE bloom_filter(0.01) GRANULARITY 1, INDEX idx_span_attr_key mapKeys(SpanAttributes) TYPE bloom_filter(0.01) GRANULARITY 1, INDEX idx_span_attr_value mapValues(SpanAttributes) TYPE bloom_filter(0.01) GRANULARITY 1, INDEX idx_duration Duration TYPE minmax GRANULARITY 1, INDEX idx_lower_span_name lower(SpanName) TYPE tokenbf_v1(32768, 3, 0) GRANULARITY 8 ) ENGINE = MergeTree PARTITION BY toDate(Timestamp) ORDER BY (ServiceName, SpanName, toDateTime(Timestamp)) TTL toDate(Timestamp) + toIntervalDay(30) SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1; ``` ユーザーは、Lucene構文を使ってトレースを絞り込めます。たとえば、`ResourceAttributes.k8s.pod.name:"checkout-675775c4cc-f2p9c"` のように指定します。 トレースのフィルタリング その結果、次のようなSQL述語になります。 ```sql theme={null} ResourceAttributes['k8s.pod.name'] = 'checkout-675775c4cc-f2p9c' ``` これは Map のキーにアクセスするため、ClickHouse は一致した各行について `ResourceAttributes` カラム全体を読み取る必要があります。Map に多くのキーが含まれている場合、このカラムは非常に大きくなる可能性があります。 この属性を頻繁にクエリする場合は、トップレベルのカラムとしてマテリアライズする必要があります。 挿入時にポッド名を抽出するには、マテリアライズドカラムを追加します: ```sql theme={null} ALTER TABLE otel_v2.otel_traces ADD COLUMN PodName String MATERIALIZED ResourceAttributes['k8s.pod.name'] ``` この時点以降、**新しい**データでは、ポッド名が専用のカラム `PodName` として保存されます。 これにより、ユーザーは Lucene 構文を使ってポッド名を効率よくクエリできるようになります。たとえば `PodName:"checkout-675775c4cc-f2p9c"` のように指定できます。 トレースのフィルタリング v2 新たに挿入されるデータでは、これにより map へのアクセスが不要になり、I/O も大幅に削減されます。 ただし、ユーザーが元の属性パス、たとえば `ResourceAttributes.k8s.pod.name:"checkout-675775c4cc-f2p9c"` に対して引き続きクエリを実行する場合でも、**ClickStack は内部的にクエリを自動的に書き換え**、マテリアライズされた `PodName` カラムを使用します。つまり、次の条件を使用します。 ```sql theme={null} PodName = 'checkout-675775c4cc-f2p9c' ``` これにより、ダッシュボード、アラート、保存済みクエリを変更しなくても、この最適化の恩恵を受けることができます。 デフォルトでは、マテリアライズドカラムは`SELECT * クエリ`の対象から除外されます。これにより、クエリ結果を常にテーブルへ再挿入できるという不変条件が保たれます。
### 過去データのマテリアライズ
マテリアライズドカラムが自動的に適用されるのは、そのカラムの作成後に挿入されたデータだけです。既存データについては、マテリアライズドカラムに対するクエリは透過的に元の Map の読み取りにフォールバックします。 過去データのパフォーマンスが重要な場合は、ミューテーションを使ってカラムをバックフィルできます。例: ```sql theme={null} ALTER TABLE otel_v2.otel_traces MATERIALIZE COLUMN PodName ``` これにより、既存の[パーツ](/ja/concepts/core-concepts/parts)が書き換えられ、カラムに値が設定されます。ミューテーションはパーツごとに単一スレッドで実行されるため、大規模なデータセットでは完了までに時間がかかることがあります。影響を抑えるため、ミューテーションの対象を特定のパーティションに限定できます: ```sql theme={null} ALTER TABLE otel_v2.otel_traces MATERIALIZE COLUMN PodName IN PARTITION '2026-01-02' ``` ミューテーションの進行状況は、たとえば `system.mutations` テーブルで確認できます。 ```sql theme={null} SELECT * FROM system.mutations WHERE database = 'otel' AND table = 'otel_traces' ORDER BY create_time DESC; ``` 対応するミューテーションの `is_done = 1` になるまで待機します。 ミューテーションでは追加の IO と CPU オーバーヘッドが発生するため、使用は必要最小限にとどめるべきです。多くの場合、古いデータは自然に期限切れになるままにしておき、新しく取り込まれたデータで得られるパフォーマンス向上を利用するだけで十分です。
## 最適化 2. スキップ索引の追加
頻繁にクエリされる属性をマテリアライズしたら、次の最適化として、クエリ実行時に ClickHouse が読み込むデータ量をさらに減らすためにデータスキッピングインデックスを追加します。 スキップ索引を使うと、一致する値が存在しないと判断できる場合に、ClickHouse はデータブロック全体のスキャンを回避できます。従来のセカンダリ索引とは異なり、スキップ索引は granule レベルで機能し、クエリフィルターによってデータセットの大部分が除外される場合に特に効果を発揮します。適切に使えば、クエリの意味を変えることなく、カーディナリティの高い属性に対するフィルタリングを大幅に高速化できます。 スキップ索引を含む ClickStack のデフォルトの traces スキーマを見てみましょう。 ```sql theme={null} CREATE TABLE IF NOT EXISTS otel_traces ( `Timestamp` DateTime64(9) CODEC(Delta(8), ZSTD(1)), `TraceId` String CODEC(ZSTD(1)), `SpanId` String CODEC(ZSTD(1)), `ParentSpanId` String CODEC(ZSTD(1)), `TraceState` String CODEC(ZSTD(1)), `SpanName` LowCardinality(String) CODEC(ZSTD(1)), `SpanKind` LowCardinality(String) CODEC(ZSTD(1)), `ServiceName` LowCardinality(String) CODEC(ZSTD(1)), `ResourceAttributes` Map(LowCardinality(String), String) CODEC(ZSTD(1)), `ScopeName` String CODEC(ZSTD(1)), `ScopeVersion` String CODEC(ZSTD(1)), `SpanAttributes` Map(LowCardinality(String), String) CODEC(ZSTD(1)), `Duration` UInt64 CODEC(ZSTD(1)), `StatusCode` LowCardinality(String) CODEC(ZSTD(1)), `StatusMessage` String CODEC(ZSTD(1)), `Events.Timestamp` Array(DateTime64(9)) CODEC(ZSTD(1)), `Events.Name` Array(LowCardinality(String)) CODEC(ZSTD(1)), `Events.Attributes` Array(Map(LowCardinality(String), String)) CODEC(ZSTD(1)), `Links.TraceId` Array(String) CODEC(ZSTD(1)), `Links.SpanId` Array(String) CODEC(ZSTD(1)), `Links.TraceState` Array(String) CODEC(ZSTD(1)), `Links.Attributes` Array(Map(LowCardinality(String), String)) CODEC(ZSTD(1)), `__hdx_materialized_rum.sessionId` String MATERIALIZED ResourceAttributes['rum.sessionId'] CODEC(ZSTD(1)), INDEX idx_trace_id TraceId TYPE bloom_filter(0.001) GRANULARITY 1, INDEX idx_rum_session_id __hdx_materialized_rum.sessionId TYPE bloom_filter(0.001) GRANULARITY 1, INDEX idx_res_attr_key mapKeys(ResourceAttributes) TYPE bloom_filter(0.01) GRANULARITY 1, INDEX idx_res_attr_value mapValues(ResourceAttributes) TYPE bloom_filter(0.01) GRANULARITY 1, INDEX idx_span_attr_key mapKeys(SpanAttributes) TYPE bloom_filter(0.01) GRANULARITY 1, INDEX idx_span_attr_value mapValues(SpanAttributes) TYPE bloom_filter(0.01) GRANULARITY 1, INDEX idx_duration Duration TYPE minmax GRANULARITY 1, INDEX idx_lower_span_name lower(SpanName) TYPE tokenbf_v1(32768, 3, 0) GRANULARITY 8 ) ENGINE = MergeTree PARTITION BY toDate(Timestamp) ORDER BY (ServiceName, SpanName, toDateTime(Timestamp)) TTL toDate(Timestamp) + toIntervalDay(30) SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1; ``` これらの索引は、よくある次の 2 つのパターンに対応しています。 * TraceId、セッション識別子、attribute キー、値など、カーディナリティの高い文字列のフィルタリング * スパンの所要時間など、数値範囲のフィルタリング
### ブルームフィルタ
ブルームフィルタ索引は、ClickStack で最もよく使われるスキップ索引タイプです。高いカーディナリティを持つ文字列カラムに適しており、一般的には少なくとも数万件の異なる値がある場合に有効です。偽陽性率 0.01、グラニュラリティ 1 は、ストレージオーバーヘッドと効果的な絞り込みのバランスが取れた、適切なデフォルトの出発点です。 Optimization 1 の例を続けると、Kubernetes のポッド名が ResourceAttributes からマテリアライズされているとします: ```sql theme={null} ALTER TABLE otel_traces ADD COLUMN PodName String MATERIALIZED ResourceAttributes['k8s.pod.name'] ``` 次に、このカラムに対するフィルタを高速化するために、ブルームフィルタのスキップ索引を追加できます。 ```sql theme={null} ALTER TABLE otel_traces ADD INDEX idx_pod_name PodName TYPE bloom_filter(0.01) GRANULARITY 1 ``` 追加したら、スキップ索引は実体化する必要があります。詳細は["スキップ索引を実体化する"](#materialize-skip-index)を参照してください。 作成して実体化すると、ClickHouse は要求されたポッド名を含まないことが確実なグラニュール全体をスキップできるようになり、`PodName:"checkout-675775c4cc-f2p9c"` のようなクエリで読み取るデータ量を削減できる可能性があります。 ブルームフィルタが最も効果を発揮するのは、特定の値が比較的少数のパーツにしか現れないような値の分布になっている場合です。これは、ポッド名、トレースID、セッション識別子のようなメタデータが時間と相関し、その結果、テーブルの順序キーに沿ってクラスター化されるオブザーバビリティのワークロードで自然によく見られます。 すべてのスキップ索引と同様に、ブルームフィルタも選択的に追加し、実際のクエリパターンに対して検証して、測定可能な効果が得られることを確認する必要があります。詳細は["スキップ索引の有効性を評価する"](#evaluating-skip-index-effectiveness)を参照してください。
### Min-max 索引
Minmax 索引は、グラニュールごとに最小値と最大値を格納する、非常に軽量な索引です。特に数値カラムや範囲クエリに効果的です。すべてのクエリを高速化できるわけではありませんが、低コストで、数値フィールドにはほとんどの場合追加する価値があります。 Minmax 索引が最も効果を発揮するのは、数値が自然に順序付けられている場合、または各パート内で狭い範囲に収まっている場合です。 たとえば、`SpanAttributes` 内の Kafka オフセットが頻繁にクエリされるとします。 ```sql theme={null} SpanAttributes['messaging.kafka.offset'] ``` この値はマテリアライズし、数値型にCASTできます： ```sql theme={null} ALTER TABLE otel_traces ADD COLUMN KafkaOffset UInt64 MATERIALIZED toUInt64(SpanAttributes['messaging.kafka.offset']) ``` minmax索引は次のように追加できます: ```sql theme={null} ALTER TABLE otel_traces ADD INDEX idx_kafka_offset KafkaOffset TYPE minmax GRANULARITY 1 ``` これにより、たとえばコンシューマラグやリプレイ動作のデバッグ時に、Kafka のオフセット範囲でフィルタリングする際、ClickHouse はパーツを効率よくスキップできるようになります。 繰り返しになりますが、索引を利用できるようになる前に、[マテリアライズ](#materialize-skip-index)しておく必要があります。
### スキップ索引をマテリアライズする
スキップ索引は、追加しただけでは新たに取り込まれるデータにしか適用されません。過去のデータは、明示的にマテリアライズするまでその索引の恩恵を受けません。 たとえば、すでにスキップ索引を追加している場合： ```sql theme={null} ALTER TABLE otel_traces ADD INDEX idx_kafka_offset KafkaOffset TYPE minmax GRANULARITY 1; ``` 既存データに対しては、索引を明示的に作成する必要があります： ```sql theme={null} ALTER TABLE otel_traces MATERIALIZE INDEX idx_kafka_offset; ``` **スキップ索引のマテリアライズ** スキップ索引のマテリアライズは、通常は軽量で安全に実行できます。特に minmax 索引ではその傾向が顕著です。大規模なデータセットに対する ブルームフィルタ 索引では、リソース使用量をより適切に制御するため、パーティション単位でマテリアライズするほうがよい場合があります。例: ```sql theme={null} ALTER TABLE otel_v2.otel_traces MATERIALIZE INDEX idx_kafka_offset IN PARTITION '2026-01-02'; ``` スキップ索引のマテリアライズはミューテーションとして実行されます。進行状況はシステムテーブルで確認できます。 ```sql theme={null} SELECT * FROM system.mutations WHERE database = 'otel' AND table = 'otel_traces' ORDER BY create_time DESC; ``` 該当するミューテーションが `is_done = 1` になるまで待ちます。 完了したら、索引データが作成されていることを確認します。 ```sql theme={null} SELECT database, table, name, data_compressed_bytes, data_uncompressed_bytes, marks_bytes FROM system.data_skipping_indices WHERE database = 'otel' AND table = 'otel_traces' AND name = 'idx_kafka_offset'; ``` ゼロ以外の値は、索引が正常にマテリアライズされたことを示します。 重要なのは、スキップ索引のサイズがクエリ性能に直接影響するという点です。数十 GB から数百 GB 級の非常に大きなスキップ索引は、クエリ実行時の評価に無視できない時間がかかることがあり、その結果、利点が薄れたり、場合によっては利点そのものがなくなったりすることさえあります。 実際には、minmax 索引は通常きわめて小さく、評価コストも低いため、ほとんどの場合は安心してマテリアライズできます。一方、ブルームフィルタ 索引は、カーディナリティ、粒度、偽陽性確率によっては大きく増える可能性があります。 ブルームフィルタ のサイズは、許容する偽陽性率を高くすることで小さくできます。たとえば、確率パラメータを `0.01` から `0.05` に引き上げると、より小さく、より高速に評価できる索引になりますが、その代わりプルーニングの効果は弱まります。スキップできるグラニュールは少なくなる可能性がありますが、索引評価が速くなることで、クエリ全体のレイテンシが改善する場合があります。 したがって、ブルームフィルタ パラメータの調整はワークロード依存の最適化であり、実際のクエリパターンと本番環境に近いデータ量で検証する必要があります。 スキップ索引の詳細については、ガイド ["ClickHouse のデータスキッピングインデックスを理解する"](/ja/concepts/features/performance/skip-indexes/skipping-indexes-examples) を参照してください。
### スキップ索引の有効性を評価する
スキップ索引のプルーニングを評価する最も確実な方法は、`EXPLAIN indexes = 1` を使用することです。これにより、クエリプランの各段階で、どれだけの [パーツ](/ja/concepts/core-concepts/parts) と [グラニュール](/ja/guides/clickhouse/data-modelling/sparse-primary-indexes#data-is-organized-into-granules-for-parallel-data-processing) が除外されるかを確認できます。多くの場合、主キーによって検索範囲がすでに絞り込まれたあとに、Skip ステージで グラニュール が大幅に減っているのが理想です。スキップ索引はパーティションプルーニングと主キープルーニングのあとに評価されるため、その効果は、残ったパーツと グラニュール に対してどれだけ削減できたかで見るのが最も適切です。 `EXPLAIN` を使えばプルーニングが実際に行われているかは確認できますが、それだけで全体として高速化されるとは限りません。スキップ索引の評価にはコストがかかり、特に索引が大きい場合はその影響が大きくなります。実際に性能が向上していることを確認するため、索引を追加してマテリアライズする前後で、必ずクエリをベンチマークしてください。 たとえば、デフォルトの Traces スキーマに含まれる、TraceId 用のデフォルトのブルームフィルタースキップ索引を見てみましょう。 ```sql theme={null} INDEX idx_trace_id TraceId TYPE bloom_filter(0.001) GRANULARITY 1 ``` 選択性の高いクエリに対してどの程度効果があるかは、`EXPLAIN indexes = 1` を使うと確認できます: ```sql theme={null} EXPLAIN indexes = 1 SELECT * FROM otel_v2.otel_traces WHERE (ServiceName = 'accounting') AND (TraceId = 'aeea7f401feb75fc5af8eb25ebc8e974'); ReadFromMergeTree (otel_v2.otel_traces) Indexes: PrimaryKey Keys: ServiceName Parts: 6/18 Granules: 255/35898 Skip Name: idx_trace_id Description: bloom_filter GRANULARITY 1 Parts: 1/6 Granules: 1/255 ``` この場合、まず主キーフィルタによってデータセットが大幅に絞り込まれ (35898 グラニュールから 255 まで) 、その後ブルームフィルタによってさらに 1 つのグラニュール (1/255) まで削減されます。これはスキップ索引にとって理想的なパターンです。主キーによる プルーニング で検索範囲を狭め、その後スキップ索引が残りの大半を除外します。 実際の効果を確認するには、同じ設定でクエリをベンチマークし、実行時間を比較します。結果のシリアライゼーションのオーバーヘッドを避けるために `FORMAT Null` を使用し、実行結果の再現性を保つためにクエリ条件 cache を無効にします: ```sql theme={null} SELECT * FROM otel_traces WHERE (ServiceName = 'accountingservice') AND (TraceId = '4512e822ca3c0c68bbf5d4a263f9943d') SETTINGS use_query_condition_cache = 0 ``` ```response theme={null} 2 rows in set. Elapsed: 0.025 sec. Processed 8.52 thousand rows, 299.78 KB (341.22 thousand rows/s., 12.00 MB/s.) Peak memory usage: 41.97 MiB. ``` 次に、スキップ索引を無効にして同じクエリを実行します。 ```sql theme={null} SELECT * FROM otel_traces WHERE (ServiceName = 'accountingservice') AND (TraceId = '4512e822ca3c0c68bbf5d4a263f9943d') FORMAT Null SETTINGS use_query_condition_cache = 0, use_skip_indexes = 0; ``` ```response theme={null} 0 rows in set. Elapsed: 0.702 sec. Processed 1.62 million rows, 56.62 MB (2.31 million rows/s., 80.71 MB/s.) Peak memory usage: 198.39 MiB. ``` `use_query_condition_cache` を無効にすると、キャッシュされたフィルタリング判定の影響を結果が受けないようにでき、`use_skip_indexes = 0` を設定すると、比較のためのクリーンなベースラインを確保できます。絞り込みが効果的で、かつ索引の評価コストが低い場合は、上の例のように、索引付きクエリのほうが大幅に高速になるはずです。 `EXPLAIN` で グラニュール の絞り込みがほとんど行われていない場合や、スキップ索引が非常に大きい場合は、索引の評価コストによって利点が相殺されることがあります。まず `EXPLAIN indexes = 1` を使って絞り込みを確認し、そのうえでベンチマークを実行してエンドツーエンドの性能向上を確認してください。
### スキップ索引を追加するタイミング
スキップ索引は、ユーザーが最も頻繁に実行するフィルタの種類と、パーツやグラニュール内のデータの分布に応じて、必要なものだけを選んで追加するべきです。目的は、索引自体の評価コストを上回るだけのグラニュールを除外することです。そのため、本番環境に近いデータでのベンチマークが不可欠です。 **フィルタに使われる数値カラムでは、minmax スキップ索引はほぼ常に有力な選択肢です。** 軽量で評価コストも低く、範囲条件に対して効果を発揮します。特に、値がおおまかに順序付けられている場合や、パーツ内で狭い範囲に収まっている場合に有効です。たとえ minmax が特定のクエリパターンで効果を発揮しなくても、通常はオーバーヘッドが十分小さいため、そのまま維持しておくのは妥当です。 **文字列カラム。カーディナリティが高く、値がスパースな場合は、ブルームフィルタを使用してください。** ブルームフィルタは、各値の出現頻度が比較的低い高カーディナリティの文字列カラム、つまり検索対象の値がほとんどのパーツやグラニュールに含まれていない場合に最も効果を発揮します。経験則として、ブルームフィルタが有望なのは、そのカラムに少なくとも 10,000 個の異なる値がある場合で、100,000 個以上の異なる値があるとさらに効果が高いことがよくあります。また、一致する値が少数の連続したパーツにまとまっている場合にも有効で、これは通常、そのカラムが順序付けキーと相関しているときに起こります。とはいえ、実際の効果はケースバイケースです。実環境での検証に勝るものはありません。
## 最適化 3. 主キーの変更
主キーは、ほとんどのワークロードにおける ClickHouse のパフォーマンスチューニングで最も重要な要素の 1 つです。効果的に調整するには、その仕組みとクエリパターンとの関係を理解する必要があります。最終的には、主キーはユーザーがどのようにデータへアクセスするか、特にどのカラムで最も頻繁にフィルタするかに沿っているべきです。 主キーは圧縮やストレージレイアウトにも影響しますが、主目的はクエリ性能の向上です。ClickStack では、標準の主キーが一般的なオブザーバビリティのアクセスパターンと高い圧縮率を考慮して、あらかじめ最適化されています。ログ、トレース、メトリクステーブルのデフォルトキーは、典型的なワークフローで良好な性能を発揮するよう設計されています。 主キーの先頭に近いカラムでフィルタするほうが、後ろにあるカラムでフィルタするよりも効率的です。デフォルト設定は大半のユーザーにとって十分ですが、特定のワークロードでは主キーを変更することで性能が向上する場合があります。 **用語に関する補足** このドキュメント全体では、「ソートキー」という用語を「主キー」と同じ意味で使っています。厳密には ClickHouse では両者は異なりますが、ClickStack では通常、テーブルの `ORDER BY` 句で指定される同じカラムを指します。詳細は、ソートキーと異なる主キーの選び方についての [ClickHouse ドキュメント](/ja/reference/engines/table-engines/mergetree-family/mergetree#choosing-a-primary-key-that-differs-from-the-sorting-key) を参照してください。 主キーを変更する前に、ClickHouse における[プライマリインデックスの仕組みを理解するためのガイド](/ja/concepts/core-concepts/primary-indexes)を読んでおくことを強く推奨します。 主キーのチューニングは、テーブルやデータ型ごとに異なります。あるテーブルやデータ型で有効な変更が、ほかでも有効とは限りません。目的は常に、たとえばログのような特定のデータ型に対して最適化することです。 **通常、最適化の対象となるのはログテーブルとトレーステーブルです。その他のデータ型で主キーの変更が必要になることはまれです。** 以下は、ログとメトリクス用の ClickStack テーブルにおけるデフォルトの主キーです。 * ログ ([`otel_logs`](/ja/clickstack/ingesting-data/schemas#logs)) - `(ServiceName, TimestampTime, Timestamp)` * トレース (['otel\_traces](/ja/clickstack/ingesting-data/schemas#traces)) - `(ServiceName, SpanName, toDateTime(Timestamp))` 他のデータ型のテーブルで使われる主キーについては、["Tables and schemas used by ClickStack"](/ja/clickstack/ingesting-data/schemas) を参照してください。たとえば、トレーステーブルは service name、span name、続いて timestamp と trace ID でのフィルタリングに最適化されています。一方、ログテーブルは service name、次に日付、そして timestamp でのフィルタリングに最適化されています。最も効率的なのは主キーの順序どおりにフィルタを適用することですが、これらのカラムのいずれかで任意の順序にフィルタしても、ClickHouse が[読み取り前にデータをプルーニング](/ja/concepts/features/performance/skip-indexes/skipping-indexes)するため、クエリは大きな恩恵を受けます。 主キーを選ぶ際には、カラムの最適な並び順を決めるうえで考慮すべき点がほかにもあります。["Choosing a primary key."](#choosing-a-primary-key) を参照してください。 **主キーはテーブルごとに個別に変更してください。ログに適した内容が、トレースやメトリクスにも適しているとは限りません。**
### 主キーの選択
まず、特定のテーブルについて、アクセスパターンがデフォルトと大きく異なるかどうかを確認します。たとえば、通常はまず Kubernetes ノードでログを絞り込み、その後にサービス名で絞り込むことが多く、これが主要なワークフローになっている場合は、主キーの変更を検討する価値があります。 **デフォルトの主キーの変更** デフォルトの主キーは、ほとんどのケースで十分です。変更は慎重に行い、クエリパターンを明確に理解したうえでのみ実施してください。主キーを変更すると、他のワークフローのパフォーマンスが低下する可能性があるため、テストは不可欠です。 必要なカラムを洗い出したら、ソートキー/主キーの最適化を始められます。 ソートキーを選ぶ際に役立つ、いくつかの基本的なルールがあります。以下の項目は互いに競合することもあるため、この順序で検討してください。このプロセスでは、キーは最大でも 4〜5 個に抑えることを目指してください。 1. 一般的なフィルタ条件やアクセスパターンに合うカラムを選択します。たとえば、オブザーバビリティの調査を通常は特定のカラム (例: ポッド名) で絞り込むことから始める場合、そのカラムは `WHERE` 句で頻繁に使用されます。使用頻度の低いカラムよりも、こうしたカラムを優先してキーに含めてください。 2. フィルタ時に全行の大部分を除外できるカラムを優先します。これにより、読み込む必要のあるデータ量を減らせます。サービス名やステータスコードは有力な候補になることがよくあります。後者については、大半の行を除外できる値でフィルタする場合に限ります。たとえば、多くのシステムでは 200 コードでフィルタすると大半の行に一致しますが、500 エラーであれば一致するのは小さな部分集合です。 3. テーブル内の他のカラムと高い相関がある可能性の高いカラムを優先します。これにより、それらの値も連続して格納されやすくなり、圧縮の改善につながります。 4. ソートキーに含まれるカラムに対する `GROUP BY` (チャート用の集計) および `ORDER BY` (ソート) の操作は、メモリ効率が向上する場合があります。 ソートキーに含めるカラムの部分集合を特定したら、それらを特定の順序で定義する必要があります。この順序は、クエリにおける後続のキーカラムでのフィルタ効率と、テーブルのデータファイルの圧縮率の両方に大きく影響する可能性があります。一般に、キーはカーディナリティの低い順に並べるのが最適です。ただし、ソートキーの後ろに現れるカラムでのフィルタは、タプルの前の方に現れるカラムより効率が落ちる点とのバランスを取る必要があります。これらの特性のバランスを取りつつ、アクセスパターンを考慮してください。最も重要なのは、複数のパターンをテストすることです。ソートキーとその最適化方法をさらに理解するには、["主キーの選択"](/ja/concepts/best-practices/choosing-a-primary-key) を読むことをお勧めします。主キーのチューニングや内部データ構造についてさらに詳しく知るには、["ClickHouse におけるプライマリインデックスの実践的入門"](/ja/guides/clickhouse/data-modelling/sparse-primary-indexes) も参照してください。
### 主キーの変更
データのインジェスト前にアクセスパターンを十分把握できている場合は、対象のデータ型に対応するテーブルを削除して再作成するだけで済みます。 以下の例は、既存のスキーマを使いながら、`ServiceName` の前に `SeverityText` カラムを含む新しい主キーを持つログテーブルを簡単に作成する方法を示しています。 #### 新しいテーブルを作成する ```sql theme={null} CREATE TABLE otel_logs_temp AS otel_logs PRIMARY KEY (SeverityText, ServiceName, TimestampTime) ORDER BY (SeverityText, ServiceName, TimestampTime) ``` **ORDER BY と主キー** 上記の例では、`PRIMARY KEY` と `ORDER BY` の両方を指定する必要があります。 ClickStack では、これらはほとんどの場合同じです。 `ORDER BY` は物理的なデータレイアウトを制御し、`PRIMARY KEY` はスパースインデックスを定義します。 まれに、非常に大規模なワークロードでは両者が異なることもありますが、ほとんどのユーザーは一致させておくべきです。 #### テーブルを入れ替えて削除する `EXCHANGE` ステートメントは、テーブル名を[アトミックに](/ja/concepts/core-concepts/glossary#atomicity)入れ替えるために使用します。一時テーブル (この時点では以前のデフォルトテーブル) は削除できます。 ```sql theme={null} EXCHANGE TABLES otel_logs_temp AND otel_logs DROP TABLE otel_logs_temp ``` ただし、**既存のテーブルの主キーは変更できません**。変更するには、新しいテーブルを作成する必要があります。 以下の手順を使うと、古いデータを保持したまま透過的にクエリできるようになります (必要であれば、HyperDX では既存のキーを使って参照を続けつつ、新しいデータはユーザーのアクセスパターンに最適化された新しいテーブル経由で参照できます) 。この方法であればインジェストパイプラインを変更する必要はなく、データは引き続きデフォルトのテーブル名に送信され、変更はすべてユーザーに対して透過的です。 既存データを新しいテーブルに backfill することは、大規模環境ではめったに見合いません。通常はコンピュートと IO のコストが高く、性能向上のメリットに見合わないためです。代わりに、古いデータは[有効期限 (TTL)](/ja/clickstack/managing/ttl)で期限切れになるままにし、新しいデータが改善されたキーの恩恵を受けるようにしてください。 以下でも、主キーの先頭カラムとして `SeverityText` を導入する同じ例を使用します。この場合は、新しいデータ用のテーブルを作成し、履歴分析のために古いテーブルは保持します。 #### 新しいテーブルを作成する 目的の主キーで新しいテーブルを作成します。接尾辞 `_23_01_2025` に注意してください。これは現在の日付に合わせて変更してください。例: ```sql theme={null} CREATE TABLE otel_logs_23_01_2025 AS otel_logs PRIMARY KEY (SeverityText, ServiceName, TimestampTime) ORDER BY (SeverityText, ServiceName, TimestampTime) ``` #### Merge テーブルを作成する [Merge エンジン](/ja/reference/engines/table-engines/special/merge) (MergeTree と混同しないでください) は、それ自体ではデータを保存しませんが、複数の別テーブルを同時に読み取れるようにします。 ```sql theme={null} CREATE TABLE otel_logs_merge AS otel_logs ENGINE = Merge(currentDatabase(), 'otel_logs*') ``` `currentDatabase()` は、このコマンドが正しいデータベースで実行されることを前提としています。そうでない場合は、データベース名を明示的に指定してください。 これで、このテーブルにクエリを実行して、`otel_logs` からデータが返ることを確認できます。 #### HyperDX が Merge テーブルを参照するように更新する ログのログソースで使用するテーブルとして `otel_logs_merge` を使うよう HyperDX を設定します。 Merge テーブルを選択 この時点では、書き込みは元の主キーのまま `otel_logs` に継続され、一方で読み取りは Merge テーブルを使用します。ユーザーに見える変更はなく、インジェストへの影響もありません。 #### テーブルを入れ替える 次に、`EXCHANGE` ステートメントを使って `otel_logs` テーブルと `otel_logs_23_01_2025` テーブルの名前をアトミックに入れ替えます。 ```sql theme={null} EXCHANGE TABLES otel_logs AND otel_logs_23_01_2025 ``` 以後、書き込みは更新後の主キーを持つ新しい `otel_logs` テーブルに送られます。既存データは `otel_logs_23_01_2025` に残り、Merge テーブル経由で引き続きアクセスできます。この接尾辞は変更が適用された日付を示しており、そのテーブルに含まれる最新の timestamp を表します。 この手順により、インジェストを中断せず、ユーザーに見える影響もなく主キーを変更できます。 この手順は、主キーをさらに変更する必要が生じた場合にも応用できます。たとえば、1 週間後に、`SeverityText` ではなく `SeverityNumber` を主キーに含めるべきだと判断した場合です。以下の手順は、主キーの変更が必要になるたびに何度でも繰り返し応用できます。 #### 新しいテーブルを作成する 必要な主キーで新しいテーブルを作成します。 以下の例では、テーブルの日付を表す接尾辞として `30_01_2025` を使用しています。例: ```sql theme={null} CREATE TABLE otel_logs_30_01_2025 AS otel_logs PRIMARY KEY (SeverityNumber, ServiceName, TimestampTime) ORDER BY (SeverityNumber, ServiceName, TimestampTime) ``` #### テーブルを入れ替える ここでは、`EXCHANGE` ステートメントを使用して、`otel_logs` テーブルと `otel_logs_30_01_2025` テーブルの名前をアトミックに入れ替えます。 ```sql theme={null} EXCHANGE TABLES otel_logs AND otel_logs_30_01_2025 ``` 以降、書き込みは更新後の主キーを持つ新しい `otel_logs` テーブルに対して行われます。古いデータは `otel_logs_30_01_2025` に残り、merge テーブル経由で引き続きアクセスできます。 **不要になったテーブル** 有効期限 (TTL) ポリシーを設定している場合 (推奨) 、書き込みを受けなくなった古い主キーのテーブルは、データの有効期限切れに伴って徐々に空になります。これらのテーブルは監視し、データがなくなった段階で定期的にクリーンアップする必要があります。現時点では、このクリーンアップは手動で行います。
## 最適化 4. materialized view の活用
ClickStack では、時間の経過に沿って1分ごとの平均リクエスト時間を計算するような、集約処理の多いクエリに依存する可視化を高速化するために、[インクリメンタルmaterialized view](/ja/concepts/features/materialized-views/incremental-materialized-view)を活用できます。この機能によりクエリ性能を大幅に向上でき、通常は1日あたり約10 TB以上の大規模なデプロイメントで特に効果を発揮し、1日あたりPB規模へのスケーリングも可能になります。インクリメンタルmaterialized view はベータであるため、注意して使用してください。 ClickStack でこの機能を使用する方法の詳細については、専用ガイド["ClickStack - Materialized Views."](/ja/clickstack/managing/materialized-views)を参照してください。
## 最適化 5. PROJECTION の活用
PROJECTION は、materialized columns、スキップ索引、主キー、materialized view を検討したうえで、最後に考慮できる高度な最適化です。PROJECTION と materialized view は似ているように見えるかもしれませんが、ClickStack では役割が異なり、適した利用シナリオもそれぞれ異なります。