filters

About this parameter

Filter the query with numeric, facet and/or tag filters.

This parameter uses SQL-like syntax, where you can use boolean operators and parentheses to combine individual filters.

Note that each attribute you use in filters must be defined as a facet. The _tags attribute is automatically defined as a facet.

Numeric Comparisons

Format: ${attributeName} ${operator} ${value}
Example: price > 12.99

The ${value} must be numeric. Supported operators are <, <=, =, !=, >= and >, with the same semantics as in virtually all programming languages.

Numeric Range

Format: ${attributeName}:${lowerBound} TO ${upperBound}
Example: price:5.99 TO 100

${lowerBound} and ${upperBound} must be numeric. Both are inclusive.

Facet filters

Format: ${facetName}:${facetValue}
Example: category:Book

Facet matching is not case sensitive.

When ${facetName} contains string values, it needs to be declared inside attributesForFaceting

Tag filters

Format: _tags:${value} (or, alternatively, just ${value})
Example: _tags:published

Tag matching is case sensitive.

If no attribute name is specified, the filter applies to _tags. For example: public OR user_42 will translate into _tags:public OR _tags:user_42.

Boolean filters

Format: facetName:${boolean_value}
Example: isEnabled:true

When ${facetName} needs to be declared inside attributesForFaceting

Boolean operators

Example:

price < 10 AND (category:Book OR NOT category:Ebook)

Individual filters can be combined via boolean operators. The following operators are supported:

• OR: must match any of the combined conditions (disjunction)
• AND: must match all of the combined conditions (conjunction)
• NOT: negate a filter

Parentheses, ( and ), can be used for grouping.

You cannot mix different filter categories inside a disjunction (OR). For example, num=3 OR tag1 OR facet:value is not allowed.

You cannot negate a group of filters, only an individual filter. For example, NOT(filter1 OR filter2) is not allowed.

