Definition endpoint

The /v1/retrieve/definition endpoint returns the current search configuration for the MarkLogic Retrieval API. This endpoint provides metadata about available constraints, collections, search options, and configuration details that can be used with the /v1/retrieve endpoint.

Overview

The retrieve definition endpoint is essential for discovering:

• Available Constraints: What filters can be applied in searches
• Configured Collections: Which collections (labels) are available
• Search Options: Configuration settings for the search engine
• Query Capabilities: What types of queries are supported
• Metadata: Information about the search configuration

Basic Usage

Simple Request

Retrieve the current search configuration:

curl -X GET http://localhost:8003/v1/retrieve/definition \
  --digest -u admin:admin

Request Parameters

This endpoint does not accept any parameters.

Response Format

Success Response

HTTP Status: 200 OK

The response contains the complete search options configuration from MarkLogic, including constraints, operators, and other search settings.

Example Response Structure:

{
  "description": "...",
  "labels": [
    {
      "label": "...",
      "description": "...",
      "requireWhen": [
        "...",
        ...
      ],
      "avoidWhen": [
        "...",
        ...
      ]
    },
    ...
  ],
  "filters": {
    "categoryValueConstraint": {
      "filterType": "...",
      "dataType": "string",
      "description": "...",
      "operators": ["eq", "ne"],
      "exampleValues": ["abstract", "full-text"],
      "caseSensitive": false,
      "wildcardSupport": false
    },
    ...
  },
  "documentSchemas": [
    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "title": "...",
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "title": { "type": "string" },
        "category": { "type": "string" }
      }
    }
  ],
  "vectorMetadata": [
    {
      "schemaName": "Medical",
      "viewName": "SmallMedicalView",
      "vectorColumn": "smallMedicalEmbedding",
      "embeddingModel": "text-embedding-3-small",
      "dimensions": 16
    }
  ],
  "metadataFields": ["entities", "labels", "relations"],
  "recommendedWorkflow": {
    "steps": [
      {
        "step": 1,
        "endpoint": "GET /v1/retrieve/definition",
        "purpose": "..."
      },
      {
        "step": 2,
        "endpoint": "POST /v1/retrieve",
        "purpose": "..."
      },
      {
        "step": 3,
        "endpoint": "POST /v1/retrieve/augment",
        "purpose": "..."
      }
    ]
  },
  "queryFormat": {
    ...
  }
}

Response Fields

• description — string; required. Human-readable description of this database deployment. Configured via the databaseDescription field in retrieveConfig.json. If not configured, returns "No description configured for this deployment. Set databaseDescription in retrieveConfig.json." — set this field so agents understand what data they are searching.
• labels — array; required. Available collection metadata objects for use with the labels parameter.
  • label — string; required. Collection name.
  • description — string; optional. Human-readable label description from config.
  • requireWhen — array of strings; optional. Guidance on when this label is recommended.
  • avoidWhen — array of strings; optional. Guidance on when this label should be avoided.
• filters — object; required. Available filters keyed by constraint name.
  • filterType — string; required. "Value", "Word", "Range", or "View".
  • dataType — string; required. Data type for the constraint, such as string, date, or int.
  • description — string; required. Human-readable description of the filter.
  • operators — array of strings; optional. Supported comparison operators. Value and Word constraints use eq and ne; Range constraints use GT, GE, LT, LE, EQ, and NE. See Filter Types.
  • exampleValues — array; optional. Sample values illustrating valid inputs for the filter.
  • caseSensitive — boolean; optional. Whether value matching is case-sensitive for Value filters.
  • wildcardSupport — boolean; optional. Whether wildcard characters are supported in constraint values for Value filters.
• documentSchemas — array; required. JSON schemas describing document structures.
• vectorMetadata — array; required. Metadata about vector embeddings, including dimensions and models.
• metadataFields — array; required. Discoverable metadata field names that can be used in the metadata request parameter for POST /v1/retrieve.
• recommendedWorkflow — object; required. Machine-readable description of the recommended three-step agent workflow. Always present. Use this to orient agents that have no prior knowledge of the API.
  • steps — array; required. Ordered list of steps.
    • step — integer; required. Step number (1, 2, 3).
    • endpoint — string; required. The endpoint to call at this step.
    • purpose — string; required. Why to call this endpoint at this step.
• queryFormat — object; required. Machine-readable reference for constructing a valid POST /v1/retrieve request body. Describes all accepted fields, their types, and how they relate to values returned elsewhere in this response. Intended for agents that need to build retrieve requests without consulting external documentation.

