Query Predicates

Predicates provide a way for complex filter expressions when querying resources.

The queryable APIs support ad-hoc filtering of resources through flexible predicates. They do so via the where query parameter that accepts a predicate expression to determine whether a specific resource representation should be included in the result.

Please note that this syntax differs from the ones used for other predicate types, most notably the predicates used to define discount targets.

The structure of predicates and the names of the fields follow the structure and naming of the fields in the documented response representation of the query results.

Examples of predicates:

// Compare a field's value to a given value
name = "Peter"
name != "Peter"
age < 42
age > 42
age <= 42
age >= 42
age <> 42

// Combine any two conditional expressions in a logical conjunction / disjunction
name = "Peter" and age < 42
name = "Peter" or age < 42

// Negate any other conditional expression
not (name = "Peter" and age < 42)

// Check whether a field's value is or is not contained in
// a specified set of values.
age in (42, 43, 44)
age not in (42, 43, 44)

// to be noted: 'in' is much more efficient than several '='
// prefer:
name in ("Peter", "Barbara")
// to:
name = "Peter" or name = "Barbara"

// Check whether an array contains all or any of a set of values
tags contains all ("a", "b", "c")
tags contains any ("a", "b", "c")

// Check whether an array is empty
tags is empty

// Check whether a field exists & has a non-null value
name is defined
name is not defined

// Descend into nested objects
dog(age < 7 and name = "Beethoven")

// Descend into nested arrays of objects
cities(zip > 10000 and zip < 20000)

// Query GeoJSON field within a circle
// The two first parameters are the longitude and latitude of the circle's center.
// The third parameter is the radius of the circle in meter.
geoLocation within circle(13.37770, 52.51627, 1000)

// Query for ProductProjections with attribute values
// - to get all results add a predicate of the same form, but starting with 'masterVariant' instead of 'variants'
// - to query for Products instead enclose the examples with 'masterData(current(<example>))' or 'masterData(staged(<example>))'
// ---------------------------
// for missing attribute
variants(not(attributes(name="attribute-name")))

// for single attribute value of TextType
variants(attributes(name="attribute-name" and value="attribute-value"))
// for multiple attribute values of TextType with same name
variants(attributes(name="attribute-name" and value in ("attribute-value-1", "attribute-value-2")))

// for single attribute value of LTextType
variants(attributes(name="attribute-name" and value(en="attribute-value")))
// for multiple attribute values of LTextType with same name
variants(attributes(name="attribute-name" and value(en="english-value" or de="german-value")))

// for EnumType or LocalizableEnumType
variants(attributes(name="attribute-name" and value(key="enum-key")))

// for MoneyType (currencyCode is required)
variants(attributes(name="attribute-name" and value(centAmount=999 and currencyCode="EUR")))
// for MoneyType with centAmount within a specific range (currencyCode is required)
variants(attributes(name="attribute-name" and value(centAmount > 999 and centAmount < 1001 and currencyCode="EUR")))

// for NumberType
variants(attributes(name="attribute-name" and value=999))
// for NumberType with value within a specific range
variants(attributes(name="attribute-name" and value > 999 and value < 1001 ))

// for DateType, TimeType or DateTimeType
variants(attributes(name="attribute-name" and value="attribute-value"))
// for DateType, TimeType or DateTimeType with a value within a specific range
variants(attributes(name="attribute-name" and value > "value-start" and value < "value-end"))

// for ReferenceType
variants(attributes(name="attribute-name" and value(typeId="reference-type-id" and id="reference-id")))

A query endpoint usually restricts predicates to only be allowed on a specified subset of a resource representation’s fields. The documentation of the endpoint lists fields that can be used for constructing predicates.

If multiple predicates are specified via multiple where query parameters, the individual predicates are combined in a logical conjunction, just as if they had been specified in a single where query parameter and combined with and.

Note: The encoding of the predicates is UTF-8 and the predicate must be URL-encoded in the HTTP request.

Example predicate for querying products:

# decoded predicate
masterData(current(slug(en="peter-42") and name(en="Peter")))

# URL-encoded predicate
masterData%28current%28slug%28en%253D%2522peter-42%2522%29%2520and%2520name%28en%253D%2522Peter%2522%29%29%29