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.

About this document

This document was last updated on September 7, 2011 and last verified on September 5. It follows the W3C Specifications (Editor's Draft) that was updated on September 7, 2011.

Basic concepts

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

Setting the ranges

To retrieve all keys within a certain range, you can do the following:

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)

Determining if a key is within range

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.

Method overview

IDBKeyRange bound (in any lower, in any upper, in optional boolean lowerOpen, in optional boolean upperOpen);
IDBKeyRange only (in any value);
IDBKeyRange lowerBound (in any bound, in optional boolean open);
IDBKeyRange upperBound (in any bound, in optional open);

Attributes

Attribute Type Description
lower readonly any Lower bound of the key range.
upper readonly any Upper bound of the key range.
lowerOpen readonly boolean Returns false if the lower-bound value is included in the key range.
upperOpen readonly boolean Returns false if the upper-bound value is included in the key range.

Methods

bound()

Creates a key range with upper and lower bounds. The bounds can be open (that is, the bounds excludes the endpoint values) or closed (that is, the bounds includes the endpoint values). By default, the bounds include the endpoints and are closed.

IDBKeyRange bound (
   in any lower,
   in any upper, 
   in optional boolean lowerOpen, 
   in optional boolean upperOpen
);
Parameters
lower
The lower bound of the key range.
upper
The upper bound of the key range.
lowerOpen
Optional. If false (default value), the range includes the lower bound value of the key range.
upperOpen
Optional. If false (default value), the range includes the upper bound value of the key range.
Returns
IDBKeyRange
The newly created key range.
Exceptions

This method can raise an IDBDatabaseException with the following code:

DATA_ERR
The following conditions raise an exception:
  • The lower or upper parameters were not passed a valid key.
  • The lower key is greater than the upper key.
  • The lower key and upper key match and either of the bounds are open.

only()

Creates a new key range containing a single value.

IDBKeyRange only (
  in any value
);
Parameters
value
The single value in the key range.
Returns
IDBKeyRange
The newly created key range.
Exceptions

This method can raise an IDBDatabaseException with the following code:

DATA_ERR
The value parameter was not passed a valid key.

lowerBound()

Creates a key range with only a lower bound. By default, it includes the lower endpoint value and is closed.

IDBKeyRange lowerBound (
  in any bound, 
  in optional boolean open
);
Parameters
bound
The value of the lower bound.
open
Optional. If false (default value), the range includes the lower-bound value.
Returns
IDBKeyRange
The newly created key range.
Exceptions

This method can raise an IDBDatabaseException with the following code:

DATA_ERR
The value parameter was not passed a valid key.

upperBound()

Creates a new upper-bound key range. By default, it includes the upper endpoint value and is closed.

IDBKeyRange upperBound (
  in any bound, 
  in optional boolean open
);
Parameters
bound
The value of the upper bound of the range.
open
Optional. If false (default value), the range includes the lower-bound value.
Returns
IDBKeyRange
The newly created key range.
Exceptions

This method can raise an IDBDatabaseException with the following code:

DATA_ERR
The value parameter was not passed a valid key.

Browser compatibility

  • Desktop
  • Mobile

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Asynchronous API 12 -webkit 4.0 (2.0) -- -- --
Synchronous API
(used with WebWorkers)
-- -- -- -- --
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Asynchronous API -- 6.0 (6.0) -- -- --

Tags (1)

Edit tags

Attachments (0)

 

Attach file