# opensearch-project/k-nn architecture

> Architecture diagram of the GitHub repository opensearch-project/k-nn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opensearch-project/k-nn
- Repository: https://github.com/opensearch-project/k-nn

## Overview

##### Project type and purpose
- This is an OpenSearch “k-N​N” search plugin: a Java/Gradle-based extension to OpenSearch that enables Approximate Nearest Neighbor (k-NN) queries using two native libraries (Faiss and NMSLIB).
- It provides REST handlers, transport actions, custom Lucene codecs, JNI bindings, a quantization/training subsystem, memory-optimized search, and an optional remote index-build client/service.

##### File structure
- Top-level modules:
- ​src/main/java/org/opensearch/knn – the core plugin code (REST, transport, index mapping, query parsing, profiling, stats).
- ​jni – C++ native code + JNI wrappers for Faiss and NMSLIB.
- ​remote-index-build-client – standalone Java client for off-cluster index construction.
- ​build-tools, scripts, gradle/ – build and CI configuration.
- ​qa, benchmarks – integration and performance tests.
- Notice patterns:
- Plugin architecture (org.opensearch.plugins.Extension)
- Strategy/Factory for engine choice (EngineResolver, MethodResolver, NativeIndexBuildStrategyFactory)
- Codec hierarchy under index/codec (custom Lucene codecs and backward compatibility)
- Query subsystem under index/query (builders, parser, iterators)
- Training/quantization under training and quantizationservice
- Memory-optimized search under memoryoptsearch

##### README for additional insights
- Confirms use of Faiss (Facebook) and NMSLIB (Yury Malkov) libraries.
- Emphasizes plugin use cases: similarity search for recommendations, fraud detection, multimedia search.
- Points to documentation on plugin installation and usage.

##### Main components and interactions
a. Client & API Layer
- External client (REST/Transport) → OpenSearch HTTP/Transport APIs → KNNPlugin REST handlers (RestTrainModelHandler, RestSearchModelHandler, etc.)
b. Plugin Core
- KNNPlugin registers:
- REST endpoints
- Transport actions (ClearCache, DeleteModel, SearchModel, TrainingModel)
- Painless scripting extensions (KNNScoreScript)
- GRPC query converters (proto under knn/grpc)
c. Query & Indexing Subsystem
- Query parser (KNNQueryBuilderParser) → KNNQueryFactory → EngineResolver
- Index-time: custom field mappers (KNNVectorFieldMapper) → Lucene index creation with custom codecs (index/codec/KNN990Codec, KNN80Codec, etc.)
d. Engine Layer
- EngineResolver chooses among:
- Faiss engine (jni + jni wrapper + org.opensearch.knn.index.engine.faiss)
- NMSLIB engine (jni wrapper + org.opensearch.knn.index.engine.nmslib)
- Lucene HNSW engine (pure-Java under engine/lucene)
- Uses Strategy pattern: NativeIndexBuildStrategy vs DefaultIndexBuildStrategy
e. JNI & Native Libraries
- JNI layer (jni/src and jni/include) loads native engine code and exposes FaissService, NmslibService, SimdVectorComputeService
- Native code links Faiss and NMSLIB patched sources under jni/external and jni/patches
f. Memory-Optimized Search
- Optional in-JVM search (memoryoptsearch) using Java Foreign-Memory API for ultra-fast vector search
g. Training & Quantization
- TrainingJobRunner listens to cluster state → spawns quantization tasks (QuantizationService) → produces quantization states stored in model index
h. Remote Index Build
- remote-index-build-client: Java HTTP client + retry strategy calls a separate remote-build service (gRPC/HTTP) to build vector indexes off-cluster
i. Storage & Metrics
- Lucene index persists vectors via custom codecs
- Model metadata and graveyard stored in internal hidden indices
- Stats suppliers collect circuit breakers, cache metrics, remote-build metrics

