https://github.com/camunda-community-hub/zeeqs
GraphQL API for Zeebe data
https://github.com/camunda-community-hub/zeeqs
data-lake graphql zeebe zeebe-tool
Last synced: 10 months ago
JSON representation
GraphQL API for Zeebe data
- Host: GitHub
- URL: https://github.com/camunda-community-hub/zeeqs
- Owner: camunda-community-hub
- License: apache-2.0
- Created: 2020-02-03T08:56:56.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-09-17T08:16:26.000Z (almost 2 years ago)
- Last Synced: 2024-09-17T10:52:11.800Z (almost 2 years ago)
- Topics: data-lake, graphql, zeebe, zeebe-tool
- Language: Kotlin
- Homepage:
- Size: 1.1 MB
- Stars: 62
- Watchers: 8
- Forks: 15
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-camunda-platform-8 - ZeeQS - GraphQL query API for aggregated Zeebe data (Applications)
README
ZeeQS - Zeebe Query Service
=========================
[](https://github.com/camunda-community-hub/community)
[](https://github.com/Camunda-Community-Hub/community/blob/main/extension-lifecycle.md#Unmaintained-)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/camunda-community-hub/community/blob/main/extension-lifecycle.md#compatiblilty)
> [!IMPORTANT]
> This community extension is **unmaintained** and outdated. It may not support new Camunda versions.
>
> Thank you to all [contributors](https://github.com/camunda-community-hub/zeeqs/graphs/contributors) for making it a great extension. :tada:
A [Zeebe](https://github.com/camunda/zeebe) community extension that provides a [GraphQL](https://graphql.org/) query
API over Zeebe's
data. The data is
imported from the broker using
the [Hazelcast exporter](https://github.com/camunda-community-hub/zeebe-hazelcast-exporter) and aggregated in the
service.
## :rocket: Install
### Docker
The docker image is published
to [GitHub Packages](https://github.com/orgs/camunda-community-hub/packages/container/package/zeeqs)
.
Run the following command to start the application:
```
docker run -p 9000:9000 ghcr.io/camunda-community-hub/zeeqs:latest
```
- Ensure that a Zeebe broker is running with
a [Hazelcast exporter](https://github.com/camunda-community-hub/zeebe-hazelcast-exporter)
- Forward the Hazelcast port to the docker container (default: `5701`)
- Configure the connection to Hazelcast (default: `localhost:5701`)
- `ZEEBE_CLIENT_WORKER_HAZELCAST_CONNECTION` (environment variable)
- `zeebe.client.worker.hazelcast.connection` (application.yaml)
Or, if you run it on your local machine (Linux only):
```
docker run --network="host" ghcr.io/camunda-community-hub/zeeqs:latest
```
After the application is started, the GraphQL endpoint is available under `http://localhost:9000/graphql`.
Go to http://localhost:9000/graphiql and explore the GraphQL API using [GraphiQL](https://github.com/graphql/graphiql).
### Docker Compose
For a local setup, the repository contains a [docker-compose file](docker/docker-compose.yml). It
contains multiple profiles for different configurations.
Use an in-memory database (H2):
```
docker-compose --profile in-memory up
```
Use a PostgreSQL database:
```
docker-compose --profile postgres up
```
After the application is started, the GraphQL endpoint is available under `http://localhost:9000/graphql`.
Go to http://localhost:9000/graphiql and explore the GraphQL API using [GraphiQL](https://github.com/graphql/graphiql).
### Configuration
By default, the API endpoint is available under the port `9000`. And the database is only in-memory (i.e. not
persistent).
To configure the application, look at the [application.yml](app/src/main/resources/application.yml) and
the [docker-compose file](docker/docker-compose.yml).
See [here](https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config)
on how to configure a Spring Boot application in general.
## :sparkles: Usage
The application provides a GraphQL endpoint under `/graphql`.
You can query the API via HTTP POST request and a JSON body containing the `query`.
For example:
```
curl \
-X POST \
-H "Content-Type: application/json" \
--data '{ "query": "{ processes { nodes { key } } }" }' \
http://localhost:9000/graphql
```
The best way to explore and inspect the GraphQL API is to use the integrated web-based tool [GraphiQL](https://github.com/graphql/graphiql). It is available
under http://localhost:9000/graphiql.
### Queries
The GraphQL API provides the following queries:
- [processes](graphql-api/src/main/resources/graphql/Process.graphqls)
- [processInstances](graphql-api/src/main/resources/graphql/ProcessInstance.graphqls)
- [jobs](graphql-api/src/main/resources/graphql/Job.graphqls)
- [userTasks](graphql-api/src/main/resources/graphql/UserTask.graphqls)
- [messages](graphql-api/src/main/resources/graphql/Message.graphqls)
- [incidents](graphql-api/src/main/resources/graphql/Incident.graphqls)
- [decisions](graphql-api/src/main/resources/graphql/Decision.graphqls)
- [decisionEvaluations](graphql-api/src/main/resources/graphql/DecisionEvaluation.graphqls)
- [errors](graphql-api/src/main/resources/graphql/Error.graphqls)
Example query
Query all processes including their number of process instances:
```graphql
{
processes {
totalCount
nodes {
key
bpmnProcessId
version
processInstances {
totalCount
}
}
}
}
```
Response:
```json
{
"data": {
"processes": {
"totalCount": 3,
"nodes": [
{
"key": "2251799813685249",
"bpmnProcessId": "demo-process",
"version": 1,
"processInstances": {
"totalCount": 3
}
},
{
"key": "2251799813685251",
"bpmnProcessId": "demo-2",
"version": 1,
"processInstances": {
"totalCount": 2
}
},
{
"key": "2251799813685269",
"bpmnProcessId": "demo-3",
"version": 1,
"processInstances": {
"totalCount": 1
}
}
]
}
}
}
```
### Pagination
In order to limit the response size and the query processing, each list query uses pagination to return only a subset of
the data. By default, it returns the first 10 items of the list.
In addition to the items, the query result contains also the total count of the items.
```graphql
{
processes(perPage: 10, page: 0) {
totalCount
nodes {
key
}
}
}
```
### Filters
Some queries allow to filter the result by passing arguments in the query.
```graphql
{
processInstances(stateIn: [ACTIVATED]) {
nodes {
key
}
}
}
```
### Subscriptions
The GraphQL API provides the following subscriptions:
- [processUpdates](graphql-api/src/main/resources/graphql/Process.graphqls)
- [processInstanceUpdates](graphql-api/src/main/resources/graphql/ProcessInstance.graphqls)
- [decisionUpdates](graphql-api/src/main/resources/graphql/Decision.graphqls)
- [decisionEvaluationUpdates](graphql-api/src/main/resources/graphql/DecisionEvaluation.graphqls)
The subscriptions are exposed via WebSockets over the same endpoint `/graphql`.
Example subscription
Subscribe to any updates of process instances:
```graphql
subscription {
processInstanceUpdates {
processInstance {
key
state
}
updateType
}
}
```
Response:
```json
{
"data": {
"processInstanceUpdates": {
"processInstance": {
"key": "2251799813685251",
"state": "ACTIVATED"
},
"updateType": "ELEMENT_INSTANCE"
}
}
}
```
## Build from Source
Build with Maven
`mvn clean install`
## Code of Conduct
This project adheres to the Contributor Covenant [Code of
Conduct](/CODE_OF_CONDUCT.md). By participating, you are expected to uphold
this code. Read more about
the [Camunda Community Code of Conduct](https://camunda.com/events/code-conduct/) and how to report
unacceptable behavior.
## License
[Apache License, Version 2.0](/LICENSE)