> ## Documentation Index
> Fetch the complete documentation index at: https://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.

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

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 /> based on their attributes.
To exclude results, use the NOT [operator](/doc/guides/managing-results/refine-results/filtering/in-depth/combining-boolean-operators).
However, there are some differences:

### `filters`

|            | Notes                                                                      |
| ---------- | -------------------------------------------------------------------------- |
| Parameter  | [`filters`](/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:

<CodeGroup>
  ```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\""))
  )
  ```
</CodeGroup>

Exclude all non-fiction books (based on their [tag](/doc/guides/managing-results/refine-results/filtering/how-to/filter-by-attributes#filter-by-tags)):

<CodeGroup>
  ```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"))
  )
  ```
</CodeGroup>

### `numericFilters`

|            | Notes                                                                |
| ---------- | -------------------------------------------------------------------- |
| Parameter  | [`numericFilters`](/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:

<CodeGroup>
  ```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")))
  )
  ```
</CodeGroup>

### `facetFilters`

|            | Notes                                                            |
| ---------- | ---------------------------------------------------------------- |
| Parameter  | [`facetFilters`](/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.

<CodeGroup>
  ```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"),
                      ]),
                  ])))
  )
  ```
</CodeGroup>

Exclude eBooks from the results:

<CodeGroup>
  ```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")))
  )
  ```
</CodeGroup>

## Combining filters and facet filters

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

<CodeGroup>
  ```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")])
      ))
  )
  ```
</CodeGroup>

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](/doc/api-reference/api-parameters/facets#usage).
</Note>