ベクトル検索 - Java 向け Tablestore SDK - Tablestore - Alibaba Cloud ドキュメントセンター

前提条件

Java 向け Tablestore SDK をインストールして、クライアントを初期化します。ベクトル検索にはバージョン 5.17.0 以降が必要です。
minScore または numCandidates を設定するには、バージョン 5.17.5 以降を使用してください。

機能の説明

ベクトル検索では、クエリベクトルとベクトルフィールド内のベクトルの間で近似最近傍 (ANN) 探索を実行します。Tablestore は、検索インデックスの作成時に設定された距離メトリックで結果をスコアリングし、最も近いデータを返します。フィールド値に一致するクエリとは異なり、ベクトル検索はベクトル間の距離から類似度を判定します。

search を呼び出し、query に KnnVectorQuery を設定します。

SearchResponse search(SearchRequest request)

次の例では、embedding フィールド内で [1.0, 0.0, 0.0, 0.0] に最も近い 3 つのベクトルを取得します。結果はスコアの降順でソートされます。

String tableName = "example_table";
String indexName = "example_index";
KnnVectorQuery query = new KnnVectorQuery();
query.setFieldName("embedding");
query.setTopK(3);
query.setFloat32QueryVector(new float[]{1.0f, 0.0f, 0.0f, 0.0f});

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(query);
searchQuery.setLimit(3);
searchQuery.setSort(new Sort(Collections.singletonList(new ScoreSort())));

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAll(true);
request.setColumnsToGet(columnsToGet);

SearchResponse response = client.search(request);
for (SearchHit hit : response.getSearchHits()) {
    System.out.println(hit.getScore() + ": " + hit.getRow());
}

説明

ベクトルフィールドの数とディメンション、および topK には制限があります。詳細については、「Search index limits」をご参照ください。

パラメータ

検索リクエスト

request は SearchRequest オブジェクトであり、次のパラメータが含まれます。

名前	型	説明
tableName (必須)	String	テーブル名。
indexName (必須)	String	検索インデックス名。
searchQuery (必須)	SearchQuery	クエリ条件および共通のクエリ設定。
columnsToGet (オプション)	SearchRequest.ColumnsToGet	返される列の設定。このパラメータを設定しない場合、プライマリキー列のみが返されます。
timeoutInMillisecond (オプション)	int	リクエストレベルのクエリタイムアウト (ミリ秒)。デフォルトは `-1` で、この場合、個別のクエリタイムアウトは設定されません。
routingValues (オプション)	`List<PrimaryKey>`	カスタムルーティングフィールドのプライマリキー値。カスタムルーティングが設定されていない場合は、このパラメータを設定しないでください。

クエリ設定

request.searchQuery は SearchQuery オブジェクトであり、次のパラメータが含まれます。

名前	型	説明
query (必須)	Query	クエリ条件。ベクトル検索の場合、このパラメータを `KnnVectorQuery` に設定してください。
offset (オプション)	Integer	クエリを開始する位置。
limit (オプション)	Integer	返す行の最大数。このパラメータを `0` に設定すると、行は返されません。
highlight (オプション)	Highlight	サマリーおよびハイライトの設定。ベクトルフィールドはサマリーとハイライトをサポートしません。
collapse (オプション)	Collapse	指定した列に基づき、結果の重複排除を行うための折りたたみ設定。
sort (オプション)	Sort	結果のソート順。スコアでソートするには `ScoreSort` を使用してください。
trackTotalCount (オプション)	int	カウントする一致行数の最大値。デフォルトは `TRACK_TOTAL_COUNT_DISABLED` で、この場合はカウントが無効になります。すべての一致行をカウントするには、このパラメータを `TRACK_TOTAL_COUNT` に設定してください。小さい値を指定するとクエリパフォーマンスが向上します。
filter (オプション)	SearchFilter	`query` の結果に適用するフィルター。
aggregationList (オプション)	`List<Aggregation>`	集約の設定。
groupByList (オプション)	`List<GroupBy>`	グルーピングの設定。
token (オプション)	byte[]	ページネーショントークン。追加のデータを取得するには、このパラメータに前回のレスポンスの `nextToken` を設定してください。各サーバー側のインデックスパーティションは、それぞれ独自の `topK` の最近傍値を返し、それらが調整ノードでマージされます。そのため、`token` を使用してページネーションを行う場合、返される行の累積数はサーバー側のインデックスパーティション数に依存します。

ベクトルクエリ条件

request.searchQuery.query は KnnVectorQuery オブジェクトであり、次のパラメータが含まれます。

