IDBKeyRange

This article is in need of a technical review.

« IDBKeyRange

The IDBKeyRange interface of the IndexedDB API represents a continuous interval over some data type that is used for keys. Records can be retrieved from object stores and indexes using keys or a range of keys. You can limit the range using lower and upper bounds. For example, you can iterate over all values of a key between x and y.

A key range can have a single value or a range with upper and lower bounds or endpoints. If the key range has both upper and lower bounds, then it is bounded; if it has no bounds, it is unbounded. A bounded key range can either be open (the endpoints are excluded) or closed (the endpoints are included). To retrieve all keys within a certain range, you can use the following code constructs:

Range Code
All keys ≤ x IDBKeyRange.upperBound(x)
All keys < x IDBKeyRange.upperBound(x, true)
All keys ≥ y IDBKeyRange.lowerBound(y)
All keys > y IDBKeyRange.lowerBound(y, true)
All keys ≥ x && ≤ y IDBKeyRange.bound(x, y)
All keys > x &&< y IDBKeyRange.bound(x, y, true, true)
All keys > x && ≤ y IDBKeyRange.bound(x, y, true, false)
All keys ≥ x &&< y IDBKeyRange.bound(x, y, false, true)
The key = z IDBKeyRange.only(z)

A key is in a key range if the following conditions are true:

  • The lower value of the key range is one of the following:
    • undefined
    • Less than key value
    • Equal to key value if lowerOpen is false.
  • The upper value of the key range is one of the following:
    • undefined
    • Greater than key value
    • Equal to key value if upperOpen is false.

Methods

IDBKeyRange.bound
Creates a new key range with upper and lower bounds.
IDBKeyRange.only
Creates a new key range containing a single value.
IDBKeyRange.lowerBound
Creates a new key range with only a lower bound.
IDBKeyRange.upperBound
Creates a new upper-bound key range.

Properties

IDBKeyRange.lower Read only
Lower bound of the key range.
IDBKeyRange.upper Read only
Upper bound of the key range.
IDBKeyRange.lowerOpen Read only
Returns false if the lower-bound value is included in the key range.
IDBKeyRange.upperOpen Read only
Returns false if the upper-bound value is included in the key range.

Examples

// Let us open our database
var request = window.indexedDB.open("toDoList", 4);
    
// store the result of opening the database in the db variable.
db = request.result;

// Open a transaction on the current database and get a reference to the object store
//that we want to pull information out of
var transaction = db.transaction(["toDoList"]);
var objectStore = transaction.objectStore("toDoList");

// Different bounds

// Only match "Walk dog"
var singleKeyRange = IDBKeyRange.only("Walk dog");
// Match anything past "Ask friends to tea", including "Ask friends to tea"
var lowerBoundKeyRange = IDBKeyRange.lowerBound("Ask friends to tea");
// Match anything past "Walk dog", but don't include "Walk dog"
var lowerBoundOpenKeyRange = IDBKeyRange.lowerBound("Walk dog", true);
// Match anything up to, but not including, "Ask friends to tea"
var upperBoundOpenKeyRange = IDBKeyRange.upperBound("Ask friends to tea", true);
// Match anything between "Ask friends to tea" and "Walk dog", but not including "Walk dog"
var boundKeyRange = IDBKeyRange.bound("Ask friends to tea", "Walk dog", false, true);

// To use one of the key ranges, pass it in as the first argument of openCursor()/openKeyCursor()
index.openCursor(boundKeyRange).onsuccess = function(event) {
  var cursor = event.target.result;
  if (cursor) {
    // Do something with the matches.
    cursor.continue();
  }
};

Specifications

Specification Status Comment
Indexed Database API Candidate Recommendation  

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 12 -webkit
23
4.0 (2.0) 10 17 Not supported
Feature Android Firefox Mobile (Gecko) Firefox OS IE Phone Opera Mobile Safari Mobile
Basic support 4.4 6.0 (6.0) 1.0.1 10 17 Not supported

Be careful in Chrome as it still implements the old specification along the new one. Similarly it still has the prefixed webkitIndexedDB property even if the unprefixed indexedDB is present.

See also

To learn more about various topics, see the following

  • Starting transactions: IDBDatabase
  • Setting transaction modes: IDBTransaction
  • The reference application for the examples in this reference: To-do Notifications (view example live.) Not every snippet appears in this example, but every example uses the same data structure and syntax, and they will make sense in the context of this example.

Document Tags and Contributors

Contributors to this page: scottrowe, pdm, jswisher, hansw, chrisdavidmills, teoli, tilgovi, grendel
Last updated by: chrisdavidmills,