Filtering your search

Filtering is primarily used in the context of front-end search. We call this faceting, where filters are displayed on the search UI as clickable items, allowing users to select one or more filters. This enables a more refined, drilled-down search experience.

How to Filter Your Data

1. Define attributes that need to be filterable (at indexing time)

Initially, filter attributes must be defined as facets, using the attributesForFaceting parameter. This can be done using the setSettings method.

C#

using Algolia.Search.Clients;
using Algolia.Search.Http;

var client = new SearchClient(new SearchConfig("YOUR_APP_ID", "YOUR_API_KEY"));

var response = await client.SetSettingsAsync(
  "<YOUR_INDEX_NAME>",
  new IndexSettings
  {
    AttributesForFaceting = new List<string>
    {
      "actor",
      "filterOnly(category)",
      "searchable(publisher)"
    },
  }
);

await client.WaitForTaskAsync("<YOUR_INDEX_NAME>", response.TaskID);

Dart

import 'package:algolia_client_search/algolia_client_search.dart';

final client = SearchClient(appId: 'YOUR_APP_ID', apiKey: 'YOUR_API_KEY');

final response = await client.setSettings(
  indexName: "<YOUR_INDEX_NAME>",
  indexSettings: IndexSettings(
    attributesForFaceting: [
      "actor",
      "filterOnly(category)",
      "searchable(publisher)",
    ],
  ),
);

await client.waitTask('<YOUR_INDEX_NAME>', response.taskID);

Go

import "github.com/algolia/algoliasearch-client-go/v4/algolia/search"

client, err := search.NewClient("YOUR_APP_ID", "YOUR_API_KEY")

response, err := client.SetSettings(client.NewApiSetSettingsRequest(
  "<YOUR_INDEX_NAME>",
  search.NewEmptyIndexSettings().SetAttributesForFaceting(
    []string{"actor", "filterOnly(category)", "searchable(publisher)"}),
))
if err != nil {
  // handle the eventual error
  panic(err)
}

// use the model directly
print(response)

taskResponse, err := searchClient.WaitForTask("<YOUR_INDEX_NAME>", response.TaskID, nil, nil, nil)
if err != nil {
  panic(err)
}

Java

import com.algolia.api.SearchClient;
import com.algolia.model.search.*;

SearchClient client = new SearchClient("YOUR_APP_ID", "YOUR_API_KEY");

client.setSettings(
  "<YOUR_INDEX_NAME>",
  new IndexSettings().setAttributesForFaceting(List.of("actor", "filterOnly(category)", "searchable(publisher)"))
);

client.waitForTask("<YOUR_INDEX_NAME>", response.getTaskID());

JavaScript

import { searchClient } from '@algolia/client-search';

const client = searchClient('YOUR_APP_ID', 'YOUR_API_KEY');

const response = await client.setSettings({
  indexName: '<YOUR_INDEX_NAME>',
  indexSettings: {
    attributesForFaceting: [
      'actor',
      'filterOnly(category)',
      'searchable(publisher)',
    ],
  },
});

// use typed response
console.log(response);

await client.waitForTask({ indexName: '<YOUR_INDEX_NAME>', taskID: response.taskID });

Kotlin

import com.algolia.client.api.SearchClient

val client = SearchClient(appId = "YOUR_APP_ID", apiKey = "YOUR_API_KEY")

var response = client.setSettings(
  indexName = "<YOUR_INDEX_NAME>",
  indexSettings = IndexSettings(
    attributesForFaceting = listOf("actor", "filterOnly(category)", "searchable(publisher)"),
  ),
)

// Use the response
println(response)

client.waitTask("<YOUR_INDEX_NAME>", response.taskID)

PHP

use Algolia\AlgoliaSearch\Api\SearchClient;

$client = SearchClient::create('<YOUR_APP_ID>', '<YOUR_API_KEY>');

$response = $client->setSettings(
    '<YOUR_INDEX_NAME>',
    ['attributesForFaceting' => [
        'actor',

        'filterOnly(category)',

        'searchable(publisher)',
    ],
    ],
);

// play with the response
var_dump($response);

$client->waitForTask('<YOUR_INDEX_NAME>', $response['taskID']);

Python

from algoliasearch.search.client import SearchClient

_client = SearchClient("YOUR_APP_ID", "YOUR_API_KEY")

response = await _client.set_settings(
    index_name="<YOUR_INDEX_NAME>",
    index_settings={
        "attributesForFaceting": [
            "actor",
            "filterOnly(category)",
            "searchable(publisher)",
        ],
    },
)

# use the class directly
print(response)

# print the JSON response
print(response.to_json())

