facetFilters

Filter search results by facet values

Use the filters parameter instead. It supports boolean combinations of multiple filters, and unifies numericFilters, tagFilters, facetFilters into a single syntax.

Usage

To use an attribute as facet filter, it must be included in the attributesForFaceting setting.

Single facet filter

Specify a filter using the "facet:value" syntax. For example, "genre:comedy" returns only records where the genre attribute is comedy.

Negative filter

Prefix the value with a minus sign to exclude matches: "facet:-value". For example, "genre:-comedy" excludes records where genre is comedy.

Combining filters with AND and OR

Use a flat array for AND conditions: ["category:Book", "author:John Doe"] returns records where category is Book and author is John Doe.

Use nested arrays for OR conditions:
[["genre:comedy", "genre:drama"]] returns records where genre is either comedy or drama.

You can combine AND with OR: [["category:Book", "category:Movie"], "author:John Doe"] means (category:Book OR category:Movie) AND author:John Doe.

You can’t group AND conditions inside an OR group. (A AND B) OR C is invalid.

Escape minus signs

If a facet value starts with -, escape it with a backslash: category:\-Movie.

This also applies to negative numbers: "count:\-12" matches string or numeric values equal to -12. To filter only numeric values, use numericFilters.

Examples

Single facet filter

Current API clients

C#

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      Query = "query",
      FacetFilters = new FacetFilters(
        new List<FacetFilters> { new FacetFilters("category:Book") }
      ),
    }
  )
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    query: "query",
    facetFilters: [
      "category:Book",
    ],
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetQuery("query").SetFacetFilters(search.ArrayOfFacetFiltersAsFacetFilters(
    []search.FacetFilters{*search.StringAsFacetFilters("category:Book")})))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setQuery("query").setFacetFilters(FacetFilters.of(Arrays.asList(FacetFilters.of("category:Book")))),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { query: 'query', facetFilters: ['category:Book'] },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams =
      SearchParamsObject(
        query = "query",
        facetFilters = FacetFilters.of(listOf(FacetFilters.of("category:Book"))),
      ),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['query' => 'query',
        'facetFilters' => [
            'category:Book',
        ],
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "query": "query",
        "facetFilters": [
            "category:Book",
        ],
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(query: "query", facet_filters: ["category:Book"])
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        query = Some("query"),
        facetFilters = Some(FacetFilters(Seq(FacetFilters("category:Book"))))
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
        query: "query",
        facetFilters: SearchFacetFilters.arrayOfSearchFacetFilters([SearchFacetFilters.string("category:Book")])
    ))
)

Legacy API clients

C#

index.Search(new Query("query")
{
    FacetFilters = new List> { new List { "category:Book" } } };
});

res, err := index.Search("query", opt.FacetFilter("category:book"))

index.search(
  new Query("query")
          .setFacetFilters(Collections.singletonList(
                  Collections.singletonList("category:Book")
          ))
);

index
  .search("query", {
    facetFilters: ["category:Book"],
  })
  .then(({ hits }) => {
    console.log(hits);
  });

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

index.search(query)

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

results = index.search("query", {"facetFilters": ["category:Book"]})

results = index.search(
  "query",
  {
    facetFilters: [
      "category:Book"
    ]
  }
)

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

let query = Query("query")
  .set(\.facetFilters, to: [
    "category:Book"
  ]
)

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

Two filters with AND

Current API clients

