Filters and facet filters

For most uses, the filters parameter is the best choice for filtering. However, numericFilters and facetFilters also offer comparable capabilities and can be used to suit different filtering needs.

Differences between filtering parameters

Whatever filtering parameter you use, the aim is to filter based on their attributes. To exclude results, use the NOT operator. However, there are some differences:

`filters`

	Notes
Parameter	`filters`
Syntax	String
Best for	Filtering with a mix of string and numeric filters
Key points	A familiar SQL syntax. You can use boolean logical operators: AND, OR, NOT

Examples

Find all books written by Stephen King:

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(new SearchParamsObject { Filters = "author:\"Stephen King\"" })
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    filters: "author:\"Stephen King\"",
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetFilters("author:\"Stephen King\""))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setFilters("author:\"Stephen King\""),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { filters: 'author:"Stephen King"' },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(filters = "author:\"Stephen King\""),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['filters' => 'author:"Stephen King"',
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "filters": 'author:"Stephen King"',
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(filters: "author:\"Stephen King\"")
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        filters = Some("author:\"Stephen King\"")
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams
        .searchSearchParamsObject(SearchSearchParamsObject(filters: "author:\"Stephen King\""))
)

Exclude all non-fiction books (based on their tag):

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(new SearchParamsObject { Filters = "NOT _tags:non-fiction" })
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    filters: "NOT _tags:non-fiction",
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetFilters("NOT _tags:non-fiction"))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setFilters("NOT _tags:non-fiction"),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { filters: 'NOT _tags:non-fiction' },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(filters = "NOT _tags:non-fiction"),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['filters' => 'NOT _tags:non-fiction',
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "filters": "NOT _tags:non-fiction",
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(filters: "NOT _tags:non-fiction")
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        filters = Some("NOT _tags:non-fiction")
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams
        .searchSearchParamsObject(SearchSearchParamsObject(filters: "NOT _tags:non-fiction"))
)

`numericFilters`

	Notes
Parameter	`numericFilters`
Syntax	String
Best for	Filtering dates and numeric values
Key points	Like `filters` but limited to numeric data

Example

Find all books that cost more than $20:

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(new SearchParamsObject { NumericFilters = new NumericFilters("price>20") })
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    numericFilters: "price>20",
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetNumericFilters(search.StringAsNumericFilters("price>20")))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setNumericFilters(NumericFilters.of("price>20")),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { numericFilters: 'price>20' },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(numericFilters = NumericFilters.of("price>20")),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['numericFilters' => 'price>20',
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "numericFilters": "price>20",
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(numeric_filters: "price>20")
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        numericFilters = Some(NumericFilters("price>20"))
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams
        .searchSearchParamsObject(SearchSearchParamsObject(numericFilters: SearchNumericFilters
                .string("price>20")))
)

`facetFilters`

	Notes
Parameter	`facetFilters`
Syntax	String or string array
Best for	Filtering with a mix of strings and complex boolean logic
Key points	Can’t be used for numeric filtering

Examples

Find books written by Stephen King or belonging to the horror genre, and also published by Penguin.

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      FacetFilters = new FacetFilters(
        new List<FacetFilters>
        {
          new FacetFilters("publisher:Penguin"),
          new FacetFilters(
            new List<FacetFilters>
            {
              new FacetFilters("author:Stephen King"),
              new FacetFilters("genre:Horror"),
            }
          ),
        }
      ),
    }
  )
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    facetFilters: [
      "publisher:Penguin",
      [
        "author:Stephen King",
        "genre:Horror",
      ],
    ],
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetFacetFilters(search.ArrayOfFacetFiltersAsFacetFilters(
    []search.FacetFilters{*search.StringAsFacetFilters("publisher:Penguin"), *search.ArrayOfFacetFiltersAsFacetFilters(
      []search.FacetFilters{*search.StringAsFacetFilters("author:Stephen King"), *search.StringAsFacetFilters("genre:Horror")})})))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setFacetFilters(
    FacetFilters.of(
      Arrays.asList(
        FacetFilters.of("publisher:Penguin"),
        FacetFilters.of(Arrays.asList(FacetFilters.of("author:Stephen King"), FacetFilters.of("genre:Horror")))
      )
    )
  ),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { facetFilters: ['publisher:Penguin', ['author:Stephen King', 'genre:Horror']] },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams =
      SearchParamsObject(
        facetFilters =
          FacetFilters.of(
            listOf(
              FacetFilters.of("publisher:Penguin"),
              FacetFilters.of(
                listOf(FacetFilters.of("author:Stephen King"), FacetFilters.of("genre:Horror"))
              ),
            )
          )
      ),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['facetFilters' => [
        'publisher:Penguin',

        [
            'author:Stephen King',

            'genre:Horror',
        ],
    ],
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "facetFilters": [
            "publisher:Penguin",
            [
                "author:Stephen King",
                "genre:Horror",
            ],
        ],
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(
    facet_filters: ["publisher:Penguin", ["author:Stephen King", "genre:Horror"]]
  )
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        facetFilters = Some(
          FacetFilters(
            Seq(
              FacetFilters("publisher:Penguin"),
              FacetFilters(Seq(FacetFilters("author:Stephen King"), FacetFilters("genre:Horror")))
            )
          )
        )
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams
        .searchSearchParamsObject(SearchSearchParamsObject(facetFilters: SearchFacetFilters
                .arrayOfSearchFacetFilters([
                    SearchFacetFilters.string("publisher:Penguin"),
                    SearchFacetFilters.arrayOfSearchFacetFilters([
                        SearchFacetFilters.string("author:Stephen King"),
                        SearchFacetFilters.string("genre:Horror"),
                    ]),
                ])))
)