await client.wait_for_task(index_name="<YOUR_INDEX_NAME>", task_id=response.task_id)

Ruby

require 'algolia'

client = Algolia::SearchClient.create('YOUR_APP_ID', 'YOUR_API_KEY')

response = client.set_settings(
  "<YOUR_INDEX_NAME>",
  IndexSettings.new(
    attributes_for_faceting: ["actor",
      "filterOnly(category)",
      "searchable(publisher)"]
  )
)

# use the class directly
puts response

# print the JSON response
puts response.to_json

client.wait_for_task("<YOUR_INDEX_NAME>", response.task_id)

Scala

import algoliasearch.api.SearchClient

val client = SearchClient(appId = "YOUR_APP_ID", apiKey = "YOUR_API_KEY")

val response = client.setSettings(
  indexName = "<YOUR_INDEX_NAME>",
  indexSettings = IndexSettings(
    attributesForFaceting = Some(Seq("actor", "filterOnly(category)", "searchable(publisher)"))
  )
)

// Use the response
val value = Await.result(response, Duration(100, "sec"))

client.waitTask("<YOUR_INDEX_NAME>", response.getTaskID())

Swift

import Search

let client = try SearchClient(appID: "YOUR_APP_ID", apiKey: "YOUR_API_KEY")

let response = try await client.setSettings(
    indexName: "<YOUR_INDEX_NAME>",
    indexSettings: IndexSettings(attributesForFaceting: [
        "actor",
        "filterOnly(category)",
        "searchable(publisher)",
    ])
)

try await client.waitForTask(with: response.taskID, in: "<YOUR_INDEX_NAME>")

2. Filter by Attributes (at query time)

The actual filtering of records is performed at query time, not at indexing time. For this, you need to use the filters parameter in your search code.

Filtering by string using the filters field

C#

// Only "Scarlett Johansson" actor
var response = await client.SearchAsync<Object>(
  new SearchMethodParams
  {
    Requests = new List<SearchQuery>
    {
      new SearchQuery(
        new SearchForHits
        {
          IndexName = "<YOUR_INDEX_NAME>",
          Query = "<YOUR_QUERY>",
          Filters = "actor:Scarlett Johansson",
        }
      )
    },
  }
);

// Only "Tom Cruise" or "Scarlett Johansson" actor
var response = await client.SearchAsync<Object>(
  new SearchMethodParams
  {
    Requests = new List<SearchQuery>
    {
      new SearchQuery(
        new SearchForHits
        {
          IndexName = "<YOUR_INDEX_NAME>",
          Query = "<YOUR_QUERY>",
          Filters = "actor:Tom Cruise OR actor:Scarlett Johansson",
        }
      )
    },
  }
);

// Everything but "Nicolas Cage" actor
var response = await client.SearchAsync<Object>(
  new SearchMethodParams
  {
    Requests = new List<SearchQuery>
    {
      new SearchQuery(
        new SearchForHits
        {
          IndexName = "<YOUR_INDEX_NAME>",
          Query = "<YOUR_QUERY>",
          Filters = "NOT actor:Nicolas Cage",
        }
      )
    },
  }
);

Dart

// Only "Scarlett Johansson" actor
final response = await client.search(
  searchMethodParams: SearchMethodParams(
    requests: [
      SearchForHits(
        indexName: "<YOUR_INDEX_NAME>",
        query: "<YOUR_QUERY>",
        filters: "actor:Scarlett Johansson",
      ),
    ],
  ),
);

// Only "Tom Cruise" or "Scarlett Johansson" actor
final response = await client.search(
  searchMethodParams: SearchMethodParams(
    requests: [
      SearchForHits(
        indexName: "<YOUR_INDEX_NAME>",
        query: "<YOUR_QUERY>",
        filters: "actor:Tom Cruise OR actor:Scarlett Johansson",
      ),
    ],
  ),
);

// Everything but "Nicolas Cage" actor
final response = await client.search(
  searchMethodParams: SearchMethodParams(
    requests: [
      SearchForHits(
        indexName: "<YOUR_INDEX_NAME>",
        query: "<YOUR_QUERY>",
        filters: "NOT actor:Nicolas Cage",
      ),
    ],
  ),
);

Go

// Only "Scarlett Johansson" actor
response, err := client.Search(client.NewApiSearchRequest(

  search.NewEmptySearchMethodParams().SetRequests(
    []search.SearchQuery{*search.SearchForHitsAsSearchQuery(
      search.NewEmptySearchForHits().SetIndexName("<YOUR_INDEX_NAME>").SetQuery("<YOUR_QUERY>").SetFilters("actor:Scarlett Johansson"))}),
))
if err != nil {
  // handle the eventual error
  panic(err)
}

