mozilla

Revision 63630 of IDBObjectStore

  • Revision slug: IndexedDB/IDBObjectStore
  • Revision title: IDBObjectStore
  • Revision id: 63630
  • Created:
  • Creator: soswow
  • Is current revision? No
  • Comment one or more formatting changes

Revision Content

{{ gecko_minversion_header("2") }}

The IDBObjectStore interface of the IndexedDB API represents an object store in a database.

Method overview

IDBRequest add (in any value, in optional any key) raises (IDBDatabaseException, DOMException);
IDBRequest clear () 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.

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

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 optional boolean unique
) raises (IDBDatabaseException);

Parameters
name
The name of the index to create.
keyPath
The key path for the index to use.
unique
If true, the index must not allow duplicate values for a single key.
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 the value of the removed record, 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:

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 or SNAPSHOT_READ.
TRANSACTION_INACTIVE_ERR
If the associated transaction is not active.

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

 

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.

{{ Note("This function produces the same result if no record with the given key exists in the database as when a record exists, but with an undefined value. To tell these situations apart, call the openCursor() method with the same key. That method provides a cursor if the record exists, and not if it does not.") }}

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:

DATA_ERR
  • 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
If the object store is not in the scope of any existing transaction, or if the associated transaction's mode is READ_ONLY or SNAPSHOT_READ.
SERIAL_ERR
If the data being stored could not be serialized by the internal structured cloning algorithm.

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.

Revision Source

