IDBObjectStore.getKey() — Methode · JavaScript-Referenz

Signatur

IDBObjectStore.prototype.getKey(query)

Beschreibung

getKey() sucht im Object Store nach dem ersten Datensatz, dessen Primärschlüssel zum übergebenen Schlüssel bzw. zur übergebenen IDBKeyRange passt, und gibt nur diesen Primärschlüssel zurück, nicht den gespeicherten Wert. Die Abfrage läuft asynchron. Das Ergebnis steht im success-Ereignis unter request.result bereit.

Die Methode eignet sich gut, um schnell zu prüfen, ob ein Datensatz existiert, oder um den ersten Schlüssel in einem Bereich zu finden, etwa „der erste Eintrag ab Datum X“. Der Datensatz selbst muss dafür nicht deserialisiert werden. Bei großen Objekten (Blobs, verschachtelte Strukturen) ist das deutlich günstiger als get().

Wird kein passender Datensatz gefunden, ist result gleich undefined. Ein Fehlerereignis gibt es in diesem Fall nicht. Die Methode muss innerhalb einer aktiven Transaktion (readonly oder readwrite) aufgerufen werden, zu der der Store gehört.

Parameter

Name	Typ	Default	Beschreibung
$query Pflicht	IDBValidKey \| IDBKeyRange		Ein gültiger Schlüssel (`number`, `string`, `Date`, `ArrayBuffer`, `Array`) oder ein `IDBKeyRange`. Bei einem Bereich wird der kleinste passende Schlüssel geliefert.

Rückgabewert

Typ

IDBRequest<IDBValidKey | undefined>

Beschreibung

Ein IDBRequest. Nach dem Ereignis success enthält result den gefundenen Primärschlüssel oder undefined, wenn nichts gefunden wurde.

Beispiele

Prüfen, ob ein Kunde existiert

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

openReq.onupgradeneeded = () => {
  const db = openReq.result;
  const store = db.createObjectStore('kunden', { keyPath: 'id' });
  store.put({ id: 42, name: 'Anna', avatar: new Blob(['...']) });
};

openReq.onsuccess = () => {
  const db = openReq.result;
  const store = db.transaction('kunden', 'readonly').objectStore('kunden');
  const req = store.getKey(42);

  req.onsuccess = () => {
    console.log(req.result !== undefined ? `Kunde ${req.result} existiert` : 'Nicht gefunden');
  };
  req.onerror = () => console.error(req.error);
};

Kunde 42 existiert

Ersten Schlüssel in einem Bereich finden (Promise-Wrapper)

const promisify = (request) => new Promise((resolve, reject) => {
  request.onsuccess = () => resolve(request.result);
  request.onerror = () => reject(request.error);
});

const ersteBestellungAb = async (db, datum) => {
  const store = db.transaction('bestellungen').objectStore('bestellungen');
  // Primärschlüssel ist ein Date
  return promisify(store.getKey(IDBKeyRange.lowerBound(datum)));
};

// Nutzung:
// const key = await ersteBestellungAb(db, new Date('2024-01-01'));
// console.log(key);

2024-01-03T00:00:00.000Z (bzw. undefined, wenn keine Bestellung existiert)

Nicht vorhandener Schlüssel liefert undefined

const checkKey = (db, key) => {
  const req = db.transaction('kunden').objectStore('kunden').getKey(key);
  req.onsuccess = () => console.log(key, '→', req.result);
};

// checkKey(db, 9999);

9999 → undefined

// Wichtig · Fallstricke

Kein Fehler bei Nichtfund: Findet die Abfrage nichts, ist result einfach undefined. Das Ergebnis muss also ausdrücklich geprüft werden.
Ausnahmen: DataError bei einem ungültigen Schlüssel oder Bereich, TransactionInactiveError, wenn die Transaktion schon beendet ist (etwa nach einem await auf ein fremdes Promise), InvalidStateError, wenn der Store gelöscht wurde.
Nur ein Treffer: Bei einem Bereich kommt nur der kleinste passende Schlüssel zurück. Für alle Treffer getAllKeys() oder openKeyCursor() verwenden.
Kompatibilität: In allen modernen Browsern und in Web Workern verfügbar. Sehr alte Browser (Internet Explorer, Edge Legacy) kennen die Methode nicht. In privaten Fenstern kann IndexedDB eingeschränkt sein.
Für Suchen über einen Index gibt es IDBIndex.getKey(). Die Methode liefert den Primärschlüssel zu einem Indexwert.

Siehe auch

IDBObjectStore IDBObjectStore.get() IDBObjectStore.getAllKeys() IDBObjectStore.openKeyCursor() IDBIndex.getKey() IDBKeyRange IDBRequest