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 IDBObjectStore
and IDBIndex
objects 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 in the value range A–Z.
A key range can be 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.lowerBound (x) |
All keys > x | IDBKeyRange.lowerBound (x, true) |
All keys ≤ y | IDBKeyRange.upperBound (y) |
All keys < y | IDBKeyRange.upperBound (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
isfalse
.
- The upper value of the key range is one of the following:
undefined
- Greater than key value
- Equal to key value if
upperOpen
isfalse
.
Note: This feature is available in Web Workers
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.
Methods
Static 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.
Instance methods
IDBKeyRange.includes()
-
Returns a boolean indicating whether a specified key is inside the key range.
Examples
The following example illustrates how you'd use a key range. Here we declare a keyRangeValue
as a range between values of "A"
and "F"
. We open a transaction (using IDBTransaction
) and an object store, and open a cursor with IDBObjectStore.openCursor
, declaring keyRangeValue
as its optional key range value. This means that the cursor will only retrieve records with keys inside that range. This range includes the values "A"
and "F"
, as we haven't declared that they should be open bounds.
If we used IDBKeyRange.bound("A", "F", true, true);
, then the range would not include "A"
and "F"
, only the values between them.
Note: For a more complete example allowing you to experiment with key range, have a look at our IDBKeyRange-example repo (view the example live too.)
function displayData() {
var keyRangeValue = IDBKeyRange.bound("A", "F");
var transaction = db.transaction(['fThings'], 'readonly');
var objectStore = transaction.objectStore('fThings');
objectStore.openCursor(keyRangeValue).onsuccess = function(event) {
var cursor = event.target.result;
if(cursor) {
var listItem = document.createElement('li');
listItem.innerHTML = '<strong>' + cursor.value.fThing + '</strong>, ' + cursor.value.fRating;
list.appendChild(listItem);
cursor.continue();
} else {
console.log('Entries all displayed.');
}
};
}
Specifications
Specification |
---|
Indexed Database API 3.0 # keyrange |
Browser compatibility
BCD tables only load in the browser
See also
- Using IndexedDB
- Starting transactions:
IDBDatabase
- Using transactions:
IDBTransaction
- Setting a range of keys:
IDBKeyRange
- Retrieving and making changes to your data:
IDBObjectStore
- Using cursors:
IDBCursor
- Reference example: To-do Notifications (view example live.)