API Reference / API Parameters / facetFilters

Jan. 14, 2021

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)
  .or("attribute1:value", "attribute2:value"),

  // (attribute1:value OR attribute2:value) AND attribute3:value (combined strings and arrays)
  .or("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_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 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, we interpret them 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: Prefixing a value with a minus sign (-) signifies excluding records with that facet value. For example: ["category:Book", "category:-Movie"] translates as category:Book AND NOT category:Movie.
Escape characters: If your facet value starts with a -, meaning it contains the -, then you must escape the character with a \ to prevent the engine from interpreting this as a negative facet filter. For example, the facet filter category:\-Movie returns all records that have a category equal to “-Movie”.
Negative numbers: If you want to filter on negative numbers, you must escape the minus with a \ to prevent the engine from interpreting this as a negative facet filter. Note that filtering on count:\-12 returns records with both string (“-12”) and numeric values (-12). If you want to return only records with numeric values, use numericFilters. The numericFilters parameter treats the minus sign (-) as a negative sign, so you can use count=-12 to retrieve all records with count equal to -12.

Examples

This example translates as category:Book.

Copy

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

1
2
3
4
5
6
7
8
9
10
11
let query = Query("query")
  .set(\.facetFilters, to: [
    "category:Book"
  ]
)

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

1
2
3
4
5
6
index.search(
  new Query("query")
          .setFacetFilters(Collections.singletonList(
                  Collections.singletonList("category:Book")
          ))
);

Simple AND filter

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

Copy

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

1
2
3
4
5
6
7
8
9
10
11
let query = Query("query")
  .set(\.facetFilters, 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
index.Search<Book>(new Query("query")
{
  FacetFilters = new List<List<string>>
  {
    new List<string> { "category:Book" },
    new List<string> { "author:John Doe" },
  }
});

1
2
3
4
5
6
7
index.search(
  new Query("query")
    .setFacetFilters(Arrays.asList(
       Collections.singletonList("category:Book"),
       Collections.singletonList("author:John Doe"),
    ))
);

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

1
2
3
4
5
6
7
8
9
10
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

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

1
2
3
4
5
6
7
8
9
10
11
let query = Query("query")
  .set(\.facetFilters, to: [
    .or("category:Book", "category:Movie")
  ]
)

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

1
2
3
4
5
6
7
8
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    facetFilters = Some(Seq(
      Seq("category:Book", "category:Movie")
    ))
  )
}

1
2
3
4
5
6
7
8
9
10
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

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

1
2
3
4
5
6
7
8
index.search('query', {
  facetFilters: [
    ['category:Book', 'category:Movie'],
    'author:John Doe'
  ]
}).then(({ hits }) => {
  console.log(hits);
});

1
2
3
4
5
6
7
8
9
10
11
let query = Query("query")
  .set(\.facetFilters, to: [
    .or("category:Book", "category:Movie"), "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
index.search(
  new Query("query").setFacetFilters(
    new JSONArray()
      .put( new JSONArray().put("category:Book").put("category:Movie") )
      .put("author: John Doe")
  )
);

1
2
3
4
5
6
7
8
index.Search<Book>(new Query("query")
{
  FacetFilters = new List<List<string>>
  {
    new List<string> { "category:Book", "category:Movie" },
    new List<string> { "author:John Doe" }
  }
});

1
2
3
4
5
6
7
index.search(
  new Query("query")
    .setFacetFilters(Arrays.asList(
      Arrays.asList("category:Book", "category:Movie"),
      Collections.singletonList("author:John Doe")
    ))
);

1
2
3
4
5
6
7
8
9
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    facetFilters = Some(Seq(
      Seq("category:Book", "category:Movie"),
      "author:John Doe"
    ))
  )
}

1
2
3
4
5
6
7
8
9
10
11
12
13
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

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

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