IDBCursor.key — Eigenschaft · JavaScript-Referenz

Signatur

get IDBCursor.key

Beschreibung

IDBCursor.key gibt den Schlüssel des Datensatzes zurück, auf dem der Cursor gerade steht. Welcher Schlüssel das ist, hängt von der Quelle des Cursors ab:

Beim Öffnen auf einem IDBObjectStore (store.openCursor() bzw. store.openKeyCursor()) ist key der Primärschlüssel des Datensatzes.
Beim Öffnen auf einem IDBIndex (index.openCursor()) ist key der Indexschlüssel, also der Wert am keyPath des Index (z. B. eine E-Mail-Adresse). Den Primärschlüssel liefert dann IDBCursor.primaryKey.

Die Eigenschaft eignet sich, um beim Durchlaufen eines Stores Schlüssel zu protokollieren, Datensätze gezielt mit store.delete(cursor.primaryKey) zu bearbeiten oder Schlüsselbereiche zu gruppieren. Bei reinen Schlüssel-Cursors (openKeyCursor()) spart man sich das Laden der Werte – key und primaryKey sind dann die einzigen Daten, die man bekommt, was bei großen Datensätzen deutlich schneller ist.

Der Wert kann jeder gültige IndexedDB-Schlüsseltyp sein: number, string, Date, ArrayBuffer/typisierte Arrays oder ein Array dieser Typen (zusammengesetzte Schlüssel). Die Eigenschaft ist nur innerhalb des success-Handlers der Cursor-Anfrage sinnvoll lesbar, solange die Transaktion aktiv ist.

Rückgabewert

Typ

Beschreibung

Der Schlüssel an der aktuellen Cursor-Position. undefined, während der Cursor gerade weiterbewegt wird (nach continue()/advance(), vor dem nächsten success) oder wenn er das Ende seines Bereichs überschritten hat.

Beispiele

Alle Primärschlüssel eines Object Stores ausgeben

const request = indexedDB.open('shop', 1);

request.onupgradeneeded = () => {
  const db = request.result;
  const store = db.createObjectStore('produkte', { keyPath: 'id' });
  store.add({ id: 1, name: 'Tastatur' });
  store.add({ id: 2, name: 'Maus' });
  store.add({ id: 3, name: 'Monitor' });
};

request.onsuccess = () => {
  const db = request.result;
  const store = db.transaction('produkte', 'readonly').objectStore('produkte');

  store.openCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (!cursor) {
      console.log('Fertig');
      return;
    }
    console.log(`Schlüssel: ${cursor.key} → ${cursor.value.name}`);
    cursor.continue();
  };
};

Schlüssel: 1 → Tastatur Schlüssel: 2 → Maus Schlüssel: 3 → Monitor Fertig

Index-Cursor: key (Indexschlüssel) vs. primaryKey

// Annahme: Store 'kunden' mit keyPath 'id' und Index 'email' auf dem Feld 'email'
const listeKunden = (db) => {
  const index = db
    .transaction('kunden', 'readonly')
    .objectStore('kunden')
    .index('email');

  index.openCursor().onsuccess = (event) => {
    const cursor = event.target.result;
    if (!cursor) return;
    // key = E-Mail (Indexschlüssel), primaryKey = id
    console.log(cursor.key, '→ id', cursor.primaryKey);
    cursor.continue();
  };
};

anna@example.com → id 7 ben@example.com → id 3 carla@example.com → id 12

Schnell nur Schlüssel in einem Datumsbereich sammeln (Promise-Wrapper)

// Store 'logs' mit Date-Objekten als Primärschlüssel
const schluesselImBereich = (db, von, bis) =>
  new Promise((resolve, reject) => {
    const keys = [];
    const store = db.transaction('logs', 'readonly').objectStore('logs');
    const req = store.openKeyCursor(IDBKeyRange.bound(von, bis));

    req.onerror = () => reject(req.error);
    req.onsuccess = () => {
      const cursor = req.result;
      if (!cursor) return resolve(keys);
      keys.push(cursor.key); // Date-Objekt, Wert wird nicht geladen
      cursor.continue();
    };
  });

// Nutzung:
// const keys = await schluesselImBereich(db, new Date('2024-01-01'), new Date('2024-01-31'));
// console.log(keys.length, keys[0].toISOString());

42 2024-01-01T08:15:00.000Z

// Wichtig · Fallstricke

Index vs. Store: Auf einem Index-Cursor ist key nicht der Primärschlüssel. Wer Datensätze per store.get()/store.delete() ansprechen will, braucht cursor.primaryKey (oder direkt cursor.delete()/cursor.update()).
Timing: Nach cursor.continue() oder advance() ist key bis zum nächsten success-Ereignis undefined. Den Wert also vorher in einer Variablen sichern, wenn er danach noch gebraucht wird.
Transaktion: Cursor-Callbacks dürfen keine await-Pausen auf fremde Promises (z. B. fetch) enthalten – die Transaktion wird sonst automatisch abgeschlossen und weitere Cursor-Aufrufe werfen TransactionInactiveError.
Wurde der zugrunde liegende Store oder Index gelöscht, wirft der Zugriff eine InvalidStateError-DOMException.
Schlüssel vom Typ Date oder Array sind Objekte – für Vergleiche indexedDB.cmp(a, b) statt === verwenden.
Kompatibilität: In allen modernen Browsern und in Web Workern verfügbar; in manchen privaten Modi (ältere Safari/Firefox-Versionen) ist IndexedDB eingeschränkt.

Siehe auch

IDBCursor IDBCursor.primaryKey IDBCursor.prototype.continue() IDBCursorWithValue.value IDBObjectStore.prototype.openCursor() IDBObjectStore.prototype.openKeyCursor() IDBIndex.prototype.openCursor() IDBKeyRange