API Reference / API Parameters / facetFilters

Feb. 26, 2019

facetFilters

Type: list of strings

Engine default: []

Parameter syntax

'facetFilters' => [
  'attribute:value', // (single string)

  // attribute1:value AND attribute2:value (multiple strings)
  'attribute1:value', 'attribute2:value'

  // attribute1:value OR attribute2:value (multiple strings within an array)
  ['attribute1:value', 'attribute2:value'],

  // (attribute1:value OR attribute2:value) AND attribute3:value (combined strings and arrays)
  ['attribute1:value', 'attribute2:value'], 'attribute3:value',

  ...
]

facetFilters: [
  'attribute:value', # (single string)

  # attribute1:value AND attribute2:value (multiple strings)
  'attribute1:value', 'attribute2:value'

  # attribute1:value OR attribute2:value (multiple strings within an array)
  ['attribute1:value', 'attribute2:value'],

  # (attribute1:value OR attribute2:value) AND attribute3:value (combined strings and arrays)
  ['attribute1:value', 'attribute2:value'], 'attribute3:value',

  ...
]

facetFilters: [
  'attribute:value', // (single string)

  // attribute1:value AND attribute2:value (multiple strings)
  'attribute1:value', 'attribute2:value'

  // attribute1:value OR attribute2:value (multiple strings within an array)
  ['attribute1:value', 'attribute2:value'],

  // (attribute1:value OR attribute2:value) AND attribute3:value (combined strings and arrays)
  ['attribute1:value', 'attribute2:value'], 'attribute3:value',

  ...
]

'facetFilters': [
  'attribute:value', # (single string)

  # attribute1:value AND attribute2:value (multiple strings)
  'attribute1:value', 'attribute2:value'

  # attribute1:value OR attribute2:value (multiple strings within an array)
  ['attribute1:value', 'attribute2:value'],

  # (attribute1:value OR attribute2:value) AND attribute3:value (combined strings and arrays)
  ['attribute1:value', 'attribute2:value'], 'attribute3:value',

  ...
]

query.facetFilters = [
  "attribute:value", // (single string)

  // attribute1:value AND attribute2:value (multiple strings)
  "attribute1:value", "attribute2:value"

  // attribute1:value OR attribute2:value (multiple strings within an array)
  ["attribute1:value", "attribute2:value"],

  // (attribute1:value OR attribute2:value) AND attribute3:value (combined strings and arrays)
  ["attribute1:value", "attribute2:value"], "attribute3:value",

  ...
]

facetFilters {
    // Declare an OR group for 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 facet filters.
    and {
        facet("attribute", "value")
        facet("attribute", true)
        facet("attribute", 0)
    }
}

.setFacetFilters(
  new JSONArray()
    .put("attribute:value")

    // attribute1:value AND attribute2:value
    .put("[attribute1:value, attribute2:value]")

    // (attribute1:value OR attribute2:value) AND attribute3:value
    .put("[attribute1:value, attribute2:value], attribute3:value")

    ...
)

FacetFilters(
  new List<string> {
    "attribute:value", // (single string)

    // attribute1:value AND attribute2:value (multiple strings)
    "attribute1:value", "attribute2:value"

    // attribute1:value OR attribute2:value (multiple strings within an array)
    ["attribute1:value", "attribute2:value"],

    // (attribute1:value OR attribute2:value) AND attribute3:value (combined strings and arrays)
    ["attribute1:value", "attribute2:value"], "attribute3:value",

    ...
  }
)

.setFacetFilters(Arrays.asList(
  "attribute:value", // (single string)

  // attribute1:value AND attribute2:value (multiple strings)
  "attribute1:value", "attribute2:value"

  // attribute1:value OR attribute2:value (multiple strings within an array)
  ["attribute1:value", "attribute2:value"],

  // (attribute1:value OR attribute2:value) AND attribute3:value (combined strings and arrays)
  ["attribute1:value", "attribute2:value"], "attribute3: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",
)

facetFilters = Some(Seq(
  "attribute:value", // (single string)

  // attribute1:value AND attribute2:value (multiple strings)
  "attribute1:value", "attribute2:value"

  // attribute1:value OR attribute2:value (multiple strings within an array)
  ["attribute1:value", "attribute2:value"],

  // (attribute1:value OR attribute2:value) AND attribute3:value (combined strings and arrays)
  ["attribute1:value", "attribute2:value"], "attribute3:value",

  ...
))

Can be used in these methods:
search, browseObjects, deleteBy, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey search, browse, delete_by, search_for_facet_values, generate_secured_api_key, add_api_key, update_api_key search, browse, 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 search, browseObjects, deleteObjectBy, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey searchAsync, browseAsync, deleteByAsync, searchForFacetValues Search, Browse, DeleteBy, SearchForFacetValues, GenerateSecuredApiKey, 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 hits by facet value.

The filters parameter provides an easier to use, SQL-like syntax, and it supports both filters and facets. We recommend using it instead of facetFilters.

Usage notes:

Format: The general format for referencing a facet value is ${attributeName}:${value}. This attribute/value combination represents a filter on a given facet value.
Multiple filters: If you specify multiple filters, they are interpreted as a conjunction (AND). If you want to use a disjunction (OR), use a nested array.
- ["category:Book", "author:John Doe"] translates as category:Book AND author:"John Doe".
- [["category:Book", "category:Movie"], "author:John Doe"] translates as (category:Book OR category:Movie) AND author:"John Doe".
Negation is supported by prefixing the value with a minus sign (-), sometimes called a dash. For example: ["category:Book", "category:-Movie"] translates as category:Book AND NOT category:Movie.
Escape characters: On the other hand, if your facet value starts with a -, meaning it contains the -, then you can escape the character with a \ to prevent the engine from interpreting this as a negative facet filter. For example, filtering on category:\-Movie will filter on all records that have a category equal to “-Movie”.

Examples

This example translates as category:Book.

Copy

$results = $index->search('query', [
  'facetFilters' => [
    "category:Book"
  ]
]);

Simple AND filter

This example translate as category:Book AND author:John Doe.

Copy

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

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

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

client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    facetFilters = Some(Seq(
      "category:Book",
      "author:John Doe"
    ))
  )
}

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

index.search(query)

Simple OR filter

This example translate as (category:Book OR category:Movie).

Copy

$results = $index->search('query', [
  'facetFilters' => [
    ["category:Book", "category:Movie"]
  ]
]);

let query = Query(query: "query")
query.facetFilters = [
  ["category:Book", "category:Movie"]
]

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

val query = query("query") {
    facetFilters {
        or {
            facet("category", "Book")
            facet("category", "Movie")
        }
    }
}

index.search(query)

AND and OR filter combination

This example translate as (category:Book OR category:Movie) AND author:John Doe.

Copy

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

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

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

index.search(
  new Query("query").setFacetFilters(
    new JSONArray()
      .put( new JSONArray().put("category:Book").put("category:Movie") )
      .put("author: John Doe")
  )
);

index.Search<Book>(new Query("query")
{
  FacetFilters = new List<List<string>> 
  { 
    new List<string> { "category:Book", "category:Movie" },
    new List<string> { "author:John Doe" }
  }
});

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

client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    facetFilters = Some(Seq(
      Seq("category:Book", "category:Movie"),
      "author:John Doe"
    ))
  )
}

val query = query("query") {
    facetFilters {
        or {
            facet("category", "Book")
            facet("category", "Movie")
        }
        and {
            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

facetFilters

About this parameter

Usage notes:

Examples

Simple filter on a single facet

Simple AND filter

Simple OR filter

AND and OR filter combination

Did you find this page helpful?

On this page