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

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.

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, the engine 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"
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.
Escape characters. If your facet value starts with a - character, you must escape the character with a \ character to prevent the engine from 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 the engine from interpreting this as a negative facet filter. 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, 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.

Examples

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

Usage notes

Examples

Simple filter on a single facet

Simple AND filter

Simple OR filter

AND and OR filter combination

On this page