AWS Builder Center
OpenSearch Vector Search Tutorial: k-NN and Embeddings

OpenSearch Vector Search Tutorial: k-NN and Embeddings

In this article, you create a vector index, store an embedding, and run a k-nearest-neighbors query to find results by similarity instead of exact words.

Series: Search on OpenSearch (8 articles)

  1. …
  2. 6
    OpenSearch Vector Search Tutorial: k-NN and Embeddings This article
OpenSearch Specialist Solutions Architect at AWS
Every query so far matched the literal words you typed. But "a wizard school story" and "Harry Potter" share no keywords, yet a reader means the same thing. Vector search closes that gap by representing text as numbers that capture meaning, then finding the closest ones. This article introduces the mechanics: the  knn_vector  field, embeddings, and the  knn  query.
This is Part 6 of a beginner series on search with  Amazon OpenSearch Service . Use a Vector search collection created with NextGen Express Create (Part 1 set up the fast path), and OpenSearch Dashboards Dev Tools.

Embeddings and k-NN, in plain terms

An embedding is a list of numbers (a vector) that represents the meaning of a piece of text or an image. Items with similar meaning have vectors that sit close together in space. k-nearest-neighbors (k-NN) search takes a query vector and returns the  k  stored vectors closest to it. "Closest" is measured by a space type, such as  l2  (Euclidean distance).
Real embeddings are produced by an embedding model and typically have hundreds or thousands of dimensions. To learn the mechanics without wiring up a model, this article uses tiny three-number vectors you write by hand. Part 7 shows how to get semantic search without hosting a model at all.

Create a vector index

A vector field is declared with the  knn_vector  type. Enable k-NN on the index, set the  dimension  to match your vectors, and choose a  space_type  and method. OpenSearch supports the HNSW (Hierarchical Navigable Small Worlds) method, which returns approximate nearest neighbors quickly.
PUT book-vectors
{
"settings": { "index.knn": true },
"mappings": {
"properties": {
"title": { "type": "text" },
"title_vector": {
"type": "knn_vector",
"dimension": 3,
"space_type": "l2",
"method": { "name": "hnsw" }
}
}
}
}
On a NextGen vector search collection, the API is simplified: you do not specify the  engine  or  mode  parameters, because the collection determines the optimal configuration internally.

Add documents with vectors

Index a few books, each with a hand-written vector standing in for its embedding.
POST book-vectors/_doc
{ "title": "A Wizard of Earthsea", "title_vector": [0.9, 0.1, 0.2] }

POST book-vectors/_doc
{ "title": "The Hobbit", "title_vector": [0.8, 0.2, 0.1] }

POST book-vectors/_doc
{ "title": "A Brief History of Time", "title_vector": [0.1, 0.9, 0.8] }
The first two vectors are close to each other (both fantasy), and the third sits far away (science). NextGen vector collections have a read-after-write latency of about 10 seconds, so wait a moment before searching.

Run a k-NN query

The  knn  query takes a query vector and a  k , and returns the  k  nearest documents.
GET book-vectors/_search
{
"size": 3,
"query": {
"knn": {
"title_vector": {
"vector": [0.85, 0.15, 0.15],
"k": 3
}
}
}
}
The query vector sits near the two fantasy titles, so they come back first, and the science title ranks last, even though no words matched. That is search by meaning. By default, NextGen vector collections exclude the stored vector from the response to reduce payload size and latency.

Combine k-NN with filters

Vector search composes with the structured filters from Part 3. You can require an exact attribute while still ranking by similarity, using the  filter  inside the  knn  query.
GET book-vectors/_search
{
"query": {
"knn": {
"title_vector": {
"vector": [0.85, 0.15, 0.15],
"k": 3,
"filter": { "range": { "year": { "gte": 2000 } } }
}
}
}
}

What to remember

  • An embedding turns meaning into a vector; k-NN finds the nearest vectors.
  • Declare the field as  knn_vector  with a  dimension  that matches your model, and set  index.knn: true .
  • On NextGen vector collections, skip  engine  and  mode ; the collection optimizes for you.
  • The hard part in production is generating the embeddings. That is exactly what Part 7 removes.

Where this series goes next

You have run search by similarity, but you supplied the vectors yourself. In Part 7, you use Automatic Semantic Enrichment, an OpenSearch Serverless feature that generates the vectors for you at indexing time, so a plain search gains semantic understanding without you hosting or calling a model.
If your k-NN query returns unexpected neighbors, share your  dimension ,  space_type , and a couple of vectors, and I will help you reason about the distances.

Series: Search on OpenSearch (8 articles)

  1. …
  2. 6
    OpenSearch Vector Search Tutorial: k-NN and Embeddings This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article