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
Instance 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.
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.)
js
function displayData() {
const keyRangeValue = IDBKeyRange.bound("A", "F");
const transaction = db.transaction(["fThings"], "readonly");
const objectStore = transaction.objectStore("fThings");
objectStore.openCursor(keyRangeValue).onsuccess = (event) => {
const cursor = event.target.result;
if (cursor) {
const listItem = document.createElement("li");
listItem.textContent = `${cursor.value.fThing}, ${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 the example live).