Guides / Managing results / Refine results / Filtering

Oct. 13, 2021

Filter an Array

What’s 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, consider the following use case. Imagine customers have several brick-and-mortar bookstores in their neighborhood. They also use an ecommerce 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 you want to filter by category and physical store, you 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"
    ]
  },
  [...]
]

You now have the necessary data to leverage Algolia’s filtering capabilities. You 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 you can filter on your array attributes, you 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
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.

Select the Search product icon on your dashboard and then 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'"
}

Did you find this page helpful?

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

On this page

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

On this page

Configuring `attributesForFaceting` (at indexing time)