WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

IndexedDB: Index anlegen, Datensatz einfügen und per Index abfragen

Lege bei einem Datenbank-Upgrade einen Sekundärindex an, füge einen Datensatz ohne Überschreiben ein und suche ihn über den Indexschlüssel statt über den Primärschlüssel.

Version: Current web platform; runtime support varies

Syntax

store.createIndex(name, keyPath)
store.createIndex(name, keyPath, { unique, multiEntry })
store.add(value)
store.add(value, key)
store.index(name)

createIndex(), add() und index() sind Instanzmethoden von IDBObjectStore in der IndexedDB-Web-API und gehören nicht zu ECMAScript. IndexedDB unterliegt der Same-Origin-Policy; die Verfügbarkeit hängt außerdem von der Laufzeitumgebung und den Speichereinstellungen des Browsers ab.

store.createIndex(name, keyPath, options) gibt sofort ein IDBIndex-Objekt zurück. Dauerhaft wird die Schemaänderung erst, wenn die Transaktion erfolgreich abgeschlossen ist. Rufe die Methode in einer aktiven versionchange-Transaktion auf, typischerweise in upgradeneeded beim Erstellen der Datenbank oder beim Erhöhen ihrer Version. Der Name identifiziert den Index; der Schlüsselpfad bestimmt den Indexschlüssel aus dem Datensatz, ohne ein Feld hinzuzufügen. IndexedDB indiziert vorhandene Datensätze und hält den Index automatisch aktuell.

unique und multiEntry sind standardmäßig false. unique: true verbietet gleiche Indexschlüssel in verschiedenen Datensätzen; vorhandene Duplikate können das Upgrade abbrechen. multiEntry: true indiziert die einzelnen gültigen Elemente eines Array-Werts, statt das ganze Array als einen Schlüssel zu verwenden. Die Option lässt sich nicht mit einem Array von Schlüsselpfaden für einen zusammengesetzten Schlüssel kombinieren (InvalidAccessError). Ein bereits vergebener Indexname löst sofort ConstraintError aus.

store.add(value[, key]) fügt eine strukturierte Kopie ein, ohne etwas zu überschreiben. Dazu muss eine readwrite- oder versionchange-Transaktion aktiv sein. Bei einem Primärschlüssel im Datensatz lässt du key weg; bei einem externen Schlüssel ohne Generator musst du ihn angeben. Bei Erfolg liefert IDBRequest.result den Primärschlüssel. Erst complete der Transaktion bestätigt den Commit. Ein doppelter Primärschlüssel oder Schlüssel eines eindeutigen Index lässt die Anfrage mit ConstraintError scheitern. put() kann einen Datensatz ersetzen, muss aber ebenfalls die Eindeutigkeit des Index beachten.

store.index(name) liefert den vorhandenen IDBIndex, der an dieselbe Transaktion gebunden ist. Die Methode legt keinen Index an und liest keinen Datensatz. Fehlt der Name, folgt NotFoundError; Groß- und Kleinschreibung sind relevant. In einer aktiven Transaktion fordert index.get(key) den ersten passenden Datensatz anhand des Indexschlüssels an, nicht anhand des Primärschlüssels. Verwende das Indexobjekt nach Transaktionsende nicht mehr zum Lesen.

Beispiele

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IndexedDB: insert and look up a contact</title>
</head>
<body>
<script>
(async () => {
  const { indexedDB, crypto } = window;
  const name = `cktis-index-${crypto.randomUUID()}`;
  const resultOf = (request) => new Promise((resolve, reject) => {
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
  const committed = (tx) => new Promise((resolve, reject) => {
    tx.oncomplete = () => resolve();
    tx.onabort = () => reject(tx.error ?? new Error('Transaction aborted'));
  });

  const open = indexedDB.open(name, 1);
  open.onupgradeneeded = () => {
    const store = open.result.createObjectStore('contacts', { keyPath: 'id' });
    store.createIndex('byEmail', 'email', { unique: true });
  };
  const db = await resultOf(open);
  let contact;
  try {
    const write = db.transaction('contacts', 'readwrite');
    write.objectStore('contacts').add({ id: 7, email: 'ada@example.test' });
    await committed(write);

    const read = db.transaction('contacts', 'readonly');
    const lookup = read.objectStore('contacts').index('byEmail').get('ada@example.test');
    await committed(read);
    contact = lookup.result;
  } finally {
    db.close();
    await resultOf(indexedDB.deleteDatabase(name));
  }
  console.log(JSON.stringify(contact));
})().catch((error) => console.error(error));
</script>
</body>
</html>

Ergebnis

{"id":7,"email":"ada@example.test"}

Stelle die HTML-Datei unter einer vertrauenswürdigen HTTPS-Adresse bereit und öffne sie in einem Browser, in dem IndexedDB und `crypto.randomUUID()` verfügbar sind. Das Beispiel erstellt eine separate Datenbank, sucht nach dem Commit anhand von `email` und schließt und löscht die Datenbank vor der Ausgabe in der Browserkonsole.

Zugehörige Lektionen

  • JavaScript · Lektion 31 · Fortgeschritten · Version: 4

Quellen