Filter Expressions

Filter expressions are used when doing lookups in JSON or JavaScript schemas. Most sections below show what you can write, with an example for both schema types.

If you are using JavaScript and your filter contains expressions, it’s often easier to use string interpolation instead of string concatination. See MDN Web Docs .

If you are comparing values containing URI special characters, you should URI encode the value in your filter expression. See MDN Web Docs.

filter(`originParentId eq '${encodeURIComponent(sourceEntity.originId)}'`)

Compare values

JavaScript
JSON

EQUALS operator

// Property value equal to constant string value
originId eq '100'

// Property value equal to expressed string value
originId eq '${sourceEntity.properties.selectedOtherPageId}'

// Property value is null
originParentId eq null

// Property value equal to integer value
properties.price eq 9

// Property value equal to decimal value
properties.price eq 9.99

// Property value equal to boolean value (true/false)
properties.isFeatured eq true

EQUALS operator

// Property value equal to constant string value
originId eq '100'

// Property value equal to expressed string value
originId eq '{p.selectedOtherPageId}'

// Property value is null
originParentId eq null

// Property value equal to integer value
properties.price eq 9

// Property value equal to decimal value
properties.price eq 9.99

// Property value equal to boolean value (true/false)
properties.isFeatured eq true

JavaScript
JSON

NOT EQUALS operator

// Property value not equal to constant string value
originId ne '100'

// Property value not equal to expressed string value
originId ne '${sourceEntity.properties.selectedOtherPageId}'

// Property value is not null
originParentId ne null

// Property value not equal to integer value
properties.price ne 9

// Property value not equal to decimal value
properties.price ne 9.99

// Property value not equal to boolean value (true/false)
properties.isFeatured ne true

NOT EQUALS operator

// Property value not equal to constant string value
originId ne '100'

// Property value not equal to expressed string value
originId ne '{p.selectedOtherPageId}'

// Property value is not null
originParentId ne null

// Property value not equal to integer value
properties.price ne 9

// Property value not equal to decimal value
properties.price ne 9.99

// Property value not equal to boolean value (true/false)
properties.isFeatured ne true

ne doesn’t match source entities that don’t have the property. properties.status ne 'archived' skips every source entity without a status. eq null doesn’t match them either, as it only matches a property that is set to null. If you need to include them, make sure every source entity has the property.

Combine conditions

JavaScript
JSON

AND operator

type eq 'article' and properties.isFeatured eq true

AND operator

type eq 'article' and properties.isFeatured eq true

JavaScript
JSON

OR operator

type eq 'article' or type eq 'contentPage'

OR operator

type eq 'article' or type eq 'contentPage'

Use parentheses to group conditions when you mix and and or.

JavaScript
JSON

Group conditions with parentheses

// Articles in either the news or the sport category
type eq 'article' and (properties.category eq 'news' or properties.category eq 'sport')

Group conditions with parentheses

// Articles in either the news or the sport category
type eq 'article' and (properties.category eq 'news' or properties.category eq 'sport')

Match a value in a list

JavaScript
JSON

Check whether the element exists in this collection

// Finds matches in predefined integers array
properties.favoriteId in (100, 200)

// Finds matches in predefined strings array
properties.color in ('blue', 'red', 'green')

// Finds matches in favorites selection (array of integers)
properties.favoriteId in (${sourceEntity.properties.favoriteIds})

// Finds matches in colors selection (array of strings)
properties.color in (${sourceEntity.properties.colors.map(c => `'${c}'`)})

Check whether the element exists in this collection

// Finds matches in predefined integers array
properties.favoriteId in (100, 200)

// Finds matches in predefined strings array
properties.color in ('blue', 'red', 'green')

// Finds matches in favorites selection (array of integers)
properties.favoriteId in {properties.favoriteIds}

// Finds matches in colors selection (array of strings)
properties.color in {properties.selectedColors}

Arrays

Use any to check the items of an array property, for example redirects or an array property on the source entity. Name the item in front of the colon, then write the condition for one item after it.

