The generated API clients are a work in progress, you can also find our stable clients on the Algolia documentation.

Skip to main content

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.

js
await client.setSettings({
  indexName: '<YOUR_INDEX_NAME>',
  indexSettings: {
    attributesForFaceting: [
      'actor',
      'filterOnly(category)',
      'searchable(publisher)',
    ],
  },
});
js
await client.setSettings({
  indexName: '<YOUR_INDEX_NAME>',
  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​

js
// 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',
    },
  ],
});
js
// 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',
    },
  ],
});

Filtering by string using the facetFilters field​

js
// 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'],
    },
  ],
});
js
// 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'],
    },
  ],
});