// use the model directly
print(response)

// Only "Tom Cruise" or "Scarlett Johansson" actor
response, err := client.Search(client.NewApiSearchRequest(

  search.NewEmptySearchMethodParams().SetRequests(
    []search.SearchQuery{*search.SearchForHitsAsSearchQuery(
      search.NewEmptySearchForHits().SetIndexName("<YOUR_INDEX_NAME>").SetQuery("<YOUR_QUERY>").SetFilters("actor:Tom Cruise OR actor:Scarlett Johansson"))}),
))
if err != nil {
  // handle the eventual error
  panic(err)
}

// use the model directly
print(response)

// Everything but "Nicolas Cage" actor
response, err := client.Search(client.NewApiSearchRequest(

  search.NewEmptySearchMethodParams().SetRequests(
    []search.SearchQuery{*search.SearchForHitsAsSearchQuery(
      search.NewEmptySearchForHits().SetIndexName("<YOUR_INDEX_NAME>").SetQuery("<YOUR_QUERY>").SetFilters("NOT actor:Nicolas Cage"))}),
))
if err != nil {
  // handle the eventual error
  panic(err)
}

// use the model directly
print(response)

Java

// Only "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .setRequests(
      List.of(new SearchForHits().setIndexName("<YOUR_INDEX_NAME>").setQuery("<YOUR_QUERY>").setFilters("actor:Scarlett Johansson"))
    ),
  Hit.class
);

// Only "Tom Cruise" or "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .setRequests(
      List.of(
        new SearchForHits()
          .setIndexName("<YOUR_INDEX_NAME>")
          .setQuery("<YOUR_QUERY>")
          .setFilters("actor:Tom Cruise OR actor:Scarlett Johansson")
      )
    ),
  Hit.class
);

// Everything but "Nicolas Cage" actor
client.search(
  new SearchMethodParams()
    .setRequests(
      List.of(new SearchForHits().setIndexName("<YOUR_INDEX_NAME>").setQuery("<YOUR_QUERY>").setFilters("NOT actor:Nicolas Cage"))
    ),
  Hit.class
);

JavaScript

// Only "Scarlett Johansson" actor
const response = await client.search({
  requests: [
    {
      indexName: '<YOUR_INDEX_NAME>',
      query: '<YOUR_QUERY>',
      filters: 'actor:Scarlett Johansson',
    },
  ],
});

// use typed response
console.log(response);

// Only "Tom Cruise" or "Scarlett Johansson" actor
const response = await client.search({
  requests: [
    {
      indexName: '<YOUR_INDEX_NAME>',
      query: '<YOUR_QUERY>',
      filters: 'actor:Tom Cruise OR actor:Scarlett Johansson',
    },
  ],
});

// use typed response
console.log(response);

// Everything but "Nicolas Cage" actor
const response = await client.search({
  requests: [
    {
      indexName: '<YOUR_INDEX_NAME>',
      query: '<YOUR_QUERY>',
      filters: 'NOT actor:Nicolas Cage',
    },
  ],
});

// use typed response
console.log(response);

Kotlin

// Only "Scarlett Johansson" actor
var response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = listOf(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = "<YOUR_QUERY>",
        filters = "actor:Scarlett Johansson",
      ),
    ),
  ),
)

// Use the response
println(response)

// Only "Tom Cruise" or "Scarlett Johansson" actor
var response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = listOf(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = "<YOUR_QUERY>",
        filters = "actor:Tom Cruise OR actor:Scarlett Johansson",
      ),
    ),
  ),
)

// Use the response
println(response)

// Everything but "Nicolas Cage" actor
var response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = listOf(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = "<YOUR_QUERY>",
        filters = "NOT actor:Nicolas Cage",
      ),
    ),
  ),
)

// Use the response
println(response)

PHP

// Only "Scarlett Johansson" actor
$response = $client->search(
    ['requests' => [
        ['indexName' => '<YOUR_INDEX_NAME>',
            'query' => '<YOUR_QUERY>',
            'filters' => 'actor:Scarlett Johansson',
        ],
    ],
    ],
);

// play with the response
var_dump($response);

// Only "Tom Cruise" or "Scarlett Johansson" actor
$response = $client->search(
    ['requests' => [
        ['indexName' => '<YOUR_INDEX_NAME>',
            'query' => '<YOUR_QUERY>',
            'filters' => 'actor:Tom Cruise OR actor:Scarlett Johansson',
        ],
    ],
    ],
);

// play with the response
var_dump($response);

