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` 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`.

**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 with JavaScript enabled. Enable JavaScript to view data.

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).