What is an array in the context of filtering? When you start filtering, many of your filter attributes will take only a single value per record. For example, in a book index, if you filter by type of story (novel, short story), you only need to tag each book with a single value - normally, a book can’t be both a novel and a short story. On the other hand, other attributes, like genre, can often contain multiple values: the same book can be included in the “crime”, “comedy”, and “historical” genres. The genre attribute therefore needs to be an array.

Generally speaking, any attribute that contains a list of values for a single record needs to be set up as an array. A single value attribute takes a string as a value; multiple values require an array, whose syntax changes depending on the programming language used.

Dataset Example

To illustrate how to use an array, we’ll solve the following use case. Imagine customers have several brick-and-mortar bookstores in their neighborhood. They also use an e-commerce store. On this website, customers can order books, but also check if the same books are available in their nearby physical stores, so they can come and pick them up themselves. In your search, you may want to add a filtering option to let them filter by book genre and by store.

Since we want to filter by category and physical store, we can create two array attributes, store and categories. Each contains the list of all available options.

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
[
  {
    "title": "Harry Potter and the Philosopher's Stone",
    "author": "J. K. Rowling",
    "popularity": 1000,
    "store": [
      "The Corner Bookshop",
      "Gibert Joseph Barbès",
      "Gibert Joseph Paris 13 - Grande Bibliothèque"
    ],
    "categories": [
      "fantasy",
      "science fiction",
      "children's literature"
    ]
  },
  {
    "title": "The World as It Is",
    "author": "Ben Rhodes",
    "popularity": 900,
    "store": [
      "The Corner Bookshop"
    ],
    "categories": [
      "history",
      "politics"
    ]
  },
  [...]
]

We now have the necessary data to leverage Algolia’s filtering capabilities. We could for example retrieve all matching books that are about politics and are in stock in the The Corner Bookshop store.

Configuring attributesForFaceting (at indexing time)

Before we can filter on our array attributes, we first need to set them as attributes for faceting.

Using the API

First, you need to set categories and store as attributesForFaceting. This happens at indexing time.

1
2
3
4
5
6
$index->setSettings([
  'attributesForFaceting' => [
    "categories", // or 'filterOnly(categories)' for filtering purposes only
    "store" // or 'filterOnly(store)' for filtering purposes only
  ]
]);

Using the Dashboard

You can set your attribute for faceting in your Algolia dashboard.

  • Go to your dashboard and select your index.
  • Click the Display tab.
  • In the Faceting section, click the Add an attribute button and select the “categories” attribute in the Attributes for faceting dropdown.
  • Don’t forget to save your changes.

Applying an array filter (at search time)

Using the API

Now, you can apply your filters. You can only filter results at query time, not at indexing time. For this, you need to use the filters parameter in your search code.

1
2
3
$results = $index->search('harry', [
  'filters' => 'categories:politics AND store:Gibert Joseph Saint-Michel'
]);

Note that you can also use facetFilters 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.
  • Select “categories: politics” then “store: The Corner Bookshop” in the Facet filters input (this leverages the facetFilters 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": "categories:politics AND store:'The Corner Bookshop'"
}

Did you find this page helpful?