Neural Search API

The Neural Search plugin provides several APIs for monitoring semantic and hybrid search features.

Stats

The Neural Search Stats API provides information about the current status of the Neural Search plugin. This includes 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.

By default, the Neural Search Stats API is disabled through a cluster setting. To enable statistics collection, use the following command:

PUT /_cluster/settings
{
  "persistent": {
    "plugins.neural_search.stats_enabled": true
  }
}

To disable statistics collection, set the cluster setting to false. When disabled, all values are reset and new statistics are not collected.

Endpoints

GET /_plugins/_neural/stats
GET /_plugins/_neural/stats/<stats>
GET /_plugins/_neural/<nodes>/stats
GET /_plugins/_neural/<nodes>/stats/<stats>

Path parameters

The following table lists the available path parameters. All path parameters are optional.

Query parameters

The following table lists the available query parameters. All query parameters are optional.

Example request

GET /_plugins/_neural/node1,node2/stats/stat1,stat2?include_metadata=true,flat_stat_paths=true

Example response

GET /_plugins/_neural/stats/
{
	"_nodes": {
		"total": 1,
		"successful": 1,
		"failed": 0
	},
	"cluster_name": "integTest",
	"info": {
		"cluster_version": "3.1.0",
		"processors": {
			"search": {
				"hybrid": {
					"comb_geometric_processors": 0,
					"comb_rrf_processors": 0,
					"norm_l2_processors": 0,
					"norm_minmax_processors": 0,
					"comb_harmonic_processors": 0,
					"comb_arithmetic_processors": 0,
					"norm_zscore_processors": 0,
					"rank_based_normalization_processors": 0,
					"normalization_processors": 0
				},
				"rerank_ml_processors": 0,
				"rerank_by_field_processors": 0,
				"neural_sparse_two_phase_processors": 0,
				"neural_query_enricher_processors": 0
			},
			"ingest": {
				"sparse_encoding_processors": 0,
				"skip_existing_processors": 0,
				"text_image_embedding_processors": 0,
				"text_chunking_delimiter_processors": 0,
				"text_embedding_processors_in_pipelines": 0,
				"text_chunking_fixed_token_length_processors": 0,
				"text_chunking_fixed_char_length_processors": 0,
				"text_chunking_processors": 0
			}
		}
	},
	"all_nodes": {
		"query": {
			"hybrid": {
				"hybrid_query_with_pagination_requests": 0,
				"hybrid_query_with_filter_requests": 0,
				"hybrid_query_with_inner_hits_requests": 0,
				"hybrid_query_requests": 0
			},
			"neural": {
				"neural_query_against_semantic_sparse_requests": 0,
				"neural_query_requests": 0,
				"neural_query_against_semantic_dense_requests": 0,
				"neural_query_against_knn_requests": 0
			},
			"neural_sparse": {
				"neural_sparse_query_requests": 0,
                "seismic_query_requests": 0
			}
		},
		"semantic_highlighting": {
			"semantic_highlighting_request_count": 0,
			"semantic_highlighting_batch_request_count": 0
		},
		"processors": {
			"search": {
				"neural_sparse_two_phase_executions": 0,
				"hybrid": {
					"comb_harmonic_executions": 0,
					"norm_zscore_executions": 0,
					"comb_rrf_executions": 0,
					"norm_l2_executions": 0,
					"rank_based_normalization_processor_executions": 0,
					"comb_arithmetic_executions": 0,
					"normalization_processor_executions": 0,
					"comb_geometric_executions": 0,
					"norm_minmax_executions": 0
				},
				"rerank_by_field_executions": 0,
				"neural_query_enricher_executions": 0,
				"rerank_ml_executions": 0
			},
			"ingest": {
				"skip_existing_executions": 0,
				"text_chunking_fixed_token_length_executions": 0,
				"sparse_encoding_executions": 0,
				"text_chunking_fixed_char_length_executions": 0,
				"text_chunking_executions": 0,
				"text_embedding_executions": 0,
				"semantic_field_executions": 0,
				"semantic_field_chunking_executions": 0,
				"text_chunking_delimiter_executions": 0,
				"text_image_embedding_executions": 0
			}
		},
        "memory": {
            "sparse": {
                "sparse_memory_usage": 0.13,
                "clustered_posting_usage": 0.06,
                "forward_index_usage": 0.06
            }
        }
	},
	"nodes": {
		"_cONimhxS6KdedymRZr6xg": {
			"query": {
				"hybrid": {
					"hybrid_query_with_pagination_requests": 0,
					"hybrid_query_with_filter_requests": 0,
					"hybrid_query_with_inner_hits_requests": 0,
					"hybrid_query_requests": 0
				},
				"neural": {
					"neural_query_against_semantic_sparse_requests": 0,
					"neural_query_requests": 0,
					"neural_query_against_semantic_dense_requests": 0,
					"neural_query_against_knn_requests": 0
				},
				"neural_sparse": {
					"neural_sparse_query_requests": 0,
                    "seismic_query_requests": 0
				},
                "memory": {
                    "sparse": {
                        "sparse_memory_usage_percentage": 0,
                        "sparse_memory_usage": 0.13,
                        "clustered_posting_usage": 0.06,
                        "forward_index_usage": 0.06
                    }
                }
			},
			"semantic_highlighting": {
				"semantic_highlighting_request_count": 0,
				"semantic_highlighting_batch_request_count": 0
			},
			"processors": {
				"search": {
					"neural_sparse_two_phase_executions": 0,
					"hybrid": {
						"comb_harmonic_executions": 0,
						"norm_zscore_executions": 0,
						"comb_rrf_executions": 0,
						"norm_l2_executions": 0,
						"rank_based_normalization_processor_executions": 0,
						"comb_arithmetic_executions": 0,
						"normalization_processor_executions": 0,
						"comb_geometric_executions": 0,
						"norm_minmax_executions": 0
					},
					"rerank_by_field_executions": 0,
					"neural_query_enricher_executions": 0,
					"rerank_ml_executions": 0
				},
				"ingest": {
					"skip_existing_executions": 0,
					"text_chunking_fixed_token_length_executions": 0,
					"sparse_encoding_executions": 0,
					"text_chunking_fixed_char_length_executions": 0,
					"text_chunking_executions": 0,
					"text_embedding_executions": 0,
					"semantic_field_executions": 0,
					"semantic_field_chunking_executions": 0,
					"text_chunking_delimiter_executions": 0,
					"text_image_embedding_executions": 0
				}
			}
		}
	}
}

