IDBObjectStore: put() メソッド

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2021.

IDBObjectStore インターフェイスの put() メソッドは、データベース内の指定のレコードを更新するか、指定のアイテムが存在しない場合は新規レコードを挿入します。

このメソッドは IDBRequest オブジェクトを返し、別スレッドで、値の構造化複製を作成し、この複製をオブジェクトストアに格納します。これは、トランザクションモードが readwrite のとき、オブジェクトストアに新規レコードを追加するか既存レコードを更新する用です。レコードが正常に格納されると、返された要求オブジェクトで、result が格納されたレコードのキーに設定され、transaction がオブジェクトストアが開かれたトランザクションに設定された success イベントが発火します。

put メソッドは 更新または挿入を行う メソッドです。 挿入のみを行う メソッドは、IDBObjectStore.add メソッドを参照してください。

更新したいレコードを指す IDBCursor があるときは、IDBObjectStore.put() を用いるよりも IDBCursor.update() で更新を行うほうがよいことを覚えておいてください。そうすることで、新規レコードを挿入するのではなく、既存のレコードを更新することが明確になります。

メモ: この機能はウェブワーカー内で利用可能です。

構文

js
put(item)
put(item, key)

引数

item

更新 (または挿入) を行いたいアイテムです。

key 省略可

更新したいレコードの主キーです。(たとえば IDBCursor.primaryKey から取得できます)

返値

この操作に関係する今後のイベントが発火する IDBRequest オブジェクトです。

操作に成功した場合は、この要求の result プロパティの値は新しいレコードのキーまたは更新したレコードのキーになります。

例外

このメソッドは、以下の種類のいずれかの DOMException を投げる可能性があります。

ReadOnlyError DOMException

この操作に対応するトランザクションが読み取り専用モードのとき投げられます。

TransactionInactiveError DOMException

この IDBObjectStore のトランザクションが実行中でないとき投げられます。

DataError DOMException

以下のいずれかの条件を満たすとき投げられます。

  • オブジェクトストアでインラインキーを使用しているかキージェネレーターが存在し、かつ引数 key が指定されたとき。
  • オブジェクトストアがアウトラインキーを用いかつキージェネレーターも存在せず、引数 key が指定されないとき。
  • オブジェクトストアがインラインキーを用いているが key ジェネレーターは存在せず、オブジェクトストアのキーパスが有効なキーを生成しないとき。
  • 引数 key が指定されたが、有効なキーでないとき。
InvalidStateError DOMException

IDBObjectStore が削除されたか取り除かれたとき投げられます。

DataCloneError DOMException

保存されるデータが内部の構造化複製アルゴリズムで複製できなかったとき投げられます。

例

以下の例では、レコードタイトルを指定した要求を行います。要求に成功すると、onsuccess 関数で (objectStoreTitleRequest.result から利用可能な) IDBObjectStore から対応するレコードを取得し、レコードのプロパティ 1 個を更新し、更新したレコードを put() を用いた別の要求によりオブジェクトストアに書き戻します。動く例全体は、To-do Notifications アプリケーションを参照してください。(動く例を見る)

js
const title = "Walk dog";

// いつも通りトランザクションを開く
const objectStore = db
  .transaction(["toDoList"], "readwrite")
  .objectStore("toDoList");

// タイトルがこの title である to-do リストのオブジェクトを取得する
const objectStoreTitleRequest = objectStore.get(title);

objectStoreTitleRequest.onsuccess = () => {
  // 結果として返されたデータオブジェクトを取得する
  const data = objectStoreTitleRequest.result;

  // オブジェクトの notified の値を "yes" に更新する
  data.notified = "yes";

  // アイテムをデータベースに書き戻す別の要求を生成する
  const updateTitleRequest = objectStore.put(data);

  // この要求を開始したトランザクションを記録する
  console.log(
    `この要求を開始したトランザクションは ${updateTitleRequest.transaction}`,
  );

  // 新しい要求が成功したら、再び displayData() 関数を実行し、表示を更新する
  updateTitleRequest.onsuccess = () => {
    displayData();
  };
};

仕様書

Specification
Indexed Database API 3.0
# ref-for-dom-idbobjectstore-put①

ブラウザーの互換性

BCD tables only load in the browser

関連情報