Capítulo 14¶

Cloudflare KV, Queues, Durable Objects y Vectorize¶

Servicios avanzados para construir aplicaciones distribuidas¶

Objetivo¶

Este capítulo tiene una meta muy práctica: que el lector comprenda por qué una arquitectura moderna no puede resolver todos sus problemas con una sola base de datos y aprenda a decidir correctamente cuándo utilizar KV, D1, Durable Objects, Queues o Vectorize dentro del ecosistema de Cloudflare.[cite:80][cite:83][cite:82]

Al finalizar, el lector será capaz de seleccionar el servicio adecuado según el tipo de dato, el patrón de acceso, el nivel de consistencia, la necesidad de coordinación en tiempo real, el uso de procesamiento asíncrono o la presencia de búsquedas semánticas impulsadas por IA.[cite:80][cite:83][cite:82]

¿Qué aprenderás?¶

Por qué una sola base de datos no resuelve todos los problemas de una aplicación moderna.[cite:80]
Cuándo utilizar Workers KV, D1, Durable Objects, Queues o Vectorize.[cite:80][cite:83][cite:82]
Cómo integrar KV, Durable Objects, Queues y Vectorize con Workers.[cite:86][cite:80][cite:82]
Qué tipo de problemas resuelve cada servicio y cuáles son sus límites naturales.[cite:80][cite:84][cite:81]
Cómo diseñar una arquitectura educativa moderna usando varios servicios de forma complementaria.[cite:80][cite:83][cite:82]

Introducción¶

Imagina una ciudad moderna. No basta con tener un solo edificio gigantesco y guardar ahí todo: viviendas, hospitales, oficinas, bodegas, estaciones de policía, centros logísticos, plantas eléctricas y bibliotecas. Aunque cupiera todo en el mismo lugar, el resultado sería ineficiente. Cada necesidad exige una infraestructura distinta.

En software ocurre exactamente lo mismo. Durante muchos años se intentó resolver casi todo con una única base de datos: sesiones, catálogos, colas de trabajo, archivos, coordinación en tiempo real, búsquedas, configuración y analítica. El resultado solía ser una arquitectura tensa, costosa y difícil de escalar.

Cloudflare propone una visión más especializada. En su guía oficial para elegir productos de datos y almacenamiento, distingue claramente entre KV para key-value de baja latencia, D1 para datos relacionales, Durable Objects para coordinación global con estado consistente, Queues para procesamiento asíncrono y Vectorize para embeddings y búsqueda semántica.[cite:80]

Esa diferenciación no complica la arquitectura; la vuelve más honesta. Un catálogo global no tiene las mismas necesidades que una transacción SQL. Un chat en tiempo real no se comporta como un sistema de reportes. Una cola de miniaturas no se diseña igual que una búsqueda semántica sobre documentos.

Para entender este capítulo conviene introducir cinco conceptos.

Persistencia¶

Persistir significa conservar información más allá de la vida inmediata de una solicitud. Un usuario puede cerrar el navegador y, aun así, sus datos deben seguir existiendo.

Estado¶

El estado describe la situación actual de algo en un momento dado. Puede ser el contador de una sala, los participantes de una sesión, el documento abierto en colaboración o la reserva temporal de un asiento. No todo estado necesita una base relacional; a veces necesita coordinación estricta y cercanía a la lógica de ejecución.[cite:80]

Mensajería¶

La mensajería desacopla procesos. En lugar de hacer todo inmediatamente dentro de una petición HTTP, un Worker puede colocar trabajo en una cola y permitir que otro consumidor lo procese después. Cloudflare describe Queues como un servicio de entrega garantizada con procesamiento en lote y sin cargos de egress.[cite:80][cite:83]

Memoria¶

En una arquitectura distribuida, la “memoria” puede significar varias cosas: cache persistente, configuración replicada, estado coordinado o incluso datos temporales de sesión. No todos esos casos se resuelven del mismo modo. KV sirve para algunos; Durable Objects para otros.[cite:80][cite:86]

Búsqueda semántica¶

La búsqueda semántica intenta encontrar resultados por significado, no solo por coincidencia exacta de palabras. Vectorize existe precisamente para almacenar embeddings y consultarlos por similitud dentro de flujos de IA y RAG.[cite:82][cite:85]

La gran lección del capítulo es esta: elegir bien el servicio no es un detalle de implementación. Es una decisión arquitectónica.

Una sola base de datos no basta¶

La documentación oficial de Cloudflare no presenta un único servicio universal, sino un conjunto de productos especializados para diferentes patrones de datos y acceso.[cite:80] Eso ya es una pista importante: si la propia plataforma distingue entre key-value, SQL relacional, coordinación stateful, mensajería y vectores, es porque esos problemas no se resuelven igual.

Un sistema de credenciales digitales, por ejemplo, puede necesitar varias capas al mismo tiempo:

D1 para usuarios, roles, escuelas y credenciales emitidas.[cite:80]
R2 para fotografías, PDFs y recursos binarios.[cite:80]
KV para configuración distribuida, feature flags o sesiones leídas constantemente.[cite:80][cite:86]
Queues para generación de PDFs, notificaciones o importaciones masivas.[cite:80]
Durable Objects para coordinación en tiempo real, contadores estrictos o reservas temporales.[cite:80]
Vectorize para búsqueda semántica sobre reglamentos, manuales o contenido educativo.[cite:82][cite:80]

