Skip to content

Commit

Permalink
Adds documentation for dynamic query parameters
Browse files Browse the repository at this point in the history
Signed-off-by: Tejas Shah <[email protected]>
  • Loading branch information
shatejas committed Jul 17, 2024
1 parent e05b400 commit b1b17b6
Showing 1 changed file with 45 additions and 1 deletion.
46 changes: 45 additions & 1 deletion _search-plugins/knn/approximate-knn.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ The following table provides examples of the number of results returned by vario
10 | 1 | 1 | 4 | 4 | 1
10 | 10 | 1 | 4 | 10 | 10
10 | 1 | 2 | 4 | 8 | 2

The number of results returned by Faiss/NMSLIB differs from the number of results returned by Lucene only when `k` is smaller than `size`. If `k` and `size` are equal, all engines return the same number of results.

Starting in OpenSearch 2.14, you can use `k`, `min_score`, or `max_distance` for [radial search]({{site.url}}{{site.baseurl}}/search-plugins/knn/radial-search-knn/).
Expand Down Expand Up @@ -256,6 +256,50 @@ POST _bulk

After data is ingested, it can be search just like any other `knn_vector` field!

### Additional query parameters
Starting with version 2.16, k-NN plugin supports additional method parameters to tune search results. This can be done by providing the right values in `method_parameters` section of the query. Here is an example of the query

```json
GET my-knn-index-1/_search
{
"size": 2,
"query": {
"knn": {
"my_vector2": {
"vector": [2, 3, 5, 6],
"k": 2,
"method_parameters" : {
"ef_search": 100
}
}
}
}
}
```
These parameters are dependent on the combination of engine and method used to build the index. The tables below will help with the valid set of parameters. Invalid combination of parameters will throw an error

Check warning on line 279 in _search-plugins/knn/approximate-knn.md

View workflow job for this annotation

GitHub Actions / style-job

[vale] reported by reviewdog 🐶 [OpenSearch.DirectionAboveBelow] Use 'following or later' instead of 'below' for versions or orientation within a document. Use 'above' and 'below' only for physical space or screen descriptions. Raw Output: {"message": "[OpenSearch.DirectionAboveBelow] Use 'following or later' instead of 'below' for versions or orientation within a document. Use 'above' and 'below' only for physical space or screen descriptions.", "location": {"path": "_search-plugins/knn/approximate-knn.md", "range": {"start": {"line": 279, "column": 108}}}, "severity": "WARNING"}

#### Hnsw

Check failure on line 281 in _search-plugins/knn/approximate-knn.md

View workflow job for this annotation

GitHub Actions / style-job

[vale] reported by reviewdog 🐶 [OpenSearch.Spelling] Error: Hnsw. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks. Raw Output: {"message": "[OpenSearch.Spelling] Error: Hnsw. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_search-plugins/knn/approximate-knn.md", "range": {"start": {"line": 281, "column": 6}}}, "severity": "ERROR"}

**ef_search**

Explores the `ef_search` number of vectors to find top k nearest neighbors. Higher value will help improve recall at the cost of search latency. The value must be greater than 0

Supported Engines | Radial query support | Notes

Check failure on line 287 in _search-plugins/knn/approximate-knn.md

View workflow job for this annotation

GitHub Actions / style-job

[vale] reported by reviewdog 🐶 [OpenSearch.TableHeadings] 'Supported Engines' is a table heading and should be in sentence case. Raw Output: {"message": "[OpenSearch.TableHeadings] 'Supported Engines' is a table heading and should be in sentence case.", "location": {"path": "_search-plugins/knn/approximate-knn.md", "range": {"start": {"line": 287, "column": 1}}}, "severity": "ERROR"}
:--- | :--- | :---
nmslib | no | Overrides the value in index settings if present in search query
faiss | yes | Overrides the value in index settings if present in search query

Check failure on line 290 in _search-plugins/knn/approximate-knn.md

View workflow job for this annotation

GitHub Actions / style-job

[vale] reported by reviewdog 🐶 [Vale.Terms] Use 'Faiss' instead of 'faiss'. Raw Output: {"message": "[Vale.Terms] Use 'Faiss' instead of 'faiss'.", "location": {"path": "_search-plugins/knn/approximate-knn.md", "range": {"start": {"line": 290, "column": 1}}}, "severity": "ERROR"}

Check failure on line 290 in _search-plugins/knn/approximate-knn.md

View workflow job for this annotation

GitHub Actions / style-job

[vale] reported by reviewdog 🐶 [OpenSearch.Spelling] Error: faiss. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks. Raw Output: {"message": "[OpenSearch.Spelling] Error: faiss. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_search-plugins/knn/approximate-knn.md", "range": {"start": {"line": 290, "column": 1}}}, "severity": "ERROR"}
lucene | no | Engine supports `k` or `ef_search`. The final result can be controlled by `size`. k-NN plugin will pick `max(k, ef_search)`

#### IVF

**nprobes**

Check failure on line 295 in _search-plugins/knn/approximate-knn.md

View workflow job for this annotation

GitHub Actions / style-job

[vale] reported by reviewdog 🐶 [OpenSearch.Spelling] Error: nprobes. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks. Raw Output: {"message": "[OpenSearch.Spelling] Error: nprobes. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_search-plugins/knn/approximate-knn.md", "range": {"start": {"line": 295, "column": 3}}}, "severity": "ERROR"}

Explores `nprobes` number of clusters to find the top k nearest neighbors. Higher value will help improve recall at the cost of search latency. The value must be greater than 0

Supported Engines | Notes

Check failure on line 299 in _search-plugins/knn/approximate-knn.md

View workflow job for this annotation

GitHub Actions / style-job

[vale] reported by reviewdog 🐶 [OpenSearch.TableHeadings] 'Supported Engines' is a table heading and should be in sentence case. Raw Output: {"message": "[OpenSearch.TableHeadings] 'Supported Engines' is a table heading and should be in sentence case.", "location": {"path": "_search-plugins/knn/approximate-knn.md", "range": {"start": {"line": 299, "column": 1}}}, "severity": "ERROR"}
:--- | :---
faiss | Overrides the value in index settings if present in search query

### Using approximate k-NN with filters

To learn about using filters with k-NN search, see [k-NN search with filters]({{site.url}}{{site.baseurl}}/search-plugins/knn/filter-search-knn/).
Expand Down

0 comments on commit b1b17b6

Please sign in to comment.