Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

IndexedDB: criar um índice, inserir um registo e pesquisar pelo índice

Cria um índice secundário numa atualização da base de dados, insere sem substituir e pesquisa pela chave do índice em vez da chave primária.

Versão: Current web platform; runtime support varies

Sintaxe

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

createIndex(), add() e index() são métodos de instância de IDBObjectStore na API Web IndexedDB, não em ECMAScript. IndexedDB segue a política da mesma origem; a disponibilidade depende do ambiente de execução e das definições de armazenamento do navegador.

store.createIndex(name, keyPath, options) devolve imediatamente um IDBIndex, mas a alteração ao esquema só fica definitiva se a transação for confirmada. Chama o método numa transação versionchange ativa, normalmente em upgradeneeded, ao criar a base de dados ou aumentar a sua versão. O nome identifica o índice; o caminho da chave determina a chave do índice a partir do registo sem lhe acrescentar um campo. IndexedDB indexa os registos existentes e mantém o índice atualizado automaticamente.

unique e multiEntry têm false como valor predefinido. unique: true impede chaves de índice iguais em registos diferentes; duplicados existentes podem abortar a atualização. multiEntry: true indexa separadamente os elementos válidos de um array em vez de usar o array inteiro como chave. Não pode ser combinado com um array de caminhos para uma chave composta (InvalidAccessError). Um nome de índice já utilizado provoca imediatamente ConstraintError.

store.add(value[, key]) insere uma cópia estruturada sem substituir um registo existente. Usa uma transação readwrite ou versionchange ativa. Omite key se a chave primária estiver incluída no valor; indica-a se for externa e não houver gerador. Se o pedido IDBRequest tiver êxito, result contém a chave primária, mas só o evento complete da transação confirma a gravação. Uma chave primária ou de índice único duplicada faz falhar o pedido com ConstraintError. put() pode substituir um registo, mas também tem de respeitar a unicidade do índice.

store.index(name) devolve o IDBIndex existente, associado à mesma transação. Não cria um índice nem lê um registo. Um nome inexistente provoca NotFoundError; há distinção entre maiúsculas e minúsculas. Numa transação ativa, index.get(key) pede o primeiro registo correspondente à chave do índice, não à chave primária. Não reutilizes o objeto para fazer leituras depois de a transação terminar.

Exemplos

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

Resultado

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

Disponibiliza o ficheiro HTML num endereço HTTPS de confiança e abre-o num navegador com IndexedDB e `crypto.randomUUID()` disponíveis. O exemplo cria uma base de dados separada, pesquisa por `email` depois de a escrita ser confirmada e fecha e elimina a base de dados antes de apresentar o resultado na consola do navegador.

Lições relacionadas

  • JavaScript · Lição 31 · Avançado · Versão: 4

Fontes