These are the main options for a clickhouse integration metabase setup:
- Metabase → ClickHouse® via JDBC driver plugin
- Metabase → Tinybird via REST API and JSON connector
- Metabase → ClickHouse® Cloud via community-maintained connector
Metabase is an open-source BI tool widely used by engineering and product teams for self-service analytics. ClickHouse® is a columnar OLAP database that handles billions of rows in sub-second queries. Connecting the two enables fast dashboards, exploratory queries, and scheduled reports without moving data to a traditional warehouse.
A clickhouse integration metabase pipeline lets analysts explore ClickHouse® data directly from the Metabase question builder, create dashboards, and embed charts in internal tools — with real-time data visualization or scheduled refresh depending on your freshness needs.
Before you pick a connector, consider these questions:
- Do you need live queries on every dashboard load, or is a scheduled refresh sufficient?
- Does your team manage ClickHouse® infrastructure, or do you use a managed service?
- Do you also need to expose the same data as REST APIs for applications beyond Metabase?
Three ways to implement clickhouse integration metabase
This section covers the three main connector paths, with configuration and code for each.
Option 1: Metabase → ClickHouse® — JDBC driver plugin
The standard approach. Metabase supports custom JDBC driver plugins dropped into its plugins/ directory. The ClickHouse® Metabase driver (maintained by ClickHouse® and community contributors) adds ClickHouse® as a first-class database option.
How it works: download the ClickHouse® Metabase driver JAR from the official GitHub release, place it in Metabase's plugins/ folder, restart Metabase, and add ClickHouse® as a database under Admin → Databases → Add database.
Metabase database configuration (via Admin UI or environment variables):
# Metabase ClickHouse® database settings
MB_DB_TYPE=clickhouse
METABASE_CLICKHOUSE_HOST=your-clickhouse-host
METABASE_CLICKHOUSE_PORT=8123
METABASE_CLICKHOUSE_DBNAME=default
METABASE_CLICKHOUSE_USER=default
METABASE_CLICKHOUSE_PASSWORD=your_password
METABASE_CLICKHOUSE_SSL=true
Once connected, Metabase discovers ClickHouse® tables and columns. Analysts can build questions using the GUI query builder or write SQL directly. For best performance, use native SQL questions to push aggregations to ClickHouse® instead of relying on auto-generated queries:
SELECT
toDate(event_time) AS event_date,
event_type,
count() AS total_events,
uniq(user_id) AS unique_users
FROM events
WHERE event_time >= today() - INTERVAL 30 DAY
GROUP BY event_date, event_type
ORDER BY event_date DESC
When this fits:
- You run self-managed ClickHouse® or ClickHouse® Cloud and want direct database access from Metabase
- Your analysts prefer the Metabase question builder for self-service exploration
- You don't need the same data exposed as APIs for other consumers
Trade-offs: driver plugins depend on Metabase version compatibility. After Metabase upgrades, validate that the ClickHouse® driver still works. The GUI query builder may generate SQL that is not well-optimized for ClickHouse®'s columnar engine. Use native SQL questions for complex queries.
Prerequisites: ClickHouse® Metabase driver JAR, Metabase 0.45+ (or Metabase Cloud with plugin support), network access to ClickHouse® port 8123 or 8443 (TLS).
Option 2: Metabase → Tinybird — REST API and JSON connector
Tinybird sits between your data and Metabase. You define SQL Pipes in Tinybird that query ClickHouse®-backed data sources, publish them as REST API endpoints, and consume those endpoints from Metabase via the JSON connector or as embedded iframes.
How it works: Tinybird Pipes return JSON over HTTPS. Metabase can consume Tinybird data via the REST API in two ways: through a custom Metabase SDK embedding that fetches Pipe results via HTTP, or by using a scheduled script to sync Tinybird data into a Metabase-supported database (PostgreSQL, MySQL) that Metabase queries natively. Tinybird's HTTP API is not a Postgres wire protocol — it is a REST/JSON interface.
cURL example: query a Tinybird Pipe endpoint:
curl -s \
-H "Authorization: Bearer YOUR_TINYBIRD_TOKEN" \
"https://api.tinybird.co/v0/pipes/metabase_events.json?start_date=2026-03-01&limit=10000"
Python script to load Tinybird data and export for Metabase scheduled import:
import requests
import json
url = "https://api.tinybird.co/v0/pipes/metabase_events.json"
params = {"start_date": "2026-03-01", "limit": 100000}
headers = {"Authorization": "Bearer YOUR_TINYBIRD_TOKEN"}
response = requests.get(url, params=params, headers=headers)
data = response.json()["data"]
# write to a local file or upload to a Metabase-accessible storage
with open("events.json", "w") as f:
json.dump(data, f)
Metabase also supports embedding Tinybird-powered charts via the Metabase SDK — publish a Pipe as an API, render the data in a Metabase question using the REST JSON source. This gives you real-time analytics without exposing ClickHouse® infrastructure.
When this fits:
- You already use Tinybird for analytics and want to reuse the same Pipes in Metabase
- You need API-first access to the data for both Metabase and application consumers
- You want to avoid exposing ClickHouse® ports to Metabase directly
Trade-offs: adds an HTTP layer between Metabase and raw data. Metabase's GUI query builder is not directly aware of Tinybird schema — you define the shape in Pipes. Best used when you control the query layer in Tinybird and expose fixed endpoints to Metabase.
Prerequisites: Tinybird account with published Pipes, Metabase instance, Tinybird API token.
Option 3: Metabase → ClickHouse® Cloud — community connector
ClickHouse® Cloud users can use the community-maintained Metabase connector distributed as a JAR from the ClickHouse® GitHub releases. It provides improved dialect support and optimized query generation for ClickHouse® Cloud.
How it works: the connector handles TLS, authentication, and SQL dialect mapping for ClickHouse® Cloud. Configure the connection in Metabase Admin with your ClickHouse® Cloud instance hostname and credentials.
Metabase Admin → Databases → Add database (ClickHouse® Cloud):
Database type: ClickHouse
Host: your-instance.clickhouse.cloud
Port: 8443
Database name: default
Username: default
Password: your_password
Use a secure connection (SSL): enabled
Once connected, Metabase discovers schemas and tables. Both GUI query builder and native SQL questions are supported.
When this fits:
- You're on ClickHouse® Cloud and want the best-supported Metabase driver for Cloud instances
- Your team uses the Metabase question builder for self-service analytics on ClickHouse® Cloud data
- You need dialect fixes and Cloud-specific optimizations that the community connector provides
Trade-offs: community-maintained means version compatibility depends on community release cadence. Pin the driver JAR version to match your Metabase version and test upgrades before deploying. Like Option 1, complex GUI queries may need native SQL fallback.
Prerequisites: ClickHouse® Cloud account, Metabase 0.45+, ClickHouse® Metabase driver JAR pinned to a tested version.
Summary: picking the right option
| Criterion | JDBC driver | Tinybird API | Cloud connector |
|---|---|---|---|
| Setup complexity | Medium (plugin install) | Low (HTTP endpoint) | Medium (plugin install) |
| Live query | Yes | No (API polling) | Yes |
| API reuse | No | Yes (same Pipe serves API + Metabase) | No |
| GUI query builder | Yes | Limited | Yes |
| Infrastructure | Any ClickHouse® | Tinybird managed | ClickHouse® Cloud only |
| Ops burden | Medium | Low | Medium |
Decision framework: what to choose for clickhouse integration metabase
Pick based on your deployment, team skills, and data usage:
- JDBC driver plugin if you run self-managed ClickHouse® and your team manages Metabase plugins. Best for teams with an existing ClickHouse® deployment who want full query builder support.
- Tinybird API if you need the same data in Metabase and in application APIs. One Pipe, multiple consumers. Best when you serve user-facing analytics and BI from the same source.
- ClickHouse® Cloud connector if you're on ClickHouse® Cloud and want the best-supported, Cloud-optimized Metabase driver.
Bottom line: if Metabase is your only consumer, use Option 1 or Option 3. If you also serve APIs or embed analytics in your product, Option 2 (Tinybird) gives you both from a single query layer.
What does clickhouse integration metabase mean (and when should you care)?
A clickhouse integration metabase setup connects Metabase's self-service analytics interface to ClickHouse®'s analytical query engine. Metabase sends SQL queries to ClickHouse®, which returns result sets that Metabase renders as charts, pivot tables, and dashboard widgets.
You should care when your data outgrows what PostgreSQL, MySQL, or a typical data warehouse can query interactively. ClickHouse® handles billions of rows with sub-second response times for aggregation and time-series queries. Metabase makes those results accessible to non-technical users through a point-and-click interface.
The integration also matters when you need real-time data processing reflected in Metabase dashboards. ClickHouse® ingests streaming data continuously, and a live connection reflects new data on each question load.
If your workload involves fewer than a few million rows and doesn't need sub-second latency, Metabase's native PostgreSQL or MySQL connectors may be simpler. ClickHouse® is the right fit when scale and query speed are the constraints.
Schema and pipeline design
Practical schema rules for Metabase queries
Metabase generates SQL based on how analysts configure questions and dashboards. Designing your ClickHouse® schema with Metabase in mind avoids common performance issues.
Rule 1: use LowCardinality(String) for dimension columns. Metabase groups and filters by categorical columns constantly. LowCardinality reduces memory usage and speeds up GROUP BY.
Rule 2: pre-aggregate with materialized views. Metabase question queries often repeat the same aggregation. A materialized view pre-computing daily or hourly rollups makes repeated queries fast.
Rule 3: partition by time. Most Metabase dashboards filter by date range. PARTITION BY toYYYYMM(event_time) enables partition pruning on time-bounded queries.
Rule 4: avoid high-cardinality breakouts in the GUI builder. Metabase's "Group by" on a UUID or free-text column produces expensive full-column scans. Guide analysts to use pre-defined dimension columns.
Example: analytics-friendly schema
CREATE TABLE events (
event_id UInt64,
user_id UInt64,
event_type LowCardinality(String),
event_time DateTime,
country LowCardinality(String),
revenue Float64,
updated_at DateTime
)
ENGINE = ReplacingMergeTree(updated_at)
PARTITION BY toYYYYMM(event_time)
ORDER BY (user_id, event_id)
A pre-aggregation materialized view for Metabase dashboards:
CREATE MATERIALIZED VIEW events_daily_mv
ENGINE = AggregatingMergeTree()
PARTITION BY toYYYYMM(event_date)
ORDER BY (event_type, country, event_date)
AS SELECT
toDate(event_time) AS event_date,
event_type,
country,
count() AS total_events,
sumState(revenue) AS total_revenue_state,
uniqState(user_id) AS unique_users_state
FROM events
GROUP BY event_date, event_type, country
Query with: SELECT event_date, event_type, sumMerge(total_revenue_state) AS revenue, uniqMerge(unique_users_state) AS users FROM events_daily_mv GROUP BY event_date, event_type.
Point Metabase at events_daily_mv for dashboards that only need daily granularity. This typically reduces query time from seconds to milliseconds.
Failure modes
Metabase driver version mismatch after upgrade. Upgrading Metabase without re-testing the ClickHouse® driver plugin can break database connections silently. Mitigation: pin the driver JAR to a tested version in your deployment configuration and validate in a staging Metabase instance before upgrading production.
GUI query builder generating unoptimized SQL. Metabase's auto-generated SQL may not use ClickHouse®-specific features like
LowCardinality, partition pruning, or materialized views. Mitigation: use native SQL questions for dashboards with complex aggregations. Educate analysts on which Metabase questions benefit from native SQL.High-cardinality breakout queries exhausting memory. Metabase questions that group by a high-cardinality string column (e.g., raw user agent, URL path) can trigger memory-intensive operations in ClickHouse®. Mitigation: set
max_memory_usageon the ClickHouse® user profile and add query complexity limits on the Metabase database connection.Schema discovery failure after column rename. If you rename a ClickHouse® column, Metabase's cached field metadata breaks existing questions. Mitigation: treat the ClickHouse® analytical schema as a stable contract. Add columns additively; avoid renames in production tables.
TLS handshake failure with self-managed ClickHouse®. The JDBC driver requires a trusted certificate chain. Self-signed or expired certificates cause connection failures. Mitigation: use a CA-signed certificate on your ClickHouse® instance and verify
ssl=truein the connection string.
Why ClickHouse® for Metabase analytics
ClickHouse® is a columnar OLAP database optimized for analytical query patterns. Vectorized execution and columnar compression deliver sub-second aggregations on billions of rows — far beyond what a row-oriented database can handle at interactive speed.
For Metabase users, this means dashboard questions return in milliseconds even on large datasets. Analysts drill down, filter by date range, and change breakouts without waiting for multi-second query execution. This is the low latency experience that makes self-service analytics practical at scale.
ClickHouse®'s MergeTree engine family supports deduplication, time-series ordering, and pre-aggregation via materialized views — patterns that map directly to Metabase's question and dashboard model. Combined with partition pruning, ClickHouse® is one of the fastest database for analytics backends Metabase can use.
Security and operational monitoring
- Authentication: create dedicated ClickHouse® users per Metabase connection with
GRANT SELECTon required databases. Avoid thedefaultuser in production. - TLS encryption: enforce TLS. ClickHouse® Cloud uses port 8443. Self-managed instances need
https_portconfigured and a valid certificate chain. - Row-level security: use ClickHouse® row policies (
CREATE ROW POLICY) to restrict data per connection user. Combine with Metabase's sandboxing feature (Metabase Enterprise) for user-level RLS. - Query limits: set
max_execution_time,max_memory_usage, andmax_rows_to_readon the ClickHouse® user profile used by Metabase to prevent runaway queries from affecting other workloads. - Audit trail: enable
system.query_login ClickHouse® and correlate with Metabase question IDs for end-to-end query tracing.
Latency, caching, and freshness considerations
Live connections via the JDBC or Cloud connector send a query to ClickHouse® on every Metabase question load. For well-indexed queries with partition pruning, expect 50–500ms response times.
Metabase question caching (Metabase Pro/Enterprise) caches question results for a configurable TTL. For dashboards that refresh every 5 minutes, enable question caching to avoid redundant ClickHouse® queries from concurrent viewers.
Tinybird Pipes add a caching layer upstream. Pipes support response caching with configurable TTLs. A Metabase embed consuming a cached Tinybird endpoint returns in single-digit milliseconds without querying ClickHouse® directly. This is the best option for high-concurrency Metabase dashboards or embedded analytics serving many simultaneous users.
Why Tinybird is a strong fit for clickhouse integration metabase
Most teams using Metabase with ClickHouse® eventually need the same analytical data elsewhere — a product feature, an embedded chart, or a customer-facing API. Managing a separate API layer means duplicated query logic and more infrastructure.
Tinybird solves this by combining managed ClickHouse®, SQL-based Pipes, and instant REST API publishing in one platform. Define a Pipe once, and the same endpoint serves Metabase (via JSON or the REST API consumer pattern) and your product (via HTTP). This is the best database for real-time analytics serving pattern when you need both BI and API consumers.
For Metabase embedding use cases, Tinybird's API layer also handles token-based auth, rate limiting, and per-customer query parameters — removing the complexity from the Metabase side and centralizing it in Pipes.
Next step: identify your most expensive Metabase question, model it as a bounded ClickHouse® Pipe in Tinybird, and validate question load time against your p95 target before switching the production dashboard.
Frequently Asked Questions (FAQs)
What driver do I need for clickhouse integration metabase?
The ClickHouse® Metabase driver — a JAR file distributed from the ClickHouse® GitHub releases. Download the version compatible with your Metabase version, place it in the plugins/ folder, restart Metabase, and add ClickHouse® as a database under Admin → Databases.
Does clickhouse integration metabase support live query mode?
Yes. The JDBC driver and Cloud connector both support live queries. Metabase sends SQL to ClickHouse® on each question load. For well-indexed queries with time-range filters, response times are typically under 500ms.
How do I improve Metabase dashboard performance with ClickHouse®?
Three approaches: use native SQL questions to control the SQL instead of relying on the GUI query builder; create materialized views for pre-aggregated rollups matching dashboard granularity; enable Metabase question caching (Metabase Pro/Enterprise) to avoid redundant ClickHouse® queries from concurrent viewers.
Can I use clickhouse integration metabase with row-level security?
Yes. Implement row-level security at the ClickHouse® layer using row policies (CREATE ROW POLICY), and use Metabase Enterprise sandboxing for user-level data filtering at the Metabase layer. Combining both provides defense-in-depth for multi-tenant Metabase dashboards.
Does the ClickHouse® Metabase driver break on Metabase upgrades?
It can, if the driver JAR and Metabase version are not compatible. Always pin the driver JAR version, test upgrades in a staging environment before production, and check the ClickHouse® driver GitHub releases for changelog notes before upgrading Metabase.
Where does Tinybird fit in a clickhouse integration metabase architecture?
Tinybird sits between ClickHouse® and Metabase. You define Pipes (SQL queries) in Tinybird, publish them as REST API endpoints, and consume them from Metabase via the JSON connector or embedding. The same Pipe also serves application APIs — removing the need for a separate API layer on top of ClickHouse®.
