Filters guide

You may use constraint-based filters with the /v1/retrieve endpoint to refine your search results.

Filters let you narrow search results to documents that match specific criteria, such as a value, date range, or collection. The filter types available to you depend on how the MarkLogic Retrieval API is configured for your environment — your administrator defines which constraints exist. Use the Definition Endpoint to discover which filters are available in your deployment before applying them.

Overview

Filters allow you to apply constraint-based filtering to your search results. They work with MarkLogic's constraint framework to narrow down results based on specific criteria such as categories, ranges, or custom constraints defined in your search configuration.

Filter Structure

Filters are specified as a JSON object where:

• Keys: Constraint names (as defined in your MarkLogic search options)
• Values: Objects containing constraint specifications

Basic Structure

{
  "filters": {
    "constraint1": {
      "constraintType": "Value",
      "constraintValue": "some-value"
    },
    ...,
    "constraintN": {
      ...
    }
  }
}

Constraint Types

• Value Constraints — Used to filter by exact values in element or JSON properties.
  • constraintType: Value
  • constraintOperator: eq (default) or ne. Use ne to exclude documents that match the value.
• Word Constraints — Used to filter by tokenized word matches in element or JSON properties. Word constraints perform case-insensitive word-level matching. Multiple words use the OR operator.
  • constraintType: Word
  • constraintOperator: eq (default) or ne. Use ne to exclude documents that match the word.
• Range Constraints — Used to filter by numeric or date ranges. Requires a constraintOperator to specify the comparison type: GT (greater than), GE (greater than or equal), LT (less than), LE (less than or equal), EQ (equal), NE (not equal).
  • constraintType: Range
  • constraintOperator: GT, GE, LT, LE, EQ, NE
  • Note: Range operators must be uppercase. They are passed through to the MarkLogic Server string-query grammar, which does not accept lowercase forms. This differs from Value and Word operators, which the Retrieval API matches case-insensitively.
  • Note: To express a bounded range, pass parallel arrays for constraintValue and constraintOperator. See Bounded ranges.
• View Constraints — Joins search results with MarkLogic Template Driven Extraction (TDE) views to access structured relational data alongside document search results. Use the Definition Endpoint to discover available view constraint names, schemas, views, and columns.
  • constraintType: View
  • constraintOperator: Not applicable.
  • Note: Constraint name must follow {schemaName}.{viewName} format that matches your configured view.
• Collection Constraints — Filter documents by MarkLogic collections. Use the labels parameter instead of filters for collection-based filtering. The optional requireWhen and avoidWhen values returned for a label by the Definition Endpoint are advisory guidance for client workflows and do not affect query execution; only the label's constraintValue does.
  • constraintType: Not applicable.
  • constraintOperator: Not applicable.
  • Note: Constraint name must match an existing collection.

Filter Behavior

AND Logic

Multiple filters are combined with AND logic - documents must match all specified filters.

Negation with ne

Value and Word constraints accept an optional constraintOperator. The default is eq, which requires documents to match the supplied value. Setting it to ne inverts the constraint, excluding documents that match:

{
  "filters": {
    "categoryValueConstraint": {
      "constraintType": "Value",
      "constraintValue": "cardiovascular",
      "constraintOperator": "ne"
    }
  }
}

All negated constraints are combined and subtracted from the positive constraints, so a request containing only ne filters returns every document that does not match them.

Bounded ranges

A single Range constraint applies one comparison. To bound a range on both ends, pass arrays of equal length for constraintValue and constraintOperator. The pairs are matched by position and combined with AND logic:

{
  "filters": {
    "publicationDateRangeConstraint": {
      "constraintType": "Range",
      "constraintValue": ["2020-01-01", "2023-12-31"],
      "constraintOperator": ["GE", "LE"]
    }
  }
}

If the two arrays have different lengths, the constraint is skipped and a warning is returned in the response.

Case Sensitivity

Case sensitivity depends on the constraint type and how your MarkLogic constraint is configured:

• Value Constraints can be case-sensitive or case-insensitive depending on the underlying constraint configuration
• Word Constraints are case-insensitive word-level matches
• Range Constraints compare values according to the configured data type and operator

Missing Values

Documents without the filtered field are excluded from results.

Empty Filters

An empty filters object {} applies no filtering (equivalent to omitting the parameter).