` 句で要求した行数より少ない結果しか返されない可能性があることです。これは、ベクトル類似度索引が返した結果行のうち1行以上が追加のフィルタを満たさない場合に発生します。
* プリフィルタリングは、一般には未解決の問題です。一部の特化型ベクトルデータベースはプリフィルタリングのアルゴリズムを提供していますが、ほとんどのリレーショナルデータベース (ClickHouse を含む) では、正確な近傍探索、つまり索引を使わない総当たりスキャンにフォールバックします。
どの戦略が使用されるかは、フィルタ条件によって異なります。
*追加フィルタがパーティションキーの一部である場合*
追加のフィルタ条件がパーティションキーの一部である場合、ClickHouse はパーティションプルーニングを適用します。
例として、テーブルがカラム `year` で範囲パーティション分割されていて、次のクエリを実行するとします。
```sql theme={null}
WITH [0., 2.] AS reference_vec
SELECT id, vec
FROM tab
WHERE year = 2025
ORDER BY L2Distance(vec, reference_vec) ASC
LIMIT 3;
```
ClickHouse は、2025 年のものを除くすべてのパーティションをプルーニングします。
*追加のフィルタは索引を使って評価できない*
追加のフィルタ条件を索引 (主キー索引、スキップ索引) で評価できない場合、ClickHouse はポストフィルタリングを適用します。
*追加のフィルタは主キー索引を使って評価できる*
追加のフィルタ条件を [主キー](/ja/reference/engines/table-engines/mergetree-family/mergetree#primary-key) で評価できる場合 (つまり、それらが主キーのプレフィックスを構成する場合) で、かつ
* フィルタ条件によってパーツ内で少なくとも 1 行が除外される場合、ClickHouse はそのパーツ内の "残った" 範囲に対してプリフィルタリングにフォールバックします。
* フィルタ条件によってパーツ内で 1 行も除外されない場合、ClickHouse はそのパーツに対してポストフィルタリングを行います。
実運用のユースケースでは、後者のケースが発生する可能性はかなり低いです。
*追加のフィルタはスキップ索引を使って評価できる*
追加のフィルタ条件を [スキップ索引](/ja/reference/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-data_skipping-indexes) (minmax 索引、set 索引など) で評価できる場合、ClickHouse はポストフィルタリングを行います。
このような場合、ベクトル類似度索引は他のスキップ索引と比べて最も多くの行を除外すると見込まれるため、最初に評価されます。
ポストフィルタリングとプリフィルタリングをより細かく制御するには、2 つの設定を使用できます。
設定 [vector\_search\_filter\_strategy](/ja/reference/settings/session-settings/vector-search#vector_search_filter_strategy) (デフォルト: 上記のヒューリスティックを実装する `auto`) は `prefilter` に設定できます。
これは、追加のフィルタ条件の選択性が極めて高い場合に、プリフィルタリングを強制するのに役立ちます。
たとえば、次のクエリはプリフィルタリングの恩恵を受ける可能性があります。
```sql theme={null}
SELECT bookid, author, title
FROM books
WHERE price < 2.00
ORDER BY cosineDistance(book_vector, getEmbedding('Books on ancient Asian empires'))
LIMIT 10
```
2ドル未満の本がごくわずかしかないとすると、ポストフィルタリングでは 0 行しか返らない可能性があります。これは、ベクトル索引から返される上位 10 件の一致結果がすべて 2 ドルを超えている可能性があるためです。
プリフィルタリングを強制すると (クエリに `SETTINGS vector_search_filter_strategy = 'prefilter'` を追加) 、ClickHouse はまず価格が 2 ドル未満の本をすべて見つけ、その後、見つかった本に対して総当たりのベクトル検索を実行します。
上記の問題を解決する別の方法として、[vector\_search\_index\_fetch\_multiplier](/ja/reference/settings/session-settings/vector-search#vector_search_index_fetch_multiplier) (デフォルト: `1.0`、最大: `1000.0`) を `1.0` より大きい値 (たとえば `2.0`) に設定することもできます。
ベクトル索引から取得する最近傍の数はこの設定値に応じて増加し、その後、それらの行に追加のフィルタが適用されて LIMIT 件の行が返されます。
たとえば、乗数を `3.0` にして再度クエリできます。
```sql theme={null}
SELECT bookid, author, title
FROM books
WHERE price < 2.00
ORDER BY cosineDistance(book_vector, getEmbedding('Books on ancient Asian empires'))
LIMIT 10
SETTING vector_search_index_fetch_multiplier = 3.0;
```
ClickHouse は各パーツのベクトル索引から 3.0 x 10 = 30 件の最近傍を取得し、その後で追加のフィルタ条件を適用します。
返されるのは、そのうち最も近い 10 件の近傍のみです。
`vector_search_index_fetch_multiplier` を設定することでこの問題を軽減できますが、極端な場合 (WHERE 条件の選択性が非常に高い場合) には、要求した N 行より少ない行しか返されない可能性が依然としてあります。
**rescoring**
ClickHouse のスキップ索引は通常、グラニュール単位でフィルタリングを行います。つまり、スキップ索引でのルックアップは (内部的には) 一致する可能性のあるグラニュールのリストを返し、後続のスキャンで読み込むデータ量を減らします。
これはスキップ索引全般では有効に機能しますが、ベクトル類似度索引では "granularity mismatch" を引き起こします。
もう少し詳しく言うと、ベクトル類似度索引は、指定された参照ベクトルに対して最も類似する N 個のベクトルの行番号を特定します。
設定 `vector_search_with_rescoring = 1` では、ClickHouse は候補行の元のフル精度ベクトルを読み取り、通常の SQL パイプラインで最終的な距離を計算します。
クエリプランで可能な場合、ClickHouse は最終的な距離計算の前に、ベクトル索引が返した候補行にスキャンを絞り込みます。
このステップは rescoring と呼ばれ、特に量子化されたベクトル索引では精度を向上させることができます。これは、最終的なランキングで索引距離ではなく保存されたベクトルを使用するためです。
追加のフィルタによって候補が削られすぎる場合や、より高い再現率が必要な場合は、設定 `vector_search_index_fetch_multiplier` を増やして、ベクトル索引が rescoring 用により多くの候補行を返すようにしてください。
そこで ClickHouse は、rescoring を無効にして、最も類似するベクトルとその距離を索引から直接返す最適化を提供しています。
この最適化はデフォルトで有効になっています。設定 [vector\_search\_with\_rescoring](/ja/reference/settings/session-settings/vector-search#vector_search_with_rescoring) を参照してください。
大まかな仕組みとしては、ClickHouse は最も類似するベクトルとその距離を仮想カラム `_distance` として利用できるようにします。
これを確認するには、`EXPLAIN header = 1` を付けてベクトル検索クエリを実行します。
```sql theme={null}
EXPLAIN header = 1
WITH [0., 2.] AS reference_vec
SELECT id
FROM tab
ORDER BY L2Distance(vec, reference_vec) ASC
LIMIT 3
SETTINGS vector_search_with_rescoring = 0
```
```result theme={null}
Query id: a2a9d0c8-a525-45c1-96ca-c5a11fa66f47
┌─explain────────────────────────────────────────────────────────────────────────────────────────────────────┐
1. │ Expression (Project names) │
2. │ Header: id Int32 │
3. │ Limit (preliminary LIMIT (without OFFSET)) │
4. │ Header: L2Distance(__table1.vec, _CAST([0., 2.]_Array(BFloat16), 'Array(BFloat16)'_String)) BFloat16 │
5. │ __table1.id Int32 │
6. │ Sorting (Sorting for ORDER BY) │
7. │ Header: L2Distance(__table1.vec, _CAST([0., 2.]_Array(BFloat16), 'Array(BFloat16)'_String)) BFloat16 │
8. │ __table1.id Int32 │
9. │ Expression ((Before ORDER BY + (Projection + Change column names to column identifiers))) │
10. │ Header: L2Distance(__table1.vec, _CAST([0., 2.]_Array(BFloat16), 'Array(BFloat16)'_String)) BFloat16 │
11. │ __table1.id Int32 │
12. │ ReadFromMergeTree (default.tab) │
13. │ Header: id Int32 │
14. │ _distance BFloat16 │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
rescoring なし (`vector_search_with_rescoring = 0`) で実行し、かつ並列レプリカが有効なクエリでは、rescoring にフォールバックする場合があります。
#### パフォーマンスチューニング
**圧縮の調整**
ほぼすべてのユースケースで、基盤となるカラム内のベクトルは高密度であり、圧縮してもあまり効果がありません。
その結果、[圧縮](/ja/reference/statements/create/table/codec) を有効にすると、ベクトルカラムへの書き込みや読み取りが遅くなります。
そのため、圧縮は無効にすることを推奨します。
そのためには、次のようにベクトルカラムに `CODEC(NONE)` を指定します。
```sql theme={null}
CREATE TABLE tab
(
id Int32,
vec Array(BFloat16) CODEC(NONE),
INDEX idx vec TYPE vector_similarity('hnsw', 'L2Distance', 2)
)
ENGINE = MergeTree ORDER BY id;
```
**索引作成のチューニング**
ベクトル類似度索引のライフサイクルは、パーツのライフサイクルと連動しています。
つまり、ベクトル類似度索引が定義された新しいパーツが作成されるたびに、その索引も作成されます。
これは通常、データが[挿入される](/ja/concepts/features/operations/insert/inserting-data)とき、または[マージ](/ja/concepts/core-concepts/merges)中に発生します。
残念ながら、HNSW は索引の作成に時間がかかることで知られており、挿入やマージを大幅に遅くする可能性があります。
ベクトル類似度索引は、データが不変である場合や、変更頻度が低い場合にのみ使用するのが理想的です。
索引作成を高速化するには、次の手法を使用できます。
まず、索引作成は並列化できます。
索引作成スレッドの最大数は、サーバー設定[max\_build\_vector\_similarity\_index\_thread\_pool\_size](/ja/reference/settings/server-settings/settings/max#max_build_vector_similarity_index_thread_pool_size)で設定できます。
最適な性能を得るには、この設定値を CPU コア数に合わせて設定してください。
次に、INSERT ステートメントを高速化するために、ユーザーはセッション設定[materialize\_skip\_indexes\_on\_insert](/ja/reference/settings/session-settings/materialize#materialize_skip_indexes_on_insert)を使用して、新たに挿入されたパーツでのスキップ索引の作成を無効にできます。
そのようなパーツに対する SELECT クエリは、厳密検索にフォールバックします。
挿入されたパーツはテーブル全体のサイズと比べて小さい傾向があるため、性能への影響はごくわずかであると見込まれます。
3 つ目に、マージを高速化するために、ユーザーはセッション設定[materialize\_skip\_indexes\_on\_merge](/ja/reference/settings/merge-tree-settings/materialize#materialize_skip_indexes_on_merge)を使用して、マージ後のパーツでのスキップ索引の作成を無効にできます。
これにより、ステートメント[ALTER TABLE \[...\] MATERIALIZE INDEX \[...\]](/ja/reference/statements/alter/skipping-index#materialize-index)と組み合わせて、ベクトル類似度索引のライフサイクルを明示的に制御できます。
たとえば、すべてのデータが取り込まれるまで、または週末のようにシステム負荷が低い時間帯まで、索引作成を遅らせることができます。
**索引利用のチューニング**
SELECT クエリでベクトル類似度索引を使用するには、それをメインメモリに読み込む必要があります。
同じベクトル類似度索引がメインメモリに繰り返し読み込まれるのを防ぐため、ClickHouse はこの種の索引専用のインメモリ cache を提供しています。
この cache が大きいほど、不要な読み込みは少なくなります。
キャッシュサイズの最大サイズは、サーバー設定[vector\_similarity\_index\_cache\_size](/ja/reference/settings/server-settings/settings/vector-similarity#vector_similarity_index_cache_size)で設定できます。
デフォルトでは、cache は最大 5 GB まで拡張できます。
次のログメッセージ (`system.text_log`) は、ベクトル類似度索引が読み込まれていることを示します。
異なるベクトル検索クエリに対してこのようなメッセージが繰り返し表示される場合は、キャッシュサイズが小さすぎることを示しています。
```text theme={null}
2026-02-03 07:39:10.351635 [1386] f0ac5c85-1b1c-4f35-8848-87a1d1aa00ba : VectorSimilarityIndex Start loading vector similarity index
<...>
2026-02-03 07:40:25.217603 [1386] f0ac5c85-1b1c-4f35-8848-87a1d1aa00ba : VectorSimilarityIndex Loaded vector similarity index: max_level = 2, connectivity = 64, size = 1808111, capacity = 1808111, memory_usage = 8.00 GiB, bytes_per_vector = 4096, scalar_words = 1024, nodes = 1808111, edges = 51356964, max_edges = 233395072
```
ベクトル類似度索引キャッシュには、ベクトル索引のインデックスグラニュールが格納されます。
個々のベクトル索引のインデックスグラニュールがキャッシュサイズより大きい場合は、キャッシュされません。
したがって、ベクトル索引のサイズ (「ストレージとメモリ消費量の見積もり」の式、または [system.data\_skipping\_indices](/ja/reference/system-tables/data_skipping_indices) に基づく) を必ず計算し、それに応じてキャッシュサイズを設定してください。
*ベクトル検索クエリが遅い場合は、まずベクトル索引キャッシュを確認し、必要に応じて増やすことが最初のステップであることを、改めて強調しておきます。*
現在のベクトル類似度索引キャッシュのサイズは、[system.metrics](/ja/reference/system-tables/metrics) に表示されます。
```sql theme={null}
SELECT metric, value
FROM system.metrics
WHERE metric = 'VectorSimilarityIndexCacheBytes'
```
特定のクエリIDを持つクエリのキャッシュヒット数とミス数は、[system.query\_log](/ja/reference/system-tables/query_log) から取得できます。
```sql theme={null}
SYSTEM FLUSH LOGS query_log;
SELECT ProfileEvents['VectorSimilarityIndexCacheHits'], ProfileEvents['VectorSimilarityIndexCacheMisses']
FROM system.query_log
WHERE type = 'QueryFinish' AND query_id = '<...>'
ORDER BY event_time_microseconds;
```
本番環境でのユースケースでは、すべてのベクトル索引が常時メモリ上に保持されるよう、cache のサイズを十分に大きくすることを推奨します。
**量子化の調整**
[量子化](https://huggingface.co/blog/embedding-quantization)は、ベクトルのメモリ使用量と、ベクトル索引の構築および走査にかかる計算コストを削減する手法です。
ClickHouse のベクトル索引は、以下の量子化オプションをサポートしています。
| Quantization | Name | Storage per dimension |
| -------------- | ----------------- | --------------------- |
| f32 | 単精度 | 4 bytes |
| f16 | 半精度 | 2 bytes |
| bf16 (default) | 半精度 (brain float) | 2 bytes |
| i8 | 4分の1精度 | 1 byte |
| b1 | バイナリ | 1 bit |
量子化を行うと、元のフル精度の浮動小数点値 (`f32`) を用いた検索と比べて、ベクトル検索の精度は低下します。
ただし、ほとんどのデータセットでは、半精度の brain float 量子化 (`bf16`) による精度低下はごくわずかであるため、ベクトル類似度索引ではこの量子化手法がデフォルトで使用されます。
4分の1精度 (`i8`) およびバイナリ (`b1`) の量子化では、ベクトル検索の精度が目に見えて低下します。
これら 2 つの量子化は、ベクトル類似度索引のサイズが利用可能な DRAM 容量を大幅に上回る場合にのみ推奨します。
この場合は、精度を向上させるために、rescoring ([vector\_search\_index\_fetch\_multiplier](/ja/reference/settings/session-settings/vector-search#vector_search_index_fetch_multiplier)、[vector\_search\_with\_rescoring](/ja/reference/settings/session-settings/vector-search#vector_search_with_rescoring)) も有効にすることを推奨します。
バイナリ量子化を推奨するのは、1) 正規化された埋め込み (つまりベクトル長 = 1。OpenAI のモデルは通常正規化されています) であり、かつ 2) 距離関数としてコサイン距離を使用する場合に限られます。
バイナリ量子化では、内部的にハミング距離を使用して近接グラフを構築し、検索を行います。
rescoring のステップでは、テーブルに格納された元のフル精度ベクトルを使用して、コサイン距離により最近傍を特定します。
**データ転送の調整**
ベクトル検索クエリにおける参照ベクトルはユーザーから与えられ、通常は大規模言語モデル (LLM) を呼び出して取得します。
ClickHouse でベクトル検索を実行する一般的な Python コードは、次のようになります
```python theme={null}
search_v = openai_client.embeddings.create(input = "[Good Books]", model='text-embedding-3-large', dimensions=1536).data[0].embedding
params = {'search_v': search_v}
result = chclient.query(
"SELECT id FROM items
ORDER BY cosineDistance(vector, %(search_v)s)
LIMIT 10",
parameters = params)
```
埋め込みベクトル (上記のスニペットの `search_v`) は、非常に大きな次元数になることがあります。
たとえば OpenAI は、1536 次元、さらには 3072 次元の埋め込みベクトルを生成するモデルを提供しています。
上記のコードでは、ClickHouse Python ドライバーが埋め込みベクトルを人間が読める文字列に変換し、その後 `SELECT` クエリ全体を文字列として送信します。
埋め込みベクトルが 1536 個の単精度浮動小数点値で構成されているとすると、送信される文字列の長さは 20 kB に達します。
その結果、トークン化、パース、および数千回に及ぶ文字列から浮動小数点値への変換によって、CPU 使用率が高くなります。
また、ClickHouse サーバーのログファイルにもかなりの容量が必要になり、`system.query_log` も肥大化します。
なお、ほとんどの LLM モデルは、埋め込みベクトルをネイティブな浮動小数点数のリストまたは NumPy 配列として返します。
そのため、Python アプリケーションでは、次のスタイルを使用して参照ベクトルのパラメータをバイナリ形式でバインドすることを推奨します。
```python theme={null}
search_v = openai_client.embeddings.create(input = "[Good Books]", model='text-embedding-3-large', dimensions=1536).data[0].embedding
params = {'$search_v_binary$': np.array(search_v, dtype=np.float32).tobytes()}
result = chclient.query(
"SELECT id FROM items
ORDER BY cosineDistance(vector, reinterpret($search_v_binary$, 'Array(Float32)'))
LIMIT 10"
parameters = params)
```
この例では、参照ベクトルはバイナリ形式のまま送信され、サーバー上で浮動小数点数の配列として再解釈されます。
これにより、サーバー側のCPU時間を節約でき、サーバーログや `system.query_log` の肥大化も防げます。
#### 管理と監視
ベクトル類似度索引のディスク上のサイズは、[system.data\_skipping\_indices](/ja/reference/system-tables/data_skipping_indices) で確認できます。
```sql theme={null}
SELECT database, table, name, formatReadableSize(data_compressed_bytes)
FROM system.data_skipping_indices
WHERE type = 'vector_similarity';
```
出力例:
```result theme={null}
┌─database─┬─table─┬─name─┬─formatReadab⋯ssed_bytes)─┐
│ default │ tab │ idx │ 348.00 MB │
└──────────┴───────┴──────┴──────────────────────────┘
```
#### 通常の スキッピング索引 との違い
通常の [スキッピング索引](/ja/concepts/features/performance/skip-indexes/skipping-indexes) と同様に、ベクトル類似度索引は グラニュール 単位で構築され、各 index block は `GRANULARITY = [N]` 個の グラニュール で構成されます (通常の スキッピング索引 のデフォルトでは `[N]` = 1) 。
たとえば、table のプライマリインデックスの granularity が 8192 (設定 `index_granularity = 8192`) で、`GRANULARITY = 2` の場合、各 index block には 16384 行が含まれます。
しかし、近似近傍探索のための data structure と algorithm は、本質的に row-oriented です。
これらは行の集合を compact に表現して保持し、ベクトル検索 queries に対して行を返します。
そのため、ベクトル類似度索引の動作には、通常の スキッピング索引 と比べてやや直感に反する違いがあります。
ユーザーが column にベクトル類似度索引を定義すると、ClickHouse は内部的に各 index block ごとにベクトル類似度の「sub-index」を作成します。
この sub-index は、自身が属する index block 内の行しか認識しないという意味で「local」です。
前述の例で、ある column に 65536 行あるとすると、4 つの index blocks (8 つの グラニュール にまたがる) と、各 index block に対応するベクトル類似度 sub-index が作成されます。
理論上、sub-index は、その index block 内で最も近い N 個の points に対応する行を直接返せます。
`vector_search_with_rescoring = 1` のクエリでは、クエリプラン がこの最適化を許可している場合、ClickHouse はこれらの行位置を使用して、保存されているベクトルから最終的な距離を計算する前に行を filter できます。
rescoring を行わない場合、ClickHouse は virtual column `_distance` を介してベクトル索引からの距離を直接使用します。
どちらのモードでも、読み取りのスケジューリングには周囲の グラニュール 範囲が引き続き使用されます。これは、通常の スキッピング索引 が index block 単位で data をスキップするのとは異なります。
`GRANULARITY` parameter は、作成されるベクトル類似度 sub-index の数を決定します。
`GRANULARITY` の値が大きいほど、ベクトル類似度 sub-index の数は少なくなりますが、それぞれは大きくなり、最終的には column (または column の data part) に sub-index が 1 つだけになる場合もあります。
その場合、その sub-index は column のすべての行を「global」に把握できるため、関連する行を含む column (part) の グラニュール を直接すべて返せます (そのような グラニュール の数は最大でも `LIMIT [N]` 個です) 。
`vector_search_with_rescoring = 1` の場合、ClickHouse はその後、該当する行位置を読み取り、それらの行について正確な距離を計算できます。
`GRANULARITY` の値が小さい場合は、各 sub-index が最大 `LIMIT N` 個の candidate rows を返せます。
その結果、より多くの candidate rows を読み込んで後段で filter する必要が生じる場合があります。
どちらの場合でも検索精度は同等で、異なるのは processing 性能だけである点に注意してください。
一般に、ベクトル類似度索引では大きな `GRANULARITY` を使用し、ベクトル類似度 structure の memory consumption が大きすぎるといった問題がある場合にのみ、より小さい `GRANULARITY` の値を使うことが推奨されます。
ベクトル類似度索引で `GRANULARITY` が指定されていない場合、デフォルト値は 1 億です。
#### 例
クエリ:
```sql title="Query" theme={null}
CREATE TABLE tab
(
id Int32,
vec Array(BFloat16),
INDEX idx vec TYPE vector_similarity('hnsw', 'L2Distance', 2)
)
ENGINE = MergeTree
ORDER BY id;
INSERT INTO tab VALUES (0, [1.0, 0.0]), (1, [1.1, 0.0]), (2, [1.2, 0.0]), (3, [1.3, 0.0]), (4, [1.4, 0.0]), (5, [1.5, 0.0]), (6, [0.0, 2.0]), (7, [0.0, 2.1]), (8, [0.0, 2.2]), (9, [0.0, 2.3]), (10, [0.0, 2.4]), (11, [0.0, 2.5]);
WITH [0., 2.] AS reference_vec
SELECT id, vec
FROM tab
ORDER BY L2Distance(vec, reference_vec) ASC
LIMIT 3;
```
```result title="Response" theme={null}
┌─id─┬─vec─────┐
1. │ 6 │ [0,2] │
2. │ 7 │ [0,2.1] │
3. │ 8 │ [0,2.2] │
└────┴─────────┘
```
近似ベクトル検索を使用する、そのほかのサンプルデータセット:
* [LAION-400M](/ja/get-started/sample-datasets/laion)
* [LAION-5B](/ja/get-started/sample-datasets/laion5b)
* [dbpedia](/ja/get-started/sample-datasets/dbpedia)
* [hackernews](/ja/get-started/sample-datasets/hacker-news-vector-search)
### 量子化コーデックを使用したベクトル検索
`Quantized` コーデックを有効にするには、まず `SET allow_experimental_codecs = 1` を設定してください。
問題が発生した場合は、[ClickHouseリポジトリ](https://github.com/clickhouse/clickhouse/issues)で issue を作成してください。
#### はじめに
[ベクトル類似度索引](#vector-similarity-index)は、グラフを走査して最近傍クエリに応答します。グラフ全体をメモリに保持できる場合、非常に高い性能を発揮します。
ただし、次の2つの条件により適用範囲が制限されます。
* **構築コストが高い。** ベクトル類似度索引の構築には多大なコストがかかります。
* **メモリ使用量が多い。** ベクトル類似度索引は大量のメモリを消費し、ベクトル自体のメモリ使用量に加えて、大きなコスト要因となります。
* **フィルタリング。** 選択性の高い `WHERE` フィルターでは、グラフ走査は有効に機能しません。述語を満たす少数の行に到達できないか、それらを見つけるために不釣り合いに多くの候補を調べる必要があるためです。
網羅スキャンには、これらの制限はいずれもありません。補助データ構造を必要とせず、パーツは連結するだけで自然にマージでき、フィルタリングではスキャン対象の行数が減るだけです。
網羅スキャンの最大の欠点は、読み取る必要があるデータ量が多いことです。フル精度の `Float32` または `BFloat16` で保存されたベクトルをスキャンする場合、ベクトルカラム全体をディスクから読み込む必要があるため、ストレージ I/O が支配的になります。
`Quantized` カラムコーデックは、この欠点を解消します。
各ベクトルを、元のフル精度の値とコンパクトな量子化表現の2通りで保存します。
ベクトル検索クエリでは、まず低コストで SIMD に適した距離関数を用いて量子化コードをスキャンし、最も有望な結果候補のショートリストを作成します。
次に、これらの候補をフル精度ベクトルに対して再ランク付けします。
量子化コードに対する初期スキャンでストレージから読み取るバイト数は、元のベクトルをスキャンする場合より大幅に少なくなります。
このコーデックは、コストの高い処理であるスキャンが、まさに ClickHouse エンジンが得意とする処理であるため、ClickHouse に適しています。
* **ベクトル化。** スキャンカーネルは SIMD 命令を活用し、CPU 使用量を削減します。
* **コアとパーツをまたいだ並列処理。** スキャンは容易に並列化できます。利用可能なすべてのスレッドとテーブルのすべてのパーツにわたって、距離が同時に計算されます。
* **分散。** 分片化されたクラスターでは、処理が複数のマシンに分散されます。各分片が自身のスライスを並列にスキャンし、コーディネーターがショートリストをマージします。
* **追加の構築コストなし。** 量子化コードはベクトルの書き込み時に生成されます。構築、調整、再構築が必要な追加の索引はないため、テーブルはデータが書き込まれるとすぐに検索可能になります。
#### コーデックの適用
`Array(Float32)` (または `Array(Float64)` / `Array(BFloat16)`) カラムに `Quantized(...)` コーデックを指定します。
```sql theme={null}
SET allow_experimental_codecs = 1;
CREATE TABLE vectors
(
id UInt32,
vec Array(BFloat16) CODEC(Quantized('rabitq', 1536))
)
ENGINE = MergeTree
ORDER BY ...;
```
コーデックは後から `ALTER TABLE` で追加または変更することはできません。
#### 量子化方式
各量子化方式には、サイズと精度の間で異なるトレードオフがあります。`dimensions` 引数はベクトル長です。
* `Quantized('rabitq', dimensions)` — 各座標に 1 ビットの符号ビットと、バイアスのないコサイン補正係数 (`dimensions/8 + 4` バイト) を持ちます。小さく、`popcount` での計算負荷が低い、強力なデフォルトです。`cosineDistance` のみ対応。
* `Quantized('turboquant', dimensions)` — 各座標に 2 ビット (1 ビットの MSE コードと 1 ビットの残差コード) を使い、より高忠実度な候補を実現します (`dimensions/4 + 4` バイト) 。`cosineDistance` のみ対応。
* `Quantized('int8', dimensions)` — 各座標に 1 つの `Int8` コードとベクトルノルムを持ちます (`dimensions + 4` バイト) 。サイズは最大ですが、最も忠実なフラットコードです。`L2Distance` と `cosineDistance` に対応します。
* `Quantized('prefix', dimensions, leading_dimensions, 'int8'|'bf16')` — Matryoshka: 先頭の `leading_dimensions` 個の座標だけを、`Int8` (ベクトルごとの scale 付き) または `BFloat16` として保持します。Matryoshka Representation Learning で学習した埋め込み向けの非常に小さなコードです。`L2Distance` と `cosineDistance` に対応します。
* `Quantized('product', dimensions, nbits, m)` — Product Quantization: パーツごとのコードブックを k-means で学習し、各ベクトルを `nbits` ビットの `m` 個のコードに変換します (そのため `dimensions` は `m` の倍数である必要があります) 。最もコンパクトな選択肢で、1 バイトあたりの再現率も最も高い一方、insert 時に学習ステップが必要です。`L2Distance` と `cosineDistance` に対応します。
`rabitq` と `turboquant` では、`dimensions` は 8 の倍数である必要があります。
#### コーデック の使用
通常の上位 `k` クエリ形式では、コーデック が自動的に使用されます ([完全検索](#exact-nearest-neighbor-search)を参照) 。
```sql theme={null}
WITH [...] AS reference_vec
SELECT id
FROM vectors
ORDER BY cosineDistance(vec, reference_vec) ASC
LIMIT 10
SETTINGS vector_search_use_quantized_codes = 1;
```
`vector_search_use_quantized_codes = 1` を設定すると、オプティマイザはクエリを2フェーズのスキャンに書き換えます。
この設定はデフォルトで無効です。
この設定を使用しない場合、同じクエリは元のベクトルに対する通常の完全スキャンとして実行されます。
すべての手法で距離関数 `cosineDistance` がサポートされます。手法 `int8`、`prefix`、`product` では、距離関数として `L2Distance` もサポートされます。
`vector_search_index_fetch_multiplier` の設定では、クエリの `LIMIT` に対してショートリストに含める候補数を指定します。
乗数を大きくすると、再スコアリングが増える代わりに再現率が向上します。
デフォルトは `1` (オーバーサンプリングなし) です。良好な再現率を得るには、通常これを (たとえば `10` に) 増やす必要があります。
### 量子化ビット (QBit)
厳密ベクトル検索を高速化する一般的な方法の 1 つは、より低精度の [float data type](/ja/reference/data-types/float) を使用することです。
たとえば、ベクトルを `Array(Float32)` ではなく `Array(BFloat16)` として保存すると、データサイズは半分になり、クエリの実行時間もそれに応じて短くなることが期待されます。
この手法は量子化として知られています。計算は高速になりますが、すべてのベクトルを総当たりで走査していても、結果の精度が低下する可能性があります。
従来の量子化では、検索時とデータ保存時の両方で精度が失われます。上の例では、`Float32` ではなく `BFloat16` を保存することになるため、あとから必要になっても、より高精度な検索は実行できません。別の方法として、量子化済みデータとフル精度データの 2 つのコピーを保存するやり方があります。これは機能しますが、余分なストレージが必要です。たとえば、元データが `Float64` で、異なる精度 (16 ビット、32 ビット、または完全な 64 ビット) で検索を実行したいケースを考えてみましょう。この場合、データのコピーを 3 つ別々に保存する必要があります。
ClickHouse は、こうした制約に対処する Quantized Bit (`QBit`) データ型を提供しており、次のことが可能です。
1. 元のフル精度データを保存する。
2. 量子化の精度をクエリ時に指定する。
これは、データをビットごとにグループ化した形式 (つまり、すべてのベクトルの i 番目のビットをまとめて保存する形式) で保存することで実現され、必要な精度レベルでのみ読み取れるようになります。これにより、必要に応じて元のデータをすべて利用できる状態を保ちながら、量子化による I/O と計算量の削減による高速化のメリットを得られます。最大精度を選択した場合、検索は厳密になります。
`QBit` 型のカラムを宣言するには、次の構文を使用します。
```sql theme={null}
column_name QBit(element_type, dimension[, stride])
```
ここで:
* `element_type` – 各ベクトル要素の型。サポートされている型は `Int8`、`BFloat16`、`Float32`、`Float64` です
* `dimension` – 各ベクトルの要素数
* `stride` – 任意。`dimension` の約数で、次元を `dimension / stride` 個の連続したグループに分割し、それぞれを別々のストリームに格納します。これにより、先頭側の次元だけを対象とする検索では、読み取るストリーム数を減らせます (Matryoshka 埋め込みで有用です)。既定値は `dimension` で、この場合、この型はストライドなしの `QBit` とバイト単位で同一です。詳細は [`QBit` data type page](/ja/reference/data-types/qbit) を参照してください。
#### `QBit` テーブルの作成とデータの追加
```sql theme={null}
CREATE TABLE fruit_animal (
word String,
vec QBit(Float64, 5)
) ENGINE = MergeTree
ORDER BY word;
INSERT INTO fruit_animal VALUES
('apple', [-0.99105519, 1.28887844, -0.43526649, -0.98520696, 0.66154391]),
('banana', [-0.69372815, 0.25587061, -0.88226235, -2.54593015, 0.05300475]),
('orange', [0.93338752, 2.06571317, -0.54612565, -1.51625717, 0.69775337]),
('dog', [0.72138876, 1.55757105, 2.10953259, -0.33961248, -0.62217325]),
('cat', [-0.56611276, 0.52267331, 1.27839863, -0.59809804, -1.26721048]),
('horse', [-0.61435682, 0.48542571, 1.21091247, -0.62530446, -1.33082533]);
```
#### `QBit` を使ったベクトル検索
L2距離を使って、単語「lemon」を表すベクトルの最近傍を見つけてみましょう。距離関数の3番目のパラメータでは、ビット単位の精度を指定します。値が大きいほど精度は高くなりますが、そのぶん必要な計算量も増えます。
`QBit` で使用できる距離関数の一覧は、[こちら](/ja/reference/data-types/qbit#vector-search-functions)で確認できます。
**フル精度検索 (64ビット) :**
```sql theme={null}
SELECT
word,
L2DistanceTransposed(vec, [-0.88693672, 1.31532824, -0.51182908, -0.99652702, 0.59907770], 64) AS distance
FROM fruit_animal
ORDER BY distance;
```
```text theme={null}
┌─word───┬────────────distance─┐
1. │ apple │ 0.14639757188169716 │
2. │ banana │ 1.998961369007679 │
3. │ orange │ 2.039041552613732 │
4. │ cat │ 2.752802631487914 │
5. │ horse │ 2.7555776805484813 │
6. │ dog │ 3.382295083120104 │
└────────┴─────────────────────┘
```
**低精度検索:**
```sql theme={null}
SELECT
word,
L2DistanceTransposed(vec, [-0.88693672, 1.31532824, -0.51182908, -0.99652702, 0.59907770], 12) AS distance
FROM fruit_animal
ORDER BY distance;
```
```text theme={null}
┌─word───┬───────────distance─┐
1. │ apple │ 0.757668703053566 │
2. │ orange │ 1.5499475034938677 │
3. │ banana │ 1.6168396735102937 │
4. │ cat │ 2.429752230904804 │
5. │ horse │ 2.524650475528617 │
6. │ dog │ 3.17766975527459 │
└────────┴────────────────────┘
```
12ビットの量子化では、距離を十分に良好に近似しつつ、クエリをより高速に実行できることがわかります。相対的な順序もおおむね保たれており、'apple' が引き続き最も近い一致です。
#### パフォーマンスに関する考慮事項
`QBit` のパフォーマンス上の利点は、精度を下げるほどストレージから読み込むデータ量が減り、I/O 操作が少なくなることにあります。さらに、`QBit` に `Float32` データが含まれている場合、精度パラメーターが 16 以下であれば、計算量の削減によるさらなる効果も得られます。精度パラメーターは、精度と速度のトレードオフを直接左右します。
* **より高い精度** (元のデータ幅に近い) : 結果はより正確になりますが、クエリは遅くなります
* **より低い精度**: 近似結果になる代わりにクエリが高速化し、メモリ使用量も削減されます
### 参考資料
ブログ:
* [ClickHouse によるベクトル検索 - 第1部](https://clickhouse.com/blog/vector-search-clickhouse-p1)
* [ClickHouse によるベクトル検索 - 第2部](https://clickhouse.com/blog/vector-search-clickhouse-p2)
* [クエリ時に精度を選べるベクトル検索エンジンを構築しました](https://clickhouse.com/blog/qbit-vector-search)