Claves e índices: el mapa de acceso

Sin lenguaje de consulta, todo lo que IndexedDB puede responder rápido está decidido de antemano por dos cosas: cómo se identifican los registros y qué proyecciones ordenadas mantienes sobre ellos. Las claves y los índices no son configuración accesoria, son el plan de acceso completo de tu base local, y se declaran en la migración, meses antes de que sepas qué preguntas te va a hacer la interfaz. Diseñarlos bien es la diferencia entre una consulta que responde en un milisegundo y un recorrido completo del almacén filtrando en JavaScript.

Dónde vive la clave

Un almacén decide, al crearse, si la clave forma parte del valor o vive fuera de él. Con keyPath la clave es en línea: el motor la extrae del propio objeto siguiendo una ruta de propiedades, que puede ser anidada como autor.id e incluso la cadena vacía, que significa que el valor entero es la clave. Sin keyPath la clave es fuera de línea y la pasas como segundo argumento en cada escritura.

// Clave en linea: el motor lee la propiedad isbn del objeto
const libros = db.createObjectStore("libros", { keyPath: "isbn" });
libros.put({ isbn: "978-84", titulo: "Rayuela" });

// Clave fuera de linea: el valor no sabe cual es su clave
const miniaturas = db.createObjectStore("miniaturas");
miniaturas.put(unBlob, "portada-978-84");

La regla práctica es simple: si el identificador pertenece conceptualmente al dato, ponlo en línea; si es un detalle de almacenamiento —una ruta, un hash de contenido, una clave binaria— déjalo fuera y ahorra bytes en cada registro. Los valores que no son objetos, como un Blob o una cadena, solo pueden usar clave fuera de línea.

El generador y sus huecos

El generador automático es un contador por almacén que empieza en uno y sube de uno en uno. Su propiedad esencial es que nunca reutiliza un número: borrar registros no lo hace retroceder, y vaciar el almacén entero tampoco. Los huecos son permanentes por diseño, porque un identificador reutilizado sería indistinguible de una referencia obsoleta.

Hay dos matices que casi nadie conoce. El primero es que escribir una clave explícita mayor que el contador lo empuja hacia arriba, de modo que la siguiente clave generada quedará por encima de la que insertaste a mano. El segundo es que abortar una transacción sí revierte el contador a su valor anterior, lo cual es coherente con la atomicidad, pero significa que no puedes usar la clave generada como un contador global de eventos.

const eventos = db.createObjectStore("eventos", {
  keyPath: "id",
  autoIncrement: true,
});

eventos.put({ texto: "uno" });   // id 1, escrito dentro del objeto
eventos.put({ texto: "dos" });   // id 2
eventos.delete(2);                // el contador no retrocede
eventos.put({ texto: "tres" });  // id 3, el hueco 2 no se reutiliza
eventos.put({ id: 900, texto: "manual" });
eventos.put({ texto: "cuatro" }); // id 901, el contador salto

Índices: únicos, compuestos y multivalor

Un índice es una proyección ordenada de una propiedad hacia las claves primarias. Se crea dentro de la migración y admite dos banderas que cambian por completo su semántica.

const notas = db.createObjectStore("notas", { keyPath: "id" });

// Indice simple
notas.createIndex("por_fecha", "creado");

// Indice unico: rechaza duplicados en escritura
notas.createIndex("por_uuid", "uuid", { unique: true });

// Indice compuesto: orden lexicografico por componentes
notas.createIndex("por_libreta_fecha", ["libreta", "creado"]);

// Indice multivalor: una entrada por cada elemento del array
notas.createIndex("por_etiqueta", "etiquetas", { multiEntry: true });

unique impone una restricción real: cualquier escritura que duplique el valor aborta la transacción con ConstraintError. Y si creas el índice sobre datos que ya contienen duplicados, la migración entera falla, lo que es una forma incómoda pero honesta de enterarte de que tu invariante nunca fue cierta.

multiEntry solo tiene sentido cuando la propiedad es un array: genera una entrada de índice por elemento, y es la única manera de responder rápido a la pregunta “dame todas las notas con la etiqueta local-first”. No se puede combinar con un keyPath compuesto: son mutuamente excluyentes.

flowchart LR
A[Almacen de notas] --> B[Indice por libreta y fecha]
A --> C[Indice multivalor por etiqueta]
B --> D[Clave compuesta ordenada por componentes]
D --> E[Solo se puede acotar por prefijo]
C --> F[Una entrada por elemento del array]
F --> G[Consulta directa por etiqueta suelta]

El índice compuesto ordena lexicográficamente componente a componente, exactamente igual que un índice de árbol equilibrado en cualquier motor relacional. De ahí sale la restricción más importante y la que más gente ignora: solo puedes acotar por un prefijo de los componentes. Un índice sobre libreta y fecha responde consultas por libreta, y por libreta más rango de fecha; no responde nada que empiece filtrando por fecha.

Rangos de consulta

IDBKeyRange es la única forma de expresar una consulta que no sea una igualdad. Tiene cuatro constructores y dos banderas de exclusividad, y con eso se cubre todo el espacio de preguntas que IndexedDB sabe responder sin recorrerlo todo.

IDBKeyRange.only(7);                       // igualdad exacta
IDBKeyRange.lowerBound(fechaInicio);       // desde ahi hacia arriba
IDBKeyRange.upperBound(fechaFin, true);    // hasta ahi, sin incluirlo
IDBKeyRange.bound(desde, hasta, false, true); // intervalo semiabierto

// Prefijo de cadena: un punto de codigo altisimo como techo
const porNombre = IDBKeyRange.bound("mar", "mar\uffff");

// Prefijo de clave compuesta: un array vacio ordena despues de toda cadena
const deLaLibreta = IDBKeyRange.bound(["trabajo"], ["trabajo", []]);

Los dos últimos ejemplos son idiomas que conviene memorizar. El primero explota el orden lexicográfico de cadenas para simular un “empieza por”. El segundo explota el orden total entre tipos que viste en la primera lección: como cualquier array ordena después de cualquier cadena, el par formado por la libreta y un array vacío es un techo perfecto para todas las entradas de esa libreta, sea cual sea su fecha.

Un rango se puede pasar a casi cualquier método de lectura, y ahí está la diferencia entre una consulta eficiente y un recorrido disfrazado. getAll y getAllKeys aceptan además un límite de resultados, count responde sin materializar nada y get sobre un índice devuelve solo la primera coincidencia en orden de clave, lo que sorprende a quien espera una lista.

const idx = tx.objectStore("notas").index("por_fecha");

idx.get(rango);              // solo el primero, no una lista
idx.getAll(rango, 20);       // los veinte primeros del rango
idx.getAllKeys(rango, 20);   // sus claves primarias, sin deserializar valores
idx.count(rango);            // cuenta en el indice, sin leer registros