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

# ClickHouse

> Query the logs, traces, and metrics your OpenTelemetry pipeline writes into ClickHouse.

Nexus can query your OpenTelemetry data in ClickHouse, to read what your services logged, traced, and measured around the time of an incident.

<Note>
  ClickHouse is connected through [Grafana](/nexus/telemetry/grafana). There's no direct ClickHouse connection, though
  self-hosted clusters can be [connected as a PostgreSQL](#connecting-direct) source instead.
</Note>

## What we support

A ClickHouse data source in Grafana is discovered as a telemetry data source in Nexus, with up to three sub-sources:

| Data source | Default tables                                                     | What it queries                                          |
| ----------- | ------------------------------------------------------------------ | -------------------------------------------------------- |
| Logs        | `otel_logs`                                                        | Log records, and trends graphed from them                |
| Traces      | `otel_traces`                                                      | A trace by ID, spans matching a search, and span metrics |
| Metrics     | `otel_metrics_gauge`, `otel_metrics_sum`, `otel_metrics_histogram` | Metric points, read as time series                       |

Logs and traces are read from whichever table your Grafana data source names, and renamed metric tables are still found.

Metrics covers gauges, counters, and explicit-bucket histograms. Exponential histograms and summaries aren't supported.

## Connecting ClickHouse

Connect [Grafana](/nexus/telemetry/grafana) with a ClickHouse data source behind it. Queries run through Grafana using its own credentials, so there's nothing separate to connect or rotate, and your cluster only needs to be reachable from Grafana. If your Grafana sits inside your network, connect it through a [proxy](/integrations/proxy).

Which signals appear depends on that data source. Logs and traces are defined by the Grafana ClickHouse plugin config, while metrics appear if the exporter's metric tables are in the connection's database.

### The user Nexus queries as

Nexus queries as the ClickHouse user configured on the Grafana data source, so give it a read-only one. The cleanest setup is a second ClickHouse data source in Grafana pointed at a dedicated user, leaving your existing one untouched:

```sql theme={null}
CREATE SETTINGS PROFILE incident_io_readonly SETTINGS readonly = 2;
CREATE USER incident_io IDENTIFIED BY 'a-strong-password' SETTINGS PROFILE incident_io_readonly;

GRANT SELECT ON otel.* TO incident_io;

GRANT SELECT ON system.tables TO incident_io;
GRANT SELECT ON system.columns TO incident_io;
GRANT SELECT ON system.data_skipping_indices TO incident_io;
GRANT SELECT ON system.parts TO incident_io;
GRANT SELECT ON system.settings TO incident_io;
```

Grant `SELECT` on your telemetry database and on the system tables above, and nothing else. Leave out the source privileges (`URL`, `S3`, `FILE`, `REMOTE`), which Nexus never needs.

Use `readonly = 2` rather than `readonly = 1`. Both refuse writes, but `readonly = 1` also blocks the limits Nexus puts on each query to cap how much of your cluster a single read can touch.

### Connecting direct

ClickHouse can speak the PostgreSQL wire protocol, so a self-hosted cluster can be connected as a [PostgreSQL](/nexus/telemetry/postgresql) data source instead. Enable ClickHouse's [PostgreSQL interface](https://clickhouse.com/docs/concepts/features/interfaces/postgresql), then connect it with its host and credentials as you would any Postgres database.

This gives you read-only SQL rather than the three signal data sources above. ClickHouse Cloud doesn't expose the interface, so it's for self-hosted clusters only.

## Related

<CardGroup cols={2}>
  <Card title="Grafana" icon="database" href="/nexus/telemetry/grafana">
    The provider ClickHouse is connected through.
  </Card>

  <Card title="How telemetry works" icon="magnifying-glass" href="/nexus/telemetry/how-it-works">
    How Nexus queries your telemetry.
  </Card>

  <Card title="ClickStack alerts" icon="bell" href="/alerts/clickstack">
    Page the right people when a ClickStack alert fires.
  </Card>
</CardGroup>