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#

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

Dart

$client->setSettings(
  '<YOUR_INDEX_NAME>',
  ['attributesForFaceting' => ['actor', 'filterOnly(category)', 'searchable(publisher)']]
);

Go

import com.algolia.model.search.*;

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

Java

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

JavaScript

client.setSettings(
  indexName: '<YOUR_INDEX_NAME>',
  indexSettings: IndexSettings(
    attributesForFaceting: [
      'actor',
      'filterOnly(category)',
      'searchable(publisher)'
    ],
  ),
);

Kotlin

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

indexName := "<INDEX_NAME>"
appID := "<APPLICATION_ID>"
apiKey := "<API_KEY>"

searchClient, _ := search.NewClient(appID, apiKey)

response, err := searchClient.SetSettings(searchClient.NewApiSetSettingsRequest(
  indexName,
  search.NewIndexSettings(
    search.WithIndexSettingsAttributesForFaceting(
      []string{
        "actor",
        "filterOnly(category)",
        "searchable(publisher)",
      },
    ),
  ),
))
if err != nil {
  panic(err)
}

taskResponse, err := searchClient.WaitForTask(
  indexName,
  response.TaskID,
  nil,
  nil,
  nil,
)

PHP

using Algolia.Search.Clients;
using Algolia.Search.Models.Search;

var client = new SearchClient("<YOUR_APP_ID>", "<YOUR_API_KEY>");
await client.SetSettingsAsync("YOUR_INDEX_NAME", new IndexSettings
{
  AttributesForFaceting = ["actor", "filterOnly(category)", "searchable(publisher)"]
});

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
await client.search({
  requests: [
    {
      indexName: '<YOUR_INDEX_NAME>',
      query: '<YOUR_QUERY>',
      filters: 'actor:Scarlett Johansson',
    },
  ],
});

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

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

Dart

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

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

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

Go

import com.algolia.model.search.*;

// Only "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .addRequests(
      new SearchForHits()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setFilters("actor:Scarlett Johansson")
    )
);

// Only "Tom Cruise" or "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .addRequests(
      new SearchForHits()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setFilters("actor:Tom Cruise OR actor:Scarlett Johansson")
    )
);

// Everything but "Nicolas Cage" actor
client.search(
  new SearchMethodParams()
    .addRequests(
      new SearchForHits()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setFilters("NOT actor:Nicolas Cage")
    )
);

Java

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

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

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

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

JavaScript

// Only 'Scarlett Johansson' actor
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
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
await client.search(
  searchMethodParams: SearchMethodParams(
    requests: [
      SearchForHits(
        indexName: '<YOUR_INDEX_NAME>',
        query: '<YOUR_QUERY>',
        filters: 'NOT actor:Nicolas Cage',
      ),
    ],
  ),
);

Kotlin

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

indexName := "<INDEX_NAME>"
appID := "<APPLICATION_ID>"
apiKey := "<API_KEY>"

searchClient, _ := search.NewClient(appID, apiKey)

// Only "Scarlett Johansson" actor
results, err := searchClient.Search(
  searchClient.NewApiSearchRequest(
    search.NewSearchMethodParams(
      []search.SearchQuery{
        search.SearchForHitsAsSearchQuery(
          search.NewSearchForHits(
            indexName,
            search.WithSearchForHitsQuery("<YOUR_QUERY>"),
            search.WithSearchForHitsFilters("actor:Scarlett Johansson"),
          ),
        ),
      },
    ),
  ),
)

// Only "Tom Cruise" or "Scarlett Johansson" actor
results, err := searchClient.Search(
  searchClient.NewApiSearchRequest(
    search.NewSearchMethodParams(
      []search.SearchQuery{
        search.SearchForHitsAsSearchQuery(
          search.NewSearchForHits(
            indexName,
            search.WithSearchForHitsQuery("<YOUR_QUERY>"),
            search.WithSearchForHitsFilters("actor:Tom Cruise OR actor:Scarlett Johansson"),
          ),
        ),
      },
    ),
  ),
)

// Everything but "Nicolas Cage" actor
results, err := searchClient.Search(
  searchClient.NewApiSearchRequest(
    search.NewSearchMethodParams(
      []search.SearchQuery{
        search.SearchForHitsAsSearchQuery(
          search.NewSearchForHits(
            indexName,
            search.WithSearchForHitsQuery("<YOUR_QUERY>"),
            search.WithSearchForHitsFilters("NOT actor:Nicolas Cage"),
          ),
        ),
      },
    ),
  ),
)

PHP

using Algolia.Search.Clients;
using Algolia.Search.Models.Search;

