Docs
Las 37 medidas del modelo semántico, con descripción, fórmula, rango, grain y cómo interpretarlas.
Esta página detalla cada una de las 37 medidas declaradas en ANALYTICS_MEASURES.
Las medidas son contratos: declaran su nombre, fórmula textual, unidad, escala, tipo de agregación y grain. El SQL que las materializa vive en los recipes.
Cómo leer cada entrada
- Fórmula — lo que declara la definición. No es el SQL literal, es la expresión conceptual.
- Escala — rango en el que queda el valor:
raw(sin cota),0_1,0_100,1_5,minus1_1(−1..1),minus2_2(−2..2). - Grain — la fila sobre la que opera la medida.
response= una fila por respuesta;entity_response= una por entidad detectada dentro de una respuesta;entity/attribute/source/engine/persona/time_bucket/funnel_stage= agrupaciones de mayor nivel. - Cómo leerlo — cómo convertir el número en una frase de negocio.
Volumen
Cuentas brutas. Escala raw, sin cota superior. Alimentan todos los ratios.
totalResponses
Total de responses en el scope. Cuenta todas las respuestas producidas por el pipeline en el run/proyecto/ventana filtrada.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
count(responses) | raw | count | response |
Cómo leerlo — es el denominador universal. Si vale 0, el scope está vacío (el filtro no matchea nada, o el run no ha producido nada todavía).
brandedResponses
Responses con al menos una entidad en scope. Subconjunto de totalResponses que tienen al menos una mención de una entidad registrada en el proyecto (own o competitor).
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
countDistinct(entity_metrics.response_id) | raw | count | response |
Cómo leerlo — brandedResponses / totalResponses te dice qué porcentaje de las respuestas del LLM en ese scope contienen información útil de marca. Si el ratio es muy bajo (p. ej. 0.1) probablemente los prompts son demasiado genéricos o los modelos evaden mencionar marcas.
ownResponses
Responses donde aparece una entidad propia. Cuenta responses distintas en las que al menos una mención es de una entidad con relación own.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
countDistinctIf(response_id, entity_relation = 'own') | raw | count | response |
Cómo leerlo — es el numerador de responseShareOfVoice. Se cuenta por response distinto: que tu marca aparezca tres veces en la misma respuesta cuenta como 1, no como 3.
totalMentions
Total de menciones de entidad. Suma las menciones individuales (no las responses). Una respuesta con 5 menciones cuenta 5.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
sum(mention_count) | raw | sum | entity_response |
Cómo leerlo — prefiere totalMentions cuando quieras medir volumen bruto de presencia (p. ej. densidad discursiva). Prefiere brandedResponses cuando quieras medir cobertura (en cuántas conversaciones apareciste).
ownMentions
Menciones atribuidas a entidades propias. Suma las menciones solo de las filas con entity_relation = 'own'.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
sumIf(mention_count, entity_relation = 'own') | raw | sum | entity_response |
Cómo leerlo — es el numerador de mentionShareOfVoice. Cuenta repeticiones: si el LLM repite tu marca tres veces en una respuesta, aporta 3 a esta cifra.
coverageCount
Responses distintas representadas por un cohort. Cuenta responses únicas dentro del corte actual (p. ej. “responses donde aparece la marca Nike en este segmento”).
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
countDistinct(response_id) | raw | count | response |
Cómo leerlo — no responde una pregunta por sí sola; es el numerador de coverageRate. Es ownResponses cuando el cohort es “mis marcas” y es genérico en cualquier otro agrupamiento.
recommendationCount
Filas con entidad en rol de recomendación positiva. Cuenta responses-entidad con la flag is_recommendation = 1, que se activa cuando una mención es subject con sentimiento ≥ 4.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
sum(is_recommendation) | raw | sum | entity_response |
Cómo leerlo — el LLM no solo menciona la marca; la recomienda como sujeto principal con sentimiento positivo. Es la cifra más cerca del valor comercial directo.
attributeMentions
Menciones de atributo. Total de asociaciones atributo-entidad detectadas (ej. “Nike” × “cómodo”). Una mención por par entidad-atributo y respuesta.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
count(attribute_mentions) | raw | count | attribute |
Cómo leerlo — volumen de narrativa cualitativa. Si es bajo relative a totalMentions, el LLM habla de marcas sin caracterizarlas (p. ej. listados).
businessImpactTotal
Business impact agregado. Suma de business_impact_score (0–100 por fila) a través de un cohort.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
sum(business_impact_score) | raw | sum | entity, etc. |
Cómo leerlo — métrica compuesta. Útil para comparar “peso total” de una marca entre períodos o entre competidores. No interpretes el valor absoluto: interpreta diferencias.
totalSourceMentions
Total de citas de fuente en el scope. Cuenta filas de response_sources (una por URL citada por el LLM con grounding).
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
count(response_sources) | raw | count | source |
Cómo leerlo — solo existe en modo analysis (con grounding). En simulation es 0 siempre.
totalCitations
Citas totales. Alias semántico de totalSourceMentions. Mismo valor; nombre distinto por contexto (el dashboard usa “citations” en la vista de sources, “source mentions” en la de atribución).
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
count(response_sources) | raw | count | source |
responsesWithCitations
Responses que citan al menos una fuente. No todas las respuestas del LLM traen grounding; esto cuenta cuántas sí.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
countDistinct(response_id) | raw | count | response |
Cómo leerlo — responsesWithCitations / totalResponses da el ratio de respuestas “con fundamento”. Varía mucho por engine: un modelo con navegación web lo tendrá alto; uno offline, muy bajo.
Share
Ratios y proporciones. Escala 0_1 (o percent 0–100 en casos excepcionales). Siempre pasan por safeRatio cuando se computan fuera de SQL.
responseShareOfVoice
Share of Voice por responses (SoV). De todas las respuestas del scope, qué fracción mencionan alguna entidad own.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
ownResponses / totalResponses | 0_1 | ratio | response |
Cómo leerlo — 0.33 = en un tercio de las conversaciones del scope apareces. 1.0 = apareces en todas (imposible en la práctica). Es la métrica base para comparar presencia competitiva en el tiempo.
Cuidado con — el denominador incluye respuestas que no mencionan ninguna entidad del proyecto. Si los prompts son genéricos, el denominador se infla artificialmente. Para filtrar ese ruido usa responseShareOfBrandedVoice.
responseShareOfBrandedVoice
Share of Branded Voice (SBoV). De las respuestas que sí mencionan alguna marca conocida, qué fracción te mencionan a ti.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
ownResponses / brandedResponses | 0_1 | ratio | response |
Cómo leerlo — responde a “cuando el LLM habla del mercado, ¿cuántas veces hablo yo?”. Elimina del denominador las respuestas donde nadie aparece. Siempre ≥ responseShareOfVoice.
mentionShareOfVoice
Share of Voice por menciones. Como SoV pero contando repeticiones dentro de cada respuesta.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
ownMentions / totalMentions | 0_1 | ratio | entity_response |
Cómo leerlo — mide densidad discursiva, no cobertura. Un LLM que mencione tu marca tres veces en una respuesta pesa más aquí que un LLM que la menciona una vez en tres respuestas distintas.
Cuidado con — los LLMs repiten marcas en listas. mentionShareOfVoice alto con responseShareOfVoice bajo suele indicar que apareces mucho en pocas respuestas (listados), no que tengas presencia dispersa.
groupResponseShare
Share de un subgrupo sobre responses totales. Responses distintas del grupo actual dividido por totalResponses. Se usa cuando agregas por persona, funnel, prompt tag, etc.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
groupResponses / totalResponses | 0_1 | ratio | response |
Cómo leerlo — en una vista agregada por persona, groupResponseShare = 0.22 para “Runner 35” significa que ese segmento de personas produjo el 22 % de las respuestas del scope global.
groupBrandedResponseShare
Share de un subgrupo sobre branded responses. Misma lógica que groupResponseShare pero denominador = branded.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
groupResponses / brandedResponses | 0_1 | ratio | response |
Cómo leerlo — útil cuando quieres ponderar “peso de un subgrupo” descontando el ruido de responses sin marca.
coverageRate
Coverage rate. De las responses totales, qué fracción cubre un cohort dado.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
coverageCount / totalResponses | 0_1 | ratio | response |
Cómo leerlo — métrica genérica de cobertura. Para entidades propias, coincide con responseShareOfVoice. Para atributos o fuentes, dice qué fracción de responses contienen ese ítem.
derivedVisibilityRate
Visibility rate derivada. Métrica ad-hoc tipo ownMentions / totalResponses: mezcla menciones (numerador) con responses (denominador).
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
ownMentions / totalResponses | 0_1 | derived | response |
Cómo leerlo — puede superar 1.0 si una marca aparece varias veces por response. Es una aproximación rápida a “cuántas veces me menciona el LLM por cada respuesta del scope”.
Cuidado con — no es un share clásico. Útil como tasa de densidad, no como proporción.
positiveSentimentRate
Tasa de sentimiento positivo. Fracción de menciones con sentimiento ≥ 4 (positivo o muy positivo) sobre el total.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
(veryPositive + positive) / total | 0_1 | ratio | response |
Cómo leerlo — 0.65 = dos tercios de las menciones son positivas. Una marca con positiveSentimentRate > 0.6 y responseShareOfVoice > 0.3 está en posición dominante.
recommendationRate
Tasa media de recomendación. Media de la flag is_recommendation (0 o 1 por fila) en el cohort.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
avg(is_recommendation) | 0_1 | average | entity_response |
Cómo leerlo — 0.4 = el 40 % de las veces que apareces, apareces recomendado.
shareOfRecommendation
Share of Recommendation. Tus recomendaciones sobre el total de recomendaciones del scope (todas las marcas).
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
recommendationCount / totalRecommendationCount | 0_1 | ratio | entity_response |
Cómo leerlo — si SoV mide presencia, SoR mide valor. Una marca puede tener SoV alto y SoR bajo (la mencionan pero no la recomiendan) o al revés.
sourceCoverageRate
Cobertura de una fuente. Fracción de responses que citan una fuente concreta.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
sourceCoverageCount / totalResponses | 0_1 | ratio | source |
Cómo leerlo — si wikipedia.org tiene sourceCoverageRate = 0.45, casi la mitad de las respuestas del scope citan Wikipedia.
sourceShare
Share de una fuente. Menciones de la fuente sobre total de menciones de fuente.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
sourceMentions / totalSourceMentions | 0_1 | ratio | source |
Cómo leerlo — dominancia de una fuente en la narrativa del LLM. Alto = el modelo tira mucho de ahí.
officialPresenceRate
Presencia oficial en fuentes. Fracción de menciones de fuente que son corporativas (dominio propio o página de producto oficial).
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
corporateSourceMentions / totalSourceMentions | 0_1 | ratio | source |
Cómo leerlo — mide cuánto se sostiene tu narrativa sobre fuentes propias vs terceros. 0.8 = el 80 % de tus citaciones son de tu propio dominio; típico cuando el SEO corporativo es fuerte. Bajo puede indicar que terceros (prensa, reviews) dominan tu narrativa.
engineCitationShare
Share de citations por engine. Citaciones de un engine sobre total de citations del scope.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
engineCitations / totalCitations | 0_1 | ratio | engine |
Cómo leerlo — algunos modelos citan más que otros. Si Gemini domina este share en un run con 3 modelos, es porque genera más citations, no porque “valga más”.
businessImpactGrowthRate
Crecimiento de business impact. Delta porcentual de businessImpactTotal respecto a la ventana previa.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
((current - previous) / previous) * 100 | raw (percent) | derived | entity |
Cómo leerlo — +18 = subiste un 18 %. 0 cuando previous = 0 (helper growthRate clampea para evitar infinitos).
Score
Puntuaciones compuestas con escala acotada. Se calculan en la capa 1 (worker) y se promedian en la capa 2.
avgVisibilityScore
Visibility score medio. Media de la columna visibility_score precomputada por fila.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
avg(visibility_score) | 0_1 | average | entity |
Cómo leerlo — visibility_score combina sentiment + position + mention ponderados (calculators.ts). Es el indicador único más usado; proxy de “¿cómo estoy en los LLMs?”. Un valor sobre 0.6 es fuerte, bajo 0.3 es débil. La interpretación depende del mercado.
avgBusinessImpactScore
Business impact score medio (0–100). Extiende visibility añadiendo competitive_score (tu ranking vs competidores en cada response).
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
avg(business_impact_score) | 0_100 | average | entity |
Cómo leerlo — el compuesto más completo. Mezcla cuatro factores con pesos canónicos (sentiment 0.30, position 0.25, mention 0.25, competitive 0.20). A diferencia de visibility, penaliza estar detrás de competidores aunque tu narrativa sea positiva.
avgAttributeIntensity
Intensidad media de atributo. Media de la columna intensity de attribute_mentions (el LLM puntúa cuán fuertemente asocia el atributo a la entidad).
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
avg(attribute_mentions.intensity) | 0_1 | average | attribute |
Cómo leerlo — 0.9 = la asociación atributo-entidad es fuerte, casi definitoria. 0.3 = aparece mencionada pero como matiz.
Position
Dónde aparece la entidad dentro de la respuesta. Números bajos = antes.
avgPositionScore
Position score normalizado. Media de position_score, que se calcula en la capa 1 como share del peso logarítmico (1 / log(position + 2)) sobre el peso total del response.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
avg(position_score) | 0_1 | average | entity |
Cómo leerlo — 1.0 = eres la única entidad y apareces primero. 0.5 = mitad del “peso posicional” del response es tuyo. Ver detalle del cálculo en Métricas · Computation § Position score.
avgMentionPosition
Posición media bruta. Media del índice 0-based donde aparecen las menciones. No está normalizado — depende del largo del response.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
avg(avg_mention_position) | raw | average | entity |
Cómo leerlo — 2.1 significa que apareces en posición 2 o 3 de media. Cuanto más bajo, más prominente. Solo comparable dentro del mismo run o prompt type.
Sentiment
El LLM devuelve sentimiento en escala 1..5. El sistema ofrece tres vistas: la escala original, la normalizada −1..1, y deltas entre ventanas temporales.
avgSentimentScore5
Sentimiento medio (1..5). Media directa de la columna sentiment tal como la devuelve el LLM.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
avg(sentiment) | 1_5 | average | attribute |
Cómo leerlo — 3.0 = neutral. 4.2 = positivo consistente. 2.0 = negativo. Útil cuando necesitas preservar la escala original (p. ej. comparar con estudios que usan el 1–5 como convención).
avgSentimentNormalized
Sentimiento medio normalizado (−1..1). Aplica (x − 3) / 2 a cada mención y promedia.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
avg(sentiment_score) | minus1_1 | average | entity |
Cómo leerlo — 0 = neutral. +1 = muy positivo uniforme. -1 = muy negativo uniforme. Esta es la escala que usa el dashboard en la mayoría de charts, porque soporta bien el centrado en cero.
sentimentDelta
Delta de sentimiento. Diferencia entre el sentimiento actual y el de la ventana anterior (misma granularidad temporal).
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
currentSentiment - previousSentiment | minus2_2 | delta | time_bucket |
Cómo leerlo — +0.4 = el sentimiento subió significativamente. El rango teórico es [-2, 2] (saltar de −1 a +1). En la práctica todo lo > |0.3| es noticia.
avgAttributeSentimentScore5
Sentimiento medio por atributo (1..5). Como avgSentimentScore5 pero agregado por atributo, no por entidad.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
avg(attribute_mentions.sentiment) | 1_5 | average | attribute |
Cómo leerlo — responde a “¿qué sentimiento hay cuando el LLM asocia tu marca a ‘cómodo’?”. Atributo-nivel, no entidad-nivel.
avgAttributeSentimentNormalized
Sentimiento medio normalizado por atributo (−1..1). Equivalente normalizado del anterior.
| Fórmula | Escala | Agregación | Grain |
|---|---|---|---|
normalize(avg(attribute_mentions.sentiment)) | minus1_1 | average | attribute |
Cómo leerlo — igual que el anterior pero en escala -1..1, útil para mezclarlo con otras métricas normalizadas en el mismo chart.
Notas transversales
own / competitor / neutral / ignored
entity_relation está denormalizada en entity_metrics en el momento de escribir. Copia el valor desde project_entities de Postgres. Consecuencia: si en un proyecto cambias una marca de competitor a own después de un run, las filas viejas conservan la relación original. Los analytics nunca se reinterpretan retroactivamente.
Denominadores que se vacían
Cualquier medida con grain response y denominador totalResponses devuelve 0 cuando el scope es vacío (vía safeRatio). No NaN, no Infinity. Los charts nunca se rompen, pero tampoco distinguen “0 % de SoV” de “no hay data”. Para esa distinción hay que mirar la totalResponses en crudo.
Diferencia visibility vs business impact
Ambos son scores compuestos. La diferencia exacta:
visibility_score= sentiment + position + mention (tres factores, normalizado por su suma de pesos).business_impact_score= los mismos tres máscompetitive_score(cuatro factores), escalado a 0–100.
Usa visibility cuando te interese la narrativa intrínseca de tu marca. Usa businessImpact cuando te interese tu posición competitiva: la misma visibility puede significar 80/100 de impact si estás solo en el mercado o 30/100 si estás quinto.