IDBIndex.keyPath — Eigenschaft · JavaScript-Referenz

Signatur

IDBIndex.keyPath

Beschreibung

Die schreibgeschützte Eigenschaft keyPath eines IDBIndex-Objekts gibt an, aus welcher Eigenschaft der gespeicherten Objekte der Index seine Schlüssel bildet. Festgelegt wird der Pfad beim Anlegen des Indexes mit IDBObjectStore.createIndex(name, keyPath, options), danach lässt er sich nicht mehr ändern.

Es gibt zwei Formen:

String: ein einfacher Name wie "email" oder ein Pfad mit Punkten wie "adresse.plz" für verschachtelte Eigenschaften.
Array von Strings: ein zusammengesetzter Index (Compound Index), z. B. ["nachname", "vorname"]. Die Indexschlüssel sind dann Arrays mit den Werten in dieser Reihenfolge.

Nützlich ist die Eigenschaft vor allem beim Untersuchen einer bestehenden Datenbank, beim Schreiben von allgemeinem Code, der mit beliebigen Indizes arbeiten soll (etwa Werkzeuge zum Debuggen oder Exportieren), und beim Prüfen, ob ein Index bei einem Schema-Upgrade neu angelegt werden muss.

Rückgabewert

Typ

string | string[]

Beschreibung

Der beim Anlegen festgelegte Schlüsselpfad: ein String (auch mit Punkten, z. B. "adresse.plz") oder bei zusammengesetzten Indizes ein Array von Strings.

Beispiele

Schlüsselpfad eines Indexes auslesen

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

request.onupgradeneeded = (event) => {
  const db = event.target.result;
  const store = db.createObjectStore('personen', { keyPath: 'id', autoIncrement: true });
  store.createIndex('nachEmail', 'email', { unique: true });
  store.createIndex('nachName', ['nachname', 'vorname']);
};

request.onsuccess = (event) => {
  const db = event.target.result;
  const tx = db.transaction('personen', 'readonly');
  const store = tx.objectStore('personen');

  console.log(store.index('nachEmail').keyPath);
  console.log(store.index('nachName').keyPath);
};

email ["nachname", "vorname"]

Alle Indizes eines Object Stores auflisten (z. B. zum Debuggen)

const beschreibeIndizes = (db, storeName) => {
  const store = db.transaction(storeName, 'readonly').objectStore(storeName);
  return Array.from(store.indexNames, (name) => {
    const index = store.index(name);
    const pfad = Array.isArray(index.keyPath)
      ? `[${index.keyPath.join(', ')}]`
      : index.keyPath;
    return `${name}: ${pfad}${index.unique ? ' (unique)' : ''}`;
  });
};

const req = indexedDB.open('kontakte', 1);
req.onsuccess = () => {
  console.log(beschreibeIndizes(req.result, 'personen').join('\n'));
};

nachEmail: email (unique) nachName: [nachname, vorname]

Index beim Schema-Upgrade nur bei geändertem Pfad neu anlegen

const req = indexedDB.open('shop', 2);

req.onupgradeneeded = (event) => {
  const db = event.target.result;
  const store = event.target.transaction.objectStore('bestellungen');
  const gewuenscht = 'kunde.plz';

  if (store.indexNames.contains('nachPlz')) {
    // keyPath ist unveränderlich – bei Abweichung neu erstellen
    if (store.index('nachPlz').keyPath !== gewuenscht) {
      store.deleteIndex('nachPlz');
      store.createIndex('nachPlz', gewuenscht);
    }
  } else {
    store.createIndex('nachPlz', gewuenscht);
  }
};

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an keyPath bewirkt nichts (im Strict Mode gibt es einen TypeError). Um den Pfad zu ändern, muss der Index in onupgradeneeded gelöscht und neu angelegt werden.
Arrays vergleichen: Bei zusammengesetzten Indizes ist keyPath ein Array. Ein Vergleich mit === prüft dann nur die Identität, nicht den Inhalt. Vorher mit Array.isArray() prüfen und die Einträge einzeln vergleichen, oder z. B. JSON.stringify() nutzen.
Manche Browser liefern bei jedem Zugriff ein neues Array-Objekt zurück, auch deshalb sollte man sich nicht auf die Identität verlassen.
Objekte, bei denen der Pfad nicht existiert oder keinen gültigen Schlüssel ergibt (z. B. undefined, null, boolean), kommen einfach nicht in den Index, ohne Fehlermeldung. Mit der Option multiEntry: true wird aus jedem Array-Element ein eigener Eintrag. Diese Option ist nur mit einem String-Pfad erlaubt, nicht mit einem Array-Pfad.
Wird die Eigenschaft gelesen, nachdem der Index gelöscht wurde, kann eine InvalidStateError-Ausnahme auftreten.
Kompatibilität: Wird von allen modernen Browsern unterstützt, auch in Web Workern. Ältere Versionen von Internet Explorer und Edge unterstützten keine zusammengesetzten Array-Pfade.

Siehe auch

IDBIndex IDBIndex.name IDBIndex.unique IDBIndex.multiEntry IDBObjectStore.keyPath IDBObjectStore.prototype.createIndex() ScreenDetailed.label