IDBIndex: openKeyCursor() method

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨July 2015⁩.

Note: This feature is available inWeb Workers.

TheopenKeyCursor() method of theIDBIndex interface returns anIDBRequest object, and, ina separate thread, creates a cursor over the specified key range, as arranged by thisindex.

The method sets the position of the cursor to the appropriate key, based on thespecified direction.

If the key range is not specified or is null, then the range includes all the keys.

Note:Cursors returned byopenKeyCursor() do notmake the referenced value available asIDBIndex.openCursor does.This makes obtaining a list of keys much more efficient.

Syntax

openKeyCursor()openKeyCursor(range)openKeyCursor(range, direction)

Parameters

rangeOptional: A key orIDBKeyRange to use as the cursor's range. If nothing ispassed, this will default to a key range that selects all the records in this objectstore.
directionOptional: The cursor'sdirection. SeeIDBCursor Constants for possiblevalues.

Return value

AnIDBRequest object on which subsequent events related to this operation are fired.

If the operation is successful, the value of the request'sresult property is:

anIDBCursor object pointing at the first record matching the given query
null if no matching records were found.

Exceptions

This method may raise aDOMException of one of the following types:

TransactionInactiveErrorDOMException: Thrown if thisIDBIndex's transaction is inactive.
TypeError: Thrown if the value for the direction parameter is invalid.
DataErrorDOMException: Thrown if the key or key range provided contains an invalid key.
InvalidStateErrorDOMException: Thrown if theIDBIndex has been deleted or removed.

In the following example we open a transaction and an object store, then get theindexlName from a simple contacts database. We then open a key cursor onthe index usingopenKeyCursor() — this works the same as opening a cursordirectly on anObjectStore usingIDBObjectStore.openKeyCursor except that the returned records are sortedbased on the index, not the primary key.

Finally, we iterate through each record in the index, and insert the last name and thecorresponding primary key of the referenced record into an HTML table.

function displayDataByIndex() {  tableEntry.textContent = "";  const transaction = db.transaction(["contactsList"], "readonly");  const objectStore = transaction.objectStore("contactsList");  const myIndex = objectStore.index("lName");  myIndex.openKeyCursor().onsuccess = (event) => {    const cursor = event.target.result;    if (cursor) {      const tableRow = document.createElement("tr");      tableRow.appendChild(document.createElement("td")).textContent =        cursor.key;      tableRow.appendChild(document.createElement("td")).textContent =        cursor.primaryKey;      tableEntry.appendChild(tableRow);      cursor.continue();    } else {      console.log("All last names displayed.");    }  };}