検索API - kNN検索（kNN search） - 《Elasticsearchガイドv8.15》日本語

kNN検索API
8.4.0で非推奨。
リクエスト
前提条件
説明
パスパラメータ
クエリパラメータ
リクエストボディ
レスポンスボディ

kNN検索API

8.4.0で非推奨。

kNN検索APIは、検索APIのknnオプションに置き換えられました。

k近傍（kNN）検索を実行し、一致するドキュメントを返します。

Python

resp = client.knn_search(
   index="my-index",
   knn={
   "field": "image_vector",
   "query_vector": [
            0.3,
            0.1,
            1.2
   ],
   "k": 10,
   "num_candidates": 100
   },
   source=[
   "name",
   "file_type"
   ],
)
print(resp)

Js

const response = await client.knnSearch({
  index: "my-index",
  knn: {
   field: "image_vector",
   query_vector: [0.3, 0.1, 1.2],
   k: 10,
   num_candidates: 100,
  },
  _source: ["name", "file_type"],
});
console.log(response);

コンソール

GET my-index/_knn_search
{
  "knn": {
   "field": "image_vector",
   "query_vector": [0.3, 0.1, 1.2],
   "k": 10,
   "num_candidates": 100
  },
  "_source": ["name", "file_type"]
}

リクエスト

GET <target>/_knn_search

POST <target>/_knn_search

前提条件

Elasticsearchのセキュリティ機能が有効になっている場合、ターゲットデータストリーム、インデックス、またはエイリアスに対して、read インデックス権限を持っている必要があります。

説明

kNN検索APIは、dense_vectorフィールドに対してk近傍（kNN）検索を実行します。クエリベクトルが与えられると、k最も近いベクトルを見つけ、それらのドキュメントを検索ヒットとして返します。

Elasticsearchは、効率的なkNN検索をサポートするためにHNSWアルゴリズムを使用します。ほとんどのkNNアルゴリズムと同様に、HNSWは結果の精度を犠牲にして検索速度を向上させる近似手法です。これは、返される結果が常に真のk最も近い隣人であるとは限らないことを意味します。

kNN検索APIは、フィルターを使用して検索を制限することをサポートしています。検索は、フィルタークエリにも一致する上位kドキュメントを返します。

パスパラメータ

<target>
（オプション、文字列）検索するデータストリーム、インデックス、およびエイリアスのカンマ区切りリスト。ワイルドカード（*）をサポートします。すべてのデータストリームとインデックスを検索するには、*または_allを使用します。

クエリパラメータ

routing
（オプション、文字列）操作を特定のシャードにルーティングするために使用されるカスタム値。

リクエストボディ

