## はじめに {#introduction} ClickHouse の全文検索(Full-text Search)が一般提供(GA)となり、本番環境で利用できるようになったことをお知らせします。 今回の GA は、強力なテキスト検索機能を ClickHouse にネイティブに組み込む取り組みの集大成です。最初の構想から実装は何度もイテレーションを重ね、そのたびに性能、使いやすさ、ClickHouse アーキテクチャ全体との統合を磨いてきました。 直近では、オブジェクトストレージ上で高い性能を確保することに注力してきました。これにより、ClickHouse Cloud のユーザーも、オープンソース版のユーザーが当然のものとしてきた速度と効率を享受できます。この実現には、的を絞った最適化をいくつも積み重ねる必要がありました。その詳細は、包括的なベンチマーク結果とあわせて、続編の記事で取り上げます。 本記事では、全文検索の主な利点を紹介し、どのような場面で使うべきかの指針を示し、実際のシナリオでの挙動を実演します。 ## ClickHouse の全文検索とは {#what_is_full_text_search_in_clickhouse} ClickHouse の全文検索は、Lucene などの検索技術と同様のアプローチで、転置インデックスとして実装されています。大まかに言えば、テキストインデックスは、各トークンとそれを含む行番号との対応を保存します。この構造により、ClickHouse は列のすべての値をスキャンすることなく、検索条件(これもトークンで構成されます)に一致し得る行を素早く特定できます。要するに、このインデックスはテキストベースのフィルタリングを高速化するものです。 トークンは、トークン化(tokenization)と呼ばれる処理で生成されます。トークン化の前に文字列値へ前処理関数を適用して値を変換し、検索の挙動を変えられます。たとえば、大文字小文字を区別せずに検索できるよう小文字化する、といった処理です。例として次を見てみましょう。  列にテキストインデックスを定義すると、このトークン化処理が挿入時(またはインデックスをマテリアライズする時)に列の値へ適用され、得られたトークンから行へのマッピングが内部に保存されます。クエリ時には、同じトークン化ロジックが検索文字列に適用されます。そのうえで転置インデックスを使い、要求されたトークンを含む候補行を効率的に特定します。 このようにテキストインデックスを使うと、文字列列を単一トークンでも複数トークンでも高速に検索できます。テキストインデックスは、通常の文字列に加えて、文字列の配列や、Map のキーと値にも使えます。「ClickHouse の全文検索で、スキャンするグラニュール数がインデックスなしのクエリより 96% 減りました。私たちのベンチマークワークロードでは、クエリのレイテンシが一貫して 7 倍近く改善しました。」
後述の例で示すように、ClickHouse ではトークン化と前処理を標準的な SQL 式で設定できます。ユーザーは、インデックス対象のデータと検索文字列の双方について、どのようにトークンへ分割するかを制御できます。これは照合の挙動と性能の両方に影響します。たとえば、n-gram トークナイザーや sparse n-gram トークナイザーを使えば、部分文字列に近い照合ができます。トークン化の戦略を選ぶことで、ユーザーは特定のユースケースやトレードオフに合わせて調整できます。 近く公開するエンジニアリング寄りの記事では、ClickHouse の列指向アーキテクチャ上での実装を詳しく解説します。あわせて、ClickHouse で従来使われてきた手法や、他の伝統的な検索エンジンと比較したベンチマーク結果も示します。 ## 全文検索インデックスを使うべき場面 {#when_should_i_use_full_text_search_indices} ClickHouse の全文検索は、大規模な文字列ベースのフィルタリングを速くすることを目的に設計しています。特に効果的なのは、大量のテキストデータの中からトークンを検索するクエリです。こうしたワークロードは、これまで[文字列照合を高速化する Bloom フィルターのスキッピングインデックス](https://clickhouse.com/docs/optimize/skipping-indexes#bloom-filter-types)などの手法に頼っていたかもしれません。テキストインデックスを使えば、String 列、文字列の配列、Map のキーと値を効率よく検索できます。その他の半構造化型のサポートも今後拡充していきます。フレーズ検索、すなわちあるトークンの直後に別のトークンが続くことを要求する検索は、現時点ではテキストインデックスで直接には高速化されません。ただし、複数トークン検索で候補集合を絞り込んだうえで、残ったグラニュールに対して通常の線形スキャンでフレーズ照合を行うことはできます。この形であれば、フレーズ検索も間接的に恩恵を受けられます。フレーズ検索の直接的な高速化は、今後のイテレーションで予定しています。
このため全文検索は、非常に大きなデータセットに対してフィルタリングと集計を組み合わせる分析ワークロードによく適合します。ClickHouse ならではの強みの一つは、数十億、さらには数兆行に対して検索を行い、その結果をすぐに集計できることです。ペタバイト規模のデータを検索し、同じクエリで集計を計算することは、高性能な分析データベースとしての ClickHouse の中核的な強みにそのまま重なります。 オブザーバビリティはその自然な例です。ClickStack では、[ログ検索を高速化するために全文検索がすでに統合されています](https://clickhouse.com/blog/whats-new-in-clickstack-january-2026#supporting-text-indices)。こうしたワークロードでは通常、特定の語でログをフィルタリングしたうえで、集計、グルーピング、可視化を行います。ログデータは、たまたま大量のテキストを含んでいるだけの、分析データの一形態にすぎません。高速なトークン照合とリアルタイム分析の組み合わせこそ、全文検索が想定しているシナリオです。 一方で、ClickHouse の全文検索が担わない領域もはっきりさせておきます。これは関連度エンジンではなく、TF-IDF や BM25 のようなスコアリングモデルを実装していません。高度なフレーズランキングのための位置情報も保存しません。トークンベースのフィルタリングを高速化する目的で設計したものです。高度な自然言語処理(NLP)や関連度重視のユースケースに向けた専用検索エンジンの代わりにはなりません。洗練されたランキングや言語処理の機能が必要であれば、従来の検索エンジンのほうが適しているかもしれません。テラバイトからペタバイト規模のデータを極めて高速にトークン照合・文字列照合し、それをリアルタイムの集計や分析と組み合わせたいなら、ClickHouse の全文検索はまさにそのためのものです。 ### ユーザー事例 - Ryft.io {#user_story_ryftio} ベータ期間中、ClickHouse Cloud のユーザーは、既存の本番ワークロードで全文検索を有効化し、大規模環境での性能と使いやすさの検証を始めました。 その一つが [Ryft.io](http://Ryft.io) です。Ryft.io は、実際の利用パターンに基づいて Apache Iceberg テーブルのメンテナンスとコンパクションを自動化するプラットフォームで、チームがレイクハウスを効率的で常に最適化された状態に保てるようにします。顧客がクエリログを提供すると、Ryft はテーブルがどのようにアクセスされているかを分析し、継続的にテーブルを管理・最適化します。  このワークフローの一部として、Ryft は現在、数億件の過去クエリに対する自由テキスト検索を ClickHouse の全文検索で実現しています。 > 「ClickHouse の全文検索で、スキャンするグラニュール数がインデックスなしのクエリより最大 96% 減りました。私たちのベンチマークワークロードでは、クエリのレイテンシが 7 倍近く改善しました。これにより、当社のクエリ分析エンジンにおける自由テキスト検索の使い勝手は根本的に変わりました。今ではシームレスな検索体験を提供でき、Ryft が継続的にもたらす性能面の効果と最適化の価値を明確に示せるようになりました。」 > >これまで、ClickHouse のユーザーは Bloom フィルターベースのスキッピングインデックスで文字列検索を高速化してきました。Bloom フィルターは有用ですが、確率的であり、グラニュール単位で動作します。つまり偽陽性が生じ得るうえ、「このデータ範囲にそのトークンが存在するかもしれない」という粗い粒度の判定しかできません。また、慎重なチューニングが必要で、複数トークン検索をネイティブにはサポートしません。テキストインデックスは根本的に異なるアプローチを取ります。トークンに対する決定的な転置インデックスを構築し、行レベルの情報を保存するため、インデックス自体が偽陽性を出すことなく、語を正確に検索できます。テキストインデックスは Bloom フィルターより大きくなりますが、大規模なテキストコーパスに対して大幅に優れたスケーラビリティと性能を発揮し、現在では大規模な文字列照合における推奨アプローチとなっています。
CREATE TABLE github.github_events(
...
body String,
...
INDEX fts_body body TYPE text(
tokenizer = splitByNonAlpha,
preprocessor = lowerUTF8(body)
),
INDEX bloom_body tokens(lower(body)) TYPE bloom_filter(0.01) GRANULARITY 8
)
ENGINE = MergeTree
ORDER BY (repo_id, event_type, created_at);
たとえば、次の問いには素早く答えられるようになりました。GitHub のコメント全体で、「ClickHouse」は時間の経過とともにどれくらい言及されているのでしょうか。テーブルスキーマ全体はこちらを参照してください。
まず、テキストインデックスと Bloom フィルターの両方を無効にし、線形スキャンを強制します。ClickHouse の並列処理をもってしても、数ギガバイトのテキストのスキャンはインタラクティブな分析には速さが足りません。ここでのクエリはすべて 3 回実行したうちの最速値です(実質的にファイルシステムキャッシュがホットな状態)。クエリの実行には ClickHouse Cloud の 32 コアのノードを使用しています。
SELECT
toStartOfMonth(created_at) AS month,
count() AS count
FROM github.github_events
WHERE hasTokenCaseInsensitive(body, 'ClickHouse')
GROUP BY month
ORDER BY month ASC
SETTINGS enable_full_text_index = 0, use_skip_indexes = 0;
次に、テキストインデックスは無効のまま、Bloom フィルターインデックスを有効にします。グラニュールの約 80% が除外され、性能が改善します。大文字小文字を区別しない照合のために、
hasTokenCaseInsensitive関数を使っている点に注意してください。
SELECT
toStartOfMonth(created_at) AS month,
count() AS count
FROM github.github_events
WHERE hasAny(tokens(lower(body)), ['clickhouse'])
GROUP BY month
ORDER BY month ASC
SETTINGS enable_full_text_index = 0, use_skip_indexes = 1, use_query_condition_cache = 0;
ここでの Bloom フィルターのオーバーヘッドは意外なほど大きいものです。スキャンされるデータ量は大幅に減っているものの、性能の改善はそれほど劇的ではありません。改善の余地はありますが、良い結果を得るにはチューニングが必要です。 最後に、全文検索インデックスを有効にします。ClickHouse は転置インデックスを使って一致する行を効率的に特定できるようになり、読み取る必要のあるデータ量が劇的に減ります。現時点で Bloom フィルターインデックスを効かせるには、クエリの式をインデックス定義と同じ式、すなわち
tokens(lower(body)に一致させる必要があります。
SELECT
toStartOfMonth(created_at) AS month,
count() AS count
FROM github.github_events
WHERE hasToken(body, 'ClickHouse')
GROUP BY month
ORDER BY month ASC
SETTINGS use_query_condition_cache = 0;
SELECT
name,
type,
formatReadableSize(data_compressed_bytes) AS compressed_bytes,
formatReadableSize(data_uncompressed_bytes) AS uncompressed_bytes
FROM system.data_skipping_indices
WHERE (`table` = 'github_events') AND (database = 'github') AND ((name = 'bloom_body') OR (name = 'fts_body'));
SELECT
formatReadableSize(sum(data_compressed_bytes)) AS compressed_size,
formatReadableSize(sum(data_uncompressed_bytes)) AS un_compressed_size
FROM system.columns
WHERE (`table` = 'github_events') AND (database = 'github');