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'],
]

optionalFilters = [
  "attribute:value",
  .or("attribute1:value", "attribute2:value")
]

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

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, generateSecuredApiKey, addApiKey, updateApiKey search, browse_objects, generate_secured_api_key, add_api_key, update_api_key search, browseObjects, generateSecuredApiKey, addApiKey, updateApiKey search, browse_objects, generate_secured_api_key, add_api_key, update_api_key search, browse, generateSecuredApiKey, addAPIKey, updateAPIKey search, browseObjects, generateSecuredApiKey, addApiKey, updateApiKey Search, Browse, GenerateSecuredApiKey, AddApiKey, UpdateApiKey Search, browse, generateSecuredApiKey, addApiKey, updateApiKey Search, BrowseObjects, GenerateSecuredAPIKey, AddAPIKey, UpdateAPIKey search, browse index, generateSecuredApiKey, add key, update key

See code examples

About this parameter

Boost or bury records based on specific criteria, but without hiding those records.

Use optional filters to promote certain records. The boolean syntax is the same as facetFilters.

Use negative optional filters to:

Promote records that don’t match a filter
Demote records that do match a filter.

For example, to promote items that don’t belong to the books category, add a category:-Books filter.

Optional filters aren’t available on the Grow plan.

If you signed up for the Community, Essential, or Plus plans before December 15, 2018, you can only use one optional filter per query.

Optional filters require the Filters criterion to be in your ranking formula (as it is by default).
Optional filters are ignored on virtual replicas since virtual replicas solely rely on custom ranking to sort results.
If you’re using exhaustive sorting or sort by attribute, optional filters are applied after the sort-by criteria. You can’t use them to boost items to the top of your ranking, as sort-by always takes precedence.
You can’t perform numeric comparisons with optional filters.

Usage notes

Negation

If your facet value starts the - character, you must escape it to prevent Algolia from interpreting it as a negative optional filter. For example, to add a filter for the category -movie, the negative optional filter should be category:\-movie.

Advanced queries

Enabling advancedSyntax lets users:

Add double quotes around phrases in a query to specify that a record must contain that phrase.
Prefix a word with a minus (-) character to specify that a record must not contain that phrase.

Examples

Apply optional filters on a search query

This example boosts all books written by John Doe.

Copy

1
2
3
4
5
6
$results = $index->search('query', [
  'optionalFilters' => [
    "category:Book",
    "author:John Doe"
  ]
]);

1
2
3
4
5
6
7
8
let query = Query()
  .set(\.optionalFilters, to: ["category:Book", "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
val query = query("query") {
    optionalFilters {
        and {
            facet("category", "Book")
            facet("author", "John Doe")
        }
    }
}

index.search(query)

1
2
3
4
5
6
7
8
var query = new Query()
{
  SearchQuery = "query",
  OptionalFilters = new List<List<string>>
  {
    new List<string> { "category:Book", "author:John Doe" }
  }
};

1
2
3
4
5
6
7
8
9
10
11
client.execute {
  search into "myIndex" query Query(
    customParameters = Some(
      Map(
        "optionalFilters" -> Some(Seq(
          "category:Book",
          "author:John Doe"
        ))
      )
    )
}

Apply negative optional filters on a search query

This example demotes all books written by John Doe.