Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

IndexedDB: creare un indice, inserire un record e cercare per indice

Crea un indice secondario durante un aggiornamento del database, inserisci senza sovrascrivere e cerca per chiave di indice anziché per chiave primaria.

Versione: Current web platform; runtime support varies

Sintassi

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

createIndex(), add() e index() sono metodi di istanza di IDBObjectStore nell’API Web IndexedDB, non in ECMAScript. IndexedDB segue la politica della stessa origine; la disponibilità dipende dall’ambiente di esecuzione e dalle impostazioni di archiviazione del browser.

store.createIndex(name, keyPath, options) restituisce subito un IDBIndex, ma la modifica allo schema diventa definitiva solo con il commit della transazione. Chiama il metodo in una transazione versionchange attiva, di solito durante upgradeneeded quando crei il database o ne aumenti la versione. Il nome identifica l’indice; il percorso della chiave ricava la chiave dell’indice dal record senza aggiungere un campo. IndexedDB indicizza i record esistenti e aggiorna automaticamente l’indice.

unique e multiEntry sono false per impostazione predefinita. unique: true vieta chiavi di indice uguali in record diversi; eventuali duplicati esistenti possono interrompere l’aggiornamento. multiEntry: true indicizza i singoli elementi validi di un valore di tipo array, anziché usare l’intero array come chiave. Non puoi combinarlo con un array di percorsi per una chiave composta (InvalidAccessError). Un nome di indice già in uso causa subito ConstraintError.

store.add(value[, key]) inserisce una copia strutturata senza sovrascrivere. Richiede una transazione readwrite o versionchange attiva. Ometti key se la chiave primaria è interna al valore; forniscila se è esterna e non c’è un generatore. Se la richiesta IDBRequest ha successo, result contiene la chiave primaria, ma solo l’evento complete della transazione conferma il commit. Un duplicato della chiave primaria o della chiave di un indice univoco fa fallire la richiesta con ConstraintError. put() può sostituire un record, ma deve comunque rispettare l’univocità dell’indice.

store.index(name) restituisce l’IDBIndex esistente, legato alla stessa transazione. Non crea un indice e non legge un record. Un nome inesistente causa NotFoundError; le maiuscole e le minuscole contano. In una transazione attiva, index.get(key) richiede il primo record corrispondente alla chiave dell’indice, non alla chiave primaria. Non riutilizzare l’oggetto per leggere dopo la fine della transazione.

Esempi

<!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>

Risultato

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

Rendi disponibile il file HTML a un indirizzo HTTPS affidabile e aprilo in un browser che supporta IndexedDB e `crypto.randomUUID()`. L’esempio crea un database separato, cerca per `email` dopo il commit della scrittura, poi chiude ed elimina il database prima di stampare il risultato nella console del browser.

Lezioni correlate

  • JavaScript · Lezione 31 · Avanzato · Versione: 4

Fonti