Pensar que una sola base puede hacerlo todo suele conducir a uno de dos errores: o se fuerza a la base relacional a comportarse como cache, broker y motor semántico al mismo tiempo, o se elige un almacén demasiado simple para problemas que exigen relaciones o consistencia fuerte.

La arquitectura moderna no consiste en coleccionar servicios por moda. Consiste en usar pocos servicios, pero correctos.

Cloudflare KV¶

¿Qué es?¶

Workers KV es el servicio de almacenamiento key-value de Cloudflare. La documentación oficial lo describe como un almacén global y de baja latencia para guardar y recuperar datos con soporte para altos volúmenes de lectura.[cite:86] En la guía de productos de almacenamiento, Cloudflare lo clasifica como eventually consistent y especialmente útil para configuraciones distribuidas, sesiones y lecturas globales rápidas.[cite:80]

¿Cómo funciona?¶

KV almacena pares clave-valor. La clave es un identificador único y el valor es el contenido asociado. Ese valor puede ser texto, JSON serializado, configuraciones, tokens o pequeños blobs según los límites permitidos por la plataforma.[cite:86]

La idea es extremadamente simple, y ahí está su poder. Si se conoce la clave, se puede recuperar el valor sin necesidad de joins ni modelos relacionales complejos.

clave -----------------> valor
"config:tema" --------> "oscuro"
"session:abc123" -----> "{...json...}"
"flag:nuevo-panel" ---> "true"

Lectura¶

KV está pensado para lecturas globales frecuentes. Cloudflare explica que las claves “calientes” pueden beneficiarse del cache interno y ver latencias típicas entre 500 microsegundos y 10 milisegundos.[cite:80] Esta característica lo vuelve muy atractivo para datos consultados constantemente y modificados poco.

Escritura¶

KV permite escritura, pero no está diseñado para patrones intensivos de actualización sobre la misma clave. Cloudflare recomienda usarlo cuando los datos no requieren consistencia inmediata y menciona un límite de 1 escritura por segundo por clave única para ciertos patrones de uso.[cite:80]

Replicación¶

Cloudflare describe KV como un almacén global que distribuye datos por su red. Esa distribución favorece lecturas cercanas al usuario, pero introduce un matiz esencial: la consistencia es eventual, no inmediata.[cite:80]

Consistencia¶

Aquí está la decisión arquitectónica clave. KV no debe tratarse como una base transaccional fuerte. Si una aplicación necesita garantías instantáneas, serialización estricta o coordinación exacta, Durable Objects o D1 serán opciones más adecuadas según el caso.[cite:80]

Latencia¶

El punto fuerte de KV es su lectura global de baja latencia. No se diseñó como una base relacional ni como una cola, sino como una capa de acceso ultrarrápido para datos simples que se leen mucho.[cite:80][cite:86]

Límites y costos¶

La documentación oficial remite a límites y pricing específicos de KV, y lo presenta como una opción orientada a grandes volúmenes de lectura con acceso por bindings desde Workers o por REST API desde aplicaciones externas.[cite:86] En arquitectura, más importante que memorizar cada cifra es entender el patrón económico: KV suele ser muy atractivo cuando el dato se distribuye mucho y se consulta constantemente.

Casos ideales para KV¶

La propia guía de Cloudflare y la documentación de KV mencionan varios casos típicos.[cite:80][cite:86]

Configuraciones¶

Un sistema puede guardar configuración por entorno, por tenant, por institución o por módulo.

Ejemplos:

config:escuela:123:tema
config:captcha:enabled
config:api:limite-diario

Tokens¶

KV puede servir para guardar material de autenticación o tokens que se leen mucho y cambian poco, especialmente cuando la validación debe ocurrir cerca del usuario.[cite:80][cite:86]

Sesiones¶

Cloudflare recomienda KV para almacenamiento de sesiones y menciona que frameworks de autenticación lo utilizan precisamente por su alto rendimiento en lectura distribuida.[cite:80]

Catálogos¶

Un catálogo de estados, países, tipos de documento o configuraciones institucionales globales puede encajar muy bien en KV.

Preferencias¶

Preferencias ligeras, como idioma, tema o banderas de interfaz, también son candidatas razonables.

Feature Flags¶

Los feature flags distribuidos son uno de los mejores ejemplos para KV: datos pequeños, altamente leídos, baja necesidad de consistencia instantánea y necesidad de distribución global.[cite:80]

Cache persistente¶

Cloudflare menciona explícitamente el cacheo de respuestas API como caso de uso de KV.[cite:86] Esto permite conservar resultados costosos y recuperarlos rápidamente sin recalcularlos en cada solicitud.

Cuándo NO utilizar KV¶

KV no es apropiado para:

Relaciones complejas entre entidades.
Consultas ad-hoc con filtros arbitrarios.
Operaciones que requieren consistencia fuerte inmediata.[cite:80]
Coordinación en tiempo real entre múltiples clientes.[cite:80]
Contadores estrictos o reservas donde dos escrituras simultáneas no pueden chocar.

En esos casos, D1 o Durable Objects suelen ser más adecuados.

Integración de KV con Workers¶

KV se integra con Workers mediante bindings.[cite:86] El patrón es parecido al de otros servicios de Cloudflare: se declara un recurso en configuración y luego se usa desde env.

Lectura¶

