For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Choose settings for OpenSearch k-NN indexes based on your embedding model, data size, query patterns, and performance goals. These settings affect recall, query latency, indexing speed, memory usage, and how easily you can change your index later.

Before you create a k-NN index, choose the vector dimension, k-NN engine, space type, HNSW parameters, shard count, replica count, and refresh interval.

Match Settings to Your Embedding Model

Your embedding model determines two important index settings:

• dimension: Value must match the number of dimensions produced by your embedding model. Common values include 384 for MiniLM, 768 for BERT-family models, 1024 for bge-large and gte-large, and 1536 for OpenAI text-embedding-3-small.
• space_type: Value must match the similarity metric recommended by your embedding model. Use cosinesimil for most text embedding models, innerproduct when the model outputs normalized vectors or recommends dot product, and l2 for models trained with Euclidean distance.

You can’t change the dimension or space_type of an existing knn_vector field, so set them correctly before indexing documents.

Use Faiss or Lucene for New Workloads

OpenSearch supports multiple k-NN engines, but Faiss and Lucene are the recommended choices for new vector workloads:

• Use Faiss for most new vector workloads. Faiss supports high-throughput vector search at scale and supports quantization options that can reduce memory usage.
• Use Lucene when you want tighter integration with OpenSearch indexing, filtering, and segment behavior.
• Use NMSLIB only when you need compatibility with older indexes. Don’t use NMSLIB for new workloads.

Both Faiss and Lucene can apply filters during graph traversal, which helps filtered k-NN queries return accurate results.

Start with Default HNSW Parameters

HNSW parameters control the tradeoff between recall, memory usage, build time, and query latency.

Start with the default values unless you have measured recall or latency problems with representative queries.

We recommend tuning ef_search first because you can change it without rebuilding the index. Increase m or ef_construction only when query-time tuning is not enough, because those settings require reindexing.

In general, tune HNSW parameters based on the tradeoff you want to make:

• Increase ef_search when you need higher recall and can accept higher query latency.
• Increase m when you need better graph connectivity and can accept higher memory usage and slower indexing.
• Increase ef_construction when you need a higher-quality graph and can accept slower index builds.

Start with Fewer Shards

Shard count controls how many partitions OpenSearch splits an index into. Each shard maintains its own k-NN graph, so more shards can add memory and query overhead.

Start with one or two shards for most k-NN indexes.

OpenSearch builds HNSW graphs per shard. More shards can reduce recall because each shard searches its own graph before OpenSearch merges results. If you increase the number of shards, you may also need to increase ef_search to preserve recall.

Increase shard count only when a single shard becomes too large for your workload or cluster size.

Use Replicas for Availability and Read Scaling

Replica count controls how many copies of each primary shard OpenSearch creates. Replicas improve availability and can increase read capacity, but they also use more storage and add indexing overhead.

Use replicas when you need better availability or more read capacity.

For development or testing, one replica may not be necessary. For production workloads, use replicas based on your availability and read-scaling requirements.

Increase Refresh Intervals During Bulk Ingestion

The refresh_interval setting controls how often OpenSearch makes newly indexed documents searchable.

The default refresh behavior can add overhead during bulk ingestion because OpenSearch refreshes frequently while you are still loading data. For bulk indexing, use a longer refresh interval, such as 30s, to reduce indexing overhead.

After ingestion, lower the refresh interval if your application needs newly indexed documents to become searchable quickly.

Store Metadata for Filtered Queries

Store metadata fields alongside your vector field, so you can filter k-NN queries.

Common metadata fields include:

• source
• created_at
• account_id
• project_id
• document_type
• language
• permissions

Use keyword, date, numeric, or boolean fields for metadata you need to filter on. This helps keep vector search scoped to the right customer, project, document type, permission boundary, or time range.

Reindex to Change Immutable Vector Settings

Some mapping changes are allowed after index creation, but vector field settings are limited.

You can add a new knn_vector field to an existing index. For example, you can add a summary_embedding field if the index already has an embedding field.

Changing embedding models also requires you to recompute embeddings, because different models may use different dimensions or similarity behavior.

Choose Exact k-NN for Small Datasets

Approximate k-NN is useful for larger datasets because it avoids comparing the query vector against every stored vector.

For small datasets, exact k-NN can be simpler and provides exact recall. Use exact k-NN if you have fewer than about 10,000 vectors or if filters usually reduce the candidate set to a small number of vectors.