Text-to-Chart

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/text-to-chart.md)

ClickStack's Text-to-Chart feature allows you to create visualizations by describing what you want to see in plain text. Rather than manually selecting metrics, filters, and group-by fields, you can type a prompt such as "error rates by service over the last 24 hours" and ClickStack will generate the corresponding chart automatically.

This feature uses a large language model (LLM) to convert your text prompt into a query, then builds the visualization in the [Chart Explorer](/docs/use-cases/observability/clickstack/dashboards#navigate-chart-explorer). It works with any configured data source.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Text-to-Chart requires an [Anthropic API key](https://console.anthropic.com/). Set the `ANTHROPIC_API_KEY` environment variable when starting ClickStack.

For open source deployments, pass the key as an environment variable. The method varies by deployment type:

- Docker (All-in-One or Local Mode)- Docker (HyperDX Only)- Docker Compose- Helm

```
docker run -e ANTHROPIC_API_KEY='<YOUR_KEY>' -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest
```

```
docker run -e ANTHROPIC_API_KEY='<YOUR_KEY>' -p 8080:8080 docker.hyperdx.io/hyperdx/hyperdx-local
```

Add the variable to your `.env` file or set it directly in the `docker-compose.yaml`:

```
services:
  app:
    environment:
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
```

Pass the key using `--set`:

```
helm install my-hyperdx hyperdx/hdx-oss-v2 \
  --set env[0].name=ANTHROPIC_API_KEY \
  --set env[0].value=<YOUR_KEY>
```

## Using Text-to-Chart[​](#using-text-to-chart "Direct link to Using Text-to-Chart")

Navigate to Chart Explorer

### Navigate to Chart Explorer[​](#navigate-chart-explorer "Direct link to Navigate to Chart Explorer")

Select **Chart Explorer** from the left menu in HyperDX.

Select a data source

### Select a data source[​](#select-data-source "Direct link to Select a data source")

Choose the data source you want to visualize — for example, **Logs**, **Traces**, or **Metrics**.

Enter a text prompt

### Enter a text prompt[​](#enter-text-prompt "Direct link to Enter a text prompt")

At the top of the Chart Explorer, locate the **AI Assistant** input. Type a natural language description of the chart you want to create. For example:

- `Show error rates by service over the last 24 hours`
- `Latency breakdown by endpoint`
- `Count of events over time grouped by severity`

ClickStack converts the prompt into a query and renders the visualization automatically.

## Trying it with demo data[​](#demo-data "Direct link to Trying it with demo data")

The quickest way to try Text-to-Chart is with the [Local Mode](/docs/use-cases/observability/clickstack/deployment/local-mode-only) Docker image and the [remote demo dataset](/docs/use-cases/observability/clickstack/getting-started/remote-demo-data):

```
docker run -e ANTHROPIC_API_KEY='<YOUR_KEY>' -p 8080:8080 clickhouse/clickstack-local:latest
```

Navigate to `localhost:8080`. To connect to demo data, go to **Team Settings** and create a new connection with the following details:

- **Connection Name**: `Demo`
- **Host**: `https://sql-clickhouse.clickhouse.com`
- **Username**: `otel_demo`
- **Password**: Leave empty

Then modify each of the sources — **Logs**, **Traces**, **Metrics**, and **Sessions** — to use the `otel_v2` database. For full details on configuring sources, see the [remote demo dataset guide](/docs/use-cases/observability/clickstack/getting-started/remote-demo-data).

Once connected, open the **Chart Explorer** and try prompts against the available logs, traces, and metrics.

## Example prompts[​](#example-prompts "Direct link to Example prompts")

The following prompts demonstrate common use cases when working with observability data:

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Prompt Data source Description|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Error count by service over time` Logs Charts the frequency of errors across services|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Average request duration grouped by endpoint` Traces Shows latency patterns per endpoint|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `P99 latency by service` Traces Identifies tail latency across services|  |  |  | | --- | --- | --- | | `Count of 5xx status codes over the last 6 hours` Logs Tracks server error trends | | | | | | | | | | | | | | |

Prompts can reference any column or attribute available in your configured data sources. The more specific the prompt, the more accurate the generated chart.

## Limitations[​](#limitations "Direct link to Limitations")

- Text-to-Chart currently supports Anthropic as the LLM provider. Support for additional providers, including OpenAI, is planned for future releases.
- Only logs and traces are supported as data sources. Prometheus metrics are not yet supported.
- Chart accuracy depends on the clarity of the prompt and the structure of the underlying data. If a generated chart does not match expectations, try rephrasing the prompt or specifying column names explicitly.

## Further reading[​](#further-reading "Direct link to Further reading")

- [From text to charts: a faster way to visualize with ClickStack](https://clickhouse.com/blog/text-to-charts-faster-way-to-visualize-clickstack) — blog post introducing the feature
- [Dashboards and visualizations](/docs/use-cases/observability/clickstack/dashboards) — manual chart creation using Chart Explorer
- [Search](/docs/use-cases/observability/clickstack/search) — full-text and property search syntax
- [Configuration](/docs/use-cases/observability/clickstack/config) — all ClickStack environment variables

- [Prerequisites](#prerequisites)- [Using Text-to-Chart](#using-text-to-chart)
    - [Navigate to Chart Explorer](#navigate-chart-explorer)- [Select a data source](#select-data-source)- [Enter a text prompt](#enter-text-prompt)- [Trying it with demo data](#demo-data)- [Example prompts](#example-prompts)- [Limitations](#limitations)- [Further reading](#further-reading)

Was this page helpful?