Lucene query strings

When you make an API call, we use the Lucene Query Parser to read it. This introduces some important considerations.

Number of filters are limited

You may apply up to 20 filters, and each filter allows up to 150 terms. The calculation of this is based on Lucene Query String semantics. For example:

  • country_code:us counts as 1 term.
  • country_code:(us OR uk) counts as 2 terms. << "uk" should be "gb"
  • headline: “The Right Way” counts as 3 terms.

Special characters

Special characters + - && || ! ( ) { } [ ] ^ “ ~ * ? : \ / are reserved for the Lucene Query String parser, so you’ll need to escape them with \ before the character if you need to use it.

For example, f-150 should be wrapped up as f\-150, or wrapped inside double quotes as "f-150".

Please note that "" will replace the special characters inside with empty space, so f\-150 will be counted as 1 term while "f-150" is counted as 2 terms.