API Reference / API Parameters / facetFilters

Nov. 25, 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)
    }
}

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 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# A

Filter hits by facet value.

It’s recommended that you use the filters parameter instead of facetFilters since filters has a more straightforward, SQL-like syntax, and supports both filters and facets.

The general format for referencing a facet value is ${attributeName}:${value}. This attribute/value combination represents a filter on a given facet value.

Usage notes#

Multiple filters#

If you specify multiple filters, Algolia interprets 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".
You can’t filter nested ORs of ANDs conditions. For example, you can’t generate a filter for (category:Book AND category:Movie) OR author:"John Doe"

Escape characters#

If your facet value starts with a - character, you must escape the character with a \ character to prevent Algoliafrom interpreting this as a negative facet filter. For example, the facet filter category:\-Movie returns all records with the category “-Movie”.

Negative numbers#

To filter negative numbers, escape the minus with a \ character to prevent Algolia from interpreting this as a negative facet filter. Filtering on count:\-12 returns records with both string (“-12”) and numeric values (-12). To return only records with numeric values, use numericFilters: this treats the minus sign (-) as a negative, so you can use count=-12 to retrieve all records with a count of -12.

Range filters#

To filter on a range of numbers, use the filters parameter and set numeric upperBound and lowerBound limits on that parameter.

Negation#

Prefix a value with a minus sign (-) to exclude records with that facet value. For example: ["category:Book", "category:-Movie"] translates as category:Book AND NOT 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# A

Simple filter on a single facet#

An example of filtering on 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#

An example of filtering on 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
9
10
val query = query("query") {
    facetFilters {
        and {
            facet("category", "Book")
            facet("author", "John Doe")
        }
    }
}

index.search(query)

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

Simple OR filter#

An example of filtering on (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
9
10
val query = query("query") {
    facetFilters {
        or {
            facet("category", "Book")
            facet("category", "Movie")
        }
    }
}

index.search(query)

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

AND and OR filter combination#

An example of filtering on (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
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)

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

Did you find this page helpful?

facetFilters

About this parameter# Found an issue? Edit this parameter A Edit this parameter

Usage notes#

Multiple filters#

Escape characters#

Negative numbers#

Range filters#

Negation#

Advanced queries#

Examples# Found an issue? Edit this parameter A Edit this parameter

Simple filter on a single facet#

Simple AND filter#

Simple OR filter#

AND and OR filter combination#

On this page

About this parameter# A

Examples# A