Skip to content

Query and rerank

Run hybrid retrieval over one or more namespaces, with reranking.

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 guide namespace from Upload documents.

Run a query

Every query goes through one endpoint, POST /api/v1/query. query and namespaces are required:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["guide"],
    "query": "How long do refunds take?",
    "top_k": 3,
    "rerank": true
  }' \
  http://127.0.0.1:8420/api/v1/query

The response has two parts, meta and results. Only the key fields of results are shown here:

{
  "meta": {
    "coverage_ratio": 1.0,
    "latency_ms": 222,
    "namespaces_failed": [],
    "namespaces_queried": ["guide"],
    "namespaces_succeeded": ["guide"],
    "warnings": []
  },
  "results": [
    {
      "content": "Refund policy\nCustomers can request a refund within 30 days of purchase. ...",
      "metadata": { "source_path": "refund-policy.txt" },
      "namespace": "guide",
      "rerank_score": 0.824,
      "score": 0.0167
    },
    {
      "content": "Shipping policy. Orders ship within 2 business days. ...",
      "metadata": { "source_path": "shipping-policy.txt" },
      "namespace": "guide",
      "rerank_score": 0.0,
      "score": 0.0164
    }
  ]
}

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

ParameterTypeDefaultDescription
querystringRequiredThe query text
namespacesstring arrayRequiredThe namespaces to search
top_kinteger10How many results to return. The minimum is 1
rerankbooleantrueWhether to reorder candidates with the reranker model
include_sourcesboolean—When true, results include source information
filterobject—Filter conditions

For the full request shape, see the HTTP API reference.

Warning

Use the plural namespaces array. A singular namespace is rejected:

{
  "error": {
    "category": "permanent",
    "code": "CX_ERR_DEPRECATED_FIELD",
    "message": "Field 'namespace' is deprecated, use 'namespaces' array instead",
    "retryable": false,
    "structured_data": { "deprecated_field": "namespace", "use_instead": "namespaces" }
  }
}

Read the results

Each result is a block:

FieldMeaning
contentThe block’s text
namespaceThe namespace the block belongs to
metadata.source_pathThe original filename of the source document
rerank_scoreThe relevance score from the reranker model
scoreThe 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:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["guide", "demo"],
    "query": "How long do refunds take?",
    "top_k": 3
  }' \
  http://127.0.0.1:8420/api/v1/query

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:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"namespaces": ["guide", "nope"], "query": "refunds", "top_k": 2}' \
  http://127.0.0.1:8420/api/v1/query

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:

{
  "coverage_ratio": 0.5,
  "namespaces_failed": [
    {
      "category": "permanent",
      "error_code": "CX_ERR_INDEX_CORRUPT",
      "message": "CX_ERR_INDEX_CORRUPT",
      "namespace": "nope",
      "retry_after_ms": null,
      "retryable": false,
      "structured_data": { "index_state": "unavailable", "namespace": "nope" }
    }
  ],
  "namespaces_queried": ["guide", "nope"],
  "namespaces_succeeded": ["guide"]
}
Important

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:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["guide"],
    "query": "How long do refunds take?",
    "top_k": 3,
    "rerank": false
  }' \
  http://127.0.0.1:8420/api/v1/query

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":"CX_WARN_RERANK_DISABLED","reason":"rerank_disabled","category":"permanent"}
CodeWhen it appearsreasoncategoryretry_after_msWhat to do
CX_WARN_RERANK_DISABLEDThe request sets "rerank": false. Ordering uses the fused retrieval score instead of the reranker model.rerank_disabledpermanent—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_DEGRADEDThe 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_degradedtransient1000Results 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_DEGRADEDThe 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_degradedtransient5000Results 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:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"namespaces": ["guide"], "query": "How long do refunds take?", "top_k": 1}' \
  'http://127.0.0.1:8420/api/v1/query?explain=true'
{
  "complexity_score": 0.8999999761581421,
  "granularity": "auto",
  "query": "How long do refunds take?",
  "routing_path": "simple",
  "rrf_path_counts": { "dense": 1, "fts5": 1 },
  "via_path_counts": { "chunk": 1 }
}

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

Table reader