filter
（オプション、[クエリDSLオブジェクト](/read/elasticsearch-8-15/adeacfff22b20f2c.md））一致する可能性のあるドキュメントをフィルタリングするためのクエリ。kNN検索は、このフィルターにも一致する上位kドキュメントを返します。この値は単一のクエリまたはクエリのリストであることができます。filterが提供されていない場合、すべてのドキュメントが一致することが許可されます。
knn
（必須、オブジェクト）実行するkNNクエリを定義します。
```
-   `````field
```
- （必須、文字列）検索対象のベクトルフィールドの名前。インデックスが有効なdense_vectorフィールドである必要があります。
- k
- （オプション、整数）上位ヒットとして返す最近傍の数。この値はnum_candidates以下でなければなりません。デフォルトはsizeです。
- num_candidates
- （オプション、整数）シャードごとに考慮する最近傍候補の数。kより大きく、kが省略された場合はsizeより大きくする必要があり、10,000を超えてはいけません。Elasticsearchは各シャードからnum_candidates結果を収集し、それらをマージして上位k結果を見つけます。num_candidatesを増やすと、最終的なk結果の精度が向上する傾向があります。デフォルトはMath.min(1.5 * k, 10_000)です。
- query_vector
- （必須、浮動小数点数または文字列の配列）クエリベクトル。検索対象のベクトルフィールドと同じ次元数である必要があります。浮動小数点数の配列または16進エンコードされたバイトベクトルである必要があります。
docvalue_fields
（オプション、文字列とオブジェクトの配列）フィールドパターンの配列。リクエストは、応答のhits.fieldsプロパティにこれらのパターンに一致するフィールド名の値を返します。
配列内のアイテムは文字列またはオブジェクトとして指定できます。ドキュメント値フィールドを参照してください。
```
-   `````field
```
- （必須、文字列）ワイルドカードパターン。リクエストは、このパターンに一致するフィールド名のドキュメント値を返します。
- format
- （オプション、文字列）ドキュメント値が返される形式。
  日付フィールドの場合、日付の日付formatを指定できます。数値フィールドの場合、DecimalFormatパターンを指定できます。
  他のフィールドデータ型については、このパラメータはサポートされていません。
fields
（オプション、文字列とオブジェクトの配列）フィールドパターンの配列。リクエストは、応答のhits.fieldsプロパティにこれらのパターンに一致するフィールド名の値を返します。
配列内のアイテムは文字列またはオブジェクトとして指定できます。fieldsオプションを参照してください。
```
-   `````field
```
- （必須、文字列）返すフィールド。ワイルドカード（*）をサポートします。
- format
- （オプション、文字列）日付および地理空間フィールドの形式。他のフィールドデータ型はこのパラメータをサポートしていません。
  dateおよびdate_nanosフィールドは日付形式を受け入れます。geo_pointおよびgeo_shapeフィールドは次のものを受け入れます：
  - geojson（デフォルト）
  - GeoJSON
  - wkt
  - Well Known Text
  - mvt(<spec>)
  - バイナリ[https://docs.mapbox.com/vector-tiles/specificationのMapboxベクタタイル]。APIはタイルをbase64エンコードされた文字列として返します。`````は//の形式で、2つのオプションのサフィックス@および/または:を持ちます。たとえば、2/0/1または2/0/1@4096:5。mvt`````パラメータ
  - <zoom>
  - （必須、整数）タイルのズームレベル。0-29を受け入れます。
  - <x>
  - （必須、整数）タイルのX座標。
  - <y>
  - （必須、整数）タイルのY座標。
  - <extent>
  - （オプション、整数）タイルの一辺のサイズ（ピクセル単位）。ベクタタイルは、等しい辺を持つ正方形です。デフォルトは4096です。
  - <buffer>
  - （オプション、整数）タイルの外側のクリッピングバッファのサイズ（ピクセル単位）。これにより、レンダラーはタイルの範囲を超えて延びるジオメトリからのアウトラインアーティファクトを回避できます。デフォルトは5です。
_source
（オプション）一致するドキュメントに対して返される@source fieldsを示します。これらのフィールドは、検索応答のhits._sourceプロパティに返されます。デフォルトはtrueです。ソースフィルタリングを参照してください。
```
-   `````true
```
- （ブール値）ドキュメント全体のソースが返されます。
- false
- （ブール値）ドキュメントソースは返されません。
- <wildcard_pattern>
- （文字列または文字列の配列）返すソースフィールドを含むワイルドカード（*）パターンまたはパターンの配列。
- <object>
- （オブジェクト）含めるまたは除外するソースフィールドのリストを含むオブジェクト。
```
-   `````excludes
```
  - （文字列または文字列の配列）応答から除外するソースフィールドを含むワイルドカード（*）パターンまたはパターンの配列。
    このプロパティを使用して、includesプロパティで指定されたサブセットからフィールドを除外することもできます。
  - includes
  - （文字列または文字列の配列）返すソースフィールドを含むワイルドカード（*）パターンまたはパターンの配列。
    このプロパティが指定されている場合、これらのソースフィールドのみが返されます。このサブセットからフィールドを除外するには、excludesプロパティを使用できます。
stored_fields
（オプション、文字列）ヒットの一部として返す保存されたフィールドのカンマ区切りリスト。フィールドが指定されていない場合、保存されたフィールドは応答に含まれません。保存されたフィールドを参照してください。
このオプションが指定されている場合、_sourceパラメータのデフォルトはfalseです。検索応答でソースフィールドと保存されたフィールドの両方を返すには、_source: trueを渡すことができます。

レスポンスボディ

kNN検索のレスポンスは、検索APIレスポンスと全く同じ構造を持っています。ただし、特定のセクションはkNN検索に特有の意味を持ちます：

ドキュメント_scoreは、クエリとドキュメントベクトルの類似性によって決定されます。similarityを参照してください。
hits.totalオブジェクトには、考慮された最近傍候補の総数が含まれ、これはnum_candidates * num_shardsです。hits.total.relationは常にeqであり、正確な値を示します。