Contains a matching value

JavaScript
JSON

Contains a matching value

// Contains specific redirect with constant string value
redirects/any(r: r eq '/old-page')

// Contains specific tags with expression string value
properties.tags/any(t: t eq '${sourceEntity.properties.selectedTag}')

// Contains articles that feature, matching constant boolean value
properties.articles/any(a: a.isFeatured eq true)

// Contains an article that is both featured and in the sport category
properties.articles/any(a: a.isFeatured eq true and a.category eq 'sport')

// Contains either tag
properties.tags/any(t: t eq 'news' or t eq 'sport')

// Contains both tags
properties.tags/any(t: t eq 'news') and properties.tags/any(t: t eq 'sport')

// Articles tagged news or sport
type eq 'article' and (properties.tags/any(t: t eq 'news') or properties.tags/any(t: t eq 'sport'))

// Contains a featured article in either category
properties.articles/any(a: a.isFeatured eq true and (a.category eq 'news' or a.category eq 'sport'))

Contains a matching value

// Contains specific redirect with constant string value
redirects/any(r: r eq '/old-page')

// Contains specific tags with expression string value
properties.tags/any(t: t eq '{p.selectedTag}')

// Contains articles that feature, matching constant boolean value
properties.articles/any(a: a.isFeatured eq true)

// Contains an article that is both featured and in the sport category
properties.articles/any(a: a.isFeatured eq true and a.category eq 'sport')

// Contains either tag
properties.tags/any(t: t eq 'news' or t eq 'sport')

// Contains both tags
properties.tags/any(t: t eq 'news') and properties.tags/any(t: t eq 'sport')

// Articles tagged news or sport
type eq 'article' and (properties.tags/any(t: t eq 'news') or properties.tags/any(t: t eq 'sport'))

// Contains a featured article in either category
properties.articles/any(a: a.isFeatured eq true and (a.category eq 'news' or a.category eq 'sport'))

Conditions combined with and inside any must all match the same item. properties.articles/any(a: a.isFeatured eq true and a.category eq 'sport') only matches if one article is both featured and in the sport category, not if one article is featured and another is in the sport category.An and that no single item can satisfy isn’t an error, it just never matches. properties.tags/any(t: t eq 'news' and t eq 'sport') finds nothing, because no tag is both. To match source entities that have both tags, use two any joined with and, as in the “Contains both tags” example.

Build the list of values from the source entity

In a JavaScript schema you can build the or list inside any from the source entity, for example from a list of selected tags. in isn’t supported inside any, so join eq comparisons with or instead:

Match any of the selected tags

export default {
  // ...
  properties: async function (sourceEntity, context) {
    const selectedTags = sourceEntity.properties.selectedTags || [];

    // An empty any() isn't a valid filter, so skip the lookup when nothing is selected
    const relatedArticles = selectedTags.length === 0
      ? []
      : await context
          .lookup(`type eq 'article' and properties.tags/any(t: ${selectedTags.map(tag => `t eq '${tag}'`).join(' or ')})`)
          .toPromise();

    return {
      relatedArticles
    };
  },
};

With selectedTags set to ['news', 'sport'], the filter becomes type eq 'article' and properties.tags/any(t: t eq 'news' or t eq 'sport').

JSON schemas can’t build a list inside any. If you need to match an array property against a list of values from the source entity, use a JavaScript schema.

Doesn’t contain a matching value

JavaScript
JSON

Doesn't contain a matching value

// Doesn't contain a specific redirect
not redirects/any(r: r eq '/old-page')

// Doesn't contain a specific tag with expression string value
not properties.tags/any(t: t eq '${sourceEntity.properties.excludedTag}')

// Articles that aren't tagged as archived
type eq 'article' and not properties.tags/any(t: t eq 'archived')

Doesn't contain a matching value

// Doesn't contain a specific redirect
not redirects/any(r: r eq '/old-page')

// Doesn't contain a specific tag with expression string value
not properties.tags/any(t: t eq '{p.excludedTag}')

