Revision 1029042 of IDBObjectStore

<p>{{APIRef("IndexedDB")}}</p>

<div>
<p>The <strong><code>IDBObjectStore</code></strong> 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.&nbsp;Records within an object store are sorted according to their keys. This sorting enables fast insertion, look-up, and ordered retrieval.</p>

<p>{{AvailableInWorkers}}</p>
</div>

<h2 id="Methods">Methods</h2>

<dl>
 <dt>{{domxref("IDBObjectStore.add()")}}</dt>
 <dd>Returns an {{domxref("IDBRequest")}} object, and, in a separate thread, creates a <a class="external" href="https://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#structured-clone">structured clone</a> of the <code>value</code>, and stores the cloned value in the object store. This is for adding new records to an object store.</dd>
 <dt>{{domxref("IDBObjectStore.clear()")}}</dt>
 <dd>Creates and immediately returns an {{domxref("IDBRequest")}} object, and clears this object store in a separate thread. This is for deleting all current records out of an object store.</dd>
 <dt>{{domxref("IDBObjectStore.delete()")}}</dt>
 <dd>returns an {{domxref("IDBRequest")}} object, and, in a separate thread, deletes the current object store. This is for deleting individual records out of an object store.</dd>
 <dt>{{domxref("IDBObjectStore.get()")}}</dt>
 <dd>Returns an {{domxref("IDBRequest")}} object, and, in a separate thread, returns the object store selected by the specified key. This is for retrieving specific records from an object store.</dd>
 <dt>{{domxref("IDBObjectStore.getAll()")}}</dt>
 <dd>Returns an {{domxref("IDBRequest")}}&nbsp;object retrieves all objects in the object store matching the specified parameter or all objects in the store if no parameters are given.</dd>
 <dt>{{domxref("IDBObjectStore.getAllKeys()")}}</dt>
 <dd>Returns an {{domxref("IDBRequest")}}&nbsp;object retrieves record keys for all objects in the object store matching the specified parameter or all objects in the store if no parameters are given.</dd>
 <dt>{{domxref("IDBObjectStore.createIndex()")}}</dt>
 <dd>Creates a new index during a version upgrade, returning a new {{domxref("IDBIndex")}} object in the connected database.</dd>
 <dt>{{domxref("IDBObjectStore.deleteIndex()")}}</dt>
 <dd>Destroys the specified index in the connected database, used during a version upgrade.</dd>
 <dt>{{domxref("IDBObjectStore.index()")}}</dt>
 <dd>Opens an index from this object store after which it can, for example, be used to return a sequence of records sorted by that index using a cursor.</dd>
 <dt>{{domxref("IDBObjectStore.put()")}}</dt>
 <dd>Returns an {{domxref("IDBRequest")}} object, and, in a separate thread, creates a <a class="external" href="https://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#structured-clone">structured clone</a> of the <code>value</code>, and stores the cloned value in the object store. This is for updating existing records in an object store when the transaction's mode is <code>readwrite</code>.</dd>
 <dt>{{domxref("IDBObjectStore.openCursor()")}}</dt>
 <dd>Returns an {{domxref("IDBRequest")}} object, and, in a separate thread, returns a new {{domxref("IDBCursorWithValue")}} object. Used for iterating through an object store by primary key with a cursor.</dd>
 <dt>{{domxref("IDBObjectStore.openKeyCursor()")}}<span style="line-height:1.5">&nbsp;</span></dt>
 <dd>Returns an {{domxref("IDBRequest")}} object, and, in a separate thread, returns a new {{domxref("IDBCursorWithValue")}}. Used for iterating through an object store with a key.</dd>
 <dt>{{domxref("IDBObjectStore.count()")}}</dt>
 <dd>Returns an {{domxref("IDBRequest")}} object, and, in a separate thread, returns the total number of records that match the provided key or {{domxref("IDBKeyRange")}}. If no arguments are provided, it returns the total number of records in the store.</dd>
</dl>

<h2 id="Properties">Properties</h2>

<dl>
 <dt>{{domxref("IDBObjectStore.indexNames")}} {{readonlyInline}}</dt>
 <dd>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.</dd>
 <dt>{{domxref("IDBObjectStore.keyPath")}} {{readonlyInline}}</dt>
 <dd>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.</dd>
 <dt>{{domxref("IDBObjectStore.name")}} {{readonlyInline}}</dt>
 <dd>The name of this object store.</dd>
 <dt>{{domxref("IDBObjectStore.transaction")}} {{readonlyInline}}</dt>
 <dd>The IDBTransaction object to which this object store belongs.</dd>
 <dt>{{domxref("IDBObjectStore.autoIncrement")}} {{readonlyInline}}</dt>
 <dd>The value of the auto increment flag for this object store.</dd>
