API Reference / API Parameters / filters

Nov 25, 2021

filters

Type: string

Engine default: "" (no filters)

Parameter syntax

'filters' => 'facet:value'
             'NOT facet:value'
             // Optional: prefix with NOT to negate the filter condition
             '_tags:value'
             // Optional: prefix each filter with NOT to negate the filter condition
             'facet:value AND | OR facet:value'
             // Optional: prefix with NOT to negate the numeric filter conditions
             'numericFacet = | != | > | >= | < | <= number'
             'numericFacet:lower_value TO higher_value'

filters: "facet:value"
         "NOT facet:value"
         # Optional: prefix with NOT to negate the filter condition
         "_tags:value"
         # Optional: prefix each filter with NOT to negate the filter condition
         "facet:value AND | OR facet:value"
         # Optional: prefix with NOT to negate the numeric filter conditions
         "numericFacet = | != | > | >= | < | <= number"
         "numericFacet:lower_value TO higher_value"

filters: 'facet:value'
         'NOT facet:value'
         // Optional: prefix with NOT to negate the filter condition
         '_tags:value'
         // Optional: prefix each filter with NOT to negate the filter condition
         'facet:value AND | OR facet:value'
         // Optional: prefix with NOT to negate the numeric filter conditions
         'numericFacet = | != | > | >= | < | <= number'
         'numericFacet:lower_value TO higher_value'

"filters": "facet:value"
           "NOT facet:value"
           # Optional: prefix with NOT to negate the filter condition
           "_tags:value"
           # Optional: prefix each filter with NOT to negate the filter condition
           "facet:value AND | OR facet:value"
           # Optional: prefix with NOT to negate the numeric filter conditions
           "numericFacet = | != | > | >= | < | <= number"
           "numericFacet:lower_value TO higher_value"

query.filters = "facet:value"
                "NOT facet:value"
                // Optional: prefix with NOT to negate the filter condition
                "_tags:value"
                // Optional: prefix each filter with NOT to negate the filter condition
                "facet:value AND | OR facet:value"
                // Optional: prefix with NOT to negate the numeric filter conditions
                "numericFacet = | != | > | >= | < | <= number"
                "numericFacet:lower_value TO higher_value"

filters {
    // Declare an OR group for facet filters.
    orFacet {
        // "attribute:value"
        facet("attribute", "value")
        facet("attribute", 0)
        facet("attribute", true)

        facet("attribute", "value", isNegated = true) // Negate a filter
    }
    // Declare an OR group for tag filters.
    orTag {
        // "_tags:value"
        tag("value")
    }
  // Declare an OR group for numeric filters.
    orNumeric {
        // "attribute:lowerBound TO upperBound"
        range("attribute", 0..10)
        range("attribute", 0f, 10f)
        // "numeric_attribute =  numeric_value"
        comparison("attribute", Less, 0f)
        comparison("attribute", LessOrEquals, 0f)
        comparison("attribute", Equals, 0f)
        comparison("attribute", NotEquals, 0f)
        comparison("attribute", Greater, 0f)
        comparison("attribute", GreaterOrEquals, 0f)
    }
    // Declare an AND group for any type of filters.
    and {
        // "attribute:value"
        facet("attribute", "value")
        facet("attribute", true)
        facet("attribute", 0)
        tag("value")
        range("attribute", 0..10)
        comparison("attribute", NumericOperator.Less, 0f)
    }
}

.Filters("facet:value")
.Filters("NOT facet:value")
// Optional: prefix with NOT to negate the filter condition
.Filters("_tags:value")
// Optional: prefix each filter with NOT to negate the filter condition
.Filters("facet:value AND | OR facet:value")
// Optional: prefix with NOT to negate the numeric filter conditions
.Filters("numericFacet = | != | > | >= | < | <= number")
.Filters("numericFacet:lower_value TO higher_value")

.setFilters("facet:value")
.setFilters("NOT facet:value")
// Optional: prefix with NOT to negate the filter condition
.setFilters("_tags:value")
// Optional: prefix each filter with NOT to negate the filter condition
.setFilters("facet:value AND | OR facet:value")
// Optional: prefix with NOT to negate the numeric filter conditions
.setFilters("numericFacet = | != | > | >= | < | <= number")
.setFilters("numericFacet:lower_value TO higher_value")

