Predicates

The following are the BQL Predicate filters, which are used to filter on a specific field against a specific value.

Main Predicates

Equals

{
  "field": "field_slug",
  "predicate": "eq",
  "value": "text"
}

Contains

{
  "field": "field_slug",
  "predicate": "contains",
  "value": "text"
}

Starts with

{
  "field": "field_slug",
  "predicate": "starts",
  "value": "text"
}

Ends with

{
  "field": "field_slug",
  "predicate": "ends",
  "value": "text"
}

Regex matching

The value should be a string that will be interpreted as a regular expression.

{
  "field": "field_slug",
  "predicate": "re",
  "value": ".*botify.*botify.*"
}

Lower than

{
  "field": "field_slug",
  "predicate": "lt",
  "value": 10
}

Lower than or equal

{
  "field": "field_slug",
  "predicate": "lte",
  "value": 10
}

Greater than

{
  "field": "field_slug",
  "predicate": "gt",
  "value": 10
}

Greater than or equal

{
  "field": "field_slug",
  "predicate": "gte",
  "value": 10
}

Between

Both boundaries are inclusive.

{
  "field": "field_slug",
  "predicate": "between",
  "value": [1, 10]
}

Is equivalent to 1 ≤ field_slug ≤ 10

Exists

Can be compared to a SQL IS NOT NULL condition, which only tests that the value will not be null.
No value needs to be specified.

{
  "field": "field_slug",
  "predicate": "exists"
}

Tree Predicates

Some fields, as the segmentation or breadcrumbs, are tree types. The tree levels are separated using slashes /.

To illustrate, for the examples below, let's consider a breadcrumb hierarchy like:

Breadcrumb level 1Breadcrumb level 2Breadcrumb level 3
ClothingTopsT-shirts

With children

Filters on the specified value and all children.

{
	"filters": {
		"field": "metadata.structured.breadcrumb.tree",
		"predicate": "with_children",
		"value": "Clothing/Tops"
	}
}

Will include results that have a:

  • breadcrumb level 1 that is Clothing, and
  • breadcrumb level 2 that is Tops

The breadcrumb level 3 doesn't matter, the filter includes both breadcrumbs that only have two levels, but also those who have three or more.

Without children

Filters solely on breadcrumbs with the specified value, excluding its children.

{
	"filters": {
		"field": "metadata.structured.breadcrumb.tree",
		"predicate": "without_children",
		"value": "Clothing/Tops"
	}
}

Will only include results that have a:

  • breadcrumb level 1 that is Clothing, and
  • breadcrumb level 2 that is Tops, and
  • breadcrumb level 3 that doesn't exist

Only children

Filters on breadcrumb children that start with the specified value, excluding values that match exactly the input.

{
	"filters": {
		"field": "metadata.structured.breadcrumb.tree",
		"predicate": "only_children",
		"value": "Clothing/Tops"
	}
}

Will include results that have a:

  • breadcrumb level 1 that is Clothing, and
  • breadcrumb level 2 that is Tops, and
  • breadcrumb level 3

The breadcrumb level 3 has to exist in order to appear.

Value Lists Predicates

Value lists are mainly used for Keyword Groups, which can be found in RealKeywords.
Once you know the identifier of the values list, you can filter that the field is contained in all values contained by the list.

{
  "field": "keyword",
  "predicate": "in_list",
  "value": "listname-identifier"
}

List Predicates

Main predicate can be used to filter on list fields, to either filter lists where at least one value matches, or all values match.

{
  "field": "list_field_slug",
  "predicate": "any.eq",
  "value": 10
}
{
  "field": "list_field_slug",
  "predicate": "all.eq",
  "value": 10
}

List of available list predicates:

  • any.eq
  • any.contains
  • any.starts
  • any.ends
  • any.re
  • any.lt
  • any.lte
  • any.gt
  • any.gte
  • any.between
  • all.eq
  • all.contains
  • all.starts
  • all.ends
  • all.re
  • all.lt
  • all.lte
  • all.gt
  • all.gte
  • all.between