Using Discovered Filters

The filters object identifies the constraint names available in this deployment. For each constraint, use its filterType as constraintType in a /v1/retrieve request. operators and exampleValues describe valid values; Value filters can also report caseSensitive and wildcardSupport.

For request formats, filter behavior, and examples for Value, Word, Range, View, and collection constraints, see the Filters Guide.

The labels array identifies available collections. Its optional requireWhen and avoidWhen fields are advisory client guidance only; a label affects search results only when it is included in the labels object of a /v1/retrieve request.

Response Details

Filter Types

The definition response includes four main types of filters:

1. Value Filters (filterType: "Value"): For exact value matching

   • Match exact values in document properties
   • Data types: string, number, boolean
   • Used for categorical filtering
   • Optional: operators (eq, ne), exampleValues, caseSensitive, wildcardSupport

2. Word Filters (filterType: "Word"): For tokenized word matching

   • Case-insensitive word-level matches within a document property
   • Multiple words in a single constraint value are combined with OR
   • Optional: operators (eq, ne), exampleValues

3. Range Filters (filterType: "Range"): For range-based filtering

   • Numeric ranges (int, float, double)
   • Date ranges (date, dateTime)
   • String ranges (lexical ordering)
   • Optional: operators (GT, GE, LT, LE, EQ, NE), exampleValues

4. View Filters (filterType: "View"): For TDE/Optic view joins

   • Join search results with relational views
   • Access structured data via SQL-like operations
   • Includes column definitions and types

Document Schemas

JSON Schema definitions describing the structure of documents in the database:

• $schema: JSON Schema version
• title: Schema name
• type: Root type (typically "object")
• properties: Document field definitions with types
• exampleUri: Example document URI

Vector Metadata

Information about vector embeddings available for vector search. Each entry in vectorMetadata corresponds to a TDE-backed embedding that can be used in the vectors parameter of /v1/retrieve.

Entries missing any required field are omitted from the response.

• schemaName — string; required. TDE schema containing the vector.
• viewName — string; required. TDE view containing the vector.
• vectorColumn — string; required. Column name of the vector. Use this value as the key in the vectors request parameter when calling /v1/retrieve: {"vectors": {"<vectorColumn>": [...]}}.
• embeddingModel — string; required. Model used to generate embeddings.
• dimensions — integer; required. Vector dimensionality — submitted vectors must be exactly this length.
• modelVersion — string; optional. Version of the embedding model.
• description — string; optional. Human-readable guidance on the domain covered and when to use this embedding.
• requireWhen — array of strings; optional. Scenarios where this embedding is recommended.
• avoidWhen — array of strings; optional. Scenarios where this embedding should not be used.

queryFormat

queryFormat is a machine-readable field specification for POST /v1/retrieve. It is intended primarily for LLM agents and programmatic clients that need to construct valid retrieve request bodies without consulting external documentation. Every value that an agent needs to fill in a request — label names, constraint names, and vector column names — is available elsewhere in the same definition response; queryFormat makes those cross-references explicit.

Top-level fields:

• endpoint — string. Always "POST /v1/retrieve".
• contentType — string. Always "application/json".
• notes — array of strings. Usage notes covering cross-references, AND/OR search query guidance.
• fields — object. One entry per accepted /v1/retrieve request field.

Fields entries:

• text — string. Keyword/boolean full-text search. Words are AND-ed by default; use OR between synonyms for broader recall. See queryFormat.notes for full search guidance.
• topk — integer. Default: 10. Maximum results per search mode. When both text and vector search run, up to 2×topk results may be returned.
• labels — object. Filter by collection. Keys are label names from the labels array in this response. Each value requires constraintValue: "MustHave" or "MustNotHave".
• filters — object. Constraint-based filters. Keys are constraint names from the filters object in this response. Each value must include constraintType matching that constraint's filterType.
• vectors — object. Vector search. Keys are vectorColumn values from vectorMetadata in this response. Each value is a number array whose length must exactly match the corresponding dimensions.
• metadata — array of strings. Field names to extract from document metadata elements. Valid values are listed in metadataFields in this response. Results appear in metadataProperties on each match. Unknown names are ignored and reported as warnings.
• entities — array of strings. Reserved — accepted but not yet implemented. When non-empty, a warning is returned in the response.
• relations — array of strings. Reserved — accepted but not yet implemented. When non-empty, a warning is returned in the response.

