Bucle de feedback analítico

Cada interacción pública de búsqueda emite una fila en la tabla unificada SearchUsageEvent. Una sola tabla con discriminador type (search_query, zero_results, click, conversion, widget_open, filter_applied, visit) mantiene el esquema pequeño y abarata la agregación.

Bucle de extremo a extremo

Descripción

El diagrama muestra cómo una petición de búsqueda, un clic en un resultado y una conversión aterrizan todos en la tabla unificada SearchUsageEvent con una correlación queryId, y luego se agregan por índice × hora × tipo en métricas de CTR, CVR y tasa de cero resultados. El dashboard de analítica de Studio expone esas métricas, y las acciones del editor (sinónimos, curations, pesos de campo, presets) fluyen de vuelta por policy-cache al read path — cerrando el bucle sin un deploy.

flowchart LR
    classDef http fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef db fill:#fef3c7,stroke:#b45309,color:#78350f
    classDef agg fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef ui fill:#ede9fe,stroke:#6d28d9,color:#4c1d95

    subgraph Stage1["1 · Query"]
        SDK1["Customer SDK / Widget"] --> Search["/api/search/public/multi"]:::http
        Search --> Hit["TS multi_search<br/>returns hits"]
        Hit --> Resp["Response sanitized<br/>queryId attached"]
        Resp --> Ev1["recordSearchUsageAsync<br/>type=search_query"]:::db
        Hit --> Zero{"hits.length == 0?"}
        Zero -- yes --> Ev2["type=zero_results"]:::db
    end

    subgraph Stage2["2 · Click"]
        SDK2["Widget / SDK click handler"] --> Track1["/api/events/track<br/>type=result_click"]:::http
        Track1 --> Ev3["type=click<br/>{ queryId, productId, position }"]:::db
    end

    subgraph Stage3["3 · Conversion"]
        SDK3["Checkout / add-to-cart"] --> Track2["/api/events/track<br/>type=conversion"]:::http
        Track2 --> Ev4["type=conversion<br/>{ queryId, productId, conversionType }"]:::db
    end

    subgraph Stage4["4 · Aggregation (async)"]
        Ev1 --> Agg["analytics aggregation<br/>group by indexId × hour × type"]:::agg
        Ev2 --> Agg
        Ev3 --> Agg
        Ev4 --> Agg
        Agg --> CTR["CTR = clicks / search_query"]
        Agg --> CVR["CVR = conversion / click"]
        Agg --> ZRR["zero-rate = zero_results / search_query"]
    end

    subgraph Stage5["5 · Dashboard refresh"]
        CTR --> Studio["apps/saas analytics dashboard"]:::ui
        CVR --> Studio
        ZRR --> Studio
        Studio --> Tune["relevance tuning:<br/>synonyms, curations,<br/>field weights, presets"]
    end

    Tune -. feeds .-> Search

Los tipos de evento

Todos los eventos comparten la forma de fila { indexId, organizationId, type, count, metadata, createdAt }. La columna JSON metadata es el único campo flexible de esquema; tiene un límite de 4 KB.

Qué une un clic con una búsqueda

El evento search_query del servidor acuña un queryId estable y lo devuelve en la respuesta. El widget devuelve el queryId en cada evento subsiguiente de click / conversion. La agregación une por (organizationId, indexId, queryId) para calcular el click-through y la conversión por consulta y por slot de ranking.

Bucle de ajuste

El dashboard de analítica del Studio muestra los tres ratios clave (CTR, CVR, zero-rate) más drilldowns por consulta. Un editor puede actuar sobre ellos:

• añadiendo una regla de sinónimo o stemming para una consulta con muchos zero-results,
• promocionando una SKU vía curation set para una consulta poco clicada,
• ajustando pesos de campo o construyendo un preset para una consulta de conversión lenta.

Estas ediciones fluyen al read path mediante policy-cache (LRU de 60 s) — el bucle se cierra sin necesidad de deploy.

Relacionado

• Ruta de lectura — dónde se sitúa recordSearchUsageAsync.
• Ciclo de vida del conector — la contraparte del lado de ingesta que produce los documentos que se buscan y se clican.