IDBIndex

The IDBIndex interface of the IndexedDB API provides asynchronous access to an index in a database. An index is a kind of object store for looking up records in another object store, called the referenced object store. You use this interface to retrieve data.

Inherits from: EventTarget

Basic concepts

You can retrieve records in an object store either through their keys or by using an index. An index lets you look up records in an object store using properties of the values in the object stores records.

The index is a persistent key-value storage where the value part of its records is the key part of a record in the referenced object store. The records in an index are automatically populated whenever records in the referenced object store are inserted, updated, or deleted. Each record in an index can point to only one record in its referenced object store, but several indexes can reference the same object store. When the object store changes, all indexes that refers to the object store are automatically updated.

The records in an index are always sorted according to the records key. However, unlike object stores, a given index can contain multiple records with the same key. Such records are further sorted according to primary key in the referenced object store.

You can grab a set of keys within a range. To learn more, see IDBKeyrange.

Example

The following is an example based on the HTML5Rocks article on IndexedDB. For Chrome, use the webkit prefix. For example, IDBKeyRange would be webkitIDBKeyRange.

// Taking care of the browser-specific prefixes.
if ('webkitIndexedDB' in window) {
   window.indexedDB = window.webkitIndexedDB;
   window.IDBTransaction = window.webkitIDBTransaction;
   window.IDBKeyRange = window.webkitIDBKeyRange;
} else if ('mozIndexedDB' in window) {
   window.indexedDB = window.mozIndexedDB;
}

...
  
html5rocks.indexedDB.getAllTodoItems = function() {
  var todos = document.getElementById("todoItems");
  todos.innerHTML = "";
  
  // Start a transaction.
  var db = html5rocks.indexedDB.db;
  // Open an object store called "todo" 
  // in "READ_WRITE" mode. 
  var trans = db.transaction(["todo"], IDBTransaction.READ_WRITE, 0);
  var store = trans.objectStore("todo");

  // We select the range of data we want to make queries over 
  // In this case, we get everything. 
  // To see how you set ranges, see IDBKeyRange.
  var keyRange = IDBKeyRange.lowerBound(0);
  // We open a cursor and attach events.
  var cursorRequest = store.openCursor(keyRange);

  cursorRequest.onsuccess = function(e) {
    var result = e.target.result;
    if(!!result == false)
      return;

    renderTodo(result.value);
    // The success event handler is fired once for each entry.
    // So call "continue" on your result object.
    // This lets you iterate across the data

    result.continue();
  };

  cursorRequest.onerror = html5rocks.indexedDB.onerror;
};

Method overview

IDBRequest get (in any key) raises (IDBDatabaseException);
IDBRequest getKey (in any key) raises (IDBDatabaseException);
IDBRequest count (in optional any key) raises (IDBDatabaseException);
IDBRequest openCursor (in any ? range, in optional unsigned short direction) raises (IDBDatabaseException);
IDBRequest openKeyCursor (in any ? range, in optional unsigned short direction) raises (IDBDatabaseException);

Attributes

Attribute Type Description
name readonly DOMString The name of this index.
objectStore readonly IDBObjectStore The name of the object store referenced by this index.
keyPath readonly DOMString The key path of this index. If null, this index is not auto-populated.
unique readonly boolean If true, this index does not allow duplicate values for a key.

Methods

get()

Returns an IDBRequest object, and, in a separate thread, finds either:

  • The value in the referenced object store that corresponds to the given key.
  • The first corresponding value, if key is a key range.

If a value is successfully found, then a structured clone of it is created and set as the result of the request object.

Note: This method produces the same result for: a) a record that doesn't exist in the database and b) a record that has an undefined value. To tell these situations apart, call the openCursor() method with the same key. That method provides a cursor if the record exists, and not if it does not.

IDBRequest get (
  in any key
) raises (IDBDatabaseException);
Parameters
key
The key or key range that identifies the record to be retrieved.
Returns
IDBRequest
A request object on which subsequent events related to this operation are fired.
Exceptions

This method can raise an IDBDatabaseException with the following code:

Attribute Description
TRANSACTION_INACTIVE_ERR The index's transaction is not active.
DATA_ERR The key parameter was not a valid value.
NOT_ALLOWED_ERR The request was made on a source object that has been deleted or removed.

getKey()

