How opensearch-project/k-nn works
Project type and purpose
• This is an OpenSearch “k-NN” 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