ClickHouse Driver for Metabase

Overview

About

The ClickHouse database driver is designed for the Metabase business intelligence front-end, allowing seamless integration and data visualization.

Compatibility with ClickHouse

This driver aims to support the stable and LTS releases of ClickHouse, as detailed below:

• After 1.50.1:
• 23.8+ : Supported
• 23.6 – 23.7 : Best effort
• 1.50.0 and earlier:
• 23.8+ : Supported
• 23.3 – 23.7 : Best effort

The connection impersonation feature requires a minimum ClickHouse version of 24.4.

For the CSV Uploads feature, it is only compatible with ClickHouse Cloud.

Installation Steps

Run Using Metabase Jar

1. Download a recent Metabase binary release (jar file) from the Metabase distribution page.
2. Download the ClickHouse driver jar from this repository’s Releases page.
3. Create a directory and copy the metabase.jar to it.
4. Create a sub-directory called plugins inside this directory.
5. Copy the ClickHouse driver jar to the plugins directory.
6. Navigate to the directory with your metabase.jar.
7. Run: MB_PLUGINS_DIR=.plugins; java -jar metabase.jar.

Example Command

export METABASE_VERSION=v0.49.3
export METABASE_CLICKHOUSE_DRIVER_VERSION=1.4.0
mkdir -p mbplugins && cd mbplugins
curl -o metabase.jar https://downloads.metabase.com$METABASE_VERSION/metabase.jar
curl -L -o pluginsch.jar https://github.com/ClickHouse/metabase-clickhouse-driver/releases/download/$METABASE_CLICKHOUSE_DRIVER_VERSION/clickhouse.metabase-driver.jar
MB_PLUGINS_DIR=.plugins; java -jar metabase.jar

Run as a Docker Container

1. If you prefer not to use the Metabase jar, you can utilize a Docker image.
2. Use the following command to set up your Docker environment:

export METABASE_DOCKER_VERSION=v0.49.3
export METABASE_CLICKHOUSE_DRIVER_VERSION=1.4.0
mkdir -p mbplugins && cd mbplugins
curl -L -o pluginsch.jar https://github.com/ClickHouse/metabase-clickhouse-driver/releases/download/$METABASE_CLICKHOUSE_DRIVER_VERSION/clickhouse.metabase-driver.jar
docker run -d -p 3000:3000 --mount type=bind,source=$PWD/plugins/ch.jar,destination=plugins/clickhouse.jar metabase/metabase:$METABASE_DOCKER_VERSION

Choosing the Right Version

Metabase Release and Corresponding Driver Version

Metabase Release	Driver Version
0.33.x	0.6
0.34.x	0.7.0
0.35.x	0.7.1
0.41.3.1	0.8.1
0.49.x	1.4.0

Creating a Metabase Docker Image with ClickHouse Driver

Utilize the convenience script build_docker_image.sh, and pass three arguments:

• Metabase version
• ClickHouse driver version
• Final Docker image tag

Example command:

bash build_docker_image.sh v0.49.3 1.4.0 my-metabase-with-clickhouse:v0.0.1

Operations

The driver is designed to function well under various scenarios. Here are some tips for optimizing your experience:

• Create a dedicated Metabase user with a read-only profile.
• Ensure your Metabase instance is in the same timezone as your ClickHouse database.
• Cross-verify query results with the clickhouse-client.
• Employ Metabase for better data organization and user accessibility.

Troubleshooting

If you encounter any issues, consider the following:

• AggregateFunction type columns are excluded from results due to JDBC driver limitations.
• If DateTime64 filters are malfunctioning, review potential type conversion issues.
• For filtering with non-latin strings and returned incorrect results, ensure your ClickHouse server is upgraded to 23.8+.

For more insights, updates, or to collaborate on AI development projects, stay connected with fxis.ai.

Contributing

We welcome contributions! Please check out our contributing guide for more information.

At fxis.ai, we believe that such advancements are crucial for the future of AI, as they enable more comprehensive and effective solutions. Our team is continually exploring new methodologies to push the envelope in artificial intelligence, ensuring that our clients benefit from the latest technological innovations.