If include_metadata is true, each stats object contains additional metadata:

{
    ...,
    "text_embedding_executions": {
      "value": 0,
      "stat_type": "timestamped_event_counter",
      "trailing_interval_value": 0,
      "minutes_since_last_event": 29061801
    },
    ...
}

For more information, see Available metadata.

Response body fields

The following sections describe response body fields.

Categories of statistics

The following table lists all categories of statistics.

Available statistics

The following table lists the available statistics. For statistics with paths prefixed with nodes.<node_id>, aggregate cluster-level statistics are also available at the same path prefixed with all_nodes.

Info statistics: Processors

Info statistics: Hybrid processors

Node-level statistics: Processors

Node-level statistics: Hybrid processors

Node-level statistics: Query

Node-level statistics: Memory

Node-level statistics: Semantic highlighting

Available metadata

When include_metadata is true, the field values in the response are replaced by their respective metadata objects, which include additional information about the statistic types, as described in the following table.

The info_string object contains the following metadata fields.

The info_counter object contains the following metadata fields.

The timestamped_event_counter object contains the following metadata fields.

Warm up

Introduced 3.3

Sparse indexes support neural sparse ANN search. To maximize search efficiency, OpenSearch caches sparse data in JVM memory.

To avoid high latency during initial searches, you can run random queries during a warmup period. After the warmup period, sparse data is stored in JVM memory, and you can start production workloads. However, this approach is indirect and requires additional effort.

As an alternative, you can use the warm up API operation to avoid latency during initial searches. This operation loads all sparse data for the primary and replica shards of the specified indexes into JVM memory. The warm up API operation is idempotent: if a segment’s sparse data is already loaded into memory, this operation has no effect. It only loads files not currently stored in memory.

This API operation only works with sparse indexes (indexes created with index.sparse set to true).

Endpoints

POST /_plugins/_neural/warmup/<index>

Path parameters

The following table lists the available path parameters.

Example request

The following request performs a warm up operation on three indexes:

POST /_plugins/_neural/warmup/index1,index2,index3

You can use the warm up API operation with index patterns to clear one or more indexes that match a specified pattern from the cache:

POST /_plugins/_neural/warmup/index*

Example response

The API call returns results only after the warm up operation finishes or the request times out:

{
  "_shards" : {
    "total" : 6,
    "successful" : 6,
    "failed" : 0
  }
}

If the request times out, then the operation continues on the cluster.

To monitor the warm up operation, use the OpenSearch Tasks API:

GET /_tasks

After the operation has finished, use the neural stats API operation to monitor the updated memory usage.

Response body fields

The following table lists all response body fields.

Best practices

To ensure that the warm up operation works properly, follow these best practices:

• Avoid running merge operations on indexes you plan to warm up: During a merge operation, OpenSearch creates new segments and may delete old ones. For example, if the warm up API operation loads sparse indexes A and B into native memory, but a merge creates a new segment C from A and B, then A and B are removed from memory but C is not yet loaded. In this case, the initial loading delay for sparse index C still occurs.

• Verify that all sparse indexes you plan to warm up can fit into JVM memory. For more information about memory limits, see neural_search.circuit_breaker.limit.

Clear cache

Introduced 3.3

During neural sparse ANN search or warm up operations, sparse data is loaded into JVM memory. You can remove this data by deleting the corresponding index.

In contrast, decreasing the neural search circuit breaker limit does not immediately evict cached sparse data. To manually clear cached data, use the neural search clear cache API operation. This operation removes all in-memory sparse data for all shards (primaries and replicas) of the indexes specified in the request.

Similar to the warm up operation, the clear cache operation is idempotent: if you attempt to clear the cache for an index that has already been evicted, the operation has no additional effect.

This API operation only works with sparse indexes (indexes created with index.sparse set to true).

Endpoints

POST /_plugins/_neural/clear_cache/<index>

Path parameters

The following table lists the available path parameters.

Example request

The following request clears the sparse data of three specified indexes from JVM memory:

POST /_plugins/_neural/clear_cache/index1,index2,index3

You can also use index patterns to clear one or more indexes that match a pattern:

POST /_plugins/_neural/clear_cache/index*

Example response

The API call returns results only after the clear cache operation finishes or the request times out:

{
  "_shards" : {
    "total" : 6,
    "successful" : 6,
    "failed" : 0
  }
}

If the request times out, the operation continues running in the cluster.

To monitor the progress of the clear cache operation, use the OpenSearch Tasks API:

GET /_tasks

After the operation finishes, use the neural stats API operation to check updated memory usage.

Response body fields

The following table lists all response body fields.