Skip to content

docs: added opensearch-jvector plugin docs #12866

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kush992 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: added opensearch-jvector plugin docs #12866

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c9a9102
docs: added opensearch-jvector plugin docs
kush992 Jul 28, 2026
9621e66
chore: corrected name in opensearch-jvector docs
kush992 Jul 28, 2026
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
1 change: 1 addition & 0 deletions _install-and-configure/additional-plugins/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ There are many more plugins available in addition to those provided by the stand
| `store-smb` | 1.0.0 |
| `transport-grpc` | 3.0.0 |
| `workload-management` | 2.18.0 |
| [`opensearch-jvector`]({{site.url}}{{site.baseurl}}/install-and-configure/additional-plugins/opensearch-jvector/) | 3.5.0 |

## Related documentation

Expand Down
68 changes: 68 additions & 0 deletions _install-and-configure/additional-plugins/opensearch-jvector.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
layout: default
title: Opensearch-jvector plugin
parent: Installing plugins
nav_order: 30

---

# Opensearch-jvector plugin

The `opensearch-jvector` plugin enables running the nearest neighbor search on billions of documents with upto 16,000 dimensions with the same ease as running any regular OpenSearch query. Aggregations and filter clauses can be applied to further refine similarity search operations.

## Differences between opensearch-jvector and k-NN

The following table highlights the differences that matter most when choosing between the built-in `k-NN` plugin and `opensearch-jvector`:

| Aspect | `k-NN` | `opensearch-jvector` |
| :----------------------- | :--------------------------------------- | :------------------------------------------------------------------------ |
| **Vector engines** | `Nmslib`, `Faiss`, `lucene` | `jvector` (primary), `lucene` |
| **Concurrent ingestion** | Supported by some vector engines | `jvector` supports concurrent inserts, enabling high-throughput ingestion |
| **Index update cost** | Usually a full rebuild required on merge | Incremental merges — no full rebuilds for updates |
| **Memory efficiency** | In-memory indexing | DiskANN-style quantization |

## Use cases of plugin

`opensearch-jvector` is a strong choice when any of the following apply to your workload:

- **Your data grows continuously.** Incremental index updates and concurrent ingestion avoid the costly full rebuilds that occur with k-NN on high-update workloads.
- **Your dataset is larger than available memory.** DiskANN-style indexing with quantization-based reranking keeps recall high while memory usage stays bounded.

Typical use cases include recommendation systems, image and video similarity search, semantic document search, and fraud detection pipelines that index millions to billions of vectors.

## Unique features

- **DiskANN Implementation (Pure Java)** - Based on `jvector` library, a pure Java implementation of DiskANN-style approximate nearest neighbour (ANN) search optimized for memory-constrained environments. It eliminates the need for native libraries such as `Faiss` and avoids the complexity and overhead associated with JNI, simplifying deployment and maintenance.
- **Scalable Thread-Safe Design** - The index is fully thread-safe and supports concurrent updates and insertions with near-linear scalability as CPU cores increase. The underlying Jvector library enables high-throughput ingestion without relying on costly merge operations to achieve parallelism.
- **Quantization Refinement During Merges** - The system refines quantization codebooks incrementally during merge operations. This approach improves search accuracy and recall without requiring a complete recomputation of codebooks, reducing computational overhead.
- **Incremental Index Updates** - `jvector` allows incremental insertion of vectors into existing indexes. This providing efficiency gains over full index rebuilds for workloads involving frequent updates, particularly for large graph-based indexes.
- **Quantized DiskANN with Reranking** - `jvector` supports DiskANN-style quantization combined with reranking, delivering significant performance improvements for datasets larger than available memory. This approach is particularly effective for large-scale deployments where traditional in-memory indexing is not feasible.
- **Product Quantization (PQ)** - PQ is implemented with high-performance SIMD optimizations and separate codebooks to enable fast vector searches with low memory usage.
- **Advanced Quantization Techniques** - `jvector` includes advanced capabilities such as Non-Vector Quantization (NVQ), and Anisotropic PQ, enabling more efficient and accurate similarity computations beyond standard quantization approaches.

## Installation

**1. Remove Existing k-NN and neural-search Plugins** (make sure no `knn` enabled indexes are created)

```bash
bin/opensearch-plugin remove opensearch-neural-search
bin/opensearch-plugin remove opensearch-knn
```

**2. Install `opensearch-jvector` Plugin**

```bash
bin/opensearch-plugin install opensearch-jvector
```

## OpenSearch compatible features

- Product Quantization (since: 3.5.0)
- MMR Search (since: 3.6.0)
- Derived Sources (since: 3.6.0)

## Limitations