// Articles that aren't tagged as archived
type eq 'article' and not properties.tags/any(t: t eq 'archived')

not in front of any also matches source entities that don’t have the array, or where it’s null or not an array.

What you can write inside `any`

Inside any, compare the item with eq and combine comparisons with and and or. Put conditions on the source entity itself outside any.These mistakes also don’t return an error, the condition just never matches:

The item on the right of eq for an array under properties, for example 'news' eq t instead of t eq 'news'. For redirects both orders work.
A condition on id, originId or a property under properties inside any, for example properties.category eq 'article'.
A condition on type, url or originParentId inside any, when it’s combined with or or the array is redirects. With redirects and or it can also match the wrong source entities: redirects/any(r: r eq '/a' or type eq 'article') matches any source entity with a redirect from article.

The following aren’t supported and return a validation error:

ne inside any. To match source entities where no item equals a value, use eq and put not in front of any.
in inside any. Join eq comparisons with or instead.
eq null inside any.
any inside any, and all.
not anywhere other than directly in front of any.
A condition on type, url or originParentId combined with and inside any, on an array under properties.
An any where and over or groups expands to more than 256 combinations, for example nine (a or b) groups combined with and. A plain or list isn’t limited. Reduce the number of or groups combined with and.

Common mistakes

You write	What happens	Write this instead
`properties.tags/any(t: t eq 'news' and t eq 'sport')`	Never matches, because no single tag is both	`properties.tags/any(t: t eq 'news') and properties.tags/any(t: t eq 'sport')`
`properties.tags/any(t: t ne 'archived')`	Validation error	`not properties.tags/any(t: t eq 'archived')`
`properties.tags/any(t: t in ('news', 'sport'))`	Validation error	`properties.tags/any(t: t eq 'news' or t eq 'sport')`
`properties.articles/any(a: 'sport' eq a.category)`	Never matches	`properties.articles/any(a: a.category eq 'sport')`
`properties.tags/any(t: t eq 'news' and type eq 'article')`	Validation error	`type eq 'article' and properties.tags/any(t: t eq 'news')`
`properties.tags/any(t: t eq 'news' and properties.category eq 'article')`	Never matches	`properties.category eq 'article' and properties.tags/any(t: t eq 'news')`

Full example

JavaScript
JSON

Full example

export default {
  // ...
  properties: function (sourceEntity, context) {
    return {
        // ...
        sportArticles: context
                .reference('featuredSportArticle')
                .filter(`type eq 'article' and properties.tags/any(t: t eq '${sourceEntity.properties.tag}') and not properties.tags/any(t: t eq 'archived')`)
                .orderBy({ propertyName: 'properties.metaData.sortOrder', direction: "asc"})
                .limit(5)
    }
  },
};

Full example

"sportArticles": {
    "type": "array",
    "input": {
        "$lookup": {
            "filter": "type eq 'article' and properties.tags/any(t: t eq '{p.tag}') and not properties.tags/any(t: t eq 'archived')",
            "orderBy": {
              "property": "properties.metaData.sortOrder",
              "sort": "asc"
            },
            "top": 5
        }
    },
    "var": "article",
    "items": {
        "type": "object",
        "properties": {
            "title": "{article.p.title}",
            "content": "{article.p.content}"
        }
    }
}

Overview

Schema reference

API

Integrations

Tutorials

Best practices

CLI

MCP server

Compare values

Combine conditions

Match a value in a list

Arrays

Contains a matching value

Build the list of values from the source entity

Doesn’t contain a matching value

What you can write inside `any`

Common mistakes

Full example

​Compare values

​Combine conditions

​Match a value in a list

​Arrays

​Contains a matching value

​Build the list of values from the source entity

​Doesn’t contain a matching value

​What you can write inside any

​Common mistakes

​Full example

Compare values

Combine conditions

Match a value in a list

Arrays

Contains a matching value

Build the list of values from the source entity

Doesn’t contain a matching value

What you can write inside `any`

Common mistakes

Full example