> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters and facet filters

> Learn about the relationship between 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 records (A record is a searchable object in an Algolia index. Each record consists of named attributes.) based on their attributes.
To exclude results, use the NOT [operator](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/in-depth/combining-boolean-operators.md).
However, there are some differences:

### `filters`

| | Notes |
| - | - |
| Parameter | [`filters`](https://www.algolia.com/doc/api-reference/api-parameters/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:

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

```dart Dart theme={"system"}
final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    filters: "author:\"Stephen King\"",
  ),
);
```

```go Go theme={"system"}
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)
}
```

```java Java theme={"system"}
SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setFilters("author:\"Stephen King\""),
  Hit.class
);
```

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

```kotlin Kotlin theme={"system"}
var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(filters = "author:\"Stephen King\""),
  )
```

```php PHP theme={"system"}
$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['filters' => 'author:"Stephen King"',
    ],
);
```

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

```ruby Ruby theme={"system"}
response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(filters: "author:\"Stephen King\"")
)
```

```scala Scala theme={"system"}
val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        filters = Some("author:\"Stephen King\"")
      )
    )
  ),
  Duration(100, "sec")
)
```

```swift Swift theme={"system"}
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](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/how-to/filter-by-attributes.md#filter-by-tags)):

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

```dart Dart theme={"system"}
final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    filters: "NOT _tags:non-fiction",
  ),
);
```

```go Go theme={"system"}
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)
}
```

```java Java theme={"system"}
SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setFilters("NOT _tags:non-fiction"),
  Hit.class
);
```

```js JavaScript theme={"system"}
const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { filters: 'NOT _tags:non-fiction' },
});
```

```kotlin Kotlin theme={"system"}
var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(filters = "NOT _tags:non-fiction"),
  )
```

```php PHP theme={"system"}
$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['filters' => 'NOT _tags:non-fiction',
    ],
);
```

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

```ruby Ruby theme={"system"}
response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(filters: "NOT _tags:non-fiction")
)
```

```scala Scala theme={"system"}
val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        filters = Some("NOT _tags:non-fiction")
      )
    )
  ),
  Duration(100, "sec")
)
```

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

### `numericFilters`

| | Notes |
| - | - |
| Parameter | [`numericFilters`](https://www.algolia.com/doc/api-reference/api-parameters/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:

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

```dart Dart theme={"system"}
final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    numericFilters: "price>20",
  ),
);
```

```go Go theme={"system"}
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)
}
```

```java Java theme={"system"}
SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setNumericFilters(NumericFilters.of("price>20")),
  Hit.class
);
```

```js JavaScript theme={"system"}
const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { numericFilters: 'price>20' },
});
```

```kotlin Kotlin theme={"system"}
var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(numericFilters = NumericFilters.of("price>20")),
  )
```

```php PHP theme={"system"}
$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['numericFilters' => 'price>20',
    ],
);
```

```python Python theme={"system"}
response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "numericFilters": "price>20",
    },
)
```

```ruby Ruby theme={"system"}
response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(numeric_filters: "price>20")
)
```

```scala Scala theme={"system"}
val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        numericFilters = Some(NumericFilters("price>20"))
      )
    )
  ),
  Duration(100, "sec")
)
```

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

### `facetFilters`

| | Notes |
| - | - |
| Parameter | [`facetFilters`](https://www.algolia.com/doc/api-reference/api-parameters/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.

```cs C# theme={"system"}
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"),
            }
          ),
        }
      ),
    }
  )
);
```

```dart Dart theme={"system"}
final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    facetFilters: [
      "publisher:Penguin",
      [
        "author:Stephen King",
        "genre:Horror",
      ],
    ],
  ),
);
```

```go Go theme={"system"}
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)
}
```

```java Java theme={"system"}
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
);
```

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

```kotlin Kotlin theme={"system"}
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"))
              ),
            )
          )
      ),
  )
```

```php PHP theme={"system"}
$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['facetFilters' => [
        'publisher:Penguin',

        [
            'author:Stephen King',

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

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

```ruby Ruby theme={"system"}
response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(
    facet_filters: ["publisher:Penguin", ["author:Stephen King", "genre:Horror"]]
  )
)
```

```scala Scala theme={"system"}
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")
)
```

```swift Swift theme={"system"}
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:

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

```dart Dart theme={"system"}
final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    facetFilters: "category:-Ebook",
  ),
);
```

```go Go theme={"system"}
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)
}
```

```java Java theme={"system"}
SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setFacetFilters(FacetFilters.of("category:-Ebook")),
  Hit.class
);
```

```js JavaScript theme={"system"}
const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { facetFilters: 'category:-Ebook' },
});
```

```kotlin Kotlin theme={"system"}
var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(facetFilters = FacetFilters.of("category:-Ebook")),
  )
```

```php PHP theme={"system"}
$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['facetFilters' => 'category:-Ebook',
    ],
);
```

```python Python theme={"system"}
response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "facetFilters": "category:-Ebook",
    },
)
```

```ruby Ruby theme={"system"}
response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(facet_filters: "category:-Ebook")
)
```

```scala Scala theme={"system"}
val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        facetFilters = Some(FacetFilters("category:-Ebook"))
      )
    )
  ),
  Duration(100, "sec")
)
```

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

## Combining filters and facet filters

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

```cs C# theme={"system"}
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") }
      ),
    }
  )
);
```

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

```go Go theme={"system"}
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)
}
```

```java Java theme={"system"}
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
);
```

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

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

```php PHP theme={"system"}
$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['filters' => '(author:"Stephen King" OR genre:"Horror")',
        'facetFilters' => [
            'publisher:Penguin',
        ],
    ],
);
```

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

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

```scala Scala theme={"system"}
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")
)
```

```swift Swift theme={"system"}
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`](#examples) 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.

> [!NOTE]
>
> Faceting on unique or uncommon attributes [may degrade search performance and relevance](https://www.algolia.com/doc/api-reference/api-parameters/facets.md#usage).