For performance reasons, filter expressions are limited to a conjunction (ANDs) of disjunctions (ORs). In other words, you can have ANDs of ORs (e.g. filter1 AND (filter2 OR filter3)), but not ORs of ANDs (e.g. filter1 OR (filter2 AND filter3).

Usage notes:

• Array Attributes: Any attribute set up as an array will match the filter as soon as one of the values in the array match.
• Keywords are case-sensitive.
• When to use quotes (simple or double, depending on the language):
  • If a value or attribute name contains spaces (see example).
  • If a value or attribute name conflicts with a keyword (see example).
  • Phrases that includes quotes, like content:"It's a wonderful day" (see example).
  • Phrases that includes quotes, like attribute:"She said "Hello World"" (see example).
• Nested attributes can be used for filtering, so authors.mainAuthor:"John Doe" is a valid filter, as long as authors.mainAuthor is declared as an attributesForFaceting.

Examples

Apply filters on a search query

1
2
3
$index->search('query', [
  'filters' => '(category:Book OR category:Ebook) AND _tags:published'
]);

1
2
3
index.search('query', {
  filters: '(category:Book OR category:Ebook) AND _tags:published'
})

1
2
3
4
5
6
index.search({
  query: 'query',
  filters: '(category:Book OR category:Ebook) AND _tags:published'
}).then(res => {
  // console.log(res);
});

1
2
3
index.search('query', {
    'filters': '(category:Book OR category:Ebook) AND _tags:published'
})

1
2
3
4
5
6
let query = Query(query: "query")
query.filters = "(category:Book OR category:Ebook) AND _tags:published"

index.search(query, completionHandler: { (res, error) in
  print(res)
})

1
2
3
4
index.search(
  new Query("")
    .setFilters("(category:Book OR category:Ebook) AND _tags:published")
);

1
2
3
4
index.Search<Book>(new Query("query")
{
    Filters = "(category:Book OR category:Ebook) AND _tags:published"
});

1
2
3
4
index.search(
  new Query("query")
    .setFilters("(category:Book OR category:Ebook) AND _tags:published")
);

1
2
3
4
res, err := index.Search(
  "query",
  opt.Filters("(category:Book OR category:Ebook) AND _tags:published"),
)

1
2
3
4
5
6
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    filters = Some("(category:Book OR category:Ebook) AND _tags:published")
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// "(category:Book OR category:Ebook) AND _tags:published"
val query = query("query") {
    filters {
        orFacet {
            facet("category", "Book")
            facet("category", "Ebook")
        }
        and {
            tag("published")
        }
    }
}

index.search(query)

Apply complex filters

1
2
3
4
5
6
7
8
9
10
$filters = 'available = 1'.
          ' AND (category:Book OR NOT category:Ebook)'.
          ' AND _tags:published'.
          ' AND publication_date:1441745506 TO 1441755506'.
          ' AND inStock > 0'.
          ' AND author:"John Doe"';

$index->search('query', [
  'filters' => $filters
]);

1
2
3
4
5
filters = 'available = 1 AND (category:Book OR NOT category:Ebook) AND _tags:published AND publication_date:1441745506 TO 1441755506 AND inStock > 0 AND author:"John Doe"'

index.search('query', {
  filters: filters
})

1
2
3
4
5
6
7
8
const filters = 'available = 1 AND (category:Book OR NOT category:Ebook) AND _tags:published AND publication_date:1441745506 TO 1441755506 AND inStock > 0 AND author:"John Doe"';

index.search({
  query: 'query',
  filters: filters
}).then(res => {
  // console.log(res);
});

1
2
3
4
5
filters = "available = 1 AND (category:Book OR NOT category:Ebook) AND _tags:published AND publication_date:1441745506 TO 1441755506 AND inStock > 0 AND author:\"John Doe\""

index.search('query', {
    'filters': filters
})

1
2
3
4
5
6
let query = Query(query: "query")
query.filters = "available = 1 AND (category:Book OR NOT category:Ebook) AND _tags:published AND publication_date:1441745506 TO 1441755506 AND inStock > 0 AND author:\"John Doe\""

index.search(query, completionHandler: { (res, error) in
  print(res)
})

1
2
3
4
5
6
7
8
9
10
11
12
13
String filters = new String(
  "available = 1"
  + " AND (category:Book OR NOT category:Ebook)"
  + " AND _tags:published"
  + " AND publication_date:1441745506 TO 1441755506"
  + " AND inStock > 0"
  + " AND author:\"John Doe\""
);

index.search(
  new Query("")
    .setFilters(filters)
);

1
2
3
4
5
6
string filters = "available = 1 AND (category:Book OR NOT category:Ebook) AND _tags:published AND publication_date:1441745506 TO 1441755506 AND inStock > 0 AND author:\"John Doe\"";

index.Search<Book>(new Query("query")
{
    Filters = filters
});

1
2
3
4
5
6
7
8
9
10
11
12
13
String filters = new String(
  "available = 1"
  + " AND (category:Book OR NOT category:Ebook)"
  + " AND _tags:published"
  + " AND publication_date:1441745506 TO 1441755506"
  + " AND inStock > 0"
  + " AND author:\"John Doe\""
);

index.search(
  new Query("query")
    .setFilters(filters)
);

1
2
3
4
5
filters := opt.Filters(
  "available = 1 AND (category:Book OR NOT category:Ebook) AND _tags:published AND publication_date:1441745506 TO 1441755506 AND inStock > 0 AND author:\"John Doe\"",
)

res, err := index.Search("query", filters)

1
2
3
4
5
6
7
8
val filters = Some("available = 1 AND (category:Book OR NOT category:Ebook) AND _tags:published AND publication_date:1441745506 TO 1441755506 AND inStock > 0 AND author:\"John Doe\"")

client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    filters = filters
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
//  available = 1
//  AND (category:Book OR NOT category:Ebook)
//  AND _tags:published
//  AND publication_date:1441745506 TO 1441755506
//  AND inStock > 0
//  AND author:\"John Doe\"";
val query = query("query") {
    filters {
        and {
            comparison("available", Equals, 1)
            tag("published")
            range("publication_date", 1441745506..1441755506)
            comparison("inStock", NumericOperator.Greater, 0)
            facet("author", "John Doe")
        }
        orFacet {
            facet("category", "Book")
            facet("category", "EBook", isNegated = true)
        }
    }
}

index.search(query)

Handle attributes with spaces

1
2
3
$index->search('query', [
  'filters' => "category:'Books and Comics'"
]);

1
2
3
index.search('query', {
  filters: "category:'Books and Comics'"
})

1
2
3
4
5
6
index.search({
  query: 'query',
  filters: 'category:"Books and Comics"'
}).then(res => {
  // console.log(res);
});

1
2
3
index.search('query', {
    'filters': "category:'Books and Comics'"
})

1
2
3
4
5
6
let query = Query(query: "query")
query.filters = "category:'Books and Comics'"

index.search(query, completionHandler: { (res, error) in
  print(res)
})

1
2
3
4
index.search(
  new Query("query")
    .setFilters("category:'Books and Comics'")
);

1
2
3
4
index.Search<Book>(new Query("query")
{
    Filters = "category:'Books and Comics'"
});

1
2
3
4
index.search(
  new Query("query")
    .setFilters("category:'Books and Comics'")
);

1
2
3
4
res, err := index.Search(
  "query",
  opt.Filters("category:'Books and Comics'"),
)

1
2
3
4
5
6
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    filters = Some("category:'Books and Comics'")
  )
}