export interface Env {
  CONFIG: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const tema = await env.CONFIG.get('config:tema');
    return new Response(tema ?? 'claro');
  }
};

Escritura¶

await env.CONFIG.put('config:tema', 'oscuro');

Actualización¶

En KV, actualizar normalmente significa sobrescribir el valor asociado a una clave.

const prefs = { idioma: 'es', tema: 'oscuro' };
await env.CONFIG.put('user:42:prefs', JSON.stringify(prefs));

Eliminación¶

await env.CONFIG.delete('user:42:prefs');

Ejemplo completo¶

export interface Env {
  PREFS: KVNamespace;
}

function json(data: unknown, status = 200): Response {
  return new Response(JSON.stringify(data), {
    status,
    headers: { 'content-type': 'application/json; charset=utf-8' }
  });
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const userId = url.searchParams.get('userId');

    if (!userId) return json({ ok: false, error: 'userId requerido' }, 400);

    if (request.method === 'GET') {
      const data = await env.PREFS.get(`user:${userId}:prefs`, 'json');
      return json({ ok: true, data: data ?? { tema: 'claro', idioma: 'es' } });
    }

    if (request.method === 'POST') {
      const body = await request.json();
      await env.PREFS.put(`user:${userId}:prefs`, JSON.stringify(body));
      return json({ ok: true }, 201);
    }

    if (request.method === 'DELETE') {
      await env.PREFS.delete(`user:${userId}:prefs`);
      return json({ ok: true });
    }

    return json({ ok: false, error: 'Método no permitido' }, 405);
  }
};

Durable Objects¶

Qué son¶

Durable Objects son una pieza clave de la plataforma Workers para coordinación global y almacenamiento consistente. Cloudflare los describe como un mecanismo de cómputo stateful con unicidad global y una API transaccional de almacenamiento.[cite:80]

Qué problema resuelven¶

Muchos problemas no caben bien ni en KV ni en una base relacional remota. Por ejemplo:

Un chat donde todos los mensajes de una sala deben pasar por un único coordinador.
Una sala de videoconferencia donde hay que conocer participantes presentes en tiempo real.
Un contador que no puede perder incrementos.
Una reservación donde dos personas no deben comprar el mismo asiento.
Un documento colaborativo donde múltiples usuarios editan simultáneamente.

Todos esos escenarios comparten una necesidad: coordinación fuerte sobre un estado compartido.

Estado persistente¶

Cloudflare explica que Durable Objects proporcionan almacenamiento consistente y transaccional asociado a cada objeto.[cite:80] Cada objeto solo puede leer y modificar sus propias claves, lo que simplifica mucho el razonamiento sobre concurrencia local.

Instancias únicas¶

La característica más distintiva es la unicidad global: para un ID dado, solo existe una instancia activa de esa clase de Durable Object en el mundo al mismo tiempo.[cite:80] Esa unicidad es oro arquitectónico porque convierte problemas distribuidos difíciles en problemas secuenciales mucho más manejables.

Sincronización¶

Si todas las solicitudes relevantes de una sala o recurso pasan por la misma instancia, sincronizar se vuelve razonable. Ya no se trata de competir entre múltiples nodos ciegos, sino de centralizar la coordinación en un único actor lógico.

Concurrencia¶

Cloudflare indica que la ejecución de un Durable Object es single-threaded, aunque varios eventos puedan procesarse fuera del orden de llegada.[cite:80] Esto obliga a pensar cuidadosamente la lógica, pero sigue dando garantías mucho más fuertes que un almacén eventualmente consistente.

Casos ideales¶

Chats¶

Una sala de chat puede mapearse a un Durable Object por sala. Así, mensajes, presencia, historial reciente y conexiones WebSocket pueden coordinarse de forma consistente.[cite:80]

Salas de videoconferencia¶

La sala necesita saber quién está conectado, quién salió y qué eventos deben propagarse a todos.

Juegos¶

Un juego en tiempo real necesita una autoridad por partida o sala para evitar estados incompatibles.

Contadores¶

Si el contador debe ser exacto, Durable Objects es mucho más natural que KV.

Colaboración en tiempo real¶

Documentos, pizarras colaborativas o sesiones interactivas encuentran aquí un terreno ideal.[cite:80]

Semáforos y reservaciones¶

Cuando solo una persona puede tomar un recurso a la vez, Durable Objects permite serializar decisiones.

Integración con Workers¶

Workers suelen actuar como puerta de entrada. Reciben la solicitud pública, determinan qué Durable Object corresponde y delegan la operación.

Cliente -> Worker -> Durable Object -> Response

Ejemplo conceptual¶

export class SalaChat extends DurableObject {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/join') {
      return new Response('joined');
    }

    if (url.pathname === '/message' && request.method === 'POST') {
      const body = await request.json();
      await this.ctx.storage.put(`msg:${Date.now()}`, body.text);
      return Response.json({ ok: true });
    }

    return new Response('Not found', { status: 404 });
  }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const roomId = 'sala-general';
    const id = env.SALA_CHAT.idFromName(roomId);
    const stub = env.SALA_CHAT.get(id);
    return stub.fetch(request);
  }
};

No se trata de memorizar esta API exacta, sino de entender la idea: el Worker enruta, el Durable Object coordina.

Queues¶

Qué son¶

Cloudflare Queues es el servicio de mensajería de la plataforma. La guía oficial lo describe como un sistema de envío y recepción de mensajes con entrega garantizada, at-least once delivery, procesamiento por lotes y sin cargos de egress.[cite:80][cite:83]

Mensajería¶

Una cola sirve para desacoplar trabajo. En lugar de obligar a una solicitud HTTP a hacerlo todo antes de responder, el sistema puede registrar un mensaje y procesarlo después.

Procesamiento asíncrono¶

Este cambio de mentalidad es enorme. Una petición del usuario puede terminar en 50 ms porque solo valida y envía un mensaje. El trabajo pesado ocurre luego en un consumidor.

Retries¶

Cloudflare documenta que, cuando falla la entrega a un consumidor, el comportamiento por defecto es reintentar tres veces antes de marcar el fallo, y que ese comportamiento puede configurarse.[cite:81]

Consumidores y productores¶

Un productor envía mensajes a la cola. Un consumidor los recibe y los procesa. El productor y el consumidor pueden ser Workers distintos o funciones separadas dentro de la misma arquitectura.[cite:80]

Dead Letter Queue¶

Cloudflare define la Dead Letter Queue como el destino de mensajes que alcanzaron el límite de reintentos sin poder procesarse correctamente.[cite:84] Si no se configura una DLQ, esos mensajes pueden eliminarse al agotarse los reintentos.[cite:84]

Casos reales¶

Enviar correos¶

El usuario se registra. El Worker escribe en D1 y luego empuja a Queue un mensaje send_welcome_email. El registro no espera al SMTP.

Procesar imágenes¶

Un upload puede disparar una cola para redimensionado, validación o etiquetado posterior.

Crear miniaturas¶

Cuando un usuario sube una fotografía a R2, otra parte del sistema puede crear varias miniaturas sin bloquear la interacción principal.

Generar PDFs¶

Un sistema de constancias puede mandar a cola la generación del PDF y responder inmediatamente con un estado “procesando”.

Notificaciones¶

Email, push, Telegram o WhatsApp pueden encolarse para mejorar resiliencia.

Importaciones masivas¶

Cargar miles de registros en línea dentro de una sola petición es mala idea. Una cola permite fragmentar el trabajo.

Flujo completo¶

Usuario
   |
   v
Worker productor
   |
   v
Queue
   |
   v
Worker consumidor
   |
   v
Servicio externo / D1 / R2 / API

Ejemplo conceptual¶

export interface Env {
  EMAIL_QUEUE: Queue;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const body = await request.json();

    await env.EMAIL_QUEUE.send({
      type: 'welcome_email',
      to: body.email,
      name: body.name
    });

    return Response.json({ ok: true, status: 'queued' }, { status: 202 });
  }
};

Consumidor:

export default {
  async queue(batch: MessageBatch<any>, env: Env): Promise<void> {
    for (const message of batch.messages) {
      const payload = message.body;
      if (payload.type === 'welcome_email') {
        // llamar proveedor de email
      }
      message.ack();
    }
  }
};

La idea central es separar el tiempo de respuesta al usuario del tiempo total de procesamiento.

Vectorize¶

Qué es una base de datos vectorial¶

Cloudflare Vectorize es una base de datos vectorial distribuida globalmente orientada a aplicaciones con IA, embeddings y búsqueda semántica.[cite:82][cite:80] Su función no es reemplazar SQL ni servir como key-value, sino almacenar vectores y consultarlos por similitud.

Embeddings¶

Un embedding es una representación numérica de un objeto —texto, imagen, audio u otro contenido— diseñada para que modelos de machine learning y algoritmos de búsqueda semántica puedan comparar significado o cercanía conceptual.[cite:82]

Dicho de forma sencilla: un embedding convierte significado en números.

Búsqueda semántica¶

Si alguien pregunta “¿cómo recupero una constancia perdida?” y un documento dice “procedimiento para reemisión de constancias”, una búsqueda por palabras exactas puede fallar. La búsqueda semántica intenta encontrar esa relación de significado. Vectorize existe precisamente para ese tipo de consulta.[cite:82][cite:93]

IA y RAG¶

Cloudflare indica que Vectorize puede usarse como parte de flujos de Retrieval Augmented Generation. El patrón típico es: generar embeddings, buscar vectores similares y pasar el contexto encontrado a un modelo generativo.[cite:80][cite:82][cite:93]

Similitud¶

En una base vectorial no se consulta “WHERE nombre = ...”. Se consulta “qué elementos son más cercanos a este vector de consulta”. Esa cercanía puede medirse con distintas métricas según el modelo y el índice.

Indexación¶

Los documentos o fragmentos se transforman en embeddings y luego se indexan. Cloudflare explica que Vectorize permite almacenar embeddings de cualquier modelo, incluidos los generados por Workers AI, y filtrarlos por metadata para reducir espacio de búsqueda.[cite:80][cite:82][cite:85]

Casos reales¶

Chatbots¶

Un chatbot institucional puede recuperar fragmentos relevantes de reglamentos, manuales o políticas antes de formular una respuesta.

Buscadores¶

Un motor de búsqueda documental puede encontrar documentos por significado, no solo por coincidencia exacta de palabras.

IA educativa¶

Sistemas como IA El Profe pueden buscar explicaciones, materiales o respuestas previas relevantes para construir contexto.

Documentación¶

La documentación técnica de una plataforma educativa puede indexarse en fragmentos para responder preguntas del personal.

Preguntas y respuestas¶

Un sistema de Q&A sobre trámites escolares o credenciales digitales es un caso muy natural.

Integración con Workers AI¶

Cloudflare documenta una integración directa entre Workers AI y Vectorize para generar embeddings y consultarlos desde Workers.[cite:85][cite:82]

Flujo completo¶

Consulta del usuario
      |
      v
Workers AI genera embedding
      |
      v
Vectorize busca similitud
      |
      v
Resultados relevantes
      |
      v
Worker arma contexto
      |
      v
Workers AI / LLM genera respuesta

Ejemplo conceptual¶

const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
  text: ['¿Cómo repongo una credencial escolar?']
});

const vector = embeddings.data[0];

const results = await env.VECTORS.query(vector, {
  topK: 5,
  returnMetadata: true
});

Cloudflare presenta este patrón como una manera de construir aplicaciones con búsqueda, recomendación, clasificación y detección basada en datos propios.[cite:82][cite:85]

Comparativa detallada¶

La mejor forma de entender estos servicios es compararlos por tipo de problema.

Servicio	Tipo de dato / problema	Fortalezas	Cuándo elegirlo
KV	Key-value distribuido	Lecturas globales rápidas, caché interna, TTL, configuración y sesiones.[cite:80][cite:86]	Cuando el dato se lee mucho, cambia poco y no requiere consistencia inmediata.
D1	SQL relacional	Consultas ad-hoc, joins, esquema estructurado, datos persistentes.[cite:80]	Cuando hay relaciones entre entidades y necesidad de SQL.
Durable Objects	Estado consistente y coordinación	Unicidad global, almacenamiento transaccional, coordinación en tiempo real.[cite:80]	Cuando un recurso necesita una autoridad única o sincronización fuerte.
Queues	Mensajería asíncrona	Entrega garantizada, retries, batching, DLQ.[cite:80][cite:81][cite:84]	Cuando el trabajo no debe ejecutarse dentro de la solicitud principal.
Vectorize	Vectores y similitud	Búsqueda semántica, embeddings, RAG, metadata filtering.[cite:80][cite:82]	Cuando el problema es significado, similitud o recuperación semántica.

Comparación con tecnologías externas¶

Tecnología	Se parece a	Diferencia principal
Firebase Firestore	D1 o KV en ciertos casos	Firestore es documental y no relacional; no sustituye coordinación fuerte ni búsqueda vectorial por sí solo.
Redis	KV o Durable Objects según patrón	Redis puede servir como cache o estado rápido, pero Cloudflare separa esos usos entre KV y Durable Objects.[cite:80]
RabbitMQ	Queues	RabbitMQ es un broker completo de mensajería; Queues ofrece una alternativa integrada en Workers.[cite:80]
Kafka	Queues / streaming	Kafka se orienta a flujos y logs de eventos a gran escala; Queues se enfoca en procesamiento asíncrono gestionado.[cite:80]
Pinecone	Vectorize	Ambos resuelven vectores, pero Vectorize vive dentro de Cloudflare y se integra con Workers AI.[cite:82][cite:85]
Weaviate	Vectorize	Weaviate es una base vectorial especializada con otro ecosistema; Vectorize simplifica un stack Cloudflare nativo.[cite:82]
Supabase Vector	Vectorize	Supabase se basa en Postgres; Vectorize es un servicio específico para embeddings y búsqueda semántica distribuida.[cite:82]

La decisión correcta no depende del marketing, sino de la forma del problema.

Arquitecturas modernas¶

Cloudflare sugiere claramente que una aplicación puede combinar múltiples productos de datos y almacenamiento dentro de una misma arquitectura.[cite:80] Esa combinación no es una excepción; es el patrón esperado.

Ejemplo base¶

Cliente
  |
  v
Workers
  |------------------> KV (config, sesiones, flags)
  |------------------> D1 (usuarios, roles, relaciones)
  |------------------> R2 (archivos, imágenes, PDFs)
  |------------------> Queues (tareas asíncronas)
  |------------------> Durable Objects (coordinación en tiempo real)
  |------------------> Vectorize (búsqueda semántica)
  v
Respuesta

Workers + KV¶

Útil para configuración, personalización, sesiones y cachés de lectura intensiva.[cite:80][cite:86]

Request -> Worker -> KV -> Worker -> Response

Workers + D1¶

Útil para datos relacionales estructurados y operaciones de negocio persistentes.[cite:80]

Request -> Worker -> D1 -> Worker -> Response

Workers + Durable Objects¶

Útil cuando el Worker necesita delegar la coordinación de una entidad única: una sala, un documento, un contador o una reservación.[cite:80]

Request -> Worker -> Durable Object -> Storage -> Response

Workers + Queues¶

Útil cuando el trabajo debe diferirse: email, PDFs, miniaturas, sincronizaciones, importaciones.[cite:80][cite:81]

Request -> Worker productor -> Queue -> Consumer -> Servicio externo

Workers + Vectorize¶

Útil cuando el Worker necesita generar embeddings, consultar similitud y construir contexto para IA.[cite:82][cite:85]

Pregunta -> Worker -> Workers AI -> Vectorize -> Worker -> Respuesta

Casos reales¶

NLink¶

Un acortador de enlaces moderno podría repartirse así:

D1 para enlaces creados, usuarios propietarios, expiración y reglas administrativas.[cite:80]
KV para cachear resoluciones de códigos muy populares y feature flags del servicio.[cite:80][cite:86]
Queues para registrar clics o generar estadísticas sin bloquear redirecciones.[cite:80]