// Everything but "Nicolas Cage" actor
$response = $client->search(
    ['requests' => [
        ['indexName' => '<YOUR_INDEX_NAME>',
            'query' => '<YOUR_QUERY>',
            'filters' => 'NOT actor:Nicolas Cage',
        ],
    ],
    ],
);

// play with the response
var_dump($response);

Python

# Only "Scarlett Johansson" actor
response = await _client.search(
    search_method_params={
        "requests": [
            {
                "indexName": "<YOUR_INDEX_NAME>",
                "query": "<YOUR_QUERY>",
                "filters": "actor:Scarlett Johansson",
            },
        ],
    },
)

# use the class directly
print(response)

# print the JSON response
print(response.to_json())

# Only "Tom Cruise" or "Scarlett Johansson" actor
response = await _client.search(
    search_method_params={
        "requests": [
            {
                "indexName": "<YOUR_INDEX_NAME>",
                "query": "<YOUR_QUERY>",
                "filters": "actor:Tom Cruise OR actor:Scarlett Johansson",
            },
        ],
    },
)

# use the class directly
print(response)

# print the JSON response
print(response.to_json())

# Everything but "Nicolas Cage" actor
response = await _client.search(
    search_method_params={
        "requests": [
            {
                "indexName": "<YOUR_INDEX_NAME>",
                "query": "<YOUR_QUERY>",
                "filters": "NOT actor:Nicolas Cage",
            },
        ],
    },
)

# use the class directly
print(response)

# print the JSON response
print(response.to_json())

Ruby

# Only "Scarlett Johansson" actor
response = client.search(
  SearchMethodParams.new(
    requests: [SearchForHits.new(
      index_name: "<YOUR_INDEX_NAME>", query: "<YOUR_QUERY>", filters: "actor:Scarlett Johansson"
    )]
  )
)

# use the class directly
puts response

# print the JSON response
puts response.to_json

# Only "Tom Cruise" or "Scarlett Johansson" actor
response = client.search(
  SearchMethodParams.new(
    requests: [SearchForHits.new(
      index_name: "<YOUR_INDEX_NAME>", query: "<YOUR_QUERY>", filters: "actor:Tom Cruise OR actor:Scarlett Johansson"
    )]
  )
)

# use the class directly
puts response

# print the JSON response
puts response.to_json

# Everything but "Nicolas Cage" actor
response = client.search(
  SearchMethodParams.new(
    requests: [SearchForHits.new(
      index_name: "<YOUR_INDEX_NAME>", query: "<YOUR_QUERY>", filters: "NOT actor:Nicolas Cage"
    )]
  )
)

# use the class directly
puts response

# print the JSON response
puts response.to_json

Scala

// Only "Scarlett Johansson" actor
val response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = Seq(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = Some("<YOUR_QUERY>"),
        filters = Some("actor:Scarlett Johansson")
      )
    )
  )
)

// Use the response
val value = Await.result(response, Duration(100, "sec"))

// Only "Tom Cruise" or "Scarlett Johansson" actor
val response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = Seq(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = Some("<YOUR_QUERY>"),
        filters = Some("actor:Tom Cruise OR actor:Scarlett Johansson")
      )
    )
  )
)

// Use the response
val value = Await.result(response, Duration(100, "sec"))

// Everything but "Nicolas Cage" actor
val response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = Seq(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = Some("<YOUR_QUERY>"),
        filters = Some("NOT actor:Nicolas Cage")
      )
    )
  )
)

// Use the response
val value = Await.result(response, Duration(100, "sec"))

Swift

// Only "Scarlett Johansson" actor
let response: SearchResponses<Hit> = try await client
    .search(searchMethodParams: SearchMethodParams(requests: [SearchQuery.searchForHits(SearchForHits(
        query: "<YOUR_QUERY>",
        filters: "actor:Scarlett Johansson",
        indexName: "<YOUR_INDEX_NAME>"
    ))]))

// Only "Tom Cruise" or "Scarlett Johansson" actor
let response: SearchResponses<Hit> = try await client
    .search(searchMethodParams: SearchMethodParams(requests: [SearchQuery.searchForHits(SearchForHits(
        query: "<YOUR_QUERY>",
        filters: "actor:Tom Cruise OR actor:Scarlett Johansson",
        indexName: "<YOUR_INDEX_NAME>"
    ))]))

// Everything but "Nicolas Cage" actor
let response: SearchResponses<Hit> = try await client
    .search(searchMethodParams: SearchMethodParams(requests: [SearchQuery.searchForHits(SearchForHits(
        query: "<YOUR_QUERY>",
        filters: "NOT actor:Nicolas Cage",
        indexName: "<YOUR_INDEX_NAME>"
    ))]))