IDBIndex: openKeyCursor() メソッド

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.

IDBIndex インターフェイスの openKeyCursor() メソッドは、IDBRequest オブジェクトを返し、別スレッドで、指定のキー範囲をこのインデックスの順で走査するカーソルを生成します。

このメソッドは、指定された方向に基づいて、カーソルの位置を適切なキーに設定します。

キー範囲が指定されないか null の場合は、範囲は全レコードを含みます。

メモ: openKeyCursor() が返すカーソルは、IDBIndex.openCursor とは違い、参照される値を用意しません。 これにより、キーのリストをより効率よく得ることができます。

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

構文

js
openKeyCursor()
openKeyCursor(range)
openKeyCursor(range, direction)

引数

range 省略可

カーソルの範囲として使用するキーまたは IDBKeyRange です。省略した場合は、このオブジェクトストア内の全レコードを選択するキー範囲になります。

direction 省略可

カーソルの方向です。取りうる値は、IDBCursor の定数を参照してください。

返値

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

操作に成功した場合は、この要求の result プロパティの値は以下になります。

  • 与えられたクエリーにマッチする最初のレコードを指す IDBCursor オブジェクト
  • マッチするレコードが見つからない場合は null

例外

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

TransactionInactiveError DOMException

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

TypeError

引数 direction の値が無効であるとき投げられます。

DataError DOMException

与えられたキーまたはキー範囲が無効なキーを含むとき投げられます。

InvalidStateError DOMException

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

例

以下の例では、トランザクションとオブジェクトストアを開き、シンプルな連絡先データベースからインデックス lName を取得します。そして、このインデックスで openKeyCursor() によりキーカーソルを開きます。これは、返されるレコードが主キーではなくこのインデックスに基づいてソートされる以外、ObjectStore で直接 IDBObjectStore.openKeyCursor を用いてカーソルを開くのと同じように動きます。

最後に、各レコードを走査し、ラストネームと対応するレコードの主キーを HTML テーブルに挿入します。

js
function displayDataByIndex() {
  tableEntry.innerHTML = "";
  const transaction = db.transaction(["contactsList"], "readonly");
  const objectStore = transaction.objectStore("contactsList");

  const myIndex = objectStore.index("lName");

  myIndex.openKeyCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const tableRow = document.createElement("tr");
      tableRow.innerHTML =
        `<td>${cursor.key}</td>` + `<td>${cursor.primaryKey}</td>`;
      tableEntry.appendChild(tableRow);

      cursor.continue();
    } else {
      console.log("全ラストネームを表示しました。");
    }
  };
}

仕様書

Specification
Indexed Database API 3.0
# ref-for-dom-idbindex-openkeycursor①

ブラウザーの互換性

BCD tables only load in the browser

関連情報