scylladb-vector-search

ScyllaDB Vector Search

このスキルの範囲を超えるタスクでは、親の scylladb スキルを使用して、ScyllaDB の概要とその他の ScyllaDB スキルの一覧を確認してください。インストールされていない場合は、https://raw.githubusercontent.com/scylladb/agent-skills/main/skills/scylladb/SKILL.md から取得してください。

Vector Search は、vector<float, N> 列に埋め込みを保存し、HNSW ベクトルインデックスを使用して近似最近傍（ANN）クエリに応答します。本番環境では ScyllaDB Cloud でのみ利用できます。インデックスはテーブルの外部で管理されるため、TRUNCATE ではクリアされません。

このスキルを使用する場合

• ScyllaDB に埋め込みを保存して類似性検索を実行したい
• ScyllaDB 上にセマンティック検索、RAG、またはレコメンデーションシステムを構築している
• ベクトルインデックスを作成する、または HNSW パラメーターを調整する
• ANN クエリを他の列のフィルターと組み合わせる必要がある
• 量子化を使ってベクトルインデックスのメモリを削減したい
• vector CQL 型をサポートするドライバーのバージョンが必要
• Docker で Vector Search をローカルまたは CI 上で試したい

関連するトピックには、代わりに次の兄弟スキルを使用してください。

• スキーマのベクトル以外の部分におけるパーティションキーとテーブル設計：scylladb-data-modeling
• Cloud クラスターへの接続とドライバーの選択：scylladb-cloud-setup
• CQL ではなく DynamoDB API を介した類似性検索：scylladb-alternator

Vector Search の実行場所

• 本番環境：ScyllaDB Cloud のみ。 Vector Search は専用のインデックス作成ノード上で実行されます。これらのノードは ScyllaDB Cloud によって管理され、CDC を介してストレージノードから同期されます。セルフホスト環境とオンプレミス環境はサポートされていません。本番環境でこれらのいずれかを計画しているユーザーには、Vector Search を利用するには Vector Search が有効な標準の ScyllaDB Cloud クラスターが必要であると伝えてください。
• 開発とテスト：ローカル Docker。 ScyllaDB コンテナーと、接続先の ScyllaDB コンテナーとは別の scylladb/vector-store コンテナー（インデックス作成サービス）を実行します。local-docker を参照してください。

基本原則

1. 構築前に理解する — Vector Search が適切なソリューションであることを確認するため、ユースケースを検証します
2. 最初にスキーマを調べる — 推奨を行う前に、既存のテーブルとインデックスを確認します
3. 実行前に説明する — 作成するインデックスについて説明し、続行する前に確認を取ります
4. デフォルト設定から始める — デフォルトの HNSW パラメーターを使用し、量子化は行いません。必要な場合にのみ調整します

ワークフロー

1. 調査フェーズ

ユースケースを理解する：

• どのような種類のデータを検索しますか？（テキスト、画像、音声、構造化データ）
• どの埋め込みモデルを使用していますか、または使用する予定ですか？
• いくつのベクトルを保存しますか？（量子化の判断に影響します）
• 類似性検索と併せてフィルタリングが必要ですか？（インデックスの種類：グローバルまたはローカルに影響します）
• レイテンシーとスループットにどのような要件がありますか？

一般的なユースケース：

• セマンティック検索 — クエリの意味と一致するドキュメントや文章を検索する
• RAG（検索拡張生成） — LLM に関連するコンテキストを提供する
• レコメンデーションシステム — ユーザーが操作したアイテムに類似するアイテムを検索する
• 画像・音声検索 — 視覚的または音響的に類似するメディアを検索する
• 異常検知 — ベクトル空間のクラスタから遠く離れた外れ値を特定する
• 重複排除 — ほぼ重複するレコードを検索する

2. 要件の決定

テーブルとインデックスを作成する前に、次の項目を明確にします。

パラメーター	決定方法
次元数	埋め込みモデルから確認します（例：384、768、1536）
類似度関数	埋め込みモデルのドキュメントから確認します（COSINE はデフォルトで、ほとんどの場合に安全です）
フィルタリングの要否	クエリで類似性とメタデータの条件を組み合わせますか？
データセットのサイズ	100 万ベクトル未満 → 量子化なし、100 万～1,000 万 → i8 を検討、1,000 万超 → b1 を検討

3. リファレンスファイルの参照

インデックスやクエリを推奨する前に、必ずクイックリファレンスにある該当ファイルを参照してください。

4. 実装

一般的な実装順序：

1. キースペースを作成します（デフォルトでタブレットが有効です）
2. vector<float, N> 列を含むテーブルを作成します
3. ベクトルを挿入します（埋め込みパイプラインから）
4. ベクトルインデックスを作成します（CREATE CUSTOM INDEX ... USING 'vector_index'）
5. ANN クエリを実行します（ORDER BY vec_col ANN OF [...] LIMIT k）
6. 必要に応じてフィルタリングを追加します（パフォーマンスのため、ローカルインデックスを推奨します）
7. メモリを節約する必要があれば、量子化を追加します

