Filter an Array

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

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
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.

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

1
2
3
results = index.search('harry', {
  filters: 'categories:politics AND store:Gibert Joseph Saint-Michel'
})

1
2
3
index.search('harry', {
  filters: 'categories:politics AND store:Gibert Joseph Saint-Michel'
});

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
index.search(
  new Query("harry")
    .setFilters("categories:politics AND store:Gibert Joseph Saint-Michel")
);

1
2
3
index.Search(new Query<Book>("harry") {
    Filters = "categories:politics AND store:Gibert Joseph Saint-Michel"
});

1
2
3
4
index.search(
  new Query("harry")
    .setFilters("categories:politics AND store:Gibert Joseph Saint-Michel")
);

1
2
3
4
res, err := index.Search(
  "harry",
  opt.Filters("categories:politics AND store:Gibert Joseph Saint-Michel"),
)

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.

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

1
2
3
{
  "filters": "categories:politics AND store:'The Corner Bookshop'"
}