C#

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      Query = "query",
      FacetFilters = new FacetFilters(
        new List<FacetFilters>
        {
          new FacetFilters("category:Book"),
          new FacetFilters("author:John Doe"),
        }
      ),
    }
  )
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    query: "query",
    facetFilters: [
      "category:Book",
      "author:John Doe",
    ],
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetQuery("query").SetFacetFilters(search.ArrayOfFacetFiltersAsFacetFilters(
    []search.FacetFilters{*search.StringAsFacetFilters("category:Book"), *search.StringAsFacetFilters("author:John Doe")})))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject()
    .setQuery("query")
    .setFacetFilters(FacetFilters.of(Arrays.asList(FacetFilters.of("category:Book"), FacetFilters.of("author:John Doe")))),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { query: 'query', facetFilters: ['category:Book', 'author:John Doe'] },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams =
      SearchParamsObject(
        query = "query",
        facetFilters =
          FacetFilters.of(
            listOf(FacetFilters.of("category:Book"), FacetFilters.of("author:John Doe"))
          ),
      ),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['query' => 'query',
        'facetFilters' => [
            'category:Book',

            'author:John Doe',
        ],
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "query": "query",
        "facetFilters": [
            "category:Book",
            "author:John Doe",
        ],
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(query: "query", facet_filters: ["category:Book", "author:John Doe"])
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        query = Some("query"),
        facetFilters = Some(FacetFilters(Seq(FacetFilters("category:Book"), FacetFilters("author:John Doe"))))
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
        query: "query",
        facetFilters: SearchFacetFilters.arrayOfSearchFacetFilters([
            SearchFacetFilters.string("category:Book"),
            SearchFacetFilters.string("author:John Doe"),
        ])
    ))
)

Legacy API clients

C#

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

res, err := index.Search(
	"query",
	opt.FacetFilterAnd("category:Book", "author:John Doe"),
)

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

index
  .search("query", {
    facetFilters: ["category:Book", "author:John Doe"],
  })
  .then(({ hits }) => {
    console.log(hits);
  });

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

index.search(query)

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

results = index.search("query", {"facetFilters": ["category:Book", "author:John Doe"]})

results = index.search(
  "query",
  {
    facetFilters: [
      "category:Book",
      "author:John Doe"
    ]
  }
)

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

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

Two filters with OR

Current API clients

C#

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      Query = "query",
      FacetFilters = new FacetFilters(
        new List<FacetFilters>
        {
          new FacetFilters(
            new List<FacetFilters>
            {
              new FacetFilters("category:Book"),
              new FacetFilters("author:John Doe"),
            }
          ),
        }
      ),
    }
  )
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    query: "query",
    facetFilters: [
      [
        "category:Book",
        "author:John Doe",
      ],
    ],
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetQuery("query").SetFacetFilters(search.ArrayOfFacetFiltersAsFacetFilters(
    []search.FacetFilters{*search.ArrayOfFacetFiltersAsFacetFilters(
      []search.FacetFilters{*search.StringAsFacetFilters("category:Book"), *search.StringAsFacetFilters("author:John Doe")})})))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject()
    .setQuery("query")
    .setFacetFilters(
      FacetFilters.of(
        Arrays.asList(FacetFilters.of(Arrays.asList(FacetFilters.of("category:Book"), FacetFilters.of("author:John Doe"))))
      )
    ),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { query: 'query', facetFilters: [['category:Book', 'author:John Doe']] },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams =
      SearchParamsObject(
        query = "query",
        facetFilters =
          FacetFilters.of(
            listOf(
              FacetFilters.of(
                listOf(FacetFilters.of("category:Book"), FacetFilters.of("author:John Doe"))
              )
            )
          ),
      ),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['query' => 'query',
        'facetFilters' => [
            [
                'category:Book',

                'author:John Doe',
            ],
        ],
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "query": "query",
        "facetFilters": [
            [
                "category:Book",
                "author:John Doe",
            ],
        ],
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(query: "query", facet_filters: [["category:Book", "author:John Doe"]])
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        query = Some("query"),
        facetFilters =
          Some(FacetFilters(Seq(FacetFilters(Seq(FacetFilters("category:Book"), FacetFilters("author:John Doe"))))))
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
        query: "query",
        facetFilters: SearchFacetFilters
            .arrayOfSearchFacetFilters([SearchFacetFilters.arrayOfSearchFacetFilters([
                SearchFacetFilters.string("category:Book"),
                SearchFacetFilters.string("author:John Doe"),
            ])])
    ))
)

Legacy API clients

C#

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

res, err := index.Search(
	"query",
	opt.FacetFilterOr("category:Book", "category:Movie"),
)