5. 検証

セットアップ後、次の点を確認します：

• ANN クエリが結果を返すこと（書き込みからクエリまでの遅延を考慮し、ベクトルの挿入後に約 1 秒待ちます）
• 類似度スコアが想定範囲内（0～1）であること（値が高いほど類似しています）
• フィルタリングされたクエリが正しく結果を絞り込んでいること

避けるべきアンチパターン

ローカルインデックスで対応できる場合、ベクトル検索で ALLOW FILTERING を絶対に使用しないでください： グローバルベクトルインデックスでは、WHERE 句を追加する際に ALLOW FILTERING が必要となり、ローカルインデックスより常に大幅に遅くなります。フィルター対象の列がパーティションキーの一部となるようにスキーマを設計し、ローカルベクトルインデックスを使用してください。

埋め込みモデルを絶対に混在させないでください： 異なる埋め込みモデルのベクトルは、互換性のないベクトル空間に属します。モデルを変更する場合は、すべてのデータを再度埋め込み、インデックスを再作成する必要があります。

LIMIT 句を絶対に省略しないでください： ANN クエリには LIMIT が必要です。指定しないと、ScyllaDB はクエリを拒否します。

エッジケースへの対処

ユーザーがまだ埋め込みモデルを用意していない場合：

• まず all-MiniLM-L6-v2（384 次元、オープンウェイト、汎用用途に適しています）を使うことを推奨します
• 本番環境では、OpenAI または Cohere の埋め込みモデルの評価を提案します

ユーザーのクラスターで Vector Search が有効になっていない場合：

• ScyllaDB Cloud UI → クラスター設定 → Vector Search を有効にするよう案内します
• セットアップ方法については、Vector Search Deployments を参照してください
• ローカルの Docker セットアップでは、vector-store コンテナーが実行中であることと、ScyllaDB に --vector-store-primary-uri が設定されていることを確認します（local-docker を参照）

クエリが結果を返さない場合：

• 書き込みからクエリまでの遅延を確認します（挿入後、約 1 秒待ちます）
• クエリベクトルの次元数がインデックスの次元数と一致することを確認します
• インデックスが正常に作成されたことを確認します
• インデックス作成時とクエリ時に同じ埋め込みモデルが使われていることを確認します

TTL が必要な場合：

• ベクトルインデックスは TTL をサポートしていません。回避策として、バックグラウンドジョブで期限切れの行を削除するアプリケーションレベルの削除を使用します。

ユーザーがすべてのベクトルを消去（テーブルをリセット）したい場合：

• TRUNCATE ではベクトルインデックスは消去されません。ベクトルストアは CDC を通じてのみインデックスを更新しますが、TRUNCATE は CDC に伝播されません。そのため、CUSTOM INDEX は残り、以前にインデックス化されたベクトルはメモリに残ります。
• 正しい解決策は、テーブルとカスタムインデックスの両方を削除して再作成することだけです。正確な DDL については、vector-type-and-indexing を参照してください。

クイックリファレンス

• vector-type-and-indexing — vector 型、タブレットの要件、CREATE CUSTOM INDEX ... USING 'vector_index'、類似度関数、HNSW パラメーター、そして TRUNCATE でインデックスがクリアされない理由について説明します。ベクターテーブルやインデックスを作成する前、またはユーザーがベクターデータのリセットを希望する場合に参照してください。
• ann-queries — ORDER BY ... ANN OF ... LIMIT の構文、類似度スコア、書き込みからクエリまでのレイテンシ、ANN クエリでサポートされない CQL 機能について説明します。ANN クエリの作成やデバッグ時に参照してください。
• filtering — グローバルベクターインデックスとローカルベクターインデックスの違い、フィルタリング検索やマルチテナント検索のスキーマ設計、およびそれらの制限について説明します。ANN クエリに WHERE 句が必要な場合に参照してください。
• quantization — 量子化レベル（f16、bf16、i8、b1）、オーバーサンプリング、再スコアリング、および作成後にインデックスオプションを変更できない理由について説明します。データセットが約 100 万ベクターを超える場合や、インデックスのメモリ使用量が懸念される場合に参照してください。
• driver-integration — vector 型に必要なドライバーの最低バージョンと、Python、Java、Go、Node.js での挿入・クエリの例について説明します。ベクターを読み書きするアプリケーションコードを作成する際に参照してください。
• local-docker — ScyllaDB と Vector Store サービスを Docker で一緒に実行する方法、それらを接続するフラグと環境変数、およびこの構成が本番環境向けではない理由について説明します。ユーザーがローカル、CI、またはテスト環境で Vector Search を使いたい場合や、ScyllaDB Cloud クラスターがない場合に参照してください。