IDBRecord — Schnittstelle · JavaScript-Referenz

Signatur

interface IDBRecord

Beschreibung

Das Interface IDBRecord gehört zur IndexedDB API. Es steht für einen einzelnen Datensatz, so wie er zum Zeitpunkt der Abfrage gespeichert war. Instanzen bekommen Sie nur als Elemente des Arrays, das die Methoden IDBObjectStore.prototype.getAllRecords() und IDBIndex.prototype.getAllRecords() zurückliefern. Einen öffentlichen Konstruktor gibt es nicht.

Jeder Datensatz hat drei schreibgeschützte Eigenschaften:

key: der Schlüssel des Datensatzes. Bei einem Object Store ist das der Primärschlüssel, bei einem Index der Indexschlüssel.
primaryKey: der Primärschlüssel des Datensatzes im Object Store.
value: der gespeicherte Wert, per structured clone deserialisiert.

Früher mussten Sie für Schlüssel und Werte zwei getrennte Abfragen stellen (getAll() und getAllKeys()) oder einen langsamen IDBCursor Schritt für Schritt durchlaufen. getAllRecords() liefert beides in einer Anfrage. Die Optionen direction und count erlauben außerdem das Lesen in umgekehrter Reihenfolge und eine effiziente Seitenaufteilung (Pagination), ohne einen Cursor zu verwenden.

Ein IDBRecord ist nur ein Schnappschuss. Wenn Sie value ändern, bleibt die Datenbank unverändert. Um Änderungen zu speichern, rufen Sie in einer readwrite-Transaktion put() mit dem primaryKey auf.

Parameter

Name	Typ	Beschreibung
$key Pflicht	any (gültiger IndexedDB-Schlüssel: number \| string \| Date \| ArrayBuffer \| Array)	Schreibgeschützte Eigenschaft. Der Schlüssel des Datensatzes. Bei Abfragen auf einen Index ist das der Indexschlüssel, bei Abfragen auf einen Object Store der Primärschlüssel.
$primaryKey Pflicht	any (gültiger IndexedDB-Schlüssel)	Schreibgeschützte Eigenschaft. Der Primärschlüssel des Datensatzes im Object Store. Brauchen Sie z. B. für `put()` oder `delete()`.
$value Pflicht	any	Schreibgeschützte Eigenschaft. Der gespeicherte Wert als strukturierte Kopie.

Rückgabewert

Typ

IDBRecord

Beschreibung

Wird nicht direkt erzeugt. getAllRecords() liefert über IDBRequest.result ein Array<IDBRecord>.

Beispiele

Alle Datensätze samt Schlüssel aus einem Object Store lesen

// Hilfsfunktion: IDBRequest in ein Promise umwandeln
const promisify = (req) => new Promise((resolve, reject) => {
  req.onsuccess = () => resolve(req.result);
  req.onerror = () => reject(req.error);
});

const openReq = indexedDB.open('shop', 1);
openReq.onupgradeneeded = () => {
  const store = openReq.result.createObjectStore('produkte', { keyPath: 'id' });
  store.createIndex('nachPreis', 'preis');
  store.put({ id: 1, name: 'Tastatur', preis: 49 });
  store.put({ id: 2, name: 'Maus', preis: 19 });
  store.put({ id: 3, name: 'Monitor', preis: 199 });
};
const db = await promisify(openReq);

const store = db.transaction('produkte').objectStore('produkte');
const records = await promisify(store.getAllRecords());

for (const { key, primaryKey, value } of records) {
  console.log(key, primaryKey, value.name);
}

1 1 Tastatur 2 2 Maus 3 3 Monitor

Die drei teuersten Produkte über einen Index abfragen (umgekehrte Reihenfolge)

const index = db.transaction('produkte').objectStore('produkte').index('nachPreis');

const top = await promisify(index.getAllRecords({ direction: 'prev', count: 3 }));

// key = Indexschlüssel (Preis), primaryKey = id
top.forEach((r) => console.log(`${r.value.name}: ${r.key} € (id ${r.primaryKey})`));

Monitor: 199 € (id 3) Tastatur: 49 € (id 1) Maus: 19 € (id 2)

Seitenweise laden (Pagination) mit Fallback für ältere Browser

const ladeSeite = async (store, nachKey = null, groesse = 50) => {
  // Nur Schlüssel größer als der letzte der vorigen Seite
  const query = nachKey === null ? null : IDBKeyRange.lowerBound(nachKey, true);

  if ('getAllRecords' in IDBObjectStore.prototype) {
    const records = await promisify(store.getAllRecords({ query, count: groesse }));
    return {
      eintraege: records.map((r) => r.value),
      naechsterKey: records.at(-1)?.primaryKey ?? null,
    };
  }

  // Fallback: zwei getrennte Anfragen
  const [werte, keys] = await Promise.all([
    promisify(store.getAll(query, groesse)),
    promisify(store.getAllKeys(query, groesse)),
  ]);
  return { eintraege: werte, naechsterKey: keys.at(-1) ?? null };
};

const tx = db.transaction('produkte');
const seite1 = await ladeSeite(tx.objectStore('produkte'), null, 2);
console.log(seite1.eintraege.map((p) => p.name), seite1.naechsterKey);

[ 'Tastatur', 'Maus' ] 2

// Wichtig · Fallstricke

Kompatibilität: IDBRecord und getAllRecords() kommen aus der Entwurfsfassung IndexedDB 3.0 und sind bisher nur in Chromium-basierten Browsern verfügbar. Prüfen Sie die Unterstützung vorher, z. B. mit 'getAllRecords' in IDBObjectStore.prototype, und sehen Sie einen Fallback über getAll() und getAllKeys() oder einen IDBCursor vor.
key und primaryKey nicht verwechseln: Bei Index-Abfragen enthält key den Indexwert, zum Beispiel den Preis. Für put() und delete() brauchen Sie immer primaryKey.
Nur ein Schnappschuss: Wenn Sie record.value ändern, wird nichts gespeichert. Die Eigenschaften selbst sind schreibgeschützt.
Kein Konstruktor: new IDBRecord() wirft einen TypeError.
Speicherbedarf: Ohne count landen alle passenden Datensätze auf einmal im Speicher. Bei großen Stores sollten Sie seitenweise mit count und IDBKeyRange laden.
Die Anfrage schlägt fehl, wenn die Transaktion schon beendet ist (TransactionInactiveError). Starten Sie alle Anfragen, bevor Sie in der Transaktion auf etwas anderes warten, zum Beispiel auf fetch.

Siehe auch

IDBObjectStore IDBIndex IDBObjectStore.prototype.getAllRecords() IDBIndex.prototype.getAllRecords() IDBObjectStore.prototype.getAll() IDBCursor IDBKeyRange