Filter by tags

Sometimes, you may want to filter search results based on a specific metadata, like a type or a category. Imagine you have an online bookstore with sections; non-fiction, history, children’s literature, politics, etc. but you have a single index for all your books. Depending on where the user is making searches from, you may want to provide a different search experience.

For example, let’s say a user goes to the politics category on your website, then starts searching for the biography of President Harry S. Truman. If your search relevance is primarily based on book popularity, by typing “harry”, they would most likely retrieve Harry Potter books first, which wouldn’t make sense to them.

Instead, what you can do is filter the results they get based on what they most likely want to see. Algolia lets you do this by allowing you to set filters based on one or several 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": 900,
    "_tags": [
      "biography",
      "history",
      "politics"
    ]
  },
  {
    "title": "Where the Buck Stops: The Personal and Private Writings of Harry S. Truman",
    "author": "Harry S. Truman",
    "popularity": 300,
    "_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 “Where the Buck Stops”, because they both have “politics” in their _tags attribute, and both have to do with 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
4
5
index.search('harry', {
  filters: 'politics' // Same as '_tags:politics'
}).then(({ hits }) => {
  console.log(hits);
});

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
5
6
7
8
9
val query = query("harry") {
    filters {
        and {
            tag("politics")
        }
    }
}

index.search(query)

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"
  )
}

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.

• Select the Search product icon on your dashboard and then 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 recommended 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.