IndexedDB Indexes: Fast Queries in the Browser

Why it exists

IndexedDB object stores let you retrieve objects by their primary key very quickly. But to find all objects where a different property has a certain value, like finding all users with is_admin: true, the browser would have to load and inspect every single object. This is incredibly slow for large datasets. Indexes solve this performance bottleneck.

The mental model

An IndexedDB index is a separate, sorted data structure that maps values of a specific property (the keyPath) back to the records in your main object store. It's like the index in the back of a textbook. Instead of reading the whole book to find mentions of a topic, you look it up in the index and get a list of page numbers, letting you jump directly to the data you need.

How it works

You create an index on an object store using the createIndex() method. This must be done inside an onupgradeneeded callback, which runs when the database version changes. You provide a name for the index and a keyPath specifying which property to index (e.g., 'email'). You can also set options. The unique: true option enforces that no two records can have the same value for the indexed property. The multiEntry: true option is powerful for array values (like a tags property); it creates an index entry for each item in the array, allowing you to efficiently query for records containing a specific tag.

When to use it

Use an index on any property you plan to query or sort by frequently. This is essential for filtering data, such as finding all products in a certain category, all users in a specific city, or all tasks marked as 'urgent'. It's the key to building responsive, data-heavy applications that don't freeze the UI during lookups.

When not to use it

Avoid creating indexes on properties you will never search by. Every index adds overhead: it consumes storage space and slightly slows down write operations (adds, updates, deletes) because the index must also be updated. Don't index everything "just in case." Also, be mindful of indexing large, complex objects or binary data, as this can be inefficient.

One canonical example

To find users by their email address, you would create an index on the 'email' property. During a database version upgrade, you'd call const userStore = db.createObjectStore('users', { keyPath: 'id' }); userStore.createIndex('emailIndex', 'email', { unique: true });. Later, to find a user, you can get the index db.transaction('users').objectStore('users').index('emailIndex') and use its get() method with an email address for a near-instant lookup, avoiding a full table scan.