IDBCursor

IndexedDB API の IDBCursor インターフェイスはデータベースの複数レコードを横断したり繰り返すためのカーソルです。

このカーソルはどのインデックスやオブジェクトをループしているかを示す元です。これは範囲内の位置を示し、レコードのキー順に増/減して動きます。カーソルはアプリケーションからカーソル範囲内の全レコードに非同期に処理できるようにします。

一度に無制限の数のカーソルを持つことができます。あるカーソルを表す同一の IDBCursor オブジェクトを取得できます。操作はインデックスやオブジェクトストアに対して実行されます。

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

インスタンスプロパティ

IDBCursor.source 読取専用

カーソルが繰り返しているIDBObjectStore か IDBIndex を返します。この関数は、カーソルが現在繰り返されていたり、繰り返しが終わりを過ぎたり、トランザクションがアクティブでなくても、null や例外を返しません。

IDBCursor.direction 読取専用

カーソルの横断の向きを返します。取りうる値については定数を見てください。

IDBCursor.key 読取専用

カーソル位置のレコードのキーを返します。カーソルが範囲外の場合、undefined にセットされます。カーソルキーはあらゆるデータ型となりえます。

IDBCursor.value 読取専用

カーソル位置のレコードの値を返します。カーソルの値はあらゆるデータ型となりえます。

IDBCursor.primaryKey 読取専用

カーソルの現在有効な主キーを返します。カーソルが現在繰り返されていたり範囲外で繰り返されていた場合、これは undefined にセットされます。カーソルの主キーはあらゆるデータ型となりえます。

インスタンスメソッド

IDBCursor.advance()

カーソルが位置を前進させる回数を設定します。

IDBCursor.continue()

カーソルを現在の方向の次の位置、省略可能な key 引数に当てはまるアイテムに進めます。

IDBCursor.continuePrimaryKey()

カーソルを引数で与えられたインデックスキーと主キーに従って設定します。

IDBCursor.delete()

IDBRequest オブジェクトを返し、別のスレッドでカーソルの位置を変えずにカーソルの位置にあるレコードを削除します。これは、特定のレコードを削除するのに使用できます。

IDBCursor.update()

IDBRequest オブジェクトを返し、別のスレッドでオブジェクトストア内のカーソルの現在の位置にある値を更新します。これは、特定のレコードを更新するのに使用できます。

定数

gecko 13: この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

警告: これらの定数は利用できません。Gecko 25 で削除されました。代わりに文字列定数を直接使う必要があります。(Firefox バグ 891944)

  • NEXT: "next" : カーソルは重複を含む全てのレコードを提示します。キーの範囲の下限から開始し、上方向に動きます。(キーの順番に単調増加します)
  • NEXTUNIQUE : "nextunique" : カーソルは重複を除いた全てのレコードを提示します。同じキーを持つ複数のレコードが存在する場合、走査の順で最初のレコードのみを取得できます。キーの範囲の下限から開始し、上方向に動きます。
  • PREV: "prev" : カーソルは重複を含む全てのレコードを提示します｡キーの範囲の上限から開始し､下方向に動きます｡(キーの順番に単調減少します)
  • PREVUNIQUE: "prevunique" : カーソルは重複を除いた全てのレコードを提示します｡同じキーを持つ複数のレコードが存在する場合､走査の順で最初のレコードのみを取得できます｡キーの範囲の上限から開始し､下方向に動きます｡

例

この単純なコードスニペットでは、トランザクションを生成し、オブジェクトストアを取得し、そしてカーソルを用いてオブジェクトストア内の全レコードを走査します。カーソルを使う場合、データをキーを用いて選択する必要はなく、単に全部を取得できます。ループにおけるそれぞれの繰り返しにおいて、カーソルオブジェクトの現在のレコードから cursor.value.foo でデータを取り出せることにも注目してください。動く例全体は、IDBCursor example を参照してください。(動く例を見る)

function displayData() {
  var transaction = db.transaction(['rushAlbumList'], "readonly");
  var objectStore = transaction.objectStore('rushAlbumList');

  objectStore.openCursor().onsuccess = function(event) {
    var cursor = event.target.result;
    if(cursor) {
      var listItem = document.createElement('li');
      listItem.innerHTML = cursor.value.albumTitle + ', ' + cursor.value.year;
      list.appendChild(listItem);

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

仕様書

Specification
Indexed Database API 3.0
# cursor-interface

ブラウザーの互換性

BCD tables only load in the browser

関連情報