Guides / Managing results / Refine results / Filtering

Oct. 26, 2020

Filter an Array

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.

Copy
[
  {
    "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.

Copy

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
  ]
]);

1
2
3
4
5
6
index.set_settings({
  attributesForFaceting: [
    'categories', # or 'filterOnly(categories)' for filtering purposes only
    'store' # or 'filterOnly(store)' for filtering purposes only
  ]
})

1
2
3
4
5
6
7
8
index.setSettings({
  attributesForFaceting: [
    'categories', // or 'filterOnly(categories)' for filtering purposes only
    'store' // or 'filterOnly(store)' for filtering purposes only
  ]
}).then(() => {
  // done
});

1
2
3
4
5
6
index.set_settings({
    'attributesForFaceting': [
        'categories', # or 'filterOnly(categories)' for filtering purposes only
        'store' # or 'filterOnly(store)' for filtering purposes only
    ]
})

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
  ]
])

1
2
3
4
5
6
7
8
final JSONObject res = index.setSettings(
  new JSONObject().put(
    "attributesForFaceting",
    new JSONArray()
      .put("categories") // or 'filterOnly(categories)' for filtering purposes only
      .put("store") // or 'filterOnly(store)' for filtering purposes only
  )
);

1
2
3
4
5
6
7
8
9
10
11
12
13
IndexSettings settings = new IndexSettings
{
    AttributesForFaceting = new List<string>
    {
      "categories", // or 'filterOnly(categories)' for filtering purposes only
      "store" // or 'filterOnly(store)' for filtering purposes only
    }
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
6
index.setSettings(
  new IndexSettings().setAttributesForFaceting(Arrays.asList(
    "categories", // or 'filterOnly(categories)' for filtering purposes only
    "store" // or 'filterOnly(store)' for filtering purposes only
  ))
);

1
2
3
4
5
6
res, err := index.SetSettings(search.Settings{
  AttributesForFaceting: opt.AttributesForFaceting(
    "categories", // or 'filterOnly(categories)' for filtering purposes only
    "store",      // or 'filterOnly(store)' for filtering purposes only
  ),
})

1
2
3
4
5
6
7
8
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    attributesForFaceting = Some(Seq(
      "categories", // or 'filterOnly(categories)' for filtering purposes only
      "store" // or 'filterOnly(store)' for filtering purposes only
    ))
  )
}

1
2
3
4
5
6
7
8
val settings = settings {
    attributesForFaceting {
        +"categories" // or FilterOnly("categories") for filtering purposes only
        +"store" // " FilterOnly("store") for filtering purposes only
    }
}

index.setSettings(settings)

Using the dashboard

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

Go to your dashboard and select your index.
Click the Configuration tab.
In the Facets subsection of Filtering and Faceting, click the “Add an attribute” button and select your categories attribute from the 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.

Copy

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

1
2
3
4
5
6
let query = Query(query: "harry")
query.filters = "categories:politics AND store:Gibert Joseph Saint-Michel"

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

1
2
3
4
5
6
client.execute {
  search into "myIndex" query Query(
    query = Some("harry"),
    filters = Some("categories:politics AND store:Gibert Joseph Saint-Michel")
  )
}

1
2
3
4
5
6
7
8
9
10
val query = query("harry") {
    filters {
        and {
            facet("categories", "politics")
            facet("store", "Gibert Joseph Saint-Michel")
        }
    }
}

index.search(query)

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. This should take you automatically to the Browse section.
Click the “Add Query Parameter” button, which is just below the search bar.
Go to the Filters tab (it should be the default).
In the Facet filters input, type categories: politics and hit enter. Now type store: The Corner Bookshop and hit enter.
Click “Apply”.

The results in your dashboard search will be political and available at The Corner Bookshop store.

You can also test for regular filters (with the filters feature). To do this go to the Custom tab of the Add Query Parameter input menu and add your filter as JSON:

Copy
{
  "filters": "categories:politics AND store:'The Corner Bookshop'"
}

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

Filter an Array

On this page

Dataset Example

Configuring attributesForFaceting (at indexing time)

Using the API

Using the dashboard

Applying an array filter (at search time)

Using the API

Using the dashboard

Did you find this page helpful?

On this page