IDBKeyRange

IndexedDB API の IDBKeyRange インターフェイスは、キーとして使われるデータ型における 1 個の連続した範囲を表します。IDBObjectStore および IDBIndex のオブジェクトから、キーまたはキーの範囲を用いてレコードを取り出すことができます。下限および上限により、範囲を制限できます。たとえば、キーが A 〜 Z の範囲にある全ての値を反復できます。

キーの範囲は、単一の値、もしくは上限および下限 (端点ともいう) をもつ範囲になり得ます。キーの範囲が上限と下限の両方を持つ場合、有界 と呼びます。境界が無い場合、非有界 と呼びます。有界のキーの範囲は、開 (端点を含まない) にも閉 (端点を含む) にもなり得ます。特定の範囲のキーを全て取得するには、以下のコードの構成を用いることができます。

範囲 コード
≥ x の全キー IDBKeyRange.lowerBound (x)
> x の全キー IDBKeyRange.lowerBound (x, true)
≤ y の全キー IDBKeyRange.upperBound (y)
< y の全キー IDBKeyRange.upperBound (y, true)
≥ x && ≤ y の全キー IDBKeyRange.bound (x, y)
> x && < y の全キー IDBKeyRange.bound (x, y, true, true)
> x && ≤ y の全キー IDBKeyRange.bound (x, y, true, false)
≥ x && < y の全キー IDBKeyRange.bound (x, y, false, true)
特定のキー = z IDBKeyRange.only (z)

キーは、以下の条件を満たすとき、キーの範囲に含まれます。

  • キーの範囲の lower の値が、以下のいずれかである
    • undefined
    • キーの値より小さい
    • lowerOpen が false であり、キーの値と等しい
  • キーの範囲の upper の値が、以下のいずれかである
    • undefined
    • キーの値より大きい
    • upperOpen が false であり、キーの値と等しい

注: この機能は Web Worker 内で利用可能です。

インスタンスプロパティ

IDBKeyRange.lower 読取専用

キーの範囲の下限です。

IDBKeyRange.upper 読取専用

キーの範囲の上限です。

IDBKeyRange.lowerOpen 読取専用

下限の値がキーの範囲に含まれるとき、false を返します。

IDBKeyRange.upperOpen 読取専用

上限の値がキーの範囲に含まれるとき、false を返します。

静的メソッド

IDBKeyRange.bound()

上限と下限を持つ新しいキーの範囲を生成します。

IDBKeyRange.only()

単一の値のみからなる新しいキーの範囲を生成します。

IDBKeyRange.lowerBound()

下限のみを持つ新しいキーの範囲を生成します。

IDBKeyRange.upperBound()

上限のみを持つ新しいキーの範囲を生成します。

インスタンスメソッド

IDBKeyRange.includes()

指定されたキーがこのキーの範囲に含まれるかを表す boolean を返します。

例

以下の例で、キーの範囲の使い方を示します。"A" と "F" の間の値を表す範囲として keyRangeValue を定義します。(IDBTransaction を用いて) トランザクションを開き、オブジェクトストアを開き、IDBObjectStore.openCursor を用いてカーソルを開きます。このとき、省略可能なキーの範囲の値として keyRangeValue を指定します。これにより、このカーソルはこの範囲に含まれるキーを持つレコードのみを取り出します。開区間にするよう指定していないので、この範囲は値 "A" および "F" を含みます。IDBKeyRange.bound("A", "F", true, true); を使った場合は、"A" と "F" は範囲に含まれず、その間の値のみが含まれます。

メモ: キーの範囲に関する実験ができるより完全な例は、IDBKeyRange-example レポジトリを参照してください。(動く例も見る)

js
function displayData() {
  const keyRangeValue = IDBKeyRange.bound("A", "F");

  const transaction = db.transaction(["fThings"], "readonly");
  const objectStore = transaction.objectStore("fThings");

  objectStore.openCursor(keyRangeValue).onsuccess = (event) => {
    const cursor = event.target.result;
    if (cursor) {
      const listItem = document.createElement("li");
      listItem.textContent = `${cursor.value.fThing}, ${cursor.value.fRating}`;
      list.appendChild(listItem);

      cursor.continue();
    } else {
      console.log("全エントリーを表示しました。");
    }
  };
}

仕様書

Specification
Indexed Database API 3.0
# keyrange

ブラウザーの互換性

BCD tables only load in the browser

関連情報