Cross-references within the response:

• labels keys → labels[].label values in this response
• filters keys → filters object keys in this response; constraintType must match that entry's filterType
• vectors keys → vectorMetadata[].vectorColumn values in this response; array length must match vectorMetadata[].dimensions
• metadata values → metadataFields values in this response

Example (abbreviated):

"queryFormat": {
  "endpoint": "POST /v1/retrieve",
  "contentType": "application/json",
  "notes": [
    "All fields are optional...",
    ...
  ],
  "fields": {
    "text": {
      "type": "string",
      "description": "...",
      "example": "..."
    },
    "topk": {
      "type": "integer",
      "default": 10,
      "description": "..."
    },
    "labels": {
      "type": "object",
      "description": "...",
      "valueSchema": {
        "constraintValue": {
          "type": "string",
          "required": true,
          "enum": ["MustHave", "MustNotHave"] 
        }
      }
    },
    "filters": {
      "type": "object",
      "description": "...",
      "constraintTypes": {
        "Range": {
          ...
        },
        "View": {
          ...
        },
        ...
      }
    },
    "vectors": {
      "type": "object",
      "description": "..."
    },
    "entities": {
      "type": "array",
      "items": "string",
      "status": "reserved",
      "description": "..."
    },
    "relations": {
      "type": "array",
      "items": "string",
      "status": "reserved",
      "description": "..."
    }
  }
}

Relationship with /v1/retrieve

The definition endpoint provides metadata that informs how to use the /v1/retrieve endpoint:

1. Constraint Names: Use the exact constraint names from the definition in your search filters
2. Constraint Types: The type determines the constraintType value (Value, Range, etc.)
3. Collection Names: Collection constraints map to labels in search requests
4. Data Types: Range constraint types inform what values are valid

Example Workflow:

# 1. Get definition
definition = get_search_definition()

# 2. Check available labels (collections)
available_labels = [label_obj['label'] for label_obj in definition['labels']]
print(f"Available labels: {available_labels}")

# 3. Check available filters
available_filters = definition['filters']
print(f"Available filters: {list(available_filters.keys())}")

# 4. Build search request using valid filters and labels
if 'categoryValueConstraint' in available_filters and 'medical-data' in available_labels:
    search_request = {
        "text": "treatment",
        "labels": {
            "medical-data": {
            "constraintValue": "MustHave"
            }
        },
        "filters": {
            "categoryValueConstraint": {
                "constraintType": "Value",
                "constraintValue": "cardiovascular"
            }
        }
    }

    # 5. Execute search
    response = requests.post(
        "http://localhost:8003/v1/retrieve",
        json=search_request,
        auth=HTTPDigestAuth("admin", "admin"),
        headers={"Content-Type": "application/json"}
    )
    results = response.json()

Error Responses

Error responses generally have the following response body:

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

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

• 400 — The request was malformed (this endpoint accepts no parameters, so a 400 typically indicates an unexpected request body or invalid content type).
  • Status: Bad Request
  • Message: Invalid request format
• 401 — Missing or invalid credentials.
  • Status: Unauthorized
  • Message: Authentication required
• 500 — Server-side failure, typically caused by a misconfigured or missing retrieveConfig.json. Check that the document exists at /marklogic-retrieval-api/retrieveConfig.json and is valid JSON.
  • Status: Internal Server Error
  • Message: Failed to load configuration

Examples

#!/bin/bash

# Fetch definition and list labels
curl -s -X GET http://localhost:8003/v1/retrieve/definition \
  --digest -u admin:admin | jq -r '.labels[] | .label'

# List all filter names
curl -s -X GET http://localhost:8003/v1/retrieve/definition \
  --digest -u admin:admin | jq -r '.filters | keys[]'

# Count filters by type
curl -s -X GET http://localhost:8003/v1/retrieve/definition \
  --digest -u admin:admin | jq '{
    value: [.filters[] | select(.filterType == "Value")] | length,
    word: [.filters[] | select(.filterType == "Word")] | length,
    range: [.filters[] | select(.filterType == "Range")] | length,
    view: [.filters[] | select(.filterType == "View")] | length
  }'

# Get vector dimensions
curl -s -X GET http://localhost:8003/v1/retrieve/definition \
  --digest -u admin:admin | jq '.vectorMetadata[] | "\(.schemaName).\(.viewName): \(.dimensions)D"'