##### Architectural patterns & design principles
- Plugin/Extension points (OpenSearch SPI)
- Strategy & Factory patterns for engine selection and index-build strategy
- Adapter pattern in JNI layer
- Command pattern for TransportActions
- Separation of concerns: REST handlers vs transport vs engine vs codec vs native

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    RESTClient["REST Client"]:::external
    TransportClient["Transport Client"]:::external
    RemoteBuildClient["Remote-Build Service"]:::external

    %% KNN Plugin Boundary
    subgraph "OpenSearch Node"
        direction TB
        Plugin["KNNPlugin"]:::java
        subgraph "API Layer"
            direction TB
            RESTHandlers["REST Handlers"]:::java
            TransportActions["Transport Actions"]:::java
        end
        subgraph "Plugin Core"
            direction TB
            PainlessScript["Painless Script Ext"]:::java
            GRPCConverters["gRPC Converters"]:::java
            FieldMappers["Field Mappers"]:::java
            QueryParser["Query Parser & Builder"]:::java
            EngineResolverNode["EngineResolver & MethodResolver"]:::java
        end
        subgraph "Engine Layer"
            direction TB
            FaissEngine["Faiss Engine"]:::java
            NmsEngine["NMSLIB Engine"]:::java
            LuceneEngine["Lucene HNSW Engine"]:::java
        end
        subgraph "JNI & Native"
            direction TB
            JNIWrapper["JNI Wrapper"]:::native
            NativeLibs["Native Libraries"]:::native
        end
        subgraph "Search & Indexing"
            direction TB
            LuceneIndex["Lucene Index & Codecs"]:::storage
            ModelIndex["Model Metadata Index"]:::storage
        end
        subgraph "Optional Modules"
            direction TB
            MemoryOpt["Memory-Optimized Search"]:::java
            subgraph "Training & Quantization"
                direction TB
                TrainingRunner["TrainingJobRunner"]:::java
                ClusterListener["ClusterStateListener"]:::java
                QuantService["QuantizationService"]:::java
                QuantModels["Quantization Models"]:::java
            end
            subgraph "Remote Index Build Integration"
                direction TB
                RemoteIntegration["Remote-Index-Build Integration"]:::java
            end
        end
        subgraph "Metrics & Stats"
            direction TB
            StatsSuppliers["Stats Suppliers"]:::java
        end
    end

    %% Flows
    RESTClient -->|HTTP| RESTHandlers
    TransportClient -->|Transport| TransportActions
    RESTHandlers --> Plugin
    TransportActions --> Plugin
    Plugin --> PainlessScript
    Plugin --> GRPCConverters
    Plugin --> FieldMappers
    Plugin --> QueryParser
    Plugin --> EngineResolverNode

    EngineResolverNode --> FaissEngine
    EngineResolverNode --> NmsEngine
    EngineResolverNode --> LuceneEngine

    FaissEngine --> JNIWrapper
    NmsEngine --> JNIWrapper
    JNIWrapper --> NativeLibs
    LuceneEngine --> LuceneIndex

    QueryParser --> EngineResolverNode
    FieldMappers --> LuceneIndex

    Plugin -->|writes| LuceneIndex
    Plugin -->|reads| ModelIndex

    MemoryOpt --> LuceneIndex

    Plugin --> MemoryOpt

    %% Training flow
    RESTClient -->|Train API| TrainingRunner
    TrainingRunner --> ClusterListener
    ClusterListener --> QuantService
    QuantService --> ModelIndex
    QuantModels --> QuantService

    %% Remote build flow
    RemoteBuildClient --> RemoteIntegration
    RemoteIntegration --> ModelIndex

    %% Metrics
    Plugin --> StatsSuppliers
    LuceneIndex --> StatsSuppliers
    ModelIndex --> StatsSuppliers

    %% Click Events
    click RESTHandlers "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/plugin/rest"
    click TransportActions "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/plugin/transport"
    click Plugin "https://github.com/opensearch-project/k-nn/blob/main/src/main/java/org/opensearch/knn/plugin/KNNPlugin.java"
    click QueryParser "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/index/query"
    click FieldMappers "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/index/mapper"
    click LuceneIndex "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/index/codec"
    click EngineResolverNode "https://github.com/opensearch-project/k-nn/blob/main/src/main/java/org/opensearch/knn/index/engine/EngineResolver.java"
    click FaissEngine "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/index/engine/faiss"
    click NmsEngine "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/index/engine/nmslib"
    click LuceneEngine "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/index/engine/lucene"
    click JNIWrapper "https://github.com/opensearch-project/k-nn/tree/main/jni"
    click MemoryOpt "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/memoryoptsearch"
    click TrainingRunner "https://github.com/opensearch-project/k-nn/blob/main/src/main/java/org/opensearch/knn/training/TrainingJobRunner.java"
    click ClusterListener "https://github.com/opensearch-project/k-nn/blob/main/src/main/java/org/opensearch/knn/training/TrainingJobClusterStateListener.java"
    click QuantService "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/index/quantizationservice"
    click QuantModels "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/quantization"
    click RemoteBuildClient "https://github.com/opensearch-project/k-nn/tree/main/remote-index-build-client"
    click RemoteIntegration "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/index/codec/nativeindex/remote"
    click ModelIndex "https://github.com/opensearch-project/k-nn/blob/main/src/main/resources/mappings/model-index.json"
    click StatsSuppliers "https://github.com/opensearch-project/k-nn/tree/main/src/main/java/org/opensearch/knn/plugin/stats"

    %% Styles
    classDef java fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef native fill:#F5B7B1,stroke:#943126,color:#512E5F
    classDef external fill:#ABEBC6,stroke:#145A32,color:#0B5345
    classDef storage fill:#F9E79F,stroke:#7D6608,color:#1C2833
```