var client = new SearchClient("<YOUR_APP_ID>", "<YOUR_API_KEY>");
await client.SearchSingleIndexAsync<Actor>("YOUR_INDEX_NAME", new SearchParams(new SearchParamsObject
{
  Query = "<YOUR_QUERY>",
  // Only "Scarlett Johansson" actor
  Filters = "actor:Scarlett Johansson"
}));

await client.SearchSingleIndexAsync<Actor>("YOUR_INDEX_NAME", new SearchParams(new SearchParamsObject
{
  Query = "<YOUR_QUERY>",
  // Only "Tom Cruise" or "Scarlett Johansson" actor
  Filters = "actor:Tom Cruise OR actor:Scarlett Johansson"
}));

await client.SearchSingleIndexAsync<Actor>("YOUR_INDEX_NAME", new SearchParams(new SearchParamsObject
{
  Query = "<YOUR_QUERY>",
  // Everything but "Nicolas Cage" actor
  Filters = "NOT actor:Nicolas Cage"
}));

Filtering by string using the facetFilters field

C#

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

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

Dart

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

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

Go

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

// Only "Scarlett Johansson" actor
client.search(
    new SearchMethodParams()
        .addRequests(
            new SearchForFacets()
                .setIndexName("<YOUR_INDEX_NAME>")
                .setQuery("<YOUR_QUERY>")
                .setFacetFilters(FacetFilters.of("actor:Scarlett Johansson"))
    )
);
// Only "Tom Cruise" or "Scarlett Johansson" actor
client.search(
    new SearchMethodParams()
        .addRequests(
            new SearchForHits()
                .setIndexName("<YOUR_INDEX_NAME>")
                .setQuery("<YOUR_QUERY>")
                .setFacetFilters(FacetFilters.of("actor:Tom Cruise OR actor:Scarlett Johansson"))
        )
);

Java

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

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

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

JavaScript

// Only 'Scarlett Johansson' actor
client.search(
    searchMethodParams: SearchMethodParams(
  requests: [
    SearchForHits(
      indexName: '<YOUR_INDEX_NAME>',
      query: '<YOUR_QUERY>',
      facetFilters: 'actor:Scarlett Johansson',
    ),
  ],
));

// Only 'Tom Cruise' or 'Scarlett Johansson' actor
client.search(
  searchMethodParams: SearchMethodParams(
    requests: [
      SearchForHits(
        indexName: '<YOUR_INDEX_NAME>',
        query: '<YOUR_QUERY>',
        facetFilters: 'actor:Tom Cruise OR actor:Scarlett Johansson',
      ),
    ],
  ),
);

Kotlin

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

indexName := "<INDEX_NAME>"
appID := "<APPLICATION_ID>"
apiKey := "<API_KEY>"

searchClient, _ := search.NewClient(appID, apiKey)

// Only "Scarlett Johansson" actor
results, err := searchClient.Search(
  searchClient.NewApiSearchRequest(
    search.NewSearchMethodParams(
      []search.SearchQuery{
        search.SearchForHitsAsSearchQuery(
          search.NewSearchForHits(
            indexName,
            search.WithSearchForHitsQuery("<YOUR_QUERY>"),
            search.WithSearchForHitsFacetFilters(
              search.StringAsFacetFilters(search.PtrString("actor:Tom Cruise")),
            ),
          ),
        ),
      },
    ),
  ),
)

// Only "Tom Cruise" or "Scarlett Johansson" actor
results, err := searchClient.Search(
  searchClient.NewApiSearchRequest(
    search.NewSearchMethodParams(
      []search.SearchQuery{
        search.SearchForHitsAsSearchQuery(
          search.NewSearchForHits(
            indexName,
            search.WithSearchForHitsQuery("<YOUR_QUERY>"),
            search.WithSearchForHitsFacetFilters(
              search.StringAsFacetFilters(search.PtrString("actor:Tom Cruise")),
            ),
            search.WithSearchForHitsFacetFilters(
              search.StringAsFacetFilters(search.PtrString("actor:Scarlett Johansson")),
            ),
          ),
        ),
      },
    ),
  ),
)

PHP

using Algolia.Search.Clients;
using Algolia.Search.Models.Search;

var client = new SearchClient("<YOUR_APP_ID>", "<YOUR_API_KEY>");
await client.SearchSingleIndexAsync<Actor>("YOUR_INDEX_NAME", new SearchParams(new SearchParamsObject
{
  Query = "<YOUR_QUERY>",
  // Only "Scarlett Johansson" actor
  FacetFilters = new FacetFilters("actor:Scarlett Johansson"),
}));

await client.SearchSingleIndexAsync<Actor>("YOUR_INDEX_NAME", new SearchParams(new SearchParamsObject
{
  Query = "<YOUR_QUERY>",
  // Only "Tom Cruise" or "Scarlett Johansson" actor
  FacetFilters = new FacetFilters("actor:Tom Cruise OR actor:Scarlett Johansson"),
}));