# Prompt-to-Endpoint: la analítica conversacional necesita una capa semántica

> Convertir una pregunta en SQL o en un endpoint no garantiza una respuesta correcta: hacen falta definiciones, grano, ownership, tests y versionado.

- Author: Viktor Berthelius (BRTHLS)
- Published: 2026-07-29
- Category: systems thinking
- Tags: posthog, conversational-analytics, semantic-layer, data-contracts
- Language: es
- Canonical: https://www.brthls.com/magazine/prompt-to-endpoint-analitica-conversacional-capa-semantica-es
- Source: BRTHLS Magazine — https://www.brthls.com

---

## Problema

La analítica conversacional promete eliminar la fricción del dashboard: preguntas «¿qué segmento retiene mejor?» y recibes una consulta, una visualización o un endpoint listo para consumir. La interfaz mejora. La semántica no necesariamente.

«Cliente activo», «conversión», «ingreso» o «churn» parecen términos claros hasta que dos equipos los calculan con ventanas, fuentes y exclusiones distintas. Un modelo puede escribir SQL válido y devolver un número preciso que responde a la definición equivocada. Cuanto más fácil sea generar consultas, más rápido se multiplica esa divergencia.

El problema no es traducir lenguaje natural a SQL. Es decidir qué significa cada concepto y conservar esa decisión cuando la pregunta se convierte en software.

## Tesis

Un prompt no debe desplegar una métrica directamente. Debe compilarse contra una capa semántica y producir un contrato verificable.

Ese contrato necesita nombre, definición, grano, fuentes, joins permitidos, filtros por defecto, zona horaria, freshness, owner, tests y versión. Solo después tiene sentido exponer el resultado como insight o endpoint estable. La conversación sirve para expresar intención; la capa semántica decide qué cálculo está autorizado para representarla.

Llamamos **Prompt-to-Endpoint** a esa cadena: pregunta, resolución semántica, consulta revisable, validación y endpoint versionado. Sin los pasos intermedios, la comodidad de la interfaz oculta deuda de datos.

## Framework

La cadena operativa tiene cinco piezas:

- **Intención:** la pregunta de negocio y la decisión que pretende informar.
- **Semántica:** definiciones canónicas, grano, dimensiones y políticas de acceso.
- **Consulta:** SQL o insight generado con filtros y límites explícitos.
- **Contrato:** esquema de respuesta, freshness, versión, owner y comportamiento ante datos incompletos.
- **Entrega:** endpoint, dashboard o respuesta conversacional que conserva trazabilidad hacia el cálculo.

Las piezas oficiales de PostHog permiten montar parte de esta arquitectura. El editor SQL consulta eventos, personas y fuentes externas. Las views guardan consultas reutilizables, exigen alias para los campos y pueden enlazarse a modelos. Los Endpoints convierten insights o SQL predefinido en URLs estables y optimizadas. La Query API queda para análisis ad hoc y documenta límites específicos de filas, paginación y exportación.

La capa semántica es la disciplina que une esas capacidades. Es una inferencia operativa, no una funcionalidad que debamos dar por supuesta.

## Por que importa ahora

PostHog presenta una interfaz donde la IA puede responder preguntas sobre datos, mientras su documentación expone SQL, views, Query API y Endpoints. La combinación reduce la distancia entre una pregunta y un artefacto consumible por otra aplicación.

Esa distancia corta es útil para analítica embebida, feeds internos o métricas públicas. También eleva el coste de una definición incorrecta: un endpoint estable puede distribuir el mismo error a producto, operaciones y clientes durante meses.

Un caso sobre Fastr circuló como señal en newsletters recientes, pero no encontramos una fuente primaria suficiente para verificar su implementación. Por eso no se usa aquí como hecho ni como prueba. La tesis se apoya únicamente en capacidades documentadas por PostHog y en la separación explícita entre consultas ad hoc, views reutilizables y endpoints predefinidos.

La pregunta correcta ya no es «¿puede la IA crear la consulta?». Es «¿puede el equipo demostrar qué definición creó, quién la aprobó y qué consumidores romperían si cambia?».

## Anti-ejemplo

«Crea un endpoint con el churn mensual por plan».

El agente une suscripciones con eventos, decide que churn significa cancelación registrada, usa UTC y excluye cuentas sin actividad. Finanzas mide pérdida de MRR al cierre en hora local; Producto incluye downgrade; Customer Success excluye impagos recuperables. Todos reciben un número defendible, pero ninguno comparte la misma métrica.

El endpoint funciona. El sistema de decisión falla.

## Protocolo (3 pasos)

1. **Registra la métrica antes del prompt.** Define fórmula, grano, fuentes, owner, exclusiones, zona horaria y freshness.
2. **Compila a un artefacto revisable.** Guarda SQL o view, añade tests con casos conocidos y valida coste y rendimiento.
3. **Pública un contrato versionado.** Expón un endpoint estable con esquema, límites, observabilidad y política de cambio.

| Capa | Contrato mínimo | Test | Fallo que evita |
| --- | --- | --- | --- |
| término | definición y owner | revisión de negocio | ambigüedad |
| dato | fuente, grano y freshness | completitud | números obsoletos |
| consulta | joins, filtros y zona horaria | casos conocidos | SQL válido, significado falso |
| endpoint | esquema y versión | compatibilidad | consumidores rotos |
| operación | coste, rate limit y trazas | carga y alertas | analítica inestable |

## Relacionado

- [AI Observability deja de ser debugging: ahora decide margen](/magazine/ai-observability-deja-ser-debugging-ahora-decide-margen-es)
- [AI Traces: la capa que convierte agentes en sistemas auditables](/magazine/ai-traces-capa-convierte-agentes-sistemas-auditables-es)
- [Decisión Quality: el KPI que reemplaza a la velocidad](/magazine/decision-quality-kpi-reemplaza-velocidad-es)

## Fuentes consultadas

- [PostHog: plataforma de analítica y PostHog AI](https://posthog.com/)
- [Endpoints - PostHog Docs](https://posthog.com/docs/endpoints)
- [API queries - PostHog Docs](https://posthog.com/docs/api/queries)
- [Creating views - PostHog Docs](https://posthog.com/docs/data-warehouse/views)
- [SQL editor - PostHog Docs](https://posthog.com/docs/data-warehouse/sql)

## Próximo paso

Toma la pregunta analítica más repetida de tu equipo y escribe su contrato sin consultar ningún dashboard. Si dos personas discrepan sobre el grano, la ventana o las exclusiones, todavía no necesitas una interfaz conversacional: necesitas resolver la semántica.

---

_Cite as: Berthelius, V. (2026). "Prompt-to-Endpoint: la analítica conversacional necesita una capa semántica". BRTHLS Magazine. https://www.brthls.com/magazine/prompt-to-endpoint-analitica-conversacional-capa-semantica-es_