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

A great way to understand things is to think how you would design it yourself.

Let's take a step back, and look at how a very simple NoSQL database would store data, then add indices.

Each Store would look like a JavaScript object (Or dictionary in python, a hash in C# ) etc...

{
  "1": {"name": "Lara", "age": "20"},
  "2": {"name": "Sara", "age": "22"},
  "3": {"name": "Joe", "age": "22"},
}

This structure is basically a list of values, plus an index to retrieve the values, like so:

//Raw JS:
var sara = data["2"]
// IndexedDB equivalent:
store.get(2)

This is super fast for direct object retrieval, but sucks for filtering. If you want to get people of a specific age, you need to loop over every value.

If you knew in advance you would be doing your queries by age, you could really speed up such queries by creating a new object which indexes the value by age:

{
  "20": [<lara>],
  "22": [<joe>, <sara>],
  ...
}

But how would you query that? You can't use the default indexing syntax (e.g. data[22] or store.get(22)) because those expect the key.

One way would be to name that second index, e.g. by_age_index and give our store object a way to access that index by name, so you could to this:

store.index('by_age_index').get(22) // Returns Joe and Sara

The last bit of the puzzle would be telling that index how to determine which records go against which key (because it has to keep itself updated when records are added/changed/removed)

In other words, how does it know Joe and Sara go against key 22, but Lara goes against key 20?

In our case, we want to use the field age from each record. This is what we mean by a keyPath.

So when defining an index, it makes sense that we would specify that as well as the name, e.g.

store.createIndex('by_age_index', 'age');

Of course, if you want to access your index like this:

store.index('age').get(22) // Returns Joe and Sara

Then you need to create your index like this:

store.createIndex('age', 'age');

Which is what most people do, which is why we see that in examples, which gives the impression that the first argument is the keyPath (whereas it's actually just the arbitrary name we give that index) leaving us unsure about what the second argument might be for.

I could have explained all this by saying:

The first parameter is the handle by which you access the index on the store, the second parameter is the name of the field on the record by which that index should group its records.

But maybe this rundown will help other people too :-)

Answer 2

A keypath is how you indicate to indexedDB which properties of your object play a special role. Similar to how you would indicate to an SQL database that a certain column in a table is the primary key of the table, or how you could tell a database to create an index on one or more particular columns in a table.

In other words, it is the path that the indexedDB implementation should follow when determining which property should be used for some calculation. For example, when searching for a value with a given key.

It is a path, and not a simple key, because it considers that object property values can also be objects. In other words, there is a hierarchy. For example, {a:{b:1}}. The "path" to the value 1 is "a.b". The path is the sequence of properties to visit to get to the value.

The key part of the name signifies that the columns play an important role. For example, in identifying the primary key property, or a particular indexed property.

Properties that are not part of the keypath are ignored in the sense that the indexedDB implementation just treats the whole object as a bag of properties, and only pays attention to those, or gains awareness of those, that are a part of a keypath.

Answer 3

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)