1
2
3
4
5
6
7
8
9
10
11
// "\"category\":\"Books and Comics\""
val query = query("query") {
    filters {
        and {
            // You don't have to escape strings, it is done for you.
            facet("category", "Books and Comics")
        }
    }
}

index.search(query)

Handle attributes conflicting with keywords

1
2
3
$index->search('query', [
  'filters' => "keyword:'OR'"
]);

1
2
3
index.search('query', {
  filters: "keyword:'OR'"
})

1
2
3
4
5
6
index.search({
  query: 'query',
  filters: 'keyword:"OR"'
}).then(res => {
  // console.log(res);
});

1
2
3
index.search('query', {
    'filters': "keyword:'OR'"
})

1
2
3
4
5
6
let query = Query(query: "query")
query.filters = "keyword:'OR'"

index.search(query, completionHandler: { (res, error) in
  print(res)
})

1
2
3
4
index.search(
  new Query("query")
    .setFilters("keyword:'OR'")
);

1
2
3
4
index.Search<Book>(new Query("query")
{
    Filters = "keyword:'OR'"
});

1
2
3
4
index.search(
  new Query("query")
    .setFilters("keyword:'OR'")
);

1
2
3
4
res, err := index.Search(
  "query",
  opt.Filters("keyword:'OR'"),
)

1
2
3
4
5
6
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    filters = Some("keyword:'OR'")
  )
}

1
2
3
4
5
6
7
8
9
10
11
// "\"keyword\":\"OR\""
val query = query("query") {
    filters {
        and {
            // You don't have to escape keywords, it is done for you.
            facet("keyword", "OR")
        }
    }
}

index.search(query)

Handle attributes with single quotes

1
2
3
$index->search('query', [
  'filters' => "content:'It\\'s a wonderful day'"
]);

1
2
3
index.search('query', {
  filters: "content:'It\\'s a wonderful day'"
})

1
2
3
4
5
6
index.search({
  query: 'query',
  filters: 'content:"It\'s a wonderful day"'
}).then(res => {
  // console.log(res);
});

1
2
3
index.search('query', {
    'filters': "content:'It\\'s a wonderful day'"
})

1
2
3
4
5
6
let query = Query(query: "query")
query.filters = "content:'It\\'s a wonderful day'"

index.search(query, completionHandler: { (res, error) in
  print(res)
})

1
2
3
4
index.search(
  new Query("query")
    .setFilters("content:'It\\'s a wonderful day'")
);

1
2
3
4
index.Search<Book>(new Query("query")
{
    Filters = "content:'It\\'s a wonderful day'"
});

1
2
3
4
index.search(
  new Query("query")
    .setFilters("content:'It\\'s a wonderful day'")
);

1
2
3
4
res, err := index.Search(
  "query",
  opt.Filters("content:'It\\'s a wonderful day'"),
)

1
2
3
4
5
6
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    filters = Some("content:'It\\'s a wonderful day'")
  )
}

1
2
3
4
5
6
7
8
9
10
11
// "\"content\":\"It's a wonderful day\""
val query = query("query") {
    filters {
        and {
          // You don't have to escape single quotes, it is done for you.
            facet("content", "It's a wonderful day")
        }
    }
}

index.search(query)

Handle attributes with double quotes

1
2
3
$index->search('query', [
  'filters' => "content:'She said \"Hello World\"'"
]);

1
2
3
index.search('query', {
  filters: "content:'She said \"Hello World\"'"
})

1
2
3
4
5
6
index.search({
  query: 'query',
  filters: 'content:"She said \\"Hello World\\""'
}).then(res => {
  // console.log(res);
});

1
2
3
index.search('query', {
    'filters': "content:'She said \"Hello World\"'"
})

1
2
3
4
5
6
let query = Query(query: "query")
query.filters = "content:'She said \"Hello World\"'"

index.search(query, completionHandler: { (res, error) in
  print(res)
})

1
2
3
4
index.search(
  new Query("query")
    .setFilters("content:'She said \"Hello World\"'")
);

1
2
3
4
index.Search<Book>(new Query("query")
{
    Filters = "content:'She said \"Hello World\"'"
});

1
2
3
4
index.search(
  new Query("query")
    .setFilters("content:'She said \"Hello World\"'")
);

1
2
3
4
res, err := index.Search(
  "query",
  opt.Filters("content:'She said \"Hello World\"'"),
)

1
2
3
4
5
6
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    filters = Some("content:'She said \"Hello World\"'")
  )
}

1
2
3
4
5
6
7
8
9
10
// "\"content\":\"She said Hello World\""
val query = query("query") {
    filters {
        and {
            facet("content", "She said \"Hello World\"")
        }
    }
}

index.search(query)

Filters syntax validator

Type your filter to validate it: