Table of contents
- 1. Method overview
- 2. Attributes
- 3. Methods
- 3.1. add()
- 3.2. clear()
- 3.3. count()
- 3.4. createIndex()
- 3.5. delete()
- 3.6. deleteIndex()
- 3.7. get()
- 3.8. index()
- 3.9. openCursor()
- 3.10. put()
- 4. Browser compatibility
The IDBObjectStore
interface of the IndexedDB API represents an object store in a database. Records within an object store are sorted according to their keys. This sorting enable fast insertion, look-up, and ordered retrieval.
Method overview
IDBRequest add (in any value, in optional any key) raises (IDBDatabaseException, DOMException); |
IDBRequest clear () raises (IDBDatabaseException); |
IDBRequest count (in optional any key) raises( IDBDatabaseException ); |
IDBIndex createIndex (in DOMString name, in DOMString keyPath, in optional boolean unique) raises (IDBDatabaseException); |
IDBRequest delete (in any key) raises ( IDBDatabaseException ); |
void deleteIndex (in any DOMString indexName) raises (IDBDatabaseException); |
IDBRequest get (in any key) raises (IDBDatabaseException); |
IDBIndex index (in DOMString name) raises (IDBDatabaseException); |
IDBRequest openCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises (IDBDatabaseException); |
IDBRequest put (in any value, in optional any key) raises (IDBDatabaseException, DOMException); |
Attributes
Attribute | Type | Description |
---|---|---|
indexNames | readonly DOMStringList | A list of the names of indexes on objects in this object store. |
keyPath | readonly DOMString | The key path of this object store. If this attribute is null, the application must provide a key for each modification operation. |
name | readonly DOMString | The name of this object store. |
Methods
add()
Returns an IDBRequest object, and, in a separate thread, creates a structured clone of the value
, and stores the cloned value in the object store. If the record is successfully stored, then a success event is fired on the returned request object, using the IDBTransactionEvent interface, with the result
set to the key for the stored record, and transaction
set to the transaction in which this object store is opened. If a record already exists in the object store with the key
parameter as its key, then an error event is fired on the returned request object, with code set to CONSTRAINT_ERR
.
IDBRequest add( in any value, in optional any key ) raises (IDBDatabaseException, DOMException);
Parameters
- value
- The value to be stored.
- key
- The key to use to identify the record. If unspecified, it results to null.
Returns
- IDBRequest
- A request object on which subsequent events related to this operation are fired.
Exceptions
This method can raise an IDBDatabaseException with the following codes:
DATA_ERR
- If the object store uses in-line keys or has a key generator, and a key parameter was provided.
If the object store uses out-of-line keys and has no key generator, and no key parameter was provided.
If the object store uses in-line keys but no key generator, and the object store's key path does not yield a valid key.
If the key parameter was provided but does not contain a valid key.
If there are indexed on this object store, and using their key path on the value parameter yields a value that is not a valid key. READ_ONLY_ERR
- If the mode of the associated transaction is
READ_ONLY
. TRANSACTION_INACTIVE_ERR
- If the associated transaction is not active.
This method can raise a DOMException with the following code:
DATA_CLONE_ERR
- If the data being stored could not be cloned by the internal structured cloning algorithm.
clear()
If the mode of the transaction that this object store belongs to is READ_ONLY
, this method raises an IDBDatabaseException with its code set to READ_ONLY_ERR
. Otherwise, this method creates and immediately returns an IDBRequest object, and clears this object store in a separate thread. Clearing an object store consists of removing all records from the object store and removing all records in indexes that reference the object store.
IDBRequest clear( ) raises (IDBDatabaseException);
Returns
- IDBRequest
- A request object on which subsequent events related to this operation are fired.
Exceptions
This method can raise an IDBDatabaseException with the following codes:
READ_ONLY_ERR
- If the mode of the transaction that this object store belongs to is READ_ONLY.
TRANSACTION_INACTIVE_ERR
- If the transaction that this object store belongs to is not active.
count()
Immediately returns an IDBRequest object and asynchronously count the amount of objects in the object store that match the parameter, a key or a key range. If the parameter is not valid returns an exception.
IDBRequest count( in option any key ) raises (IDBDatabaseException);
Parameters
- key
- The key or key range that identifies the records to be counted.
Returns
- IDBRequest
- A request object on which subsequent events related to this operation are fired.
Exceptions
This method can raise an IDBDatabaseException with the following codes:
DATA_ERR
- If the object store uses in-line keys or has a key generator, and a key parameter was provided.
If the object store uses out-of-line keys and has no key generator, and no key parameter was provided.
If the object store uses in-line keys but no key generator, and the object store's key path does not yield a valid key.
If the key parameter was provided but does not contain a valid key.
If there are indexed on this object store, and using their key path on the value parameter yields a value that is not a valid key. NOT_ALLOWED_ERR
- The request was made on a source object that has been deleted or removed.
createIndex()
Creates and returns a new index in the connected database. Note that this method must be called only from a VERSION_CHANGE
transaction callback.
IDBIndex createIndex ( in DOMString name, in DOMString keyPath, in Object optionalParameters ) raises (IDBDatabaseException);
Parameters
- name
- The name of the index to create.
- keyPath
- The key path for the index to use.
- optionalParameters
- Warning: The latest draft of the specification changed this to
IDBIndexParameters
, which is not yet recognized by any browserOptions object whose attributes are optional parameters to the method. It includes the following properties:
Attribute Description unique
If true, the index will not allow duplicate values for a single key. multientry
If true, the index will add an entry in the index for each array element when the keypath resolves to an Array. If false, it will add one single entry containing the Array. Unknown parameters are ignored.
Returns
- IDBIndex
- The newly created index.
Exceptions
This method can raise an IDBDatabaseException with the following codes:
CONSTRAINT_ERR
- If an index with the same name (based on case-sensitive comparison) already exists in the connected database.
NOT_ALLOWED_ERR
- If this method was not called from a
VERSION_CHANGE
transaction callback.
delete()
Immediately returns an IDBRequest
object, and removes the record specified by the given key from this object store, and any indexes that reference it, in a separate thread. If no record exists in this object store corresponding to the key, an error event is fired on the returned request object, with its code
set to NOT_FOUND_ERR
and an appropriate message
. If the record is successfully removed, then a success event is fired on the returned request object, using the IDBTransactionEvent
interface, with the result
set to undefined
, and transaction set to the transaction in which this object store is opened.
IDBRequest delete ( in any key ) raises (IDBDatabaseException);
Parameters
- key
- The key to use to identify the record.
Returns
- IDBRequest
- A request object on which subsequent events related to this operation are fired.
Exceptions
This method can raise an IDBDatabaseException with the following codes:
deleteIndex()
Destroys the index with the specified name in the connected database. Note that this method must be called only from a VERSION_CHANGE
transaction callback.
void removeIndex( in DOMString indexName ) raises (IDBDatabaseException);
Parameters
NOT_ALLOWED_ERR
- If the object store is not in the scope of any existing transaction, or if the associated transaction's mode is
READ_ONLY
orSNAPSHOT_READ
. TRANSACTION_INACTIVE_ERR
- If the associated transaction is not active.
- indexName
- The name of the existing index to remove.
Exceptions
This method can raise an IDBDatabaseException with the following codes:
NOT_ALLOWED_ERR
- If this method was not called from a VERSION_CHANGE transaction callback.
NOT_FOUND_ERR
- If no index exists with the specified name (based on case-sensitive comparison) in the connected database.
get()
Immediately returns an IDBRequest object, and retrieves the requested record from the object store in a separate thread. If the operation is successful, then a success event is fired on the returned object, using the IDBTransactionEvent interface, with its result
set to the retrieved value, and transaction
set to the transaction in which this object store is opened. If a record does not exist in the object store for the key parameter, then an error event is fired on the returned object, with its code
set to NOT_FOUND_ERR
and an appropriate message
.
IDBRequest get( in any key ) raises (IDBDatabaseException);
Parameters
- key
- The key identifying the record to retrieve.
Returns
IDBRequest
- A request object on which subsequent events related to this operation are fired.
Exceptions
This method can raise an IDBDatabaseException with the following code:
DATA_ERR
- If the
key
parameter was not a valid value. TRANSACTION_INACTIVE_ERR
- If the associated transaction is not active.
index()
Opens the named index in this object store.
IDBIndex index( in DOMString name ) raises (IDBDatabaseException);
Parameters
- name
- The name of the index to open.
Returns
IDBIndex
- An object for accessing the index.
Exceptions
This method can raise an IDBDatabaseException with the following code:
NOT_FOUND_ERR
- If no index exists with the specified name (based on case-sensitive comparison) in the connected database.
openCursor()
Immediately returns an IDBRequest object, and creates a cursor over the records in this object store, in a separate thread. If there is even a single record that matches the key range, then a success event is fired on the returned object, with its result
set to the IDBCursor object for the new cursor. If no records match the key range, then a success event is fired on the returned object, with its result
set to null.
IDBRequest openCursor ( in optional IDBKeyRange range, in optional unsigned short direction ) raises (IDBDatabaseException);
Parameters
- range
- The key range to use as the cursor's range. If this parameter is unspecified or null, then the range includes all the records in the object store.
- direction
- The cursor's direction.
Returns
IDBRequest
- A request object on which subsequent events related to this operation are fired.
Exceptions
This method can raise an IDBDatabaseException with the following code:
NOT_ALLOWED_ERR
- If this object store is not in the scope of any existing transaction on the connected database.
put()
Returns an IDBRequest object, and, in a separate thread, creates a structured clone of the value
, and stores the cloned value in the object store. If the record is successfully stored, then a success event is fired on the returned request object, using the IDBTransactionEvent interface, with the result
set to the key for the stored record, and transaction
set to the transaction in which this object store is opened.
IDBRequest put( in any value, in optional any key ) raises (IDBDatabaseException, DOMException);
Parameters
- value
- The value to be stored.
- key
- The key to use to identify the record. If unspecified, it results to null.
Returns
- IDBRequest
- A request object on which subsequent events related to this operation are fired.
Exceptions
This method can raise an IDBDatabaseException with the following codes:
- If this object store uses out-of-line keys and does not use a key generator, but the
key
parameter was not passed - If the object store uses in-line keys, but the
value
object does not have a property identified by the object store's key path.
NOT_ALLOWED_ERR
READ_ONLY
or SNAPSHOT_READ
.SERIAL_ERR
This method can raise a DOMException with the following code:
DATA_CLONE_ERR
- If the data being stored could not be cloned by the internal structured cloning algorithm.
Browser compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | 12 | 4.0 (2.0) | -- | -- | -- |
count() | ? | 10.0 (10.0) | -- | -- | -- |
Feature | Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|
Basic support | -- | 6.0 (6.0) | -- | -- | -- |
count() | -- | ? | -- | -- | -- |