Retrieval and ranking model

MarkLogic Retrieval API (MRA) performs retrieval after MarkLogic MCP Server forwards a Retrieve tool request. MRA can use full-text search, vector similarity search, labels, and filters. When a request contains more than one search signal, MRA returns the signals together rather than calculating a single blended relevance score.

Retrieval pipeline

MRA processes a retrieval request in this general order:

1. Apply configured base filters and request labels and filters to restrict the candidate set.
2. Run full-text search when the request contains text.
3. Run a vector search for each supplied vector.
4. Merge results that have the same document URI.
5. Return matching URIs, scores, extracted text, and requested metadata.

There is no separate learned reranking layer. Full-text and vector scores remain independent in the response.

Full-text retrieval and scoring

Full-text retrieval uses MarkLogic Server search indexes. The default scoring method is BM25 with a configurable length-normalization weight.

The text field follows these behaviors:

• Multiple terms are combined with AND by default.
• The explicit OR operator broadens the query to documents matching any alternative.
• Double quotation marks identify an exact phrase.
• Results include a full-text score in score.fulltext.

For example, diabetes treatment requires both terms, whereas diabetes OR treatment allows either term.

Use labels and filters for required structural constraints rather than attempting to express every restriction as query text.

Vector retrieval and scoring

[MarkLogic Server 12 and up]

Vector retrieval uses cosine similarity between a request vector and a vector column configured through vectorMetadata.

For each configured embedding, MarkLogic Server applies the following validation and scoring:

• The request identifies the target by its vectorColumn name.
• The supplied vector length must match the configured dimensions.
• The vector is evaluated independently.
• The resulting similarity value appears in score.vectors.<vectorColumn>.

For a vector-only match, score.fulltext is 0.

Labels and filters

Labels and filters determine which documents are eligible to appear in the result set. They are applied before scoring and do not increase or decrease a document's relevance score.

Labels

Labels represent MarkLogic Server collections. A request can require or exclude a collection by using MustHave or MustNotHave.

Configured label descriptions, requireWhen guidance, and avoidWhen guidance help an MCP client decide whether a label is appropriate. This guidance is advisory. Only labels included in the retrieval request affect execution. See Retrieve config.

Filters

Filters apply configured MarkLogic Server search constraints or TDE view joins. MRA supports filter types like these:

• Value filters for exact values
• Range filters for comparisons and ranges
• View filters for TDE and Optic data

Multiple labels and filters narrow the candidate set according to the request's combination rules. The MCP client uses RetrieveDefinition to discover the names and supported properties available in the current deployment.

topk behavior

topk limits each search pass independently:

• Full-text search returns up to topk results.
• Each vector search returns up to topk results.

The merged response can therefore contain more than topk matches. Treat topk as a per-signal limit, not as a global limit on the final merged result set.

Result merging

MRA merges full-text and vector result sets by document URI. If the same URI appears in more than one result set, then the results are consolidated:

• The document appears once in the merged response.
• The document's full-text score is retained.
• The document's vector scores are added under score.vectors.

MRA does not calculate a blended score that combines the full-text and vector values. These values must be evaluated as parallel relevance signals.

Because the response does not provide a unified score, do not assume that scores from different search modes can be compared directly or that the merged order represents a learned reranking stage.

Returned result information

Each match can include this information:

• The document URI in id
• Collection labels
• score.fulltext
• One or more values under score.vectors
• Text extracted with configured XPath expressions
• Requested metadata properties
• Chunk information when the document matches a configured chunk pattern

For text searches, totalMatches reports the count from the text-search pass. It is not a count of every possible result across the merged full-text and vector result sets. Vector-only responses do not include totalMatches.

Extracted text and augmentation

For full-text results, configured extraction XPath expressions can return text and its source XPath in extractedText.fulltextExtractedText. An MCP client can pass the returned URI and XPath to Augment to retrieve the corresponding document fragment.

For whole-document retrieval, the MCP client passes document URI strings to Augment. For fragment retrieval, the MCP client can pass objects containing uri and xpath. When requested, provenance identifies the source document and XPath used for the returned fragment.

Tuning guidance

• Start with a small topk and increase it when testing shows that relevant results are omitted.
• Use OR for synonyms or alternate terminology when broader full-text recall is required.
• Use labels and filters for required inclusion, exclusion, property, range, or view conditions.
• Use vector retrieval when semantic similarity is needed.
• Inspect full-text and vector scores separately when both retrieval modes are used.
• Verify vector model names and dimensions against RetrieveDefinition before submitting vectors.
• Adjust BM25 length normalization only after testing demonstrates an undesirable ranking pattern.

Limitations

• MRA does not produce a single blended full-text and vector score.
• topk is applied per search pass rather than to the final merged result set.
• totalMatches represents the text-search pass when text is present.
• Entity and relation inputs are accepted but are not used for search expansion.