Query and rerank
On this page you’ll query one namespace and then several, learn to read the scores and metadata in a response, and see what to do when part of a query fails.
Prerequisites
- A running Cortrix service. See the Quickstart.
- A namespace with processed documents. This page reuses the
guidenamespace from Upload documents.
Run a query
Every query goes through one endpoint, POST /api/v1/query. query and namespaces are required:
The response has two parts, meta and results. Only the key fields of results are shown here:
The refund policy, which is relevant to the question, comes first with a rerank score of 0.824. The unrelated shipping policy gets a rerank score of 0.
Request parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | Required | The query text |
namespaces | string array | Required | The namespaces to search |
top_k | integer | 10 | How many results to return. The minimum is 1 |
rerank | boolean | true | Whether to reorder candidates with the reranker model |
include_sources | boolean | — | When true, results include source information |
filter | object | — | Filter conditions |
For the full request shape, see the HTTP API reference.
Use the plural namespaces array. A singular namespace is rejected:
Read the results
Each result is a block:
| Field | Meaning |
|---|---|
content | The block’s text |
namespace | The namespace the block belongs to |
metadata.source_path | The original filename of the source document |
rerank_score | The relevance score from the reranker model |
score | The score after fusing the retrieval paths |
Use rerank_score to judge whether a result is relevant to the question. score is the fused score used for ordering. Its values are small and aren’t a good absolute measure of relevance.
Query across namespaces
List several namespaces in namespaces, and the results are merged into one ranked list:
Each result’s namespace field tells you where it came from. Use ["*"] to query every namespace you have access to, up to 100.
Handle partial failure
When you query across namespaces, the request still returns HTTP 200 even if some namespaces fail. Check meta to see whether the result is complete:
Here nope doesn’t exist, and the response meta looks like this. Note that a missing or misspelled namespace is reported as CX_ERR_INDEX_CORRUPT, not as a not-found error:
Don’t judge completeness from the HTTP status code alone. A coverage_ratio below 1 means the results cover only some of the namespaces. Every entry in namespaces_failed carries retryable and category, which you can use to decide whether to retry.
Turn off reranking
Set rerank to false to skip reranking:
In testing, the response still carried a rerank_score field with reranking off, but with completely different values. In the example above, the first result went from 0.824 to 0.033. Don’t compare scores across the two modes.
The response also carries a CX_WARN_RERANK_DISABLED warning.
For when reranking helps and when it doesn’t, see When to rerank.
Check for degraded results
meta.warnings is an array of JSON objects with string fields code, reason, and category; some entries also include an integer retry_after_ms in milliseconds. These warnings don’t change the HTTP status: the response still returns HTTP 200 with results.
For example, a request with "rerank": false adds this entry to meta.warnings:
| Code | When it appears | reason | category | retry_after_ms | What to do |
|---|---|---|---|---|---|
CX_WARN_RERANK_DISABLED | The request sets "rerank": false. Ordering uses the fused retrieval score instead of the reranker model. | rerank_disabled | permanent | — | Expected when you asked for it. Don’t retry. Set rerank to true or omit it if you want reranked order. |
CX_WARN_LLM_RERANK_DEGRADED | The request sets "llm_rerank": true, a query-time LLM is configured, and there are at least two results. LLM calls fail, time out, or return unusable rankings, leaving a window without any usable vote. | llm_rerank_degraded | transient | 1000 | Results are usable and keep their order from before LLM reranking, never a partial LLM order. If LLM ordering matters, wait retry_after_ms and send the same request again. |
CX_WARN_RAG_FUSION_DEGRADED | The request sets "rag_fusion": true, a query-time LLM is configured, the query takes the multi-query path, and the LLM call that generates query variants fails. | rag_fusion_degraded | transient | 5000 | Results are usable but come from the original query alone, without variants. To get fused results, wait retry_after_ms and retry. |
The two LLM warnings report a failure of a step that ran. A missing warning doesn’t prove the step ran. To confirm, use ?explain=true and look for llm_rerank or rag_fusion under explain.llm_dependent_features; each key is present only when that step ran.
See how a query ran
Add ?explain=true and the response gains an explain section describing the path the query took:
The output is shortened. The full object has more fields, including ns_id, routing_decision_source, crag_verdict, crag_score, and llm_dependent_features.
rrf_path_counts shows that this query used both vector search (dense) and full-text search (fts5), and that the two result sets were then fused and ranked.
Next steps
- Work with memory
- Python SDK: run the same query with
client.search(). - HTTP API reference