k-NN plugin API

    Introduced 1.0

    The k-NN API provides information about the current status of the k-NN plugin. The plugin keeps track of both cluster-level and node-level statistics. Cluster-level statistics have a single value for the entire cluster. Node-level statistics have a single value for each node in the cluster. You can filter the query by nodeId and statName:

    Note: Some stats contain graph in the name. In these cases, graph is synonymous with native library index. The term graph is a legacy detail, coming from when the plugin only supported the HNSW algorithm, which consists of hierarchical graphs.

    1. GET /_plugins/_knn/stats?pretty
    2. {
    3.     "_nodes" : {
    4.         "total" : 1,
    5.         "successful" : 1,
    6.         "failed" : 0
    7.     },
    8.     "cluster_name" : "my-cluster",
    9.     "circuit_breaker_triggered" : false,
    10.     "model_index_status" : "YELLOW",
    11.     "nodes" : {
    12.       "JdfxIkOS1-43UxqNz98nw" : {
    13.         "graph_memory_usage_percentage" : 3.68,
    14.         "graph_query_requests" : 1420920,
    15.         "graph_memory_usage" : 2,
    16.         "cache_capacity_reached" : false,
    17.         "load_success_count" : 179,
    18.         "training_memory_usage" : 0,
    19.         "indices_in_cache" : {
    20.             "myindex" : {
    21.                 "graph_memory_usage" : 2,
    22.                 "graph_memory_usage_percentage" : 3.68,
    23.                 "graph_count" : 2
    24.             }
    25.         },
    26.         "script_query_errors" : 0,
    27.         "hit_count" : 1420775,
    28.         "knn_query_requests" : 147092,
    29.         "total_load_time" : 2436679306,
    30.         "miss_count" : 179,
    31.         "training_memory_usage_percentage" : 0.0,
    32.         "graph_index_requests" : 656,
    33.         "faiss_initialized" : true,
    35.         "training_errors" : 0,
    36.         "eviction_count" : 0,
    37.         "nmslib_initialized" : false,
    38.         "script_compilations" : 0,
    39.         "script_query_requests" : 0,
    40.         "graph_query_errors" : 0,
    41.         "graph_index_errors" : 0,
    42.         "training_requests" : 17,
    43.         "script_compilation_errors" : 0
    44.     }
    45.   }
    46. }
    1. GET /_plugins/_knn/HYMrXXsBSamUkcAjhjeN0w/stats/circuit_breaker_triggered,graph_memory_usage?pretty
    2. {
    3.     "_nodes" : {
    4.         "total" : 1,
    5.         "successful" : 1,
    6.         "failed" : 0
    7.     },
    8.     "cluster_name" : "my-cluster",
    9.     "circuit_breaker_triggered" : false,
    10.     "nodes" : {
    11.         "HYMrXXsBSamUkcAjhjeN0w" : {
    12.             "graph_memory_usage" : 1
    13.         }
    14.     }
    15. }

    Warmup operation

    Introduced 1.0

    The native library indices used to perform approximate k-Nearest Neighbor (k-NN) search are stored as special files with other Apache Lucene segment files. In order for you to perform a search on these indices using the k-NN plugin, the plugin needs to load these files into native memory.

    If the plugin hasn’t loaded the files into native memory, it loads them when it receives a search request. The loading time can cause high latency during initial queries. To avoid this situation, users often run random queries during a warmup period. After this warmup period, the files are loaded into native memory and their production workloads can begin. This loading process is indirect and requires extra effort.

    As an alternative, you can avoid this latency issue by running the k-NN plugin warmup API operation on whatever indices you’re interested in searching. This operation loads all the native library files for all of the shards (primaries and replicas) of all the indices specified in the request into native memory.

    Usage

    This request performs a warmup on three indices:

    1. GET /_plugins/_knn/warmup/index1,index2,index3?pretty
    2. {
    3.   "_shards" : {
    4.     "total" : 6,
    5.     "successful" : 6,
    6.     "failed" : 0
    7.   }
    8. }

    total indicates how many shards the k-NN plugin attempted to warm up. The response also includes the number of shards the plugin succeeded and failed to warm up.

    The call doesn’t return results until the warmup operation finishes or the request times out. If the request times out, the operation still continues on the cluster. To monitor the warmup operation, use the OpenSearch _tasks API:

    After the operation has finished, use the k-NN _stats API operation to see what the k-NN plugin loaded into the graph.

    For the warmup operation to function properly, follow these best practices:

    • Don’t run merge operations on indices that you want to warm up. During merge, the k-NN plugin creates new segments, and old segments are sometimes deleted. For example, you could encounter a situation in which the warmup API operation loads native library indices A and B into native memory, but segment C is created from segments A and B being merged. The native library indices for A and B would no longer be in memory, and native library index C would also not be in memory. In this case, the initial penalty for loading native library index C is still present.

    • Confirm that all native library indices you want to warm up can fit into native memory. For more information about the native memory limit, see the knn.memory.circuit_breaker.limit statistic. High graph memory usage causes cache thrashing, which can lead to operations constantly failing and attempting to run again.

    Introduced 1.2

    Used to retrieve information about models present in the cluster. Some native library index configurations require a training step before indexing and querying can begin. The output of training is a model that can then be used to initialize native library index files during indexing. The model is serialized in the k-NN model system index.

    1. GET /_plugins/_knn/models/{model_id}

    Usage

    1. GET /_plugins/_knn/models/test-model?pretty
    2. {
    3.   "model_id" : "test-model",
    4.   "model_blob" : "SXdGbIAAAAAAAAAAAA...",
    5.   "state" : "created",
    6.   "timestamp" : "2021-11-15T18:45:07.505369036Z",
    7.   "description" : "Default",
    8.   "error" : "",
    9.   "space_type" : "l2",
    10.   "dimension" : 128,
    11.   "engine" : "faiss" 
    12. }
    1. GET /_plugins/_knn/models/test-model?pretty&filter_path=model_id,state
    2. {
    3.   "model_id" : "test-model",
    4.   "state" : "created"
    5. }

    Search Model

    Introduced 1.2

    Use an OpenSearch query to search for models in the index.

    Introduced 1.2

    Used to delete a particular model in the cluster.

    Usage

    1. DELETE /_plugins/_knn/models/{model_id}
    2. {
    3.   "model_id": {model_id},
    4. }

    Train Model

    Introduced 1.2

    1. POST /_plugins/_knn/models/{model_id}/_train?preference={node_id}
    2. {
    3.     "training_index": "train-index-name",
    4.     "training_field": "train-field-name",
    5.     "dimension": 16,
    6.     "max_training_vector_count": 1200,
    7.     "search_size": 100,
    8.     "description": "My model",
    9.     "method": {
    10.         "name":"ivf",
    11.         "engine":"faiss",
    12.         "space_type": "l2",
    13.         "parameters":{
    14.             "nlist":128,
    15.             "encoder":{
    16.                 "name":"pq",
    17.                 "parameters":{
    18.                     "code_size":8
    19.                 }
    20.             }
    21.         }
    22.     }
    23. }
    25. {
    26.     "model_id": "model_x"
    27. }
    1. POST /_plugins/_knn/models/_train?preference={node_id}
    2. {
    3.     "training_index": "train-index-name",
    4.     "training_field": "train-field-name",
    5.     "dimension": 16,
    6.     "max_training_vector_count": 1200,
    7.     "search_size": 100,
    8.     "description": "My model",
    9.     "method": {
    10.         "name":"ivf",
    11.         "engine":"faiss",
    12.         "space_type": "l2",
    13.         "parameters":{
    14.             "nlist":128,
    15.             "encoder":{
    16.                 "name":"pq",
    17.                 "parameters":{
    18.                     "code_size":8
    19.                 }
    20.             }
    21.         }
    22.     }
    23. }
    25. {
    26. }