Retrieve endpoint

Save PDF

Last Updated: September 9, 2026
6 minute read

Documentation

The /v1/retrieve endpoint is the primary search interface for the MarkLogic Retrieval API. It provides powerful document search capabilities using text queries, vectors, constraint-based filters, and collection labels.

Overview

The retrieve endpoint searches for documents in the MarkLogic database and returns a list of matching document URIs. It supports:

Text Search: Full-text search using MarkLogic's search capabilities (supports phrase search with double quotes)
Vector Search: Vector similarity search using embeddings
Constraint Filters: Apply filters based on document properties
Collection Labels: Filter by MarkLogic collections with MustHave/MustNotHave logic
Entity Inputs: Accepted for future entity expansion; non-empty values currently return a warning
Relation Inputs: Accepted for future relation expansion; non-empty values currently return a warning
Result Limiting: Control the number of results returned

Basic Usage

HTTP POST is recommended for most queries, especially those with complex parameters.

curl -X POST http://localhost:8003/v1/retrieve \
  -H "Content-Type: application/json" \
  --digest -u admin:admin \
  -d '{
    "text": "heart disease treatment",
    "topk": 20,
    "labels": {
      "medical-data": {
        "constraintValue": "MustHave"
      }
    }
  }'

GET requests are supported and useful for testing with a web browser, but require URL-encoded parameters.

curl -X GET "http://localhost:8003/v1/retrieve?text=diabetes&topk=5" \
  --digest -u admin:admin

Parameters

text (string)

The search query text. Performs full-text search across document content. See Searching Using String Queries.

Important: Empty text parameter returns empty results (not all documents)

Syntax:

Individual words (AND): "diabetes treatment" - matches documents containing BOTH 'diabetes' AND 'treatment'
OR operator: "diabetes OR treatment" - matches documents containing 'diabetes' OR 'treatment' (or both)
Exact phrase: "\"chronic bronchitis\"" - matches only the exact phrase "chronic bronchitis"
Mixed query (AND): "\"heart disease\" treatment" - matches documents with exact phrase "heart disease" AND word "treatment"
Phrase with OR: "\"heart disease\" OR diabetes" - matches documents with exact phrase "heart disease" OR word 'diabetes'
Multiple phrases (AND): "\"Type 2 diabetes\" \"insulin resistance\"" - matches documents with BOTH exact phrases
Multiple OR operators: "asthma OR diabetes OR hypertension" - matches documents with any of these terms

Behavior:

Default boolean logic is AND (all terms must match)
Use explicit OR operator for union behavior (any term matches)
Phrases must use double quotes (") for exact matching
Empty quoted phrases ("") return no results
Results are ordered by relevance score

topk (integer)

Maximum number of results to return per search type (full-text or vector). When both full-text and vector searches run, the merged result set may contain up to 2× this value. Default is 10.

labels (object)

Collection-based filtering with MustHave/MustNotHave constraints. Keys are collection names, values specify whether documents must have or must not have that collection.

Structure:

{
  "text": "clinical trials",
  "labels": {
    "collection1": {
      "constraintValue": "MustHave"
    },
    "collection2": {
      "constraintValue": "MustNotHave"
    }
  }
}

filters (object)

Constraint-based filtering using MarkLogic constraints. Filters allow you to narrow results by document properties, ranges, or custom constraints.

Structure:

{
  "text": "clinical trials",
  "filters": {
    "categoryValueConstraint": {
      "constraintType": "Value",
      "constraintValue": "cardiovascular"
    },
    "statusConstraint": {
      "constraintType": "Value",
      "constraintValue": "completed"
    }
  }
}

📖 For comprehensive filter documentation, see the Filters Guide.

vectors (object)

Vector search using embeddings. Keys are embedding names, values are arrays of numbers representing the embedding vectors.

Structure:

{
  "vectors": {
    "embedding1": [0.1, 0.2, 0.3, 0.4, 0.5],
    "embedding2": [0.6, 0.7, 0.8, 0.9, 1.0]
  }
}

metadata (array)

Specify which metadata fields to include in the response. Valid values must come from metadataFields in GET /v1/retrieve/definition.

Example:

{
  "text": "clinical studies",
  "metadata": ["labels", "entities"]
}

If unknown field names are requested, the endpoint returns a warning listing invalid names and still returns values for valid requested fields.

Response Format

Success Response

HTTP Status: 200 OK

Body:

{
  "matches": [
    {
      "id": "/pubmed/39702603.xml",
      "labels": ["medical-data", "pubmed"],
      "score": {
        "fulltext": 7680,
        "vectors": {}
      },
      "extractedText": {
        "vectorExtractedText": null,
        "fulltextExtractedText": null
      }
    },
    ...
  ],
  "totalMatches": 42
}

Response Fields:

The response is an object with the following top-level fields:

matches — array (required): Array of result objects, ordered by relevance.
totalMatches — integer (optional): Total number of documents in the database that match the search query, regardless of the topk limit. Present for text-based searches; absent for vector-only queries (when only vectors is provided). Use this to determine whether topk needs to be increased to capture more results.
warnings — array of strings (optional): Warning messages generated during query processing, including filter configuration issues, non-empty entities or relations parameters, and unknown metadata field names. Absent when there are no warnings.

Each match object in the matches array contains:

id — string (required): The document URI/identifier.
labels — array of strings (required): Collections assigned to the matching document.
score — object (required): Relevance scores for the document.
- fulltext — number (required): Full-text search relevance score; higher is better.
- vectors — object (required): Vector similarity scores keyed by embedding name.
extractedText — object (required): Text extractions from the document.
- vectorExtractedText — object or null (required): For vector search results, an object keyed by vector column name. Each value maps non-system Optic row column names to values; null for full-text-only results.
- fulltextExtractedText — array of objects or null (required): Text extracted through configured XPath expressions. Each object has text and xpathSource properties. null for vector-only results, or an empty array when no extractionXPaths are configured. See extractionXPaths in the Retrieve Config Guide.
metadataProperties — object (optional): Extracted metadata field values keyed by field name. Present only when the metadata parameter was provided, and only for full-text search results.
chunkData — object (optional): Present only for a pre-processed RAG chunk identified by the chunks configuration in retrieveConfig.json. Absent for non-chunk documents.
- chunkCollection — string (required): The MarkLogic collection that identified this document as a chunk.
- parentUri — string (optional): URI of the original source document. Omitted if the configured chunkIdRegex lacks capture group 1.
- chunkNumber — integer (optional): Zero-based ordinal position within the parent document. Omitted if the configured chunkIdRegex lacks capture group 2.
- totalChunks — integer (optional): Total number of chunks detected for the same parent document. Omitted when the total cannot be derived.
- previousChunkUri — string (optional): URI of the immediately previous chunk. Omitted for first chunks or when the neighbor cannot be derived or found.
- nextChunkUri — string (optional): URI of the immediately next chunk. Omitted for last chunks or when the neighbor cannot be derived or found.
- extractedText — array of strings (required): Text extracted from the chunk via the extractionXPaths configured in the matching chunks entry of retrieveConfig.json.

See chunks in the Retrieve Config Guide for configuration details.

Empty Results

If no documents match the search criteria, the matches array will be empty:

{
  "matches": []
}

Error Responses

Error responses generally have the following response body:

{
  "errorResponse": {
    "statusCode": 400,
    "status": "Bad Request",
    "message": "Invalid parameter format"
  }
}

The errorResponse object always contains statusCode (the numeric HTTP status), status (the HTTP reason phrase), and message (a human-readable description).

400 — Invalid request format or parameters.
- Status: Bad Request
- Message: Invalid parameter format
401 — Missing or invalid authentication.
- Status: Unauthorized
- Message: Authentication required
500 — Server-side error.
- Status: Internal Server Error
- Message: Search execution failed

Search Behavior

Filter Combination Logic

Multiple filters use AND logic (all must match)
Labels (collections) are combined with AND logic for multiple collections
Filters and labels are combined together (document must satisfy both)

Result Ordering

Results in the matches array are ordered by:

Relevance score - Higher score.fulltext values appear first
Vector similarity - When vectors are provided, score.vectors influences ranking
Text match quality - Exact matches rank higher than partial matches

The matches array contains results in descending order of relevance, with the most relevant documents first.

Performance Considerations

Text-only searches: Very fast, uses MarkLogic's optimized indexes
Vector searches: May be slower for large embedding dimensions
Multiple filters: Each additional filter adds processing overhead
Large topk values: May impact performance, use reasonable limits

MarkLogic MCP Server