Indexing

Each list can contain multiple indexes. These indexes are used to efficiently sort, filter, and search items in the list.

Indexes use JSON pointer syntax to point to a specific field or sub-section of an item's data. This is a "best effort" operation, meaning that if the field does not exist in a given item, the index will skip that item.

As such, indexes are most effective when the field being indexed is present in all items - this works especially well with list schemas because they enforce a consistent structure across all items in the list.

Let's walk through the process of creating an index, then using it for various purposes to see what it looks like in practice.

Creating an index

To create an index, you need to make a POST request to the /lists/{listId}/indexes endpoint.

Here we've created a basic index inside the sample-list list which points to the /name field in each item's data.

If we have 3 items in this list with the following data:

Item #1

Item #2

Item #3

Then we will have indexed the following values:

When we create or update an index, the API will automatically update all of the indexed values for each item in the list. This means that the index will always be up-to-date with the latest data.

Alias indexes

The index we created above is an "alias" index (note that we set "alias": true), which means that it provides a way to reference each item by a unique value instead of the item's id.

This is similar to how we can set a pathName on lists. The main difference is that alias indexes allow us to dynamically generate the alias based on the item's data.

Here are two ways of fetching an item:

Fetching the item by id:

Fetching the item by alias:

Sorting lists

If an index is enabled for sorting, we can use the index pathName in the ?order parameter to sort items in the list. Items might be sorted differently depending on the value type of the index; numbers will be sorted numerically, while strings will be sorted alphabetically.

Here's an example:

Filtering items

If an index is enabled for filtering, we can use the index pathName as a parameter when fetching items. The parameter value will be used to filter items.

If the index value type is 'string', items will be filtered based on partial string match. For example, using the index we created above, filtering by ?name=al would match items with name equal to "Alice", "Mallory", "Gonzales", "Khalil", and so on.

Index value types 'number' or 'date' will be matched exactly, however we can prefix the filter value in various ways to change how this works:

Here's an example:

Searching lists

If an index is enabled for searching, indexed values will be used to identify matching items when searching a list.

Searching uses Okapi BM25 scoring to rank items based on how well they match the search query. Search terms must be at least 3 characters long and are case-insensitive.

Here's an example of searching a list using the index we created above: