Pular para o conteúdo principal

Extracción de Datos de Elasticsearch - Sistema Builder (Post-Migración)

  • Atualizado

Indice:

  1. Introducción
  2. Estructura de datos (Índice por Eventos)
  3. Proceso de extracción de datos

 

Introducción

Esta documentación tiene como objetivo facilitar a desarrolladores, analistas de datos y equipos técnicos la transición exitosa hacia el nuevo sistema de extracción de datos de Elasticsearch posterior a la migración a Builder (Blip), proporcionando una guía completa para migrar consultas y procesos del esquema anterior (índices Tickets/Mensajes) al nuevo esquema unificado de Eventos, garantizando la continuidad operativa de reportes, dashboards y procesos automatizados, y permitiendo a los usuarios aprovechar las mejoras de rendimiento del nuevo entorno mediante la implementación de mejores prácticas de extracción de datos.

La documentación correspondiente a la extracción de datos previa a la migración se puede consultar en la siguiente entrada de Confluence. La información disponible para extracción se puede consultar en el siguiente enlace.

La presente documentación corresponde a la extracción de datos posterior a la migración del Contacto Inteligente de Flux a Builder. Se expone la información correspondiente al índice por eventos, la documentación proporcionada por elasticsearch para consulta de la API REST disponible y algunos ejemplos de consulta.

Estructura de datos (Índice por Eventos)

El Índice por Eventos de Blip es un modelo de indexación que genera un documento por cada interacción registrada en la conversación, ya sea una entrada del usuario a algún copy, un cambio de flujo o la ejecución de una acción. Esta estructura permite el análisis detallado del comportamiento de los usuarios previo a la migración y permite trabajar a futuro con eventos personalizados (compuestos por la dupla categoría/acción) disponibles para extracción. Los campos disponibles a extraer pueden consultarse en este documento.

 

Proceso de extracción de datos

La extracción de datos desde el índice por eventos se realiza utilizando la API REST _search de Elasticsearch. Esta API permite enviar consultas estructuradas para recuperar interacciones específicas del bot, almacenadas como documentos independientes dentro del índice. En el nuevo esquema post-migración, cada documento representa un evento puntual dentro de la conversación, como el ingreso a un paso (step), el envío de un mensaje, o la interacción a través de una campaña.

  1. Endpoint base

Las consultas se ejecutan sobre el índice de eventos, por ejemplo:

bash

POST /blip_builder_flags_prod/_search
 

  1. Ejemplo de consulta

A continuación se presentan consultas comunes para extraer información clave del índice por eventos, con enfoque en reportes conversacionales, encuestas, campañas y análisis de comportamiento de usuarios.

  1. Obtener eventos de calificación de encuesta

Esta consulta filtra todos los eventos donde los usuarios respondieron una encuesta (por ejemplo, valorando con una puntuación del 1 al 5). 

{
  "query": {
    "bool": {
      "must": [
        { "term": { "grade.name.keyword": "nombre_encuesta" } },
        { "range": { "date": { "gte": "now-30d/d", "lte": "now/d" } } }
      ]
    }
  },
  "size": 500,
  "_source": ["userId", "message", "date", "ticketId", "grade.number"]
}


 

  1. Obtener usuarios únicos que respondieron en cierto periodo

Con esta consulta se obtienen los userId distintos que interactuaron con el bot en un periodo determinado:

{
  "size": 0,
  "query": {
    "range": {
      "date": {
        "gte": "2025-07-01T00:00:00Z",
        "lte": "2025-07-23T23:59:59Z"
      }
    }
  },
  "aggs": {
    "usuarios_unicos": {
      "cardinality": {
        "field": "userId.keyword"
      }
    }
  }
}

  1. Obtener todos los mensajes con origen en campaña de WhatsApp


 

Filtra todos los eventos generados por una campaña de WhatsApp (WA_CAMPAIGN):

{
  "query": {
    "bool": {
      "must": [
        { "term": { "origin.keyword": "WA_CAMPAIGN" } },
     
        { "range": { "date": { "gte": "2025-07-01", "lte": "2025-07-23" } } }
      ]
    }
  },
  "size": 100,
  "_source": ["userId", "message", "campaignId", "date", "step"]
}


 

  1. Contar eventos por paso del flujo

Mide cuántos eventos ocurrieron en cada step, útil para análisis de embudo conversacional:

{
  "size": 0,
  "query": {
    "range": {
      "date": {
        "gte": "2025-07-01",
        "lte": "2025-07-23"
      }
    }
  },
  "aggs": {
    "eventos_por_paso": {
      "terms": {
        "field": "step.keyword",
        "size": 10
      }
    }
  }
}


 

  1. Traer primer mensaje del usuario por sesión

Filtra el primer evento de cada ticket (útil para analizar intenciones iniciales):

{
  "size": 0,
  "query": {
    "range": {
      "date": {
        "gte": "2025-07-01",
        "lte": "2025-07-23"
      }
    }
  },
  "aggs": {
    "por_ticket": {
      "terms": {
        "field": "ticketId.keyword",
        "size": 1000
      },
      "aggs": {
        "primer_mensaje": {
          "top_hits": {
            "size": 1,
            "sort": [{ "date": { "order": "asc" } }],
            "_source": ["message", "userId", "date"]
          }
        }
      }
    }
  }
}


 

  1. Extraer eventos de un bot específico (por tenantId)

Filtra el primer evento de cada ticket (útil para analizar intenciones iniciales):

{
  "query": {
    "bool": {
      "must": [
      
        { "range": { "date": { "gte": "2025-07-01", "lte": "2025-07-23" } } }
      ]
    }
  },
  "size": 100,
  "_source": ["userId", "message", "origin", "step", "date"]
}

  1. Buenas prácticas

Al consultar el índice por eventos en entornos de producción, es fundamental aplicar buenas prácticas que garanticen eficiencia, precisión y bajo impacto en el rendimiento del clúster. A continuación se listan recomendaciones clave: 

  1. Filtrado por rango de fechas

  • Siempre acotar las consultas con una cláusula range sobre el campo date o @timestamp, evitando exploraciones completas del índice.
  • Utilizar formato ISO (YYYY-MM-DDTHH:mm:ssZ) o expresiones relativas como now-30d/d. 
json
"range": {
  "date": {
    "gte": "now-7d/d",
    "lte": "now/d"
  }
}

  1. Uso de _source para limitar campos

  • Especificar únicamente los campos necesarios en el bloque _source para reducir el peso de la respuesta y acelerar las transferencias de datos.

"_source": ["userId", "message", "date", "step"]


 

  1. Preferencia por .keyword en filtros exactos

  • Para valores exactos en filtros (term, terms, cardinality, etc.), usar la versión .keyword del campo.

     
  • Evitar match en campos analizados para mantener precisión.

{ "term": { "tenantId.keyword": "nombre_tenant" } }


 

  1. Paginación eficiente

  • Para volúmenes pequeños, se puede usar from + size (hasta 10,000 documentos).
  • Para extracciones masivas, se recomienda:

     
    • scroll: para recorridos por lotes completos del índice (requiere manejo de _scroll_id).

       
    • search_after: para navegación por páginas basada en ordenamiento (ej. por date), evitando limitaciones de paginación estándar. 
"sort": [{ "date": "asc" }],
"search_after": ["2025-07-23T14:28:27.473Z"]


 

  1. Uso de agregaciones para métricas

  • Utilizar aggs para obtener métricas directas desde Elasticsearch (usuarios únicos, conteo por paso, etc.) sin necesidad de procesamiento posterior.
  • Ejemplo: usuarios únicos en un rango de tiempo:
"aggs": {
  "usuarios_unicos": {
    "cardinality": {
      "field": "userId.keyword"
    }
  }
}

  1. Validar consultas en entornos de desarrollo

  • Probar las consultas primero con filtros estrictos (size: 10, tenantId) para evitar sobrecargas y validar estructura de respuesta.

     

  1. Evitar match_all o consultas sin filtros

  • No ejecutar consultas sin filtros de fecha o tenant, especialmente en índices por eventos con alto volumen, para prevenir timeouts o bloqueos del clúster.

     

  1. Algunas referencias de interés

Search API: https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search

Paginate search results: https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html 

Query DSL: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html 

Keyword datatype: https://www.elastic.co/guide/en/elasticsearch/reference/current/keyword.html 

Aggregation | Elasticsearch Guide: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html

Artigos relacionados