¿Por qué esta combinación? Porque resolver una URL corta requiere velocidad extrema, pero administrar enlaces, dueños y expiraciones exige persistencia estructurada.

IA El Profe¶

Un sistema de IA educativa puede usar:

Vectorize para embeddings y recuperación semántica.[cite:82]
Workers AI para generar embeddings y respuestas.[cite:85]
R2 para documentos fuente y materiales pesados.[cite:82][cite:80]
D1 para usuarios, historial y permisos.[cite:80]
Queues para indexación asíncrona de nuevo contenido.[cite:80]

Esta es una arquitectura de libro para RAG educativo.

Credenciales Digitales¶

D1 para alumnos, escuelas, credenciales y bitácoras.[cite:80]
R2 para fotografías y PDFs.[cite:80]
KV para configuración institucional y validaciones de lectura frecuente.[cite:80][cite:86]
Queues para generación de constancias, credenciales PDF y notificaciones.[cite:80]

Sistema Escolar¶

D1 para estructura académica: alumnos, cursos, docentes, grupos, evaluaciones.[cite:80]
KV para catálogos globales o preferencias.[cite:80]
Queues para importaciones, sincronizaciones y reportes pesados.[cite:80]
Durable Objects para módulos de colaboración o coordinación en tiempo real, por ejemplo una sala viva de clase o control de turnos.[cite:80]

Sistema de Notificaciones¶

El corazón aquí es Queues. El Worker registra el evento, manda mensaje a la cola y el consumidor decide si enviar correo, push, Telegram o WhatsApp.[cite:80][cite:81]

Chat de soporte¶

El núcleo ideal es Durable Objects porque cada conversación o sala necesita estado coordinado y, frecuentemente, WebSockets o sincronización fuerte.[cite:80]

Generador de constancias¶

D1 para datos estructurados.
R2 para PDF final.
Queues para renderización asíncrona.
KV para plantillas o configuraciones leídas intensamente.

Motor de búsqueda documental¶

R2 para documentos fuente.
Vectorize para embeddings e índice semántico.[cite:82]
Workers AI para embeddings y respuestas.[cite:85]
D1 para metadatos administrativos, permisos o auditoría.[cite:80]

Diagramas ASCII¶

Workers + KV¶

+---------+      +---------+      +-------------+
| Cliente | ---> | Worker  | ---> | Workers KV  |
+---------+      +---------+      +-------------+
      ^                |                  |
      +----------------+------------------+

Workers + D1¶

+---------+      +---------+      +------+
| Cliente | ---> | Worker  | ---> | D1   |
+---------+      +---------+      +------+
      ^                |              |
      +----------------+--------------+

Workers + Durable Objects¶

+---------+      +---------+      +------------------+
| Cliente | ---> | Worker  | ---> | Durable Object   |
+---------+      +---------+      +------------------+
                                      |
                                      v
                                 consistent storage

Workers + Queues¶

+---------+      +----------------+      +--------+      +----------------+
| Cliente | ---> | Worker produce | ---> | Queue  | ---> | Worker consume |
+---------+      +----------------+      +--------+      +----------------+

Workers + Vectorize¶

+---------+      +---------+      +------------+      +-----------+
| Cliente | ---> | Worker  | ---> | Workers AI | ---> | Vectorize |
+---------+      +---------+      +------------+      +-----------+
      ^                                                       |
      +---------------------- respuesta contextual ------------+

Arquitectura completa¶

[Navegador / App]
       |
       v
    [Workers]
       |-----------------------------> [KV]
       |-----------------------------> [D1]
       |-----------------------------> [R2]
       |-----------------------------> [Durable Objects]
       |-----------------------------> [Queues Producer] ---> [Queues] ---> [Consumer]
       |-----------------------------> [Workers AI] ---> [Vectorize]
       v
   [Respuesta]

Flujo de procesamiento asíncrono¶

Usuario solicita constancia
        |
        v
Worker valida datos en D1
        |
        v
Worker coloca trabajo en Queue
        |
        v
Consumer genera PDF
        |
        v
PDF se almacena en R2
        |
        v
D1 actualiza estado = listo

Buenas prácticas¶

Elegir el servicio por patrón de acceso, no por costumbre.
Usar KV para lectura global simple, no para consistencia fuerte.[cite:80]
Usar D1 cuando el dominio es relacional y requiere SQL.[cite:80]
Usar Durable Objects cuando hay coordinación estricta de un recurso único.[cite:80]
Usar Queues para desacoplar procesos largos o frágiles.[cite:80][cite:81]
Usar Vectorize solo cuando realmente hay embeddings y búsqueda semántica.[cite:82]
Mantener R2 para binarios grandes y D1 para metadatos estructurados.[cite:80]
Diseñar productores y consumidores idempotentes en Queues, porque la entrega es al menos una vez.[cite:80][cite:81]

Errores comunes¶

Guardar en D1 datos que son solo configuración global y luego sufrir latencia innecesaria.
Usar KV para algo que necesita consistencia instantánea.
Intentar resolver chat en tiempo real con una tabla SQL en lugar de un coordinador stateful.
Hacer procesamiento pesado dentro del request en lugar de moverlo a Queues.
Querer búsquedas semánticas con solo LIKE '%texto%' en SQL.
Construir una arquitectura “bonita” en el diagrama, pero sin justificar por qué cada servicio está ahí.

