Search Filters

Added in: release-2023-07

Search filters can be used to filter documents using a custom query DSL.

Filter Fields

Metadata fields must be indexed. Please read the Publication Index guide for further information. Details of the core metadata plugins, along with their built-in indexing capabilities, can be found in the Metadata Plugin List.

The index type of each field will determine which query capabilities are supported:

Query Expressions

Term

The standard value comparison behaviour.

An exact match is required, although some type coercion may be applied.

{
  key: 'metadata.title',
  term: 'My Title'
}

An array can also be provided as the ’term’ value, which behaves like an OR operator.

{
  key: 'metadata.language.locale',
  term: ['de', 'fr']
}

Range

Search within a range.

{
  key: 'metadata.count',
  range: {lte: 2}
}

Multiple range terms (‘gt’, ‘gte’, ’lt’, ’lte’) can be combined.

{
  key: 'metadata.count',
  range: {gt: 1, lt: 5}
}

Exists

Check if a property has been set.

When querying a metadata property with an object value, always use the key of a leaf node (e.g. metadata.teaserImage.mediaId), because the parent itself (e.g. metadata.teaserImage) is not indexed.

{
  key: 'metadata.teaserImage.mediaId',
  exists: true
}

Logical Operators

The logical operators allow you to group queries, and to change from the default AND behaviour of the top-level array. All logical operator values can be an object, or an array, containing logical operators or query expressions.

AND

All conditions must be met for a publication to be included in the results.

{
  and: [
    {key: 'metadata.news', term: true},
    {key: 'metadata.teaserImage.mediaId', exists: false}
  ]
}

OR

Any condition can be met for a publication to be included in the results.

{
  or: [
    {key: 'metadata.image.mediaId', exists: true},
    {key: 'metadata.teaserImage.mediaId', exists: true}
  ]
}

NOT

This operator negates the expression contained within.

{
  not: {key: 'metadata.language.locale', term: 'de'}
}

To negate multiple conditions nest another logical operator within.

{
  not: {
    or: [
      {key: 'metadata.news', term: false},
      {key: 'metadata.language.locale', term: 'fr'}
    ]
  }
}

Example

An example of how the logical operators and query expressions can be combined to create a more complex query:

const filters = JSON.stringify({
  or: [
    {
      and: [
        {
          key: 'metadata.count',
          range: {lte: 2}
        },
        {
          key: 'metadata.bool',
          exists: true
        },
        {
          not: {
            key: 'metadata.title',
            term: 'My Title'
          }
        }
      ]
    },
    {
      key: 'metadata.count',
      term: 3
    }
  ]
})

const response = await fetch(`api/v1/publications/search?filters=${filters}`)
const results = await response.json()

Sort Fields

Valid sort fields are:

• relevance
• sortDate
• documentId
• contentType
• firstPublicationDate
• lastPublicationDate
• significantPublicationDate
• visiblePublicationDate
• metadata.*

The default sort order is sortDate descending (see Sort Date), with documentId descending used as a fallback when multiple results have exactly the same sortDate.

relevance will only have an affect if you provide a search term.

Most metadata properties can be used to sort, but not those indexed as text or boolean (see Filter Fields).

When a string is used to define the sort order, the order can be reversed by prefixing the property with a - (e.g. -sortDate,documentId).

Documents which don’t have an indexed value will appear at the end of the results.