Analytics

Analytics rules capture what your users search for - popular queries, queries with no results, per-document counters, and raw event logs - and aggregate them into collections you can search and facet like any other data.

Rule Types

Type	What It Captures
`popular_queries`	Search queries by frequency, aggregated into a destination collection as `{q, count}` documents
`nohits_queries`	Queries that returned zero results - your content-gap report
`counter`	Weighted per-document counters (e.g., click or conversion counts) accumulated onto a field of the target documents
`log`	A bounded, queryable ring of raw events

Create a Rule

POST /analytics/rules
Content-Type: application/json
X-TYPESENSE-API-KEY: YOUR_API_KEY

{
  "name": "product-popular-queries",
  "type": "popular_queries",
  "collection": "products",
  "event_type": "search",
  "params": {
    "destination_collection": "product_queries",
    "capture_search_requests": true,
    "limit": 1000
  }
}

With capture_search_requests: true, every search against the collection is captured automatically - no client changes needed. popular_queries and nohits_queries rules require params.destination_collection; counter rules require params.counter_field.

Send Explicit Events

Clients can also report events directly (clicks, conversions, or searches from systems that bypass the search API):

POST /analytics/events
Content-Type: application/json
X-TYPESENSE-API-KEY: YOUR_API_KEY

{
  "name": "product-clicks",
  "event_type": "click",
  "data": {"doc_id": "prod-42", "q": "laptop"}
}

Flush Aggregates

Aggregation into destination collections happens on flush:

POST /analytics/flush
X-TYPESENSE-API-KEY: YOUR_API_KEY

Popular/no-hits rules write {q, count} documents (counts accumulate across flushes); counter rules add their weighted deltas onto the target documents' counter field. GET /analytics/status reports pending event counts per rule.

API Reference

GET    /analytics/rules          # list rules
POST   /analytics/rules          # create a rule
GET    /analytics/rules/{name}   # get a rule
PUT    /analytics/rules/{name}   # update a rule
DELETE /analytics/rules/{name}   # delete a rule

POST   /analytics/events         # ingest an event
GET    /analytics/events         # query the event log
POST   /analytics/flush          # aggregate into destination collections
GET    /analytics/status         # pending counts per rule