</dl>

<dl>
</dl>

<h2 id="Example">Example</h2>

<p>This example shows a variety of different uses of ObjectStores, from updating the data structure with {{domxref("IDBObjectStore.createIndex")}}&nbsp;inside an <code>onupgradeneeded</code> function, to adding a new item to our object store with {{domxref("IDBObjectStore.add")}}. For a full working example, see our&nbsp;<a href="https://github.com/mdn/to-do-notifications/" style="line-height: 1.5;">To-do Notifications</a><span style="line-height:1.5">&nbsp;app (</span><a href="https://mdn.github.io/to-do-notifications/" style="line-height: 1.5;">view example live</a><span style="line-height:1.5">.)</span></p>

<pre class="brush: js">
// Let us open our database
var DBOpenRequest = window.indexedDB.open("toDoList", 4);

DBOpenRequest.onsuccess = function(event) {
  note.innerHTML += '&lt;li&gt;Database initialised.&lt;/li&gt;';
 
  // store the result of opening the database in the db variable.
  db = DBOpenRequest.result;
};

// This event handles the event whereby a new version of the database needs to be created
// Either one has not been created before, or a new version number has been submitted via the
// window.indexedDB.open line above
DBOpenRequest.onupgradeneeded = function(event) {
  var db = event.target.result;
 
  db.onerror = function(event) {
    note.innerHTML += '&lt;li&gt;Error loading database.&lt;/li&gt;';
  };

  // Create an objectStore for this database
 
  var objectStore = db.createObjectStore("toDoList", { keyPath: "taskTitle" });
 
  // define what data items the objectStore will contain
 
  objectStore.createIndex("hours", "hours", { unique: false });
  objectStore.createIndex("minutes", "minutes", { unique: false });
  objectStore.createIndex("day", "day", { unique: false });
  objectStore.createIndex("month", "month", { unique: false });
  objectStore.createIndex("year", "year", { unique: false });

  objectStore.createIndex("notified", "notified", { unique: false });
 
  note.innerHTML += '&lt;li&gt;Object store created.&lt;/li&gt;';
};

// Create a new item to add in to the object store
var newItem = [
&nbsp; { taskTitle: "Walk dog", hours: 19, minutes: 30, day: 24, month: 'December', year: 2013, notified: "no" }
];

// open a read/write db transaction, ready for adding the data
var transaction = db.transaction(["toDoList"], "readwrite");
    
// report on the success of opening the transaction
transaction.oncomplete = function(event) {
  note.innerHTML += '&lt;li&gt;Transaction opened for task addition.&lt;/li&gt;';
};

transaction.onerror = function(event) {
  note.innerHTML += '&lt;li&gt;Transaction not opened due to error. Duplicate items not allowed.&lt;/li&gt;';
};

// create an object store on the transaction
var objectStore = transaction.objectStore("toDoList");
// add our newItem object to the object store
var objectStoreRequest = objectStore.add(newItem[0]);        

objectStoreRequest.onsuccess = function(event) {
  note.innerHTML += '&lt;li&gt;New item added to database.&lt;/li&gt;';
}</pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('IndexedDB', '#idl-def-IDBObjectStore', 'IDBObjectStore')}}</td>
   <td>{{Spec2('IndexedDB')}}</td>
   <td>&nbsp;</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility" name="Browser_compatibility">Browser compatibility</h2>

<div>{{CompatibilityTable}}</div>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>23{{property_prefix("webkit")}}<br />
    24</td>
   <td>10 {{property_prefix("moz")}}<br />
    {{CompatGeckoDesktop("16.0")}}</td>
   <td>10, partial</td>
   <td>15</td>
   <td>7.1</td>
  </tr>
  <tr>
   <td>Available in workers</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile("37.0")}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Android Webview</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>Firefox OS</th>
   <th>IE Phone</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
   <th>Chrome for Android</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>4.4</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile("22.0")}}</td>
   <td>1.0.1</td>
   <td>10</td>
   <td>22</td>
   <td>8</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td>Available in workers</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile("37.0")}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB">Using IndexedDB</a></li>
 <li>Starting transactions: {{domxref("IDBDatabase")}}</li>
 <li>Using transactions: {{domxref("IDBTransaction")}}</li>
 <li>Setting a range of keys: {{domxref("IDBKeyRange")}}</li>
 <li>Retrieving and making changes to your data: {{domxref("IDBObjectStore")}}</li>
 <li>Using cursors: {{domxref("IDBCursor")}}</li>
 <li>Reference example: <a class="external" href="https://github.com/mdn/to-do-notifications/tree/gh-pages">To-do Notifications</a> (<a class="external" href="https://mdn.github.io/to-do-notifications/">view example live</a>.)</li>
</ul>