Curiosidades¶

Cloudflare señala que D1 y Queues están construidos sobre Durable Objects, lo que revela hasta qué punto Durable Objects es una pieza de bajo nivel importante para sistemas distribuidos dentro de la plataforma.[cite:80]
Cloudflare Access utiliza KV para almacenar y distribuir credenciales de usuario de forma segura y cercana al usuario, un ejemplo muy claro de por qué KV está pensado para lecturas globales rápidas.[cite:80]
Vectorize puede devolver resultados que referencien documentos en KV, perfiles en D1 o archivos en R2, lo que permite construir flujos de IA completos sin salir de la plataforma Cloudflare.[cite:82]

Resumen¶

Cloudflare no ofrece un único almacén universal porque los problemas modernos no tienen una única forma. KV resuelve lecturas distribuidas de baja latencia; D1 resuelve relaciones y consultas SQL; Durable Objects resuelve coordinación stateful; Queues resuelve trabajo asíncrono; y Vectorize resuelve similitud y búsqueda semántica.[cite:80][cite:82][cite:83]

La arquitectura profesional aparece cuando estas piezas se combinan con criterio. Una plataforma educativa real puede usar Workers como puerta de entrada, D1 para estructura académica, R2 para archivos, KV para configuración, Queues para tareas pesadas, Durable Objects para colaboración y Vectorize para IA documental.[cite:80][cite:82]

La pregunta correcta ya no es “¿qué base de datos debo usar?”, sino “¿qué tipo de problema estoy resolviendo en este módulo?”. Esa pregunta cambia por completo la calidad de la arquitectura.

Glosario¶

Persistencia: capacidad de conservar datos más allá de la ejecución inmediata.
Estado: situación actual de un recurso o proceso.
Key-value: modelo simple de almacenamiento basado en clave y valor.[cite:86]
Workers KV: almacén key-value global, de baja latencia y consistencia eventual.[cite:80][cite:86]
D1: base de datos relacional serverless para SQL en Cloudflare.[cite:80]
Durable Object: unidad stateful con unicidad global y almacenamiento consistente.[cite:80]
Global uniqueness: garantía de una sola instancia activa por ID de Durable Object.[cite:80]
Queue: cola de mensajes para procesamiento asíncrono.[cite:80]
Consumer: proceso que recibe y maneja mensajes de una cola.
Producer: proceso que publica mensajes a una cola.
Retry: reintento de entrega o procesamiento de un mensaje.[cite:81]
Dead Letter Queue: cola donde terminan mensajes fallidos tras agotar reintentos.[cite:84]
Embedding: representación vectorial de contenido para modelos y búsqueda semántica.[cite:82]
Vectorize: base de datos vectorial distribuida para embeddings y consultas de similitud.[cite:82]
RAG: patrón de generación aumentada por recuperación documental.[cite:80][cite:93]
Metadata filtering: filtro adicional aplicado a búsquedas vectoriales para reducir espacio de búsqueda.[cite:80][cite:82]
TTL: tiempo de vida de un dato almacenado.[cite:80]
At-least-once delivery: garantía de que un mensaje será entregado una o más veces, no exactamente una.[cite:80]
Stateful serverless: cómputo serverless que mantiene estado consistente, como Durable Objects.[cite:80]
Semantic search: búsqueda por significado y similitud conceptual.[cite:82][cite:93]

20 preguntas de autoevaluación¶

¿Por qué una sola base de datos no resuelve todos los problemas de una aplicación moderna?[cite:80]
¿Qué tipo de problema resuelve Workers KV?[cite:80][cite:86]
¿Qué significa que KV sea eventually consistent?[cite:80]
¿En qué casos KV es una mala elección?
¿Qué hace especial a Durable Objects frente a KV o D1?[cite:80]
¿Qué significa la unicidad global de un Durable Object?[cite:80]
¿Por qué Durable Objects es adecuado para chat o colaboración en tiempo real?[cite:80]
¿Qué ofrece Queues que no ofrece una petición HTTP directa?[cite:80]
¿Qué significa at-least-once delivery en Queues?[cite:80]
¿Qué papel cumplen los retries en una cola?[cite:81]
¿Qué es una Dead Letter Queue y cuándo se utiliza?[cite:84]
¿Qué es un embedding?[cite:82]
¿Qué diferencia hay entre búsqueda semántica y búsqueda por palabras clave?[cite:82][cite:93]
¿Qué problema resuelve Vectorize?[cite:82]
¿Cómo se integra Vectorize con Workers AI?[cite:85]
¿Cuándo conviene usar D1 y cuándo KV dentro del mismo sistema?[cite:80]
¿Cómo justificarías el uso de Queues en un generador de constancias?
¿Qué servicio elegirías para un contador exacto compartido y por qué?[cite:80]
¿Qué arquitectura usarías para una IA educativa basada en documentos?[cite:82][cite:85]
¿Cómo combinarías Workers, D1, KV, R2, Queues, Durable Objects y Vectorize en una plataforma educativa completa?[cite:80][cite:82]

Proyecto práctico¶

El objetivo del proyecto es diseñar la arquitectura completa de una plataforma educativa moderna utilizando todos los servicios estudiados. La meta no es “usar todo porque sí”, sino justificar técnicamente por qué cada pieza existe.

Módulos del sistema¶

