Skip to main content
The Visual Editor lets you apply filters with Rules. If you want to apply optional filters or other API parameters, you need to add them in the Manual Editor as JSON. In this guide, FACET:VALUE refers to a facet-value pair, such as, author:shakespeare.

​
Filters

Filters excludes that don’t match the filter. If you have a multi-word VALUE (such as William Shakespeare), wrap it in single quotes. For example:
JSON
If your VALUE contains an apostrophe (such as Tony d’Arbon), escape the apostrophe with double backslashes and wrap the whole string in single quotes. For example:
JSON

​
Optional filters

Optional filters don’t remove records from the results, but they promote or demote matching records. You can fine-tune the behavior of optional filters with filter scores.
Any attribute you want to use as an optional filter must be declared as a facet.

​
Examples for optional filters

The following examples show different use cases for optional filters, their JSON representation, and the effect on filter scoring.

​
Promote a category

Filter scoring: +1 for all matching records
JSON

​
Promote several categories with equal weight

Filter scoring: +1 for all records matching one or more filter
JSON

​
Promote several categories with different weights per category

Filter scoring: +X or +Y, whichever matches and has the highest value
JSON

​
Promote several categories with a combined score

Filter scoring: +1 or +2, depending on the number of matching filters
JSON

​
Promote several categories with combined weighting

Filter scoring: +X, +Y, or +X+Y, depending on the matching filters
JSON

​
Demote a category

Filter scoring: +1 for all records that don’t match the filter
JSON

​
Demote several categories equally

Filter scoring: +1 for all records that don’t match any of the filters
JSON

​
Optional filters with multiple words

Unlike filters, you don’t need to wrap a multi-word VALUE with single quotes if it contains spaces. For example:
JSON

​
See also

Last modified on May 19, 2026