> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nippy.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Consulta tus datos de ruletas, supply, cursos y más en lenguaje natural

## Ejemplos de lo que puedes preguntarle a tu agente

* "¿Cuántos giros de ruleta hubo esta semana vs la semana pasada?"
* "¿Qué productos se retiraron más en el último mes? Dame el top 5"
* "Compara cuánta gente se inscribió a cursos en enero vs febrero"
* "¿Cuántos asistentes tuvo cada centro este trimestre?"
* "Muéstrame la evolución diaria de premios canjeados en mayo"

Con Analytics, tú haces la pregunta en español y tu agente la convierte en la consulta adecuada contra tus datos. No necesitas saber de bases de datos — tu agente se encarga de todo.

**Tu negocio está aislado automáticamente.** Solo ves tus propios datos, sin necesidad de pasar IDs ni filtros.

## ¿Qué datos puedes consultar?

Puedes preguntar sobre estas áreas de tu negocio:

| Área        | Qué puedes preguntar                                |
| ----------- | --------------------------------------------------- |
| Ruletas     | Giros, premios ganados, tipos de regalo y fechas    |
| Supply      | Retiros de inventario por trabajador y por producto |
| Stock       | Niveles actuales de stock por producto              |
| Cursos      | Inscripciones y gente que completó cada curso       |
| Aprendizaje | Progreso de alumnos en el LMS                       |
| Asistentes  | Gente que asistió a centros y eventos               |

Tu agente sabe exactamente qué datos corresponden a cada área. Solo haz la pregunta y él elige la fuente correcta.

## Tools

### `analytics_execute_pipeline`

Haz una pregunta sobre tus datos y obtén los resultados. Úsala para consultas directas como "¿cuántos premios se canjearon este mes?".

<ParamField body="collection" type="string" required>
  Área de datos a consultar. Tu agente elige automáticamente la correcta.
</ParamField>

<ParamField body="pipeline" type="array" required>
  La consulta en sí. Tu agente la construye automáticamente a partir de tu pregunta. Es un arreglo de pasos que transforman y filtran los datos para responder exactamente lo que necesitas.
</ParamField>

**Respuesta:**

```json theme={null}
{
  "collection": "roulettesMaterializedView",
  "collection_label": "Ruletas",
  "count": 3,
  "results": [...],
  "summary": "3 resultado(s) · Ruletas"
}
```

**Ejemplo — total de giros de ruleta este mes:**

```json theme={null}
{
  "name": "analytics_execute_pipeline",
  "arguments": {
    "collection": "roulettesMaterializedView",
    "pipeline": [
      {
        "$match": {
          "createdAt": {
            "$gte": "2026-05-01T00:00:00Z",
            "$lte": "2026-05-08T23:59:59Z"
          }
        }
      },
      {
        "$group": {
          "_id": null,
          "totalSpins": {"$sum": 1},
          "totalWins": {
            "$sum": {"$cond": [{"$eq": ["$result", "win"]}, 1, 0]}
          }
        }
      }
    ]
  }
}
```

**Ejemplo — top 5 productos con más retiros:**

```json theme={null}
{
  "name": "analytics_execute_pipeline",
  "arguments": {
    "collection": "nippysupplyMaterializedView",
    "pipeline": [
      {
        "$group": {
          "_id": "$productName",
          "totalWithdrawals": {"$sum": "$quantity"}
        }
      },
      {"$sort": {"totalWithdrawals": -1}},
      {"$limit": 5}
    ]
  }
}
```

**Ejemplo — cursos completados por mes:**

```json theme={null}
{
  "name": "analytics_execute_pipeline",
  "arguments": {
    "collection": "coursesMaterializedView",
    "pipeline": [
      {
        "$match": {
          "status": "completed"
        }
      },
      {
        "$group": {
          "_id": {
            "$dateToString": {
              "format": "%Y-%m",
              "date": "$completedAt"
            }
          },
          "total": {"$sum": 1}
        }
      },
      {"$sort": {"_id": 1}}
    ]
  }
}
```

***

### `analytics_execute_pipelines`

Compara dos o más períodos o segmentos de una sola vez. Úsala para preguntas como "compara los giros de abril vs mayo" o "inscripciones Q1 vs Q2".

<ParamField body="queries" type="array" required>
  Lista de 2 a 5 consultas. Cada una con:

  * `label` (string): nombre descriptivo del corte, e.g. `"Abril 2026"`
  * `collection` (string): área de datos (tu agente la elige)
  * `pipeline` (array): la consulta (tu agente la construye)
</ParamField>

***

<Accordion title="Detalles técnicos (avanzado)">
  Si quieres escribir las consultas manualmente o necesitas los nombres exactos, aquí están los detalles:

  **Áreas de datos y sus identificadores:**

  | Área        | Identificador                 |
  | ----------- | ----------------------------- |
  | Ruletas     | `roulettesMaterializedView`   |
  | Supply      | `nippysupplyMaterializedView` |
  | Stock       | `stockLevelsMaterializedView` |
  | Cursos      | `coursesMaterializedView`     |
  | Aprendizaje | `nippyLearnMaterializedView`  |
  | Asistentes  | `attendeesMaterializedView`   |

  **Operaciones permitidas:** `$match`, `$group`, `$sort`, `$limit`, `$project`, `$unwind`, `$lookup`, `$addFields`, `$count`

  **Operaciones no permitidas:** `$out`, `$merge`, `$function`, `$accumulator`, `$where`, `$facet`

  **Límite:** máximo 100 resultados. **Fechas:** usar formato ISO 8601 (`"2026-01-01"` o `"2026-01-01T00:00:00Z"`).

  **Importante:** no incluyas `businessId` en ninguna consulta. El servidor lo inyecta solo.
</Accordion>