opt.Filters("facet:value")
opt.Filters("NOT facet:value")
// Optional: prefix with NOT to negate the filter condition
opt.Filters("_tags:value")
// Optional: prefix each filter with NOT to negate the filter condition
opt.Filters("facet:value AND | OR facet:value")
// Optional: prefix with NOT to negate the numeric filter conditions
opt.Filters("numericFacet = | != | > | >= | < | <= number")
opt.Filters("numericFacet:lower_value TO higher_value")

filters = Some("facet:value")
          Some("NOT facet:value")
          // Optional: prefix with NOT to negate the filter condition
          Some("_tags:value")
          // Optional: prefix each filter with NOT to negate the filter condition
          Some("facet:value AND | OR facet:value")
          // Optional: prefix with NOT to negate the numeric filter conditions
          Some("numericFacet = | != | > | >= | < | <= number")
          Some("numericFacet:lower_value TO higher_value")

Can be used in these methods:
search, browseObjects, deleteBy, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey search, browse_objects, delete_by, search_for_facet_values, generate_secured_api_key, add_api_key, update_api_key search, browseObjects, deleteBy, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey search, browse_objects, delete_by, search_for_facet_values, generate_secured_api_key, add_api_key, update_api_key search, browse, deleteBy, searchForFacetValues, generateSecuredApiKey, addAPIKey, updateAPIKey search, browseObjects, deleteObjectBy, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey Search, Browse, DeleteBy, SearchForFacetValues, GenerateSecuredApiKeys, AddApiKey, UpdateApiKey Search, browse, deleteBy, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey Search, BrowseObjects, DeleteBy, SearchForFacetValues, GenerateSecuredAPIKey, AddAPIKey, UpdateAPIKey search, browse index, delete by, search into facet values, generateSecuredApiKey, add key, update key

See code examples

About this parameter

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

Filter combinations can be created using SQL-style boolean logic, including AND, OR, and parentheses for grouping.

You must declare every attribute you use as a filter in attributesForFaceting, except _tags, which are automatically included.

For more inforamtion, see Filters and boolean operators.

Usage notes

Filtering array attributes

Filters on array attributes need only one array element to match. For example, if a record contains the array attribute genres: ["fiction", "thriller", "sci-fi"], the filter genres:thriller returns this record.

Nested attributes for filtering

For example, authors.mainAuthor:"John Doe" is a valid filter, as long as you declare authors.mainAuthor in attributesForFaceting.

Use of quotes

Use quotes in these cases (single or double, depending on the language):

Attribute names or values with spaces.
Attribute names or values conflict with keywords, such as, NOT, OR, or AND.
Attribute names or values with single quotes, such as content:"It's a wonderful day".
Attribute names or values with double quotes, such as attribute:"She said "Hello World"".

Examples

Apply filters on a search query

Copy

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

1
2
3
4
5
6
7
8
let query = Query("query")
  .set(\.filters, to: "(category:Book OR category:Ebook) AND _tags:published")

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

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)

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")
  )
}

Apply complex filters

Copy

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
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', {
  filters: filters
}).then(({ hits }) => {
  console.log(hits);
});

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
let query = Query("query")
  .set(\.filters, to: "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) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

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)

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
  )
}

Handle attributes with spaces

Copy

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

1
2
3
4
5
6
7
8
let query = Query("query")
  .set(\.filters, to: "category:'Books and Comics'")

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

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

Copy

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

1
2
3
4
5
6
7
8
let query = Query("query")
  .set(\.filters, to: "keyword:'OR'")

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

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

Copy

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

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

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

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

Copy

1
2
3
$index->search('query', [
  'filters' => "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)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
index.Search<Book>(new Query("query")
{
    Filters = "content:'She said \"Hello World\"'"
});

  swift: |

let query = Query("query")
  .set(\.filters, to: "content:'She said \"Hello World\"'")

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

Did you find this page helpful?

filters

About this parameter

Usage notes

Filtering array attributes

Nested attributes for filtering

Use of quotes

Examples

Apply filters on a search query

Apply complex filters

Handle attributes with spaces

Handle attributes conflicting with keywords

Handle attributes with single quotes

Handle attributes with double quotes

On this page