index.search(
  new Query("query")
    .setFacetFilters(Arrays.asList(
      Arrays.asList("category:Book", "category:Movie")
    ))
);

index
  .search("query", {
    facetFilters: [["category:Book", "category:Movie"]],
  })
  .then(({ hits }) => {
    console.log(hits);
  });

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

index.search(query)

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

results = index.search("query", {"facetFilters": [["category:Book", "category:Movie"]]})

results = index.search(
  "query",
  {
    facetFilters: [
      ["category:Book", "category:Movie"]
    ]
  }
)

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

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

Multiple filters with AND and OR

Current API clients

C#

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      Query = "query",
      FacetFilters = new FacetFilters(
        new List<FacetFilters>
        {
          new FacetFilters("author:John Doe"),
          new FacetFilters(
            new List<FacetFilters>
            {
              new FacetFilters("category:Book"),
              new FacetFilters("category:Movie"),
            }
          ),
        }
      ),
    }
  )
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    query: "query",
    facetFilters: [
      "author:John Doe",
      [
        "category:Book",
        "category:Movie",
      ],
    ],
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetQuery("query").SetFacetFilters(search.ArrayOfFacetFiltersAsFacetFilters(
    []search.FacetFilters{*search.StringAsFacetFilters("author:John Doe"), *search.ArrayOfFacetFiltersAsFacetFilters(
      []search.FacetFilters{*search.StringAsFacetFilters("category:Book"), *search.StringAsFacetFilters("category:Movie")})})))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject()
    .setQuery("query")
    .setFacetFilters(
      FacetFilters.of(
        Arrays.asList(
          FacetFilters.of("author:John Doe"),
          FacetFilters.of(Arrays.asList(FacetFilters.of("category:Book"), FacetFilters.of("category:Movie")))
        )
      )
    ),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { query: 'query', facetFilters: ['author:John Doe', ['category:Book', 'category:Movie']] },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams =
      SearchParamsObject(
        query = "query",
        facetFilters =
          FacetFilters.of(
            listOf(
              FacetFilters.of("author:John Doe"),
              FacetFilters.of(
                listOf(FacetFilters.of("category:Book"), FacetFilters.of("category:Movie"))
              ),
            )
          ),
      ),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['query' => 'query',
        'facetFilters' => [
            'author:John Doe',

            [
                'category:Book',

                'category:Movie',
            ],
        ],
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "query": "query",
        "facetFilters": [
            "author:John Doe",
            [
                "category:Book",
                "category:Movie",
            ],
        ],
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(
    query: "query",
    facet_filters: ["author:John Doe", ["category:Book", "category:Movie"]]
  )
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        query = Some("query"),
        facetFilters = Some(
          FacetFilters(
            Seq(
              FacetFilters("author:John Doe"),
              FacetFilters(Seq(FacetFilters("category:Book"), FacetFilters("category:Movie")))
            )
          )
        )
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
        query: "query",
        facetFilters: SearchFacetFilters.arrayOfSearchFacetFilters([
            SearchFacetFilters.string("author:John Doe"),
            SearchFacetFilters.arrayOfSearchFacetFilters([
                SearchFacetFilters.string("category:Book"),
                SearchFacetFilters.string("category:Movie"),
            ]),
        ])
    ))
)

Legacy API clients

C#

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

res, err := index.Search(
	"query",
	opt.FacetFilterAnd(
		opt.FacetFilterOr("category:Book", "category:Movie"),
		"author:John Doe",
	),
)

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

index
  .search("query", {
    facetFilters: [["category:Book", "category:Movie"], "author:John Doe"],
  })
  .then(({ hits }) => {
    console.log(hits);
  });

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

index.search(query)

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

results = index.search(
    "query", {"facetFilters": [["category:Book", "category:Movie"], "author:John Doe"]}
)

results = index.search(
  "query",
  {
    facetFilters: [
      ["category:Book", "category:Movie"],
      "author:John Doe"
    ]
  }
)

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

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