<p>{{ gecko_minversion_header("2") }}</p>
<p>The <code>IDBObjectStore</code> interface of the <a href="/en/IndexedDB" title="en/IndexedDB">IndexedDB API</a> represents an <a href="/en/IndexedDB#gloss_object_store" title="en/IndexedDB#gloss object store">object store</a> in a database.</p>
<h2>Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#add" title="#add">add</a> (in any value, in optional any key) raises (<a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a>, <a href="/En/DOM/DOMException" title="en/DOM/DOMException">DOMException</a>);<br> </code></td> </tr> <tr> <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#clear" title="#clear">clear</a> () raises (<a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a>);</code></td> </tr> <tr> <td><code><a href="/en/IndexedDB/IDBIndex" title="en/IndexedDB/IDBIndex">IDBIndex</a> <a href="#createIndex" title="#createIndex">createIndex</a>  (in <a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a> name, in </code><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code><code> keyPath, in optional boolean unique) raises (<a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a>);<br> </code></td> </tr> <tr> <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#delete" title="#delete">delete</a> (in any key) raises (</code><code><a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a></code><code>);</code></td> </tr> <tr> <td><code>void <a href="#deleteIndex" title="#deleteIndex">deleteIndex</a> (in any </code><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code><code> indexName) raises (<a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a>);</code></td> </tr> <tr> <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#get" title="#get">get</a> (in any key) raises (<a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a>);<br> </code></td> </tr> <tr> <td><code><a href="/en/IndexedDB/IDBIndex" title="en/IndexedDB/IDBIndex">IDBIndex</a> <a href="#index" title="#index">index</a> (in </code><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code><code> name) raises (<a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a>);<br> </code></td> </tr> <tr> <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#openCursor" title="#openCursor">openCursor</a> (in optional <a href="/en/IndexedDB/IDBKeyRange" title="en/IndexedDB/IDBKeyRange">IDBKeyRange</a> range, in optional unsigned short direction) raises (<a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a>);<br> </code></td> </tr> <tr> <td><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> <a href="#put" title="#put">put</a> (in any value, in optional any key) raises (<a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a>, <a href="/En/DOM/DOMException" title="en/DOM/DOMException">DOMException</a>);<br> </code></td> </tr> </tbody>
</table>
<h2>Attributes</h2>
<table class="standard-table"> <thead> <tr> <th scope="col">Attribute</th> <th scope="col">Type</th> <th scope="col">Description</th> </tr> </thead> <tbody> <tr> <td><code><a name="attr_indexNames">indexNames</a><br> </code></td> <td><code>readonly DOMStringList<br> </code></td> <td>A list of the names of <a href="/en/IndexedDB#gloss_index" title="en/IndexedDB#gloss index">indexes</a> on objects in this object store.</td> </tr> <tr> <td><code><a name="attr_keyPath">keyPath</a><br> </code></td> <td><code>readonly </code><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code></td> <td>The <a href="/en/IndexedDB#gloss_key_path" title="en/IndexedDB#gloss key path">key path</a> of this object store. If this attribute is null, the application must provide a key for each modification operation.</td> </tr> <tr> <td><code><a name="attr_name">name</a><br> </code></td> <td><code>readonly </code><code><a href="/En/DOM/DOMString" title="en/DOM/DOMString">DOMString</a></code></td> <td>The name of this object store.</td> </tr> </tbody>
</table>
<h2>Methods</h2>
<h3 name="add">add()</h3>
<p>Returns an <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> object, and, in a separate thread, creates a <a class=" external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#structured-clone" title="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#structured-clone">structured clone</a> of the <code>value</code>, 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 <a href="/en/IndexedDB/IDBTransactionEvent" title="en/IndexedDB/IDBTransactionEvent">IDBTransactionEvent</a> interface, with the <code><a href="/en/IndexedDB/IDBSuccessEvent#attr_result" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a></code> set to the key for the stored record, and <code><a href="/en/IndexedDB/IDBTransactionEvent#attr_transaction" title="en/IndexedDB/IDBTransactionEvent#attr transaction">transaction</a></code> set to the transaction in which this object store is opened. If a record already exists in the object store with the <code>key</code> parameter as its key, then an error event is fired on the returned request object, with <a href="/en/IndexedDB/IDBErrorEvent#attr_code" title="en/IndexedDB/IDBErrorEvent#attr code">code</a> set to <code><a href="/en/IndexedDB/IDBDatabaseException#CONSTRAINT_ERR" title="en/IndexedDB/DatabaseException#CONSTRAINT ERR">CONSTRAINT_ERR</a></code>.</p>
<pre>IDBRequest add(
  in any value,
  in optional any key
) raises (IDBDatabaseException, DOMException);
</pre>
<h5>Parameters</h5>
<dl> <dt>value</dt> <dd>The value to be stored.</dd> <dt>key</dt> <dd>The key to use to identify the record. If unspecified, it results to null.</dd>
</dl>
<h5>Returns</h5>
<dl> <dt><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></dt> <dd>A request object on which subsequent events related to this operation are fired.</dd>
</dl>
<h5>Exceptions</h5>
<p>This method can raise an <a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a> with the following codes:</p>
<dl> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#DATA_ERR" title="en/IndexedDB/DatabaseException#DATA ERR">DATA_ERR</a></code></dt> <dd>If the object store uses in-line keys or has a key generator, and a key parameter was provided.<br> If the object store uses out-of-line keys and has no key generator, and no key parameter was provided.<br> 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.<br> If the key parameter was provided but does not contain a valid key.<br> 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.</dd> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#READ_ONLY_ERR" title="en/IndexedDB/IDBDatabaseException#READ ONLY ERR">READ_ONLY_ERR</a></code></dt> <dd>If the mode of the associated transaction is <code><a href="/en/IndexedDB/IDBTransaction#READ_ONLY" title="en/IndexedDB/IDBTransaction#READ ONLY">READ_ONLY</a></code>.</dd> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#TRANSACTION_INACTIVE_ERR" title="en/IndexedDB/IDBDatabaseException#TRANSACTION INACTIVE ERR">TRANSACTION_INACTIVE_ERR</a></code></dt> <dd>If the associated transaction is not active.</dd>
</dl>
<p>This method can raise a <a href="/En/DOM/DOMException" title="en/DOM/DOMException">DOMException</a> with the following code:</p>
<dl> <dt><code>DATA_CLONE_ERR</code></dt> <dd>If the data being stored could not be cloned by the internal structured cloning algorithm.</dd>
</dl>
<dl> <h3 name="clear">clear()</h3>
<p>If the mode of the transaction that this object store belongs to is <code><a href="/en/IndexedDB/IDBTransaction#READ_ONLY" title="en/IndexedDB/IDBTransaction#READ ONLY">READ_ONLY</a></code>, this method raises an <a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a> with its code set to <code><a href="/en/IndexedDB/IDBDatabaseException#READ_ONLY_ERR" title="en/IndexedDB/IDBDatabaseException#READ ONLY ERR">READ_ONLY_ERR</a></code>. Otherwise, this method creates and immediately returns an <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> 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.</p>
<pre>void clear(
) raises (IDBDatabaseException); 
</pre>
<h5>Returns</h5>
<dl> <dt><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></dt> <dd>A request object on which subsequent events related to this operation are fired.</dd>
</dl>
<h5>Exceptions</h5>
<p>This method can raise an <a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a> with the following codes:</p>
<dl> <dt><a href="/en/IndexedDB/IDBDatabaseException#READ_ONLY_ERR" title="en/IndexedDB/IDBDatabaseException#READ ONLY ERR"><code>READ_ONLY_ERR</code></a></dt> <dd>If the mode of the transaction that this object store belongs to is READ_ONLY.</dd> <dt><a href="/en/IndexedDB/IDBDatabaseException#TRANSACTION_INACTIVE_ERR" title="en/IndexedDB/IDBDatabaseException#TRANSACTION INACTIVE ERR"><code>TRANSACTION_INACTIVE_ERR</code></a></dt> <dd>If the transaction that this object store belongs to is not active.</dd>
</dl><h3 name="createIndex">createIndex()</h3> <p>Creates and returns a new index in the connected database. Note that this method must be called only from a <a href="/en/IndexedDB/IDBTransaction#VERSION_CHANGE" title="en/IndexedDB/IDBTransaction#VERSION CHANGE"><code>VERSION_CHANGE</code></a> transaction callback.</p> <pre>IDBIndex createIndex (
  in DOMString name, 
  in DOMString keyPath, 
  in optional boolean unique
) raises (IDBDatabaseException);

