Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions docs/reference/mapping/types/dense-vector.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -91,11 +91,9 @@ PUT my-index-2
efficient kNN search. Like most kNN algorithms, HNSW is an approximate method
that sacrifices result accuracy for improved speed.

//tag::dense-vector-indexing-speed[]
NOTE: Indexing vectors for approximate kNN search is an expensive process. It
can take substantial time to ingest documents that contain vector fields with
`index` enabled.
//end::dense-vector-indexing-speed[]

Dense vector fields cannot be indexed if they are within
<<nested, `nested`>> mappings.
Expand Down
36 changes: 24 additions & 12 deletions docs/reference/search/search-your-data/knn-search.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -46,15 +46,13 @@ based on a similarity metric, the better its match.
vector function

In most cases, you'll want to use approximate kNN. Approximate kNN offers lower
latency and better support for large datasets at the cost of slower indexing and
reduced accuracy. However, you can configure this method for higher accuracy in
exchange for slower searches.
at the cost of slower indexing and imperfect accuracy.

Exact, brute-force kNN guarantees accurate results but doesn't scale well with
large, unfiltered datasets. With this approach, a `script_score` query must scan
each matched document to compute the vector function, which can result in slow
search speeds. However, you can improve latency by using the <<query-dsl,Query
DSL>> to limit the number of matched documents passed to the function. If you
large datasets. With this approach, a `script_score` query must scan each
matching document to compute the vector function, which can result in slow
search speeds. However, you can improve latency by using a <<query-dsl,query>>
to limit the number of matching documents passed to the function. If you
filter your data to a small subset of documents, you can get good search
performance using this approach.

Expand All @@ -78,8 +76,6 @@ score documents based on similarity between the query and document vector. For a
list of available metrics, see the <<dense-vector-similarity,`similarity`>>
parameter documentation.

include::{es-repo-dir}/mapping/types/dense-vector.asciidoc[tag=dense-vector-indexing-speed]

[source,console]
----
PUT my-approx-knn-index
Expand Down Expand Up @@ -156,13 +152,29 @@ most similar results from each shard. The search then merges the results from
each shard to return the global top `k` nearest neighbors.

You can increase `num_candidates` for more accurate results at the cost of
slower search speeds. A search with a high number of `num_candidates` considers
more candidates from each shard. This takes more time, but the search has a
higher probability of finding the true `k` top nearest neighbors.
slower search speeds. A search with a high value for `num_candidates`
considers more candidates from each shard. This takes more time, but the
search has a higher probability of finding the true `k` top nearest neighbors.

Similarly, you can decrease `num_candidates` for faster searches with
potentially less accurate results.

[discrete]
[[knn-indexing-considerations]]
==== Indexing considerations
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm very open to suggestions for a better name :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the reason we put this section in knnSearch guide? Isn't a better place for it the indexing section of dense-vector document?
Or we provide these kind of suggestions only in reference guides as this one?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was wondering this myself and would appreciate @jrodewig's opinion here. I was thinking of this reference as a combined "how to" for kNN search, where we offer guidance about what method to choose, other best practices, etc. I think of the API and field type docs more as specific references that don't give high-level guidance like this.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm very open to suggestions for a better name :)

I think Indexing considerations is fine. However, you could do Indexing speed if wanted.

I was thinking of this reference as a combined "how to" for kNN search, where we offer guidance about what method to choose, other best practices, etc. I think of the API and field type docs more as specific references that don't give high-level guidance like this.

Yep. That's pretty much my model of these docs. I'm okay with linking from the dense-vector docs to this section, but I think this content is a little too dense and specific to approximate kNN search for the dense-vector reference docs.


Indexing vectors for approximate kNN search can take substantial time because
of how expensive it is to build the ANN index structures. You may need to
increase the client request timeout for index and bulk requests.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of ANN, we may want to mention HNSW graphs here. We talk about them in the next paragraph without much of an introduction.

I took a stab at a suggestion, but feel free to edit or ignore if wanted.

Suggested change
Indexing vectors for approximate kNN search can take substantial time because
of how expensive it is to build the ANN index structures. You may need to
increase the client request timeout for index and bulk requests.
{es} shards are composed of segments, which are internal storage elements in the
index. For approximate kNN search, {es} stores the dense vector values of each
segment as an https://arxiv.org/abs/1603.09320[HNSW graph]. Indexing vectors for
approximate kNN search can take substantial time because of how expensive it is
to build these graphs. You may need to increase the client request timeout for
index and bulk requests.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This reorganization works nicely, I'll adopt it.


Elasticsearch shards are composed of segments, which are internal storage
elements in the index. <<indices-forcemerge,Force merging>> the index to a
single segment can improve kNN search latency. With only one segment, the
search needs to check a single, all-inclusive HNSW graph. But when there are
multiple segments, kNN search must check several smaller HNSW graphs as it
searches each segment after another. Note that you should only force merge an
index if it is no longer being written to.

[discrete]
[[approximate-knn-limitations]]
==== Limitations for approximate kNN search
Expand Down