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

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

PHP

$client->setSettings(
  '<YOUR_INDEX_NAME>',
  ['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

JavaScript

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

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

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

PHP

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

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

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

Filtering by string using the facetFilters field

JavaScript

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

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

PHP

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

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