| name | run-eventql-query |
| description | Run an EventQL query against an EventSourcingDB instance. Use when the user wants to query, filter, aggregate, or analyze events using the EventQL query language. |
| allowed-tools | Bash, Read, AskUserQuestion |
Run EventQL Query
Run an EventQL query against an EventSourcingDB instance.
Shared Instructions
First read ${CLAUDE_PLUGIN_ROOT}/shared/common.md. It explains how to determine the base URL and API token, how to handle NDJSON responses, and which conventions apply. Follow it throughout this skill.
Also read ${CLAUDE_PLUGIN_ROOT}/shared/cloudevents.md when query results contain full events. It explains how events are structured, including the EventSourcingDB-specific metadata fields.
Request
This endpoint returns NDJSON:
curl -s --no-buffer -X POST \
-H "authorization: Bearer ${ESDB_API_TOKEN}" \
-H "content-type: application/json" \
-d '<REQUEST_BODY>' \
"${ESDB_URL:-http://localhost:3000}/api/v1/run-eventql-query" \
| grep -v '"type":"heartbeat"'
Request Body
{
"query": "<EventQL query>"
}
Example
curl -s --no-buffer -X POST \
-H "authorization: Bearer ${ESDB_API_TOKEN}" \
-H "content-type: application/json" \
-d "{\"query\": \"FROM e IN events PROJECT INTO e\"}" \
"${ESDB_URL:-http://localhost:3000}/api/v1/run-eventql-query" \
| grep -v '"type":"heartbeat"'
Common EventQL Patterns
- All events:
FROM e IN events PROJECT INTO e
- Filter by type:
FROM e IN events WHERE e.type == "io.eventsourcingdb.library.book-acquired" PROJECT INTO e
- Filter by subject:
FROM e IN events WHERE e.subject == "/books/42" PROJECT INTO e
- Count:
FROM e IN events WHERE e.type == "io.eventsourcingdb.library.book-borrowed" PROJECT INTO { total: COUNT() }
- Group by type:
FROM e IN events GROUP BY e.type PROJECT INTO { type: UNIQUE(e.type), count: COUNT() }
- Latest N events:
FROM e IN events ORDER BY e.time DESC TOP 10 PROJECT INTO e
Response
NDJSON stream with one line per result row:
{"type":"row","payload":{...}}
