Creating and Querying Indexes

Why indexes?

Every IndexedDB object store is keyed by its primary key (the keyPath or an auto-incremented id). That is efficient for lookups by primary key, but if you want to query by a different field — for example, find all contacts by their name — you need an index.

An index is a secondary sorted structure that maps a chosen field’s value back to the record’s primary key. Once created, you can call get() or getAll() on the index exactly as you would on the store itself.

Creating an index with `createIndex()`

Indexes must be created (or deleted) inside the onupgradeneeded callback. You cannot add an index to an existing store outside of an upgrade transaction.

const request = indexedDB.open('mydb', 1);

request.onupgradeneeded = (event) => {
  const db = event.target.result;

  // Create the object store
  const store = db.createObjectStore('contacts', { keyPath: 'id' });

  // Create an index on the 'name' field
  store.createIndex('by_name', 'name', { unique: false });
};

`createIndex(name, keyPath, options)` parameters

Parameter	Purpose
`name`	The index name you will use to retrieve it later with `store.index(name)`
`keyPath`	The property path on each record to index (e.g. `'name'`, `'address.city'`)
`unique`	If `true`, the store rejects records whose indexed value duplicates an existing one
`multiEntry`	If `true` and the indexed property is an array, each array element gets its own entry in the index

Opening the index and querying

After the upgrade, open the index from a normal read/write transaction with store.index('by_name'), then call get(value) for a single record or getAll(value) for all matching records.

const tx = db.transaction('contacts', 'readonly');
const store = tx.objectStore('contacts');
const nameIndex = store.index('by_name');

// Single match
const getReq = nameIndex.get('Alice');
getReq.onsuccess = () => console.log(getReq.result); // { id: 1, name: 'Alice', ... }

// All records (no filter → returns every record sorted by index key)
const getAllReq = nameIndex.getAll();
getAllReq.onsuccess = () => console.log(getAllReq.result);

Passing a value to getAll(value) filters to records whose indexed field equals that value. Passing no argument (or undefined) returns every record in the store, ordered by the index key.

The `unique` flag

// Enforce unique emails
store.createIndex('by_email', 'email', { unique: true });

With unique: true, any add() or put() that would create a duplicate indexed value throws a ConstraintError. Use this for fields like email addresses or usernames where duplicates are not allowed.

The `multiEntry` flag

// Record: { id: 1, tags: ['js', 'idb', 'storage'] }
store.createIndex('by_tag', 'tags', { multiEntry: true });

With multiEntry: true, an array-valued field produces one index entry per element. You can then call index.getAll('idb') and the record above will be returned even though the value of tags is an array.

Runnable: create an index and query it

Browser Storage

(async function () {
  // Helper: wrap an IDBRequest in a Promise
  function req(r) {
    return new Promise((resolve, reject) => {
      r.onsuccess = () => resolve(r.result);
      r.onerror = () => reject(r.error);
    });
  }

  // 1. Open the database (version 1)
  const db = await new Promise((resolve, reject) => {
    const openReq = indexedDB.open('demo-advanced-indexes', 1);

    openReq.onupgradeneeded = (event) => {
      const database = event.target.result;
      const store = database.createObjectStore('contacts', { keyPath: 'id' });
      store.createIndex('by_name', 'name', { unique: false });
      console.log('Store and index created.');
    };

    openReq.onsuccess = () => resolve(openReq.result);
    openReq.onerror = () => reject(openReq.error);
  });

  // 2. Add two records
  const writeTx = db.transaction('contacts', 'readwrite');
  const writeStore = writeTx.objectStore('contacts');
  await req(writeStore.put({ id: 1, name: 'Alice', email: 'alice@example.com' }));
  await req(writeStore.put({ id: 2, name: 'Bob',   email: 'bob@example.com' }));
  await new Promise((resolve, reject) => {
    writeTx.oncomplete = resolve;
    writeTx.onerror = () => reject(writeTx.error);
  });
  console.log('Records inserted.');

  // 3. Query using the index
  const readTx = db.transaction('contacts', 'readonly');
  const readStore = readTx.objectStore('contacts');
  const nameIndex = readStore.index('by_name');

  // Single lookup
  const alice = await req(nameIndex.get('Alice'));
  console.log('Alice email:', alice.email);

  // Get all records (sorted by name)
  const all = await req(nameIndex.getAll());
  console.log('All contacts by name:', all.map(function(c) { return c.name; }).join(', '));

  // 4. Clean up
  db.close();
  await new Promise((resolve, reject) => {
    const delReq = indexedDB.deleteDatabase('demo-advanced-indexes');
    delReq.onsuccess = resolve;
    delReq.onerror = () => reject(delReq.error);
  });
  console.log('Database deleted — cleanup done.');
})();

Trade-offs

Option	Benefit	Cost
Creating an index on a frequently-queried field	Much faster reads/searches on that field, no need to scan every record	Every write must also update the index, slowing writes down and using extra storage
No index at all (search via cursor + your own filter)	No write overhead, no extra storage used	Reads/searches must scan every record, getting slower as the store grows
`multiEntry: true` on an array field	Efficiently searches each element inside an array	Adds one index entry per array element, so the index grows with the element count

Common mistakes

Trying to create a new index outside onupgradeneeded — this throws immediately. Indexes can only be created or removed inside an upgrade transaction.
Setting unique: true on a field that already has duplicate values — writing a record with a duplicate indexed value throws ConstraintError immediately. Make sure the field is genuinely unique before turning this on.
Forgetting that getAll() on an index sorts by the index key, not the primary key — if you expect primary-key order but query through an index, the results are instead sorted by the indexed field.