Returns an IDBRequest object, and, in a separate thread, finds either:

  • The value in the index that corresponds to the given key
  • The first corresponding value, if key is a key range.

If a value is successfully found, then a structured clone of it is created and set as the result of the request object.

Note: This method produces the same result for: a) a record that doesn't exist in the database and b) a record that has an undefined value. To tell these situations apart, call the openCursor() method with the same key. That method provides a cursor if the record exists, and not if it does not.

IDBRequest getKey (
  in any key
) raises (IDBDatabaseException);
Parameters
key
The key or key range that identifies the record to be retrieved.
Returns
IDBRequest
A request object on which subsequent events related to this operation are fired.
Exceptions

This method can raise a IDBDatabaseException with the following code:

Attribute Description
TRANSACTION_INACTIVE_ERR The index's transaction is not active.
DATA_ERR The key parameter was not a valid value.
NOT_ALLOWED_ERR The request was made on a source object that has been deleted or removed.

count()

Returns an IDBRequest object, and in a separate thread, returns the number of records within a key range. For example, if you want to see how many records are between keys 1000 and 2000 in an object store, you can write the following: var req = store.count(IDBKeyRange.bound(1000, 2000));

IDBRequest count (
  in optional any key
) raises (IDBDatabaseException);
Parameters
key
The key or key range that identifies the record to be counted.
Returns
IDBRequest
A request object on which subsequent events related to this operation are fired.
Exceptions

This method can raise a IDBDatabaseException with the following code:

Attribute Description
DATA_ERR The key parameter was not a valid value.
NOT_ALLOWED_ERR The request was made on a source object that has been deleted or removed.

openCursor()

Returns an IDBRequest object, and, in a separate thread, creates a cursor over the specified key range. The method sets the position of the cursor to the appropriate record, based on the specified direction.

  • If the key range is not specified or is null, then the range includes all the records.
  • If at least one record matches the key range, then a success event is fired on the result object, with its result set to the new IDBCursor object; the value of the cursor object is set to a structured clone of the referenced value.
  • If no records match the key range, then then an error event is fired on the request object, with its code set to NOT_FOUND_ERR and a suitable message.
IDBRequest openCursor (
  in optional any? range, 
  in optional unsigned short direction
) raises (IDBDatabaseException);
Parameters
range
Optional. The key range to use as the cursor's range.
direction
Optional. The cursor's required direction. See IDBCursor Constants for possible values.
Returns
IDBRequest
A request object on which subsequent events related to this operation are fired.
Exceptions

This method can raise an IDBDatabaseException with the following code:

Attribute Description
TRANSACTION_INACTIVE_ERR The index's transaction is not active.
DATA_ERR The key parameter was not a valid value.
NOT_ALLOWED_ERR The request was made on a source object that has been deleted or removed.

openKeyCursor()

Returns an IDBRequest object, and, in a separate thread, creates a cursor over the specified key range, as arranged by this index. The method sets the position of the cursor to the appropriate record, based on the specified direction.

  • If the key range is not specified or is null, then the range includes all the records.
  • If at least one record matches the key range, then a success event is fired on the result object, with its result set to the new IDBCursor object; the value of the cursor object is set to the value of the found record.
  • If no records match the key range, then then an error event is fired on the request object, with its code set to NOT_FOUND_ERR and a suitable message.
IDBRequest openKeyCursor (
  in optional any? range, 
  in optional unsigned short direction
) raises (IDBDatabaseException);
Parameters
range
Optional. The key range to use as the cursor's range.
direction
Optional. The cursor's required direction. See IDBCursor Constants for possible values.
Returns
IDBRequest
A request object on which subsequent events related to this operation are fired.
Exceptions

This method can raise an IDBDatabaseException with the following code:

Attribute Description
TRANSACTION_INACTIVE_ERR The index's transaction is not active.
DATA_ERR The key parameter was not a valid value.
NOT_ALLOWED_ERR The request was made on a source object that has been deleted or removed.

Browser compatibility

  • Desktop
  • Mobile

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 12 -webkit  4.0 (2.0) -- -- --
count() -- 10.0 (10.0) -- -- --
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support -- 4.0 (2.0) -- -- --
count() -- 10.0 (10.0) -- -- --

Tags (2)

Edit tags

Attachments (0)

 

Attach file