Exclude eBooks from the results:

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

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    facetFilters: "category:-Ebook",
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetFacetFilters(search.StringAsFacetFilters("category:-Ebook")))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setFacetFilters(FacetFilters.of("category:-Ebook")),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { facetFilters: 'category:-Ebook' },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(facetFilters = FacetFilters.of("category:-Ebook")),
  )

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

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "facetFilters": "category:-Ebook",
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(facet_filters: "category:-Ebook")
)

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

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams
        .searchSearchParamsObject(SearchSearchParamsObject(facetFilters: SearchFacetFilters
                .string("category:-Ebook")))
)

You can combine filter and facet filters in the same search query. For example:

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      Filters = "(author:\"Stephen King\" OR genre:\"Horror\")",
      FacetFilters = new FacetFilters(
        new List<FacetFilters> { new FacetFilters("publisher:Penguin") }
      ),
    }
  )
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    filters: "(author:\"Stephen King\" OR genre:\"Horror\")",
    facetFilters: [
      "publisher:Penguin",
    ],
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().
    SetFilters("(author:\"Stephen King\" OR genre:\"Horror\")").
    SetFacetFilters(search.ArrayOfFacetFiltersAsFacetFilters(
      []search.FacetFilters{*search.StringAsFacetFilters("publisher:Penguin")})),
)))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject()
    .setFilters("(author:\"Stephen King\" OR genre:\"Horror\")")
    .setFacetFilters(FacetFilters.of(Arrays.asList(FacetFilters.of("publisher:Penguin")))),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { filters: '(author:"Stephen King" OR genre:"Horror")', facetFilters: ['publisher:Penguin'] },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams =
      SearchParamsObject(
        filters = "(author:\"Stephen King\" OR genre:\"Horror\")",
        facetFilters = FacetFilters.of(listOf(FacetFilters.of("publisher:Penguin"))),
      ),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['filters' => '(author:"Stephen King" OR genre:"Horror")',
        'facetFilters' => [
            'publisher:Penguin',
        ],
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "filters": '(author:"Stephen King" OR genre:"Horror")',
        "facetFilters": [
            "publisher:Penguin",
        ],
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(
    filters: "(author:\"Stephen King\" OR genre:\"Horror\")",
    facet_filters: ["publisher:Penguin"]
  )
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        filters = Some("(author:\"Stephen King\" OR genre:\"Horror\")"),
        facetFilters = Some(FacetFilters(Seq(FacetFilters("publisher:Penguin"))))
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
        filters: "(author:\"Stephen King\" OR genre:\"Horror\")",
        facetFilters: SearchFacetFilters
            .arrayOfSearchFacetFilters([SearchFacetFilters.string("publisher:Penguin")])
    ))
)

In this case, the results of this are the same as the preceding example for facetFilters but more generally may prove to be more flexible. For example, you can use filters programmatically to create a reduced set of records based on a user’s profile, and then apply facetFilters to reflect the facets that users have chosen.

Limits and performance

Since each filter adds complexity to queries, there’s a limit on the total number of combined filters you can use of 1,000.

Faceting on unique or uncommon attributes may degrade search performance and relevance.

​Differences between filtering parameters

​filters

​Examples

​numericFilters

​Example

​facetFilters

​Examples

​Combining filters and facet filters

​Limits and performance

Differences between filtering parameters

`filters`

Examples

`numericFilters`

Example

`facetFilters`

Examples

Combining filters and facet filters

Limits and performance