- `opensearch-jvector` plugin is not part of the default OpenSearch distribution
- `opensearch-knn` and `opensearch-jvector` cannot be installed simultaneously
- `opensearch-jvector` is not recognized by the upstream version of `opensearch-neural-search` plugin.
87 changes: 71 additions & 16 deletions _mappings/supported-field-types/knn-methods-engines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ OpenSearch supports the following engines:
- [**Lucene**](#lucene-engine): The native search library, offering an HNSW implementation with efficient filtering capabilities
- [**Faiss**](#faiss-engine) (Facebook AI Similarity Search): A comprehensive library implementing both the HNSW and IVF methods, with additional vector compression options
- [**NMSLIB**](#nmslib-engine-deprecated) (Non-Metric Space Library): A legacy implementation of HNSW (now deprecated)
- [**jvector**]({{site.url}}{{site.baseurl}}/install-and-configure/additional-plugins/opensearch-jvector/): Available through the `opensearch-jvector` plugin (not included in the default distribution). Implements DiskANN-style approximate nearest neighbor search using the `disk_ann` method. Supports concurrent inserts, incremental merges, and native Product Quantization (PQ). Cannot be installed alongside `opensearch-knn`.

## Method definition example

Expand Down Expand Up @@ -76,7 +77,7 @@ Mapping parameter | Required | Default | Updatable | Description
:--- | :--- | :--- | :--- | :---
`name` | Yes | N/A | No | The nearest neighbor method. Valid values are `hnsw`, `ivf`, and `flat`. Not every engine combination supports each of the methods. For a list of supported methods, see the section for a specific engine.
`space_type` | No | `l2` | No | The vector space used to calculate the distance between vectors. Valid values are `l1`, `l2`, `linf`, `cosinesimil`, `innerproduct`, `hamming`, and `hammingbit`. Not every method/engine combination supports each of the spaces. For a list of supported spaces, see the section for a specific engine. Note: This value can also be specified at the top level of the mapping. For more information, see [Spaces]({{site.url}}{{site.baseurl}}/mappings/supported-field-types/knn-spaces/).
`engine` | No | `faiss` | No | The approximate k-NN library to use for indexing and search. Valid values are `faiss`, `lucene`, and `nmslib` (deprecated).
`engine` | No | `faiss` | No | The approximate k-NN library to use for indexing and search. Valid values are `faiss`, `lucene`, `nmslib` (deprecated), and `jvector` (requires the [`opensearch-jvector` plugin]({{site.url}}{{site.baseurl}}/install-and-configure/additional-plugins/opensearch-jvector/)).
`parameters` | No | `null` | No | The parameters used for the nearest neighbor method. For more information, see the section for a specific engine.

## Lucene engine
Expand Down Expand Up @@ -396,7 +397,58 @@ An index created in OpenSearch version 2.11 or earlier will still use the previo
}
```

## Choosing the right method
## `jvector` engine

The `jvector` engine is available through the [`opensearch-jvector` plugin]({{site.url}}{{site.baseurl}}/install-and-configure/additional-plugins/opensearch-jvector/) and is not included in the default OpenSearch distribution. It cannot be installed alongside `opensearch-knn`. The `jvector` engine implements DiskANN-style approximate nearest neighbor search in pure Java, with no JNI dependency.

### Supported methods

The `jvector` engine supports the following method.

Method name | Requires training | Supported spaces
:--- | :--- | :---
`disk_ann` | No | `l2`, `cosinesimil`, `innerproduct`

### Method parameters

| Parameter | Default | Description |
|---|---|---|
| `m` | `16` | Bi-directional link count per node. Higher values improve recall, increase index size. |
| `ef_construction` | `100` | Candidate list size during graph construction. Higher values improve recall, slow ingestion. |
| `advanced.alpha` | `1.2` | Diversity factor for neighbor selection |
| `advanced.neighbor_overflow` | `1.2` | Overflow factor for neighbor lists |
| `advanced.hierarchy_enabled` | `false` | Enable hierarchical graph structure |
| `advanced.num_pq_subspaces` | — | Number of PQ subspaces. Must be ≤ dimension. |
| `advanced.min_batch_size_for_quantization` | `1024` | Documents needed before quantization is trained |
| `advanced.leading_segment_merge_disabled` | `false` | Prevent leading segment from being rebuilt during force merge |

### Space Types

The `space_type` field controls which distance metric is used.

| Value | Distance metric | Use case |
|---|---|---|
| `l2` | Euclidean distance (L2 norm) | General-purpose; raw coordinates |
| `cosinesimil` | Cosine similarity | Text embeddings; direction matters more than magnitude |
| `innerproduct` | Dot product (inner product) | Embeddings where magnitude carries meaning (e.g., biencoder models) |

The default is `l2` when `space_type` is omitted.

### Example configuration

```json
"method": {
"name": "disk_ann",
"engine": "jvector",
"space_type": "l2",
"parameters": {
"m": 16,
"ef_construction": 100
}
}
```

## Choosing the right method and engine

There are several options to choose from when building your `knn_vector` field. To select the correct method and parameters, you should first understand the requirements of your workload and what trade-offs you are willing to make. Factors to consider are (1) query latency, (2) query quality, (3) memory limits, and (4) indexing latency.

Expand All @@ -406,23 +458,26 @@ If you want to use less memory and increase indexing speed as compared to HNSW w

If memory is a concern, consider adding a PQ encoder to your HNSW or IVF index. Because PQ is a lossy encoding, query quality will drop.

You can reduce the memory footprint by a factor of 2, with a minimal loss in search quality, by using the [`fp_16` encoder]({{site.url}}{{site.baseurl}}/vector-search/optimizing-storage/faiss-scalar-quantization/#16-bit-quantization). If your vector dimensions are within the [-128, 127] byte range, we recommend using the [byte quantizer]({{site.url}}{{site.baseurl}}/mappings/supported-field-types/knn-memory-optimized/#byte-vectors) to reduce the memory footprint by a factor of 4. To learn more about vector quantization options, see [k-NN vector quantization]({{site.url}}{{site.baseurl}}/vector-search/optimizing-storage/knn-vector-quantization/).
If your dataset grows continuously or exceeds available memory, consider the [jvector engine](#jvector-engine) (via the [`opensearch-jvector` plugin]({{site.url}}{{site.baseurl}}/install-and-configure/additional-plugins/opensearch-jvector/)). It supports concurrent inserts, incremental merges without full graph rebuilds, and native PQ with better recall at higher compression ratios.

You can reduce the memory footprint by a factor of 2, with a minimal loss in search quality, by using the [`fp_16` encoder]({{site.url}}{{site.baseurl}}/vector-search/optimizing-storage/faiss-scalar-quantization/#16-bit-quantization). If your vector dimensions are within the [-128, 127] byte range, we recommend using the [byte quantizer]({{site.url}}{{site.baseurl}}/mappings/supported-field-types/knn-memory-optimized/#byte-vectors) to reduce the memory footprint by a factor of 4. To learn more about vector quantization options, see [k-NN vector quantization]({{site.url}}{{site.baseurl}}/vector-search/optimizing-storage/knn-vector-quantization/).

## Engine recommendations

In general, select Faiss for large-scale use cases. Lucene is a good option for smaller deployments and offers benefits like smart filtering, where the optimal filtering strategy—pre-filtering, post-filtering, or exact k-NN—is automatically applied depending on the situation. The following table summarizes the differences between each option.

| | Faiss/HNSW | Faiss/IVF | Lucene/HNSW |
|:---|:---|:---|:---|
| Max dimensions | 16,000 | 16,000 | 16,000 |
| Filter | Post-filter | Post-filter | Filter during search |
| Training required | No (Yes for PQ) | Yes | No |
| Similarity metrics | `l2`, `innerproduct`, `cosinesimil` | `l2`, `innerproduct`, `cosinesimil` | `l2`, `cosinesimil` |
| Number of vectors | Tens of billions | Tens of billions | Less than 10 million |
| Indexing latency | Low | Lowest | Low |
| Query latency and quality | Low latency and high quality | Low latency and low quality | High latency and high quality |
| Vector compression | Flat <br><br>PQ | Flat <br><br>PQ | Flat |
| Memory consumption | High <br><br> Low with PQ | Medium <br><br> Low with PQ | High |
In general, select Faiss for large-scale use cases. Lucene is a good option for smaller deployments and offers benefits like smart filtering, where the optimal filtering strategy—pre-filtering, post-filtering, or exact k-NN—is automatically applied depending on the situation. Consider `jvector` for high-update workloads or memory-constrained large-scale deployments. The following table summarizes the differences between each option.

| | Faiss/HNSW | Faiss/IVF | Lucene/HNSW | jvector/disk_ann |
|:---|:---|:---|:---|:---|
| Max dimensions | 16,000 | 16,000 | 16,000 | 16,000 |
| Filter | Post-filter | Post-filter | Filter during search | Filter during search <br><br> Post-filter |
| Training required | No (Yes for PQ) | Yes | No | No |
| Similarity metrics | `l2`, `innerproduct`, `cosinesimil` | `l2`, `innerproduct`, `cosinesimil` | `l2`, `cosinesimil` | `l2`, `cosinesimil`, `innerproduct`, `l1`, `linf` |
| Number of vectors | Tens of billions | Tens of billions | Less than 10 million | Billions |
| Indexing latency | Low | Lowest | Low | Low (concurrent inserts) |
| Query latency and quality | Low latency and high quality | Low latency and low quality | High latency and high quality | Low latency and high quality |
| Vector compression | Flat <br><br>PQ | Flat <br><br>PQ | Flat | Flat <br><br> PQ (native, no training) |
| Memory consumption | High <br><br> Low with PQ | Medium <br><br> Low with PQ | High | Low (DiskANN) <br><br> Very low with PQ |
| Plugin required | No | No | No | Yes ([opensearch-jvector]({{site.url}}{{site.baseurl}}/install-and-configure/additional-plugins/opensearch-jvector/)) |

## Memory estimation

Expand Down
Loading
Loading