🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
API Reference / API Parameters / tagFilters
Type: list of strings
Engine default: []
Formerly: tags
Parameter syntax
'tagFilters' => [

  // value1 OR value2
  ['value1', 'value2'],

  // (value1 OR value2) AND value3
  ['value1', 'value2'], 'value3',


Can be used in these methods:

About this parameter

Filter hits by tags.

tagFilters is a different way of filtering, which relies on the _tags attribute. It uses a simpler syntax than filters. You can use it when you want to do simple filtering based on tags.

For more advanced filtering, we recommend the filters parameter instead. Filters can be placed in any attribute, at any level (deep nesting included). Tags can only be contained in a top-level _tags attribute. Additionally, Filters provide an easier to use, SQL-like syntax.

Usage notes

  • _tags: For this setting to work, your records need to have a _tags attribute.

  • Multiple filters: If you specify multiple tags, they are interpreted as a conjunction (AND). If you want to use a disjunction (OR), use a nested array.

  • Negation is supported by prefixing the tag value with a minus sign (-), sometimes called a dash. For example, ["tag1", "-tag2"] translates as tag1 AND NOT tag2.

  • No record count: Tag filtering is used for filtering only. You will not get a count of records that match the filters. In this way, it is the same as using filterOnly() in the attributesForFaceting.


Apply tag filters

We want to look for books or movies which are Sci-fi: "(Book OR Movie) AND SciFi".

$results = $index->search('query', [
  'tagFilters' => [
  • ["Book", "Movie"] translates as Book AND Movie
  • [["Book", "Movie"], "SciFi"] translates as (Book OR Movie) AND SciFi"
Did you find this page helpful?