</pre> <h5>Parameters</h5> <dl> <dt>name</dt> <dd>The name of the index to create.</dd> <dt>keyPath</dt> <dd>The key path for the index to use.</dd> <dt>unique</dt> <dd>If true, the index must not allow duplicate values for a single key.</dd> <h5>Returns</h5> <dt><a href="/en/IndexedDB/IDBIndex" title="en/IndexedDB/IDBIndex">IDBIndex</a></dt> <dd>The newly created index.</dd> </dl> <h5>Exceptions</h5> <p>This method can raise an <a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a> with the following codes:</p> <dl> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#CONSTRAINT_ERR" title="en/IndexedDB/DatabaseException#CONSTRAINT ERR">CONSTRAINT_ERR</a></code></dt> <dd>If an index with the same name (based on case-sensitive comparison) already exists in the connected database.</dd> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#NOT_ALLOWED_ERR" title="en/IndexedDB/DatabaseException#NOT ALLOWED ERR">NOT_ALLOWED_ERR</a></code></dt> <dd>If this method was not called from a <a href="/en/IndexedDB/IDBTransaction#VERSION_CHANGE" title="en/IndexedDB/IDBTransaction#VERSION CHANGE"><code>VERSION_CHANGE</code></a> transaction callback.</dd> </dl> <h3 name="delete">delete()</h3>
<p>Immediately returns an <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> 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><a href="/en/IndexedDB/IDBErrorEvent#attr_code" title="en/IndexedDB/IDBErrorEvent#attr code">code</a></code> set to <code><a href="/en/IndexedDB/IDBDatabaseException#NOT_FOUND_ERR" title="en/IndexedDB/IDBDatabaseException#NOT FOUND ERR">NOT_FOUND_ERR</a></code> and an appropriate <code><a href="/en/IndexedDB/IDBErrorEvent#attr_message" title="en/IndexedDB/IDBErrorEvent#attr message">message</a></code>. If the record is successfully removed, then a success event is fired on the returned request object, using the <a href="/en/IndexedDB/IDBTransactionEvent" title="en/IndexedDB/IDBTransactionEvent">IDBTransactionEvent</a> interface, with the <a href="/en/IndexedDB/IDBSuccessEvent#attr_result" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a> set to the value of the removed record, and <a href="/en/IndexedDB/IDBTransactionEvent#attr_transaction" title="en/IndexedDB/IDBTransactionEvent#attr transaction">transaction</a> set to the transaction in which this object store is opened.</p>
<pre>IDBRequest delete (
  in any key
) raises (IDBDatabaseException); 
</pre>
<h5>Parameters</h5>
<dl> <dt>key</dt> <dd>The key to use to identify the record.</dd>
</dl>
<h5>Returns</h5>
<dl> <dt><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></dt> <dd>A request object on which subsequent events related to this operation are fired.</dd>
</dl>
<h5>Exceptions</h5>
<p>This method can raise an <a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a> with the following codes:</p>
<dl> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#NOT_ALLOWED_ERR" title="en/IndexedDB/DatabaseException#NOT ALLOWED ERR">NOT_ALLOWED_ERR</a></code></dt> <dd>If the object store is not in the <a href="/en/IndexedDB#gloss_scope" title="en/IndexedDB#gloss scope">scope</a> of any existing <a href="/en/IndexedDB#gloss_transaction" title="en/IndexedDB#gloss transaction">transaction</a>, or if the associated transaction's mode is <a href="/en/IndexedDB/IDBTransaction#const_read_only" title="en/IndexedDB/IDBTransaction#const read only"><code>READ_ONLY</code></a> or <a href="/en/IndexedDB/IDBTransaction#const_snapshot_read" title="en/IndexedDB/IDBTransaction#const snapshot read"><code>SNAPSHOT_READ</code></a>.</dd> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#TRANSACTION_INACTIVE_ERR" title="en/IndexedDB/IDBDatabaseException#TRANSACTION INACTIVE ERR">TRANSACTION_INACTIVE_ERR</a></code></dt> <dd>If the associated transaction is not active.</dd> <h3 name="deleteIndex">deleteIndex()</h3>
<p>Destroys the index with the specified name in the connected database. Note that this method must be called only from a <code><a href="/en/IndexedDB/IDBTransaction#VERSION_CHANGE" title="en/IndexedDB/IDBTransaction#VERSION CHANGE">VERSION_CHANGE</a></code> transaction callback.</p>
<pre>void removeIndex(
  in DOMString indexName
) raises (IDBDatabaseException); 
</pre>
<h5>Parameters</h5>
<p>
 </p><dt>indexName</dt>
