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.

JavaScript

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

PHP

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

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

Java

java
import com.algolia.model.search.*;
client.setSettings(
  "<YOUR_INDEX_NAME>",
  new IndexSettings()
    .addAttributesForFaceting("actor")
    .addAttributesForFaceting("filterOnly(category)")
    .addAttributesForFaceting("searchable(publisher)")
);

java
import com.algolia.model.search.*;
client.setSettings(
  "<YOUR_INDEX_NAME>",
  new IndexSettings()
    .addAttributesForFaceting("actor")
    .addAttributesForFaceting("filterOnly(category)")
    .addAttributesForFaceting("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

JavaScript

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

PHP

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

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

Java

java
import com.algolia.model.search.*;
// Only "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.ofSearchForFacets(
      new SearchForFacets()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setFilters("actor:Scarlett Johansson")
    )
  )
);
// Only "Tom Cruise" or "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.ofSearchForFacets(
      new SearchForFacets()
        .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(SearchQuery.ofSearchForFacets(
      new SearchForFacets()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setFilters("NOT actor:Nicolas Cage")
    )
  )
);

java
import com.algolia.model.search.*;
// Only "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.ofSearchForFacets(
      new SearchForFacets()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setFilters("actor:Scarlett Johansson")
    )
  )
);
// Only "Tom Cruise" or "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.ofSearchForFacets(
      new SearchForFacets()
        .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(SearchQuery.ofSearchForFacets(
      new SearchForFacets()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .setFilters("NOT actor:Nicolas Cage")
    )
  )
);

Filtering by string using the facetFilters field

JavaScript

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

PHP

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

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

Java

java
import com.algolia.model.search.*;
// Only "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.ofSearchForFacets(
      new SearchForFacets()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .addFacetFilters("actor:Scarlett Johansson")
    )
  )
);
// Only "Tom Cruise" or "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.ofSearchForFacets(
      new SearchForFacets()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .addFacetFilters("actor:Tom Cruise")
        .addFacetFilters("actor:Scarlett Johansson")
    )
  )
);

java
import com.algolia.model.search.*;
// Only "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.ofSearchForFacets(
      new SearchForFacets()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .addFacetFilters("actor:Scarlett Johansson")
    )
  )
);
// Only "Tom Cruise" or "Scarlett Johansson" actor
client.search(
  new SearchMethodParams()
    .addRequests(SearchQuery.ofSearchForFacets(
      new SearchForFacets()
        .setIndexName("<YOUR_INDEX_NAME>")
        .setQuery("<YOUR_QUERY>")
        .addFacetFilters("actor:Tom Cruise")
        .addFacetFilters("actor:Scarlett Johansson")
    )
  )
);