# ClickHouse Analytics with Bonnard

> Connect Bonnard to ClickHouse and ship governed event, log, and time-series metrics to AI agents, dashboards, and your product from a YAML semantic layer.

Bonnard gives you a ClickHouse semantic layer defined in YAML, version-controlled, and queryable from AI agents, React components, and REST APIs. If your team stores event data, logs, or time-series metrics in ClickHouse, Bonnard connects directly and exposes governed data through MCP, React SDK, REST API, and markdown dashboards.

## How does Bonnard connect to ClickHouse?

Add ClickHouse as a datasource in your Bonnard project. Define the connection in your `datasources.yml`:

```yaml
# datasources.yml
datasources:
  - name: clickhouse_db
    type: clickhouse
    host: clickhouse.example.com
    port: 8443
    database: analytics
    username: bonnard_readonly
    password: ${CLICKHOUSE_PASSWORD}
    ssl: true
```

Then run:

```bash
bon datasource add clickhouse_db
bon deploy
```

Bonnard connects to your ClickHouse instance over HTTP, introspects your database, and deploys your [semantic layer](/semantic-layer). Works with self-hosted ClickHouse and ClickHouse Cloud. Your data is queryable through every Bonnard surface within minutes.

## What do you get?

Once connected, your ClickHouse data is available through four surfaces:

**[MCP](/glossary/mcp) server.** Run `bon mcp` and your AI agents (Claude, ChatGPT, Cursor) query governed ClickHouse metrics with row-level security. Generate publishable keys per tenant for customer-facing [agentic analytics](/agentic-analytics).

**React SDK.** Drop `BarChart`, `LineChart`, and `BigValue` components into your product. Every chart queries your ClickHouse database through the semantic layer with multi-tenant access controls applied automatically.

**REST API.** Query metrics programmatically from any language or platform. Type-safe queries with the TypeScript SDK or raw HTTP from anywhere.

**Markdown dashboards.** Author dashboards in markdown, deploy with `bon deploy`, and share governed views with your team or customers.

## How does Bonnard compare to querying ClickHouse directly?

| Capability | ClickHouse direct | Bonnard + ClickHouse |
|------------|------------------|---------------------|
| Metric definitions | SQL views, materialized views | YAML semantic layer (version-controlled) |
| AI agent access | None | MCP server with publishable keys |
| Embedded analytics | Build from scratch | React SDK with multi-tenant auth |
| Dashboards | Grafana, Metabase (external) | Markdown dashboards, deployed via CLI |
| Multi-tenancy | Row policies (manual) | Publishable keys + automatic row filters |
| Pre-aggregation | Materialized views, projections | Automatic pre-aggregation cache |
| Access control | ClickHouse users + quotas | YAML-defined RBAC + audit logging |
| Deployment | SQL migration scripts | `bon deploy` (no restart, no SSH) |

## FAQ

**Does Bonnard support ClickHouse?**

Yes. ClickHouse is a first-class Bonnard datasource. Both self-hosted ClickHouse and ClickHouse Cloud are supported. Configure your connection in YAML, run `bon datasource add`, and deploy.

**Is ClickHouse good for real-time analytics with Bonnard?**

ClickHouse is optimized for sub-second queries on billions of rows. Combined with the semantic layer, you get governed, real-time metrics exposed to AI agents, dashboards, and embedded charts. The pre-aggregation cache further accelerates repeated queries.

**Can I use ClickHouse materialized views with Bonnard?**

Yes. Bonnard queries your ClickHouse database as-is, including materialized views. You can also layer the pre-aggregation cache on top for additional caching. Define your cubes over ClickHouse tables or materialized views and Bonnard handles the rest.

**Does Bonnard support ClickHouse Cloud?**

Yes. Use your ClickHouse Cloud endpoint as the host in `datasources.yml`, set `ssl: true`, and provide your credentials. Bonnard connects over HTTPS. All features (MCP, React SDK, dashboards, RBAC) work with ClickHouse Cloud the same way they work with self-hosted ClickHouse.

## Related

- [DuckDB integration](/integrations/duckdb) -- another analytics-optimized engine
- [What is Pre-Aggregation?](/glossary/pre-aggregation) -- how caching reduces query load
- [What is a Semantic Layer?](/glossary/semantic-layer) -- how metric definitions work