Filter By Tags

Dataset Example

Algolia lets you add tags to each of your records thanks to the special attribute _tags. This reserved Algolia attribute automatically works as a filter without you having to set it as an attribute for faceting.

Therefore, we can leverage this attribute and tag books by categories or genre.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
[
  {
    "title": "Harry Potter and the Philosopher's Stone",
    "author": "J. K. Rowling",
    "popularity": 1000,
    "_tags": [
      "fantasy",
      "science fiction",
      "children's literature"
    ]
  },
  {
    "title": "Harry Potter and the Goblet of Fire",
    "author": "J. K. Rowling",
    "popularity": 3000,
    "_tags": [
      "fantasy",
      "science fiction",
      "children's literature"
    ]
  },
  {
    "title": "Harry Potter and the Chamber of Secrets",
    "author": "J. K. Rowling",
    "popularity": 2000,
    "_tags": [
      "fantasy",
      "science fiction",
      "children's literature"
    ]
  },
  {
    "title": "The Accidental President: Harry S. Truman and the Four Months That Changed the World",
    "author": "A. J. Baime",
    "popularity": 300,
    "_tags": [
      "biography",
      "history",
      "politics"
    ]
  },
  {
    "title": "The World as It Is",
    "author": "Ben Rhodes",
    "popularity": 900,
    "_tags": [
      "history",
      "politics"
    ]
  },
  ...
]

We now have the necessary data to leverage Algolia’s filtering capabilities. For instance, if we typed “harry” and restricted our search to “politics”, we could retrieve “The Accidental President” and “The World as It Is”, because they both have “politics” in their _tags attribute, and both are about Harry Truman.

_tags is a reserved word and so it is not searchable by default.

Using the API

1
2
3
$results = $index->search('harry', [
  'filters' => 'politics' // Same as '_tags:politics'
]);

1
2
3
results = index.search('harry', {
  filters: 'politics' # Same as '_tags:politics'
})

1
2
3
index.search('harry', {
  filters: 'politics' // Same as '_tags:politics'
});

1
2
3
results = index.search('harry', {
    'filters': 'politics' # Same as '_tags:politics'
})

1
2
3
4
5
6
let query = Query(query: "harry")
query.filters = "politics" // Same as "_tags:politics"

index.search(query, completionHandler: { (res, error) in
  print(res)
})

1
2
3
4
index.search(
  new Query("harry")
    .setFilters("politics") // Same as "_tags:politics"
);

1
2
3
index.Search(new Query<JObject>("harry") {
    Filters = "politics"
});

1
2
3
4
index.search(
  new Query("harry")
    .setFilters("politics") // Same as "_tags:politics"
);

1
2
3
4
res, err := index.Search(
  "harry",
  opt.Filters("politics"), // Same as "_tags:politics"
)

1
2
3
4
5
6
client.execute {
  search into "myIndex" query Query(
    query = Some("harry"),
    filters = Some("politics") // Same as "_tags:politics"
  )
}

1
2
3
4
5
6
7
8
9
val query = query("harry") {
    filters {
        and {
            tag("politics")
        }
    }
}

index.search(query)

If you don’t specify any attribute name, the filter applies to _tags. For example, politics translates into _tags:politics.

Note that you can also use tagFilters to do the same thing.

Using the Dashboard

Regarding filters, you can’t set them directly in the dashboard since you can only filter at query time. Yet, you can test for specific filters in the dashboard before using them in your search code.

• Go to your dashboard and select your index.
• Click the Add Query Param button.
• Go to the Filters tab.
• Type “politics” in the Tag filters input (this leverages the tagFilters feature).
• Click Apply.

You can also test for regular filters (with the filters feature). Go to the Custom tab and add your filter as JSON:

1
2
3
{
  "filters": "politics"
}

The Difference Between _tags and a Custom Array

Using _tags

The _tags reserved attribute is dedicated to filtering. For that reason, you don’t have to set it as an attribute for faceting and use the filterOnly modifier like you would with a custom attribute. The _tags attribute comes ready and optimized for filtering. If you only have a single group of tags, using _tags is the recommend approach.

Note that, because _tags isn’t defined as a facet, you don’t get a count of records that match the filters.

Using custom attributes

On the other hand, you could have use cases where it would make sense to keep tags separate in different attributes. For example, you may want to refine results further and also filter by chapter. It wouldn’t make sense to mix everything up in _tags, so in the case of several types of filters, creating a custom attribute is the way to go.