API Reference / API Parameters / optionalFilters

Feb. 26, 2019

optionalFilters

Type: list of strings

Engine default: []

Parameter syntax

'optionalFilters' => [
    'attribute:value',
    ['attribute1:value', 'attribute2:value'],
]

optionalFilters: [
    'attribute:value',
    ['attribute1:value', 'attribute2:value'],
]

optionalFilters: [
  'attribute:value',
  ['attribute1:value', 'attribute2:value'],
]

'optionalFilters': [
    'attribute:value',
    ['attribute1:value', 'attribute2:value'],
]

let optionalFilters = ["category:Book", "author:John Doe"]

optionalFilters {
    // Declare an OR group for optional facet filters.
    or {
        facet("attribute", "value")
        facet("attribute", 0)
        facet("attribute", true)

        facet("attribute", "value", isNegated = true) // Negate a facet filter
    }
    // Declare an AND group for optional facet filters.
    and {
        facet("attribute", "value")
        facet("attribute", true)
        facet("attribute", 0)
    }
}

.setOptionalFilters("attribute:value", "attribute1:value")

var optionalFilters =  new List<List<string>> 
{ 
    new List<string> {"attribute:value"},
    new List<string> {"attribute1:value", "attribute2:value"},
}

.addCustomParameter(
  "optionalFilters",
  Arrays.asList(
    "attribute:value",
    Arrays.asList(
      "attribute1:value",
      "attribute2:value"
    )
  )
)

// Single string
opt.FacetFilter("attribute:value")

// attribute1:value AND attribute2:value
opt.FacetFilterAnd("attribute1:value", "attribute2:value")

// attribute1:value OR attribute2:value
opt.FacetFilterOr("attribute1:value", "attribute2:value")

// (attribute1:value OR attribute2:value) AND attribute3:value
opt.FacetFilterAnd(
  opt.FacetFilterOr("attribute1:value", "attribute2:value"),
  opt.FacetFilter("attribute3:value"),
)

// (attribute1:value OR attribute2:value) AND attribute3:value (alternative)
opt.FacetFilterAnd(
  []string{"attribute1:value", "attribute2:value"},
  "attribute3:value",
)

"optionalFilters" -> Some(Seq(
  "attribute:value",
  Some(Seq(
    "attribute1:value",
    "attribute2:value"
  )),
))

Can be used in these methods:
search, browseObjects, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey search, browse, search_for_facet_values, generate_secured_api_key, add_api_key, update_api_key search, browse, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey search, browse_objects, search_for_facet_values, generate_secured_api_key, add_api_key, update_api_key search, browse, searchForFacetValues search, browseObjects, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey searchAsync, browseAsync, searchForFacetValues Search, Browse, SearchForFacetValues, GenerateSecuredApiKey, AddApiKey, UpdateApiKey Search, browse, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey Search, BrowseObjects, SearchForFacetValues, GenerateSecuredAPIKey, AddAPIKey, UpdateAPIKey search, browse index, search into facet values, generateSecuredApiKey, add key, update key

See code examples

About this parameter

Create filters for ranking purposes, where records that match the filter are ranked highest.

Optional filtering behaves like normal filters, meaning that it returns records that match both the query and the filters. However, it also returns records that do not match the filters. The effect is on the ranking: records matching the filters are ranked higher than records that do not match the filters.

Usage notes:

The boolean syntax is the same as facetFilters, except for negative syntax. If you use negative syntax, for example categories:-Book, it will not work; it will be transformed into categories:Book.
Promoting results: See how you can use optionalFilters to promote filters and facets.
Ranking Formula: This setting will only work if the Filters criterion is part of the ranking. Filters is by default part of the ranking; so if you’ve removed it, and yet wish to use option filters, you’ll need to add it back to the ranking formula.

For customers on the Community, Essential and Plus legacy plans who signed up before December 15, 2018, optional filters are limited to only one per query. Free plans do not have access to optional filters.

For all other plans (Enterprise, Pro, Starter), optional filters are unlimited.

Examples

Apply optional filters on a search query

Copy

$results = $index->search('query', [
  'optionalFilters' => [
    "category:Book",
    "author:John Doe"
  ]
]);

let query = Query()
query.optionalFilters = ["category:Book", "author:John Doe"]

index.search(query) { (content, error) in
   if error == nil {
        print(content)
   }
}

index.search(
        new Query("query").setOptionalFilters(
                Collections.singletonList(Arrays.asList(
                        "category:Book",
                        "author:John Doe")))
);

client.execute {
  search into "myIndex" query Query(
    customParameters = Some(
      Map(
        "optionalFilters" -> Some(Seq(
          "category:Book",
          "author:John Doe"
        ))
      )
    )
}

val query = query("query") {
    optionalFilters {
        and {
            facet("category", "Book")
            facet("author", "John Doe")
        }
    }
}

index.search(query)

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

iOS

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

iOS InstantSearch

Android InstantSearch

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Magento 1

Magento 2

WordPress

Shopify

optionalFilters

About this parameter

Usage notes:

Examples

Apply optional filters on a search query

Did you find this page helpful?

On this page