名前	型	説明
fieldName (必須)	String	ベクトルフィールド名。フィールドは Vector 型である必要があり、クエリベクトルのディメンションは、検索インデックスの作成時に設定したディメンションと一致する必要があります。
topK (必須)	Integer	取得する最近傍ベクトルの数。最大：`1000`。大きい値を指定すると、より多くの候補が返され、再現率が向上する可能性がありますが、クエリレイテンシーとコストが増加する場合があります。
float32QueryVector (必須)	float[]	類似度の計算に使用する Float32 のクエリベクトル。配列長はベクトルフィールドのディメンションと一致する必要があります。
filter (オプション)	Query	ベクトル検索の結果が満たす必要がある非ベクトルのクエリ条件。複数の非ベクトル `Query` オブジェクトを組み合わせることができます。
weight (オプション)	Float	ベクトルクエリの関連性の重み。値は `0` 以上である必要があります。デフォルト：`1.0`。大きい値を指定すると、一致する行を変更せずに、ベクトルクエリのスコアが最終的な関連度スコアに与える影響が大きくなります。
minScore (オプション)	Float	最小スコアのしきい値。値は `0` 以上である必要があります。デフォルト：`0`。スコアがこの値より大きいデータのみが返されます。
numCandidates (オプション)	Integer	最近傍を計算する際に、各インデックスパーティションでアクセスする候補数。有効な値：`[topK, 1000]`。大きい値を指定すると再現率が向上する可能性がありますが、クエリ時間が増加する場合があります。

返される列

request.columnsToGet は SearchRequest.ColumnsToGet オブジェクトであり、次のパラメータが含まれます。

名前	型	説明
columns (オプション)	`List<String>`	返す属性列。`returnAll` と `returnAllFromIndex` がどちらも `false` の場合にのみ、このパラメータを設定してください。このパラメータを設定しない場合、プライマリキー列のみが返されます。
returnAll (オプション)	boolean	テーブル内のすべての属性列を返すかどうかを指定します。デフォルト：`false`。
returnAllFromIndex (オプション)	boolean	インデックス化されたすべての属性列を返すかどうかを指定します。デフォルト：`false`。このパラメータと `returnAll` を同時に `true` に設定することはできません。

レスポンス

検索レスポンス

search は SearchResponse オブジェクトを返します。次の表に、主要フィールドを示します。

名前	型	説明
totalCount	long	一致する行数。値は `getTotalCount()` を呼び出して取得します。返される値は `trackTotalCount` に依存します。
rows	`List<Row>`	このクエリで返される行。値は `getRows()` を呼び出して取得します。返される行数は `limit` を超えません。
searchHits	`List<SearchHit>`	検索ヒット。値を取得するには `getSearchHits()` を呼び出して、行とスコアを取得します。
nextToken	byte[]	次ページのトークン。値は `getNextToken()` を呼び出して取得します。値が `null` でない場合、次のリクエストでこの値を `token` として渡すことで、追加のデータを取得できます。
isAllSuccess	boolean	すべてのインデックスパーティションがクエリされたかどうかを示します。値は `isAllSuccess()` を呼び出して取得します。このフィールドが `false` の場合、レスポンスには部分的な結果が含まれ、`totalCount` は実際の一致行数より少ない可能性があります。

検索ヒット

response.searchHits[] の各要素は SearchHit オブジェクトであり、次の主要フィールドが含まれます。

名前	型	説明
row	Row	一致した行。値は `getRow()` を呼び出して取得します。
score	Double	ベクトルクエリのスコア。値は `getScore()` を呼び出して取得します。距離メトリックと `weight` がこの値に影響します。

例

非ベクトル条件と最小スコアによるフィルタリング

filter を使用して最近傍が非ベクトルのクエリ条件を満たすように指定し、minScore を使用してスコアがしきい値以下のデータを除外します。次の例では、category が book、price が 4 未満で、ベクトルのスコアが 0.6 を超えるデータのみを返します。

KnnVectorQuery filteredQuery = new KnnVectorQuery();
filteredQuery.setFieldName("embedding");
filteredQuery.setTopK(10);
filteredQuery.setFloat32QueryVector(
        new float[]{1.0f, 0.0f, 0.0f, 0.0f});
filteredQuery.setMinScore(0.6f);
filteredQuery.setFilter(QueryBuilders.bool()
        .must(QueryBuilders.term("category", "book"))
        .must(QueryBuilders.range("price").lessThan(4)));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(filteredQuery);
searchQuery.setLimit(10);

候補数の調整

numCandidates を設定すると、最近傍を計算する際に各インデックスパーティションでアクセスする候補セットを拡大できます。次の例では、4 つの候補から最も近い 3 つのベクトルを取得します。

KnnVectorQuery candidateQuery = new KnnVectorQuery();
candidateQuery.setFieldName("embedding");
candidateQuery.setTopK(3);
candidateQuery.setFloat32QueryVector(
        new float[]{1.0f, 0.0f, 0.0f, 0.0f});
candidateQuery.setNumCandidates(4);

SearchQuery candidateSearchQuery = new SearchQuery();
candidateSearchQuery.setQuery(candidateQuery);
candidateSearchQuery.setLimit(3);

Tablestore:ベクトル検索