What's the purpose of keyPath in IDBObjectStore.createIndex()?

Question

I've been reading all around the MDN, but I get stuff like:

keyPath
The key path for the index to use. Note that it is possible to create an index with an empty keyPath, and also to pass in a sequence (array) as a keyPath.

Well, no s@!t, keyPath is a key path. But what is that?

In all examples, it's the same thing as the name of the column (or index, as they call it):

  objectStore.createIndex("hours", "hours", { unique: false });
  objectStore.createIndex("minutes", "minutes", { unique: false });
  objectStore.createIndex("day", "day", { unique: false });
  objectStore.createIndex("month", "month", { unique: false });
  objectStore.createIndex("year", "year", { unique: false });

They say that you can pass:

• An empty string - ""
• A valid JavaScript identifier (I assume this means valid JS variable name)
• Multiple javascript identifiers separated by periods, eg: "name.name2.foo.bar"
• An array containing any of the above, eg.: ["foo.bar","","name"]

I can't imagine what purpose does this serve. I absolutely do not understand what keyPath is and what can I use it for. Can someone please provide example usage where keyPath is something else than the name of the column? An explanation what effect do values of keyPath have on the database?

Answer 1

Examples might help. If you use a key path with an object store, you can have keys plucked out of the objects being stored rather than having to specify them on each put() call. For example, with records that just have an id and name, you could use the record's id as a primary key for the object store:

store = db.createObjectStore('my_store', {keyPath: 'id'});
store.put({id: 987, name: 'Alice'});
store.put({id: 123, name: 'Bob'});

Which gives you this store:

key   | value
------+-------------------
123   | {id: 123, name: 'Bob'}
987   | {id: 987, name: 'Alice'}

But if you want to look record up by name, you create an index:

name_index = store.createIndex('index_by_name', 'name');

Which gives you this index:

key     | primary key | value
--------+-------------+--------------------------
'Alice' | 987         | {id: 987, name: 'Alice'}
'Bob'   | 123         | {id: 123, name: 'Bob'}

(The index doesn't really store a copy of the value, just the primary key. But it's easier to visualize this way. This also explains the properties you'll see on a cursor if you iterate over the index.)

So now you can look up a record by name with:

req = name_index.get('Alice')

When records are added to the store, the key path is used to generate the key for the index.

Key paths with . separators can be used for lookups in more complex records. Key paths that are arrays can either produce compound keys (where the key is itself an array), or multiple index entries (if multiEntry: true is specified)