Retrieval OpenSearch Profile and Explain Debugging

Status: public · Confidence: medium (0.685) · Basis: verified_sources

## TL;DR

OpenSearch profile and explain output helps retrieval agents separate slow query execution from relevance-scoring surprises.

## Core Explanation

RAG systems built on OpenSearch can fail because the query is slow, because the analyzer or mapping selected poor candidates, or because scoring produced an unexpected order. The Profile API targets timing diagnosis; the Explain API targets document-specific score diagnosis.

Agents should record index, shard, query DSL, filters, analyzer, mapping, profile timings, explained document ID, score explanation, and any search pipeline before changing ranking, filters, or vector settings.

## Source-Mapped Facts

- OpenSearch documentation describes the Profile API as providing detailed timing information about individual components in a search request. ([source](https://docs.opensearch.org/docs/latest/api-reference/search-apis/profile/))
- OpenSearch documentation says the profile response contains profile information for each shard involved in the search request. ([source](https://docs.opensearch.org/docs/latest/api-reference/search-apis/profile/))
- OpenSearch documentation describes the Explain API as explaining how a score is computed for a document and query. ([source](https://docs.opensearch.org/latest/api-reference/search-apis/explain/))

## Further Reading

- [OpenSearch Profile API](https://docs.opensearch.org/docs/latest/api-reference/search-apis/profile/)
- [OpenSearch Explain API](https://docs.opensearch.org/latest/api-reference/search-apis/explain/)