La plataforma tendrá estos módulos:

Portal web y API.
Autenticación y sesiones.
Gestión académica.
Credenciales digitales.
Repositorio documental.
IA educativa para búsqueda y preguntas.
Notificaciones.
Chat de soporte.
Procesamiento de constancias y tareas pesadas.

Selección de servicios¶

Workers¶

Workers será la puerta de entrada HTTP para APIs, middlewares, validación y orquestación. Cloudflare lo posiciona como la capa serverless central para conectar bindings a servicios de datos y almacenamiento.[cite:83][cite:86]

R2¶

R2 almacenará fotografías, constancias PDF, materiales didácticos, videos y documentos binarios. Cloudflare lo recomienda para objetos no estructurados y archivos grandes.[cite:80]

D1¶

D1 almacenará usuarios, escuelas, docentes, alumnos, cursos, inscripciones, roles, credenciales, bitácoras y metadatos documentales. Es el componente relacional del sistema.[cite:80]

KV¶

KV guardará configuración por institución, feature flags, sesiones de lectura intensiva, catálogos y cachés persistentes de consultas frecuentes.[cite:80][cite:86]

Queues¶

Queues manejará generación de constancias, envío de correos, procesamiento de imágenes, indexación de documentos y otras tareas asíncronas que no deben ejecutarse dentro del request principal.[cite:80][cite:81]

Durable Objects¶

Durable Objects coordinará el chat de soporte, la presencia en salas, posibles turnos de atención y contadores exactos por sesión o aula virtual. Su valor aquí es la coordinación stateful estricta.[cite:80]

Vectorize¶

Vectorize almacenará embeddings de reglamentos, manuales, constancias, preguntas frecuentes y materiales educativos para ofrecer búsqueda semántica y soporte a la IA institucional.[cite:82][cite:85]

Diagrama completo de arquitectura¶

[ Navegador / App móvil ]
           |
           | HTTPS
           v
      [ Cloudflare Workers ]
           |
           |-- valida sesión ------------------------------> [ KV ]
           |
           |-- consulta datos estructurados --------------> [ D1 ]
           |
           |-- lee/sube archivos --------------------------> [ R2 ]
           |
           |-- coordina chat/turnos -----------------------> [ Durable Objects ]
           |
           |-- encola tareas ------------------------------> [ Queues ]
           |                                                  |
           |                                                  v
           |                                            [ Consumers ]
           |                                                  |
           |                     +----------------------------+---------------------------+
           |                     |                            |                           |
           |                     v                            v                           v
           |                  [ R2 ]                       [ D1 ]                 [ APIs externas ]
           |
           |-- genera embeddings con Workers AI ---------> [ Workers AI ]
           |                                                  |
           |                                                  v
           |----------------------------------------------> [ Vectorize ]
           |
           v
      [ Respuesta al usuario ]

Recorrido de una solicitud¶

Imaginemos una solicitud real: un alumno entra al portal, busca “cómo descargar mi constancia”, luego pide generar una nueva.

El navegador envía una petición HTTPS al Worker.
El Worker valida la sesión consultando KV, donde se guardan datos de acceso de lectura frecuente.[cite:80]
El Worker consulta D1 para recuperar identidad, permisos y datos académicos del alumno.[cite:80]
Si el alumno lanza una pregunta en lenguaje natural, el Worker genera un embedding con Workers AI y consulta Vectorize para encontrar fragmentos documentales relevantes.[cite:82][cite:85]
Si la solicitud es “genera mi constancia”, el Worker valida reglas en D1 y coloca un mensaje en Queues.[cite:80][cite:81]
Un consumer procesa el mensaje, genera el PDF, lo sube a R2 y actualiza D1 con el estado del documento.[cite:80]
Si el alumno abre el chat de soporte, el Worker enruta la sesión hacia un Durable Object responsable de esa sala o conversación.[cite:80]
Finalmente, el Worker devuelve la respuesta apropiada al cliente: confirmación, estado, enlace firmado o contenido contextual.

Justificación técnica¶

Esta arquitectura funciona porque cada servicio resuelve un problema diferente:

KV reduce latencia para datos simples y altamente leídos.[cite:80]
D1 organiza el dominio relacional de la institución.[cite:80]
R2 evita meter binarios en SQL.[cite:80]
Queues desacopla trabajo pesado y frágil.[cite:80][cite:81]
Durable Objects resuelve coordinación consistente de recursos compartidos.[cite:80]
Vectorize permite significado y recuperación semántica, algo que ni D1 ni KV están diseñados para hacer.[cite:82]

Evolución por fases¶

Fase 1:
Workers + D1 + R2 + KV

Fase 2:
Añadir Queues para PDFs, emails e importaciones

Fase 3:
Añadir Durable Objects para chat, presencia y coordinación en tiempo real

Fase 4:
Añadir Workers AI + Vectorize para búsqueda semántica e IA institucional

Conclusión del proyecto¶

El valor pedagógico de este proyecto no está en memorizar servicios, sino en aprender a detectar la forma del problema. Si el dato es simple y se lee por todo el mundo, KV suele ser una gran respuesta. Si el dominio es relacional, D1 es más natural. Si hace falta coordinación estricta, Durable Objects. Si el trabajo debe diferirse, Queues. Si se busca por significado, Vectorize.[cite:80][cite:82]

Ese criterio es el que separa una aplicación funcional de una arquitectura profesional.