<dd>The name of the existing index to remove.</dd>
</dl>
<h5>Exceptions</h5>
<p>This method can raise an <a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a> with the following codes:</p>
<dl> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#NOT_ALLOWED_ERR" title="en/IndexedDB/DatabaseException#NOT ALLOWED ERR">NOT_ALLOWED_ERR</a></code></dt> <dd>If this method was not called from a <a href="/en/IndexedDB/IDBTransaction#VERSION_CHANGE" title="en/IndexedDB/IDBTransaction#VERSION CHANGE">VERSION_CHANGE</a> transaction callback.</dd> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#NOT_FOUND_ERR" title="en/IndexedDB/IDBDatabaseException#NOT FOUND ERR">NOT_FOUND_ERR</a></code></dt> <dd>If no index exists with the specified name (based on case-sensitive comparison) in the connected database.</dd>
</dl>
<h3 name="get">get()</h3>
<p>Immediately returns an <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> 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 <a href="/en/IndexedDB/IDBTransactionEvent" title="en/IndexedDB/IDBTransactionEvent">IDBTransactionEvent</a> interface, with its <code><a href="/en/IndexedDB/IDBSuccessEvent#attr_result" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a></code> set to the retrieved value, and <code><a href="/en/IndexedDB/IDBTransactionEvent#attr_transaction" title="en/IndexedDB/IDBTransactionEvent#attr transaction">transaction</a></code> 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><a href="/en/IndexedDB/IDBErrorEvent#attr_code" title="en/IndexedDB/IDBErrorEvent#attr code">code</a></code> set to <code><a href="/en/IndexedDB/IDBDatabaseException#NOT_FOUND_ERR" title="en/IndexedDB/IDBDatabaseException#NOT FOUND ERR">NOT_FOUND_ERR</a></code> and an appropriate <code><a href="/en/IndexedDB/IDBErrorEvent#attr_message" title="en/IndexedDB/IDBErrorEvent#attr message">message</a></code>.</p>
<p>{{ Note("This function produces the same result if no record with the given key exists in the database as when a record exists, but with an <code>undefined</code> value. To tell these situations apart, call the openCursor() method with the same key. That method provides a cursor if the record exists, and not if it does not.") }}</p>
<pre>IDBRequest get(
  in any key
) raises (IDBDatabaseException);
</pre>
<h5>Parameters</h5>
<dl> <dt>key</dt> <dd>The key identifying the record to retrieve.</dd>
</dl>
<h5>Returns</h5>
<dl> <dt><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></code></dt> <dd>A request object on which subsequent events related to this operation are fired.</dd>
</dl>
<h5>Exceptions</h5>
<p>This method can raise an <a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a> with the following code:</p>
<dl> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#DATA_ERR" title="en/IndexedDB/IDBDatabaseException#DATA ERR">DATA_ERR</a></code></dt> <dd>If the <code>key</code> parameter was not a valid value.</dd> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#TRANSACTION_INACTIVE_ERR" title="en/IndexedDB/IDBDatabaseException#TRANSACTION INACTIVE ERR">TRANSACTION_INACTIVE_ERR</a></code></dt> <dd>If the associated transaction is not active.</dd>
</dl><h3 name="index">index()</h3>
<p>Opens the named index in this object store.</p>
<pre>IDBIndex index(
  in DOMString name
) raises (IDBDatabaseException);
</pre>
<h5>Parameters</h5>
<dl> <dt>name</dt> <dd>The name of the index to open.</dd>
</dl>
<h5>Returns</h5>
<dl> <dt><code><a href="/en/IndexedDB/IDBIndex" title="en/IndexedDB/IDBIndex">IDBIndex</a></code></dt> <dd>An object for accessing the index.</dd>
</dl>
<h5>Exceptions</h5>
<p>This method can raise an <a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a> with the following code:</p>
<dl> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#NOT_FOUND_ERR" title="en/IndexedDB/IDBDatabaseException#NOT FOUND ERR">NOT_FOUND_ERR</a></code></dt> <dd>If no index exists with the specified name (based on case-sensitive comparison) in the connected database.</dd>
</dl>
<h3 name="openCursor">openCursor()</h3>
<p>Immediately returns an <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> object, and creates a <a href="/en/IndexedDB#gloss_cursor" title="en/IndexedDB#gloss cursor">cursor</a> over the records in this object store, in a separate thread. If there is even a single record that matches the <a href="/en/IndexedDB#gloss_key_range" title="en/IndexedDB#gloss key range">key range</a>, then a success event is fired on the returned object, with its <code><a href="/en/IndexedDB/IDBSuccessEvent#attr_result" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a></code> set to the <a href="/en/IndexedDB/IDBCursor" title="en/IndexedDB/IDBCursor">IDBCursor</a> object for the new cursor. If no records match the key range, then a success event is fired on the returned object, with its <code><a href="/en/IndexedDB/IDBSuccessEvent#attr_result" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a></code> set to null.</p>
<pre>IDBRequest openCursor (
  in optional IDBKeyRange range, 
  in optional unsigned short direction
) raises (IDBDatabaseException);
</pre>
<h5>Parameters</h5>
<dl> <dt>range</dt> <dd>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.</dd> <dt>direction</dt> <dd>The cursor's <a href="/en/IndexedDB#gloss_direction" title="en/IndexedDB#gloss direction">direction</a>.</dd>
</dl>
<h5>Returns</h5>
<dl> <dt><code><a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a></code></dt> <dd>A request object on which subsequent events related to this operation are fired.</dd>
</dl>
<h5>Exceptions</h5>
<p>This method can raise an IDBDatabaseException with the following code:</p>
<dl> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#NOT_ALLOWED_ERR" title="en/IndexedDB/DatabaseException#NOT ALLOWED ERR">NOT_ALLOWED_ERR</a></code></dt> <dd>If this object store is not in the scope of any existing transaction on the connected database.</dd>
</dl>
<h3 name="put">put()</h3>
<p>Returns an <a href="/en/IndexedDB/IDBRequest" title="en/IndexedDB/IDBRequest">IDBRequest</a> object, and, in a separate thread, creates a <a class=" external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#structured-clone" title="http://www.whatwg.org/specs/web-apps/current-work/multipage/urls.html#structured-clone">structured clone</a> of the <code>value</code>, 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 <a href="/en/IndexedDB/IDBTransactionEvent" title="en/IndexedDB/IDBTransactionEvent">IDBTransactionEvent</a> interface, with the <code><a href="/en/IndexedDB/IDBSuccessEvent#attr_result" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a></code> set to the key for the stored record, and <code><a href="/en/IndexedDB/IDBTransactionEvent#attr_transaction" title="en/IndexedDB/IDBTransactionEvent#attr transaction">transaction</a></code> set to the transaction in which this object store is opened.</p>
<pre>IDBRequest put(
  in any value,
  in optional any key
) raises (IDBDatabaseException, DOMException);
</pre>
<h5>Parameters</h5>
<dl> <dt>value</dt> <dd>The value to be stored.</dd> <dt>key</dt> <dd>The key to use to identify the record. If unspecified, it results to null.</dd>
</dl>
<h5>Returns</h5>
<dl> <dt>IDBRequest</dt> <dd>A request object on which subsequent events related to this operation are fired.</dd>
</dl>
<h5>Exceptions</h5>
<p>This method can raise an <a href="/en/IndexedDB/IDBDatabaseException" title="en/IndexedDB/IDBDatabaseException">IDBDatabaseException</a> with the following codes:</p>
<dl> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#DATA_ERR" title="en/IndexedDB/DatabaseException#DATA ERR">DATA_ERR</a></code></dt> <ul> <li>If this object store uses <a href="/en/IndexedDB#gloss_out-of-line_key" title="en/IndexedDB#gloss out-of-line key">out-of-line keys</a> and does not use a <a href="/en/IndexedDB#gloss_key_generator" title="en/IndexedDB#gloss key generator">key generator</a>, but the <code>key</code> parameter was not passed</li> <li>If the object store uses <a href="/en/IndexedDB#gloss_in-line_key" title="en/IndexedDB#gloss in-line key">in-line keys</a>, but the <code>value</code> object does not have a property identified by the object store's key path.</li> </ul> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#NOT_ALLOWED_ERR" title="en/IndexedDB/DatabaseException#NOT ALLOWED ERR">NOT_ALLOWED_ERR</a></code></dt> <dd>If the object store is not in the <a href="/en/IndexedDB#gloss_scope" title="en/IndexedDB#gloss scope">scope</a> of any existing <a href="/en/IndexedDB#gloss_transaction" title="en/IndexedDB#gloss transaction">transaction</a>, or if the associated transaction's mode is <a href="/en/IndexedDB/IDBTransaction#const_read_only" title="en/IndexedDB/IDBTransaction#const read only"><code>READ_ONLY</code></a> or <a href="/en/IndexedDB/IDBTransaction#const_snapshot_read" title="en/IndexedDB/IDBTransaction#const snapshot read"><code>SNAPSHOT_READ</code></a>.</dd> <dt><code><a href="/en/IndexedDB/IDBDatabaseException#SERIAL_ERR" title="en/IndexedDB/IDBDatabaseException#SERIAL ERR">SERIAL_ERR</a></code></dt> <dd>If the data being stored could not be serialized by the internal structured cloning algorithm.</dd>
</dl>
<p>This method can raise a <a href="/En/DOM/DOMException" title="en/DOM/DOMException">DOMException</a> with the following code:</p>
<dl> <dt><code>DATA_CLONE_ERR</code></dt> <dd>If the data being stored could not be cloned by the internal structured cloning algorithm.</dd>
</dl></dl>
Revert to this revision