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

Create filters for ranking purposes, where records that match the filter are ranked higher, or lower in the case of a negative optional filter.

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. If you use negative filters, items that match your filter are ranked lower than other records.

Filter scoring allows you to rank filtered records.

Usage notes

If you’re using exhaustive sorting or sort-by at the top of your ranking formula, the optional filters are applied after the sort-by criteria. They can’t be used to boost items to the top of your ranking, as the sort-by will always take precedence.
The boolean syntax is the same as facetFilters.
Numeric comparisons: you can’t perform numeric comparisons with optional filters.
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.
Negative optional filters: It is possible to boost item that do not match your optional filter with the - syntax. For example, if you want to promote items that do not belong to the category books, you can add a category:-Books filter.
Escape characters: If your facet value starts the - character, you must escape it to prevent then engine from interpreting your filter as a negative filter. For example, if you want to add a filter on the category -Movie, your filter should have an \ before the - character: category:\-movie.
optionalFilters doesn’t impact pinned items.

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. For all other plans, optional filters are unlimited.

Examples

Apply optional filters on a search query

In this example, we boost 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

In this example, we boost all books that are not written by John Doe.