Docs Developer Site
DeveloperDocsXpStableStorageFilters

Filters

Contents

Introduction

Filters work differently from queries. When searching with a regular query, steps like sorting and scoring are done to produce the result.

These are relatively costly operations. A filter does none of these steps. A filter only removes nodes from the result - and is executed after the query statement, if it exists.

As such, filters are the most efficient way of limiting hits when you only need basic comparison statements.

XP XP 7.11.0 7.11.0 It is recommended to use query filtering instead of filters, however they can be used simultaneously.

Syntax

Filters are defined using a DSL (Domain Specific Language) expressed in JSON.

Below is an example of a filter used in the content-API

Sample filter usage 
var result = contentLib.query({
    start: 0,
    count: 2,
    query: "data.city = 'Oslo' AND fulltext('data.description', 'garden', 'AND') ",
    filters: {
        boolean: {
            must: {
                exists: {
                    field: "modifiedTime"
                }
            },
            mustNot: {
                hasValue: {
                    field: "myField",
                    values: [
                        "cheese",
                        "fish",
                        "onion"
                    ]
                }
            }
        },
        notExists: {
            field: "unwantedField"
        },
        ids: {
            values: ["id1", "id2"]
        }
    }
});

If specifying several filters on root level, the filters are automatically joined with a boolean "must" clause, meaning all filters much match.

The following filters are supported:

exists

The exists filter filter outs any document not containing any values in the given property.

field (string)

The property path

Sample use of exists filter 
{
  "start": 0,
  "count": 2,
  "filters": {
    "exists": {
      "field": "publish.from"
    }
  }
}

notExists

The notExists filter removes nodes containing values in the given property.

field (string)

The property path

Sample use of notExists filter 
{
  "start": 0,
  "count": 2,
  "filters": {
    "notExists": {
      "field": "publish.from"
    }
  }
}

hasValue

The hasValue filter matches if document contain any of the values given in the value list

field (string) The property path

values (object[]) Array of values to decide a match

Sample hasValue filter 
{
  "start": 0,
  "count": 2,
  "filters": {
    "hasValue": {
      "field": "product",
      "values" : [
        "plunge saw",
        "combination square",
        "router",
        "mitre saw"
      ]
    }
  }
}

ids

The ids filter is a shorthand filter to filter on ids

values (string[]) Arrays of ids to match

Sample ids filter 
{
  "start": 0,
  "count": 2,
  "filters": {
    "ids": {
      "values": [
        "0123456789",
        "1234567890"
      ]
    }
  }
}

boolean

The boolean filter combines functions in logical expressions

must (filter[])

All functions on the must array must evaluate to true for the filter to match

mustNot (filter[])

All functions in the mustNot array must evaluate to false for the filter to match

should (filter[])

One or more of the functions in the should array must evaluate to true for the filter to match

Sample boolean filter 
{
  "start": 0,
  "count": 2,
  "filters": {
    "boolean": {
      "must": {
        "exists": {
          "field": "modifiedTime"
        }
      },
      "mustNot": {
        "hasValue": {
          "field": "myField",
          "values": [
            "cheese",
            "fish",
            "onion"
          ]
        }
      }
    }
  }
}

Contents

Contents