This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new bf73475d7c9 [Doc] Update Metabase doc for the standalone community
driver (#4010)
bf73475d7c9 is described below
commit bf73475d7c9d1e4c5d15e325f4c5a0990a54fb5e
Author: Mingyu Chen (Rayner) <[email protected]>
AuthorDate: Fri Jul 24 21:15:26 2026 +0800
[Doc] Update Metabase doc for the standalone community driver (#4010)
## What this PR does
Rewrites the Metabase integration doc to match the latest **standalone
Metabase Doris community driver** (`metabase-doris-driver` v1.0.0).
Content was sourced from the updated internal doc and synced across
languages and versions.
Key changes:
- Switch to the standalone `metabase-doris-driver` v1.0.0, with download
+ SHA-256 checksum verification steps
- New prerequisites: Java 21 and Metabase `0.59.6.3`+
- Expanded connection parameters (`Catalog`, `Database (optional)`,
`SSL`, `Sync Schemas Include/Exclude`, additional JDBC options) and
Catalog/database scoping behavior
- New **Driver capabilities and limitations** section
- New **Doris → Metabase data type mapping** section
Existing `metabase-01..15.png` image assets are reused; no images added
or renamed.
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
- [ ] Japanese candidate translation needed
## Docs Checklist
- [x] Checked by AI
- [ ] Test Cases Built
- [x] Updated required version and language counterparts, or explained
why not
- [x] If only one language changed, confirmed whether source/translation
counterparts need sync
> Note: 3.x / 2.1 still use the older `ecosystem/bi/metabase.md` layout
describing the previous driver, so they are intentionally left
unchanged. The Japanese doc has not been migrated to the new
`connection-integration/data-integration` path yet, so it is not updated
here.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: morningman <[email protected]>
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
---
.../data-integration/metabase.md | 161 ++++++++++++++-----
.../data-integration/metabase.md | 173 +++++++++++++++------
.../data-integration/metabase.md | 173 +++++++++++++++------
.../data-integration/metabase.md | 161 ++++++++++++++-----
4 files changed, 492 insertions(+), 176 deletions(-)
diff --git a/docs/connection-integration/data-integration/metabase.md
b/docs/connection-integration/data-integration/metabase.md
index a599068d84f..b3968372954 100644
--- a/docs/connection-integration/data-integration/metabase.md
+++ b/docs/connection-integration/data-integration/metabase.md
@@ -2,7 +2,7 @@
{
"title": "Metabase",
"language": "en",
- "description": "Connect to Doris in Metabase using the Apache Doris
Driver, configure data sources, build visualization dashboards with SQL, and
explore Catalogs, parameterized queries, and performance tuning
recommendations.",
+ "description": "Connect Metabase to Apache Doris using the Doris Driver,
configure data sources, build dashboards, and use Catalog and parameterized
SQL.",
"keywords": [
"Metabase connect Doris",
"Apache Doris Metabase Driver",
@@ -17,6 +17,8 @@
Metabase is an open source business intelligence tool that provides data
analysis, data visualization, interactive dashboards, data drill-down, SQL
query editing, and data export. With the Metabase Apache Doris Driver, Metabase
can integrate Apache Doris databases and tables as data sources to query Doris
internal data and external data, and to build visualization dashboards.
+The driver is a standalone Metabase community driver and is not built into
Metabase.
+
This article starts from user scenarios and describes how to complete the
following operations:
| Scenario | User goal | Main operations |
@@ -34,40 +36,63 @@ Before you start configuration, make sure the following
environment is ready:
| Item | Requirement |
|------|------|
-| Metabase | Download and install Metabase 0.48.0 or later. For details, see
the [Metabase installation
documentation](https://www.metabase.com/docs/latest/installation-and-operation/installing-metabase)
|
+| Metabase | Download and install Metabase `0.59.6.3` or later. For
installation instructions, see the [Metabase installation
documentation](https://www.metabase.com/docs/latest/installation-and-operation/installing-metabase)
|
+| Java | Java 21 is required to run Metabase |
| Apache Doris | Prepare an accessible Apache Doris cluster |
-| Doris driver | Download the latest
[metabase-doris-driver](https://velodb-bi-connector-1316291683.cos.ap-hongkong.myqcloud.com/Metabase/latest/doris.metabase-driver.jar)
|
+| Doris driver | Download the [Metabase Doris
Driver](https://github.com/xylaaaaa/metabase-doris-driver/releases/tag/v1.0.0) |
+
+### Download and verify the driver
+
+Download the Release JAR and its checksum file:
+
+```bash
+curl -LO
https://github.com/xylaaaaa/metabase-doris-driver/releases/download/v1.0.0/doris.metabase-driver-v1.0.0.jar
+curl -LO
https://github.com/xylaaaaa/metabase-doris-driver/releases/download/v1.0.0/doris.metabase-driver-v1.0.0.jar.sha256
+sha256sum -c doris.metabase-driver-v1.0.0.jar.sha256
+```
+
+The expected SHA-256 digest is as follows:
+
+```text
+b23e82f19a7f9226343e42566e1e192b6df7a0dfc48a73d2101fc74bfec243f3
+```
### Install the driver for a regular deployment
If Metabase is deployed in the regular way, install the Doris driver as
follows:
-1. Download the Doris Driver.
+1. Download and verify the driver Release files as described above.
-2. Create the Metabase plugins directory (if it does not exist):
+2. If the Metabase plugins directory does not exist, create it:
```bash
- mkdir -p $path_metabase/plugins
+ mkdir -p /path/to/metabase/plugins
```
-3. Copy the JAR file to the plugins directory:
+3. Copy the Release JAR to the plugins directory:
```bash
- cp doris.metabase-driver.jar $path_metabase/plugins
+ cp doris.metabase-driver-v1.0.0.jar
/path/to/metabase/plugins/doris.metabase-driver.jar
```
4. Restart the Metabase service.
+5. Check the Metabase startup log to confirm that the `doris` driver is
registered. In **Admin Settings** > **Databases** > **Add database**, you
should be able to see the **Apache Doris** database type.
+
### Install the driver for a Docker deployment
-If Metabase is started with Docker, you are recommended to start it by
mounting `doris.metabase-driver.jar`. The plugin path inside the Docker
container is `/plugins/`.
+If you start Metabase with Docker, you are recommended to start it by mounting
`doris.metabase-driver.jar`. The plugin path inside the Docker container is
`/plugins/`.
-1. Download the Doris Driver.
+1. Download and verify the driver Release files.
-2. Start Metabase with a command similar to the following:
+2. Start the container with a Metabase image that meets the prerequisites:
```bash
- docker run -d -p 3000:3000 --name metabase -v
$host_path/doris.metabase-driver.jar:/plugins/doris.metabase-driver.jar
metabase/metabase
+ docker run -d \
+ -p 3000:3000 \
+ --name metabase \
+ -v
"$(pwd)/doris.metabase-driver-v1.0.0.jar:/plugins/doris.metabase-driver.jar:ro"
\
+ metabase/metabase
```
## Configure the Doris data source
@@ -79,22 +104,29 @@ After installing Metabase and `metabase-doris-driver`, you
can add a data source
### Connection parameters
-The following parameters are required when connecting to Apache Doris:
+The following fields are required when connecting to Apache Doris:
| Parameter | Meaning | Example |
|------|------|------|
| **Display Name** | Display name of the data source | Doris-TPCH |
| **Host** | Doris FE node address | 127.0.0.1 |
-| **Port** | Doris Query Port (MySQL protocol port) | 9030 |
-| **Catalog name** | Catalog name. Optional, defaults to `internal` | internal
|
-| **Database name** | Database name. Required | tpch |
+| **Port** | Doris Query Port (MySQL protocol port), defaults to `9030` | 9030
|
+| **Catalog** | Catalog name. Optional, defaults to `internal` | internal |
+| **Database (optional)** | The database in the selected Catalog. Optional;
when left empty, all visible databases in the Catalog are discovered | tpch |
| **Username** | Username | root |
| **Password** | Password | your_password |
+| **SSL** | Enable JDBC TLS. The driver uses MariaDB `sslMode=trust` and does
not verify the server certificate or hostname | false |
+| **Sync Schemas Include** | Optional. Used when **Database (optional)** is
empty. A comma-separated allowlist of databases | tpch |
+| **Sync Schemas Exclude** | Optional. Used when **Database (optional)** is
empty. A comma-separated denylist of databases. The exclude rule takes
precedence over the include rule | information_schema |
+| **Additional JDBC connection string options** | Other MariaDB JDBC URL
parameters | connectTimeout=10000 |
+
+Select the Catalog and database scope as follows:
-Fill in the database name as follows:
+- **Internal tables**: Keep **Catalog** as `internal` and fill in a database
such as `tpch`.
+- **External tables**: Fill in the external Catalog and a database visible in
that Catalog.
+- **Multiple databases**: Leave **Database (optional)** empty. The driver
discovers the databases visible to the configured account, and applies the
include and exclude lists before listing the tables in them.
-- **Querying internal tables**: Enter the database name directly, for example
`tpch`. The system automatically uses the `internal` Catalog.
-- **Querying external tables or data lakes**: Fill in the Catalog
configuration. If you only connect to internal tables, you do not need to
consider this option.
+When **Database (optional)** is empty, the driver excludes
`information_schema`, `__internal_schema`, and `mysql` by default. The include
and exclude rules are matched case-insensitively; if the same database appears
in both lists, the exclude rule takes precedence. If **Database (optional)** is
set explicitly, the sync scope is limited to that database, and the include and
exclude settings do not change the sync scope.
### Configuration steps
@@ -119,7 +151,8 @@ Fill in the database name as follows:
| **Display name** | Doris-TPCH |
| **Host** | 127.0.0.1 |
| **Port** | 9030 |
- | **Database name** | tpch |
+ | **Catalog** | internal |
+ | **Database (optional)** | tpch |
| **Username** | admin |
| **Password** | ****** |
@@ -127,7 +160,7 @@ Fill in the database name as follows:
6. Click **Save** to save the configuration.
-7. Metabase automatically tests the connection and synchronizes database
metadata. If the connection succeeds, a success message is displayed.
+7. Metabase tests the connection and starts synchronizing database metadata.
If the connection succeeds, a success message is displayed.
@@ -161,7 +194,7 @@ Suppose you need to analyze how the order amounts of
different shipping methods
To compute the revenue, you need to use a custom SQL expression.
-1. Click **view sql** in the upper right corner to switch, then click
**convert this question to SQL** to edit the SQL.
+1. Click **view sql** in the upper right corner, then click **convert this
question to SQL** to edit the SQL.
@@ -226,6 +259,21 @@ To compute the revenue, you need to use a custom SQL
expression.
You have now successfully connected Metabase to Apache Doris and completed
data analysis and visualization dashboard creation.
+## Driver capabilities and limitations
+
+The following table summarizes the driver capabilities and current support
boundaries.
+
+| Capability | Support status and boundaries |
+|------|------|
+| Internal Catalog | Supports synchronizing and querying Doris internal tables
|
+| Native SQL | Supported. SQL is executed with the permissions of the
configured Doris account; the driver does not force statements to be read-only |
+| Query Builder | Supports group aggregation and bucketing by day |
+| External Catalog | Supports synchronizing and querying data in Doris
External Catalogs; the available scope and metadata completeness depend on the
specific connector |
+| Native template parameters | Supports numeric, text, and optional blocks |
+| Complex types | Top-level `ARRAY`, `MAP`, `JSON`, and opaque complex fields
remain visible; nested subfields are not expanded |
+| Key and index metadata | Primary keys, foreign keys, indexes, and table
permissions are not synchronized |
+| Metabase write features | Data upload, write-back, Actions, data editing,
and persisted models are not supported |
+
## Advanced scenarios
{/* Knowledge type: Feature description */}
@@ -233,38 +281,69 @@ You have now successfully connected Metabase to Apache
Doris and completed data
### Use Catalog to access external data
-Doris supports the multi-Catalog feature, which can query external data
sources and perform cross-data-source queries. When using Catalog in Metabase,
you can choose either of the following options.
-
-1. Configure `Catalog` on the connection configuration page, and configure an
external table database under that Catalog in `Database`. For example:
+Set **Catalog** and **Database (optional)** on the connection page to
synchronize tables in a Doris external Catalog:
- | Configuration | Example value | Description |
- |--------|--------|------|
- | `catalog` | `hive_catalog` | Access the Catalog named `hive_catalog` |
- | `database` | `warehouse` | Access the `warehouse` database under the
Catalog |
+| Configuration | Example value | Description |
+|--------|--------|------|
+| `Catalog` | `hive_catalog` | Select the Doris Catalog named `hive_catalog` |
+| `Database (optional)` | `warehouse` | Select the `warehouse` database in the
Catalog |
-2. Specify the Catalog explicitly in the SQL query:
+Specify the Catalog explicitly in the SQL query:
- ```sql
- SELECT * FROM hive.warehouse.orders LIMIT 100;
- ```
+```sql
+SELECT * FROM hive.warehouse.orders LIMIT 100;
+```
### Use parameterized queries
-Metabase supports using variables in SQL queries, which makes it easy to
create interactive dashboards:
+The driver supports basic Native SQL template parameters. The following
example uses a numeric parameter, a text parameter, and an optional block:
```sql
SELECT
- l_shipmode,
- SUM(l_extendedprice * (1 - l_discount)) AS revenue
-FROM lineitem
-WHERE l_shipdate BETWEEN {{start_date}} AND {{end_date}}
- AND l_shipmode = {{ship_mode}}
-GROUP BY l_shipmode
+ category,
+ COUNT(*) AS row_count,
+ SUM(amount) AS total_amount
+FROM orders
+WHERE amount > {{min_amount}}
+[[AND category = {{category}}]]
+GROUP BY category
```
-After saving, you can dynamically filter data on the dashboard with dropdowns
or date pickers.
+When `category` has no value, Metabase removes the entire optional block.
+
+| Template capability | Support status |
+|----------|----------|
+| Numeric variables | Supported |
+| Text variables | Supported |
+| Optional blocks `[[ ... ]]` | Supported |
+| Field filters | Not supported |
+| Card references such as `{{#card-id}}` | Not supported |
+| Dynamic table references | Not supported |
+
+### Data types
+
+During metadata synchronization, the driver maps Doris types to Metabase base
types as shown in the following table:
+
+| Doris type | Metabase base type |
+|------------|-------------------|
+| `BOOLEAN` | `type/Boolean` |
+| `TINYINT`, `SMALLINT`, `INT`, `INTEGER`, including display widths such as
`INT(11)` | `type/Integer` |
+| `BIGINT`, `LARGEINT`, including display widths such as `BIGINT(20)` |
`type/BigInteger` |
+| `FLOAT`, `DOUBLE` | `type/Float` |
+| `DECIMAL` | `type/Decimal` |
+| `DATE`, `DATEV2` | `type/Date` |
+| `TIME`, including fractional-second precision | `type/Time` |
+| `DATETIME`, `DATETIMEV2`, `TIMESTAMP` | `type/DateTime` |
+| `TIMESTAMPTZ` | `type/DateTimeWithTZ` |
+| `CHAR`, `VARCHAR`, `STRING`, `TEXT` | `type/Text` |
+| `JSON`, `JSONB` | `type/JSON` |
+| `ARRAY` | `type/Array` |
+| `MAP` | `type/Dictionary` |
+| `STRUCT`, `VARIANT`, `HLL`, `BITMAP` | `type/*` |
+
+Nested fields inside `ARRAY`, `MAP`, `JSON`, `STRUCT`, or `VARIANT` values are
not expanded into Metabase subfields. `LARGEINT` maps to `type/BigInteger` and
does not require conversion to a string.
### Performance tuning recommendations
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/connection-integration/data-integration/metabase.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/connection-integration/data-integration/metabase.md
index f6cdc35a37f..ce6a180fb9b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/connection-integration/data-integration/metabase.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/connection-integration/data-integration/metabase.md
@@ -2,7 +2,7 @@
{
"title": "Metabase",
"language": "zh-CN",
- "description": "在 Metabase 中通过 Apache Doris Driver 连接 Doris，配置数据源、使用 SQL
构建可视化仪表盘，并查看 Catalog、参数化查询和性能优化建议。",
+ "description": "使用 Doris Driver 将 Metabase 连接到 Apache
Doris，配置数据源、构建仪表盘，并使用 Catalog 和参数化 SQL。",
"keywords": [
"Metabase 连接 Doris",
"Apache Doris Metabase Driver",
@@ -17,6 +17,8 @@
Metabase 是一个开源商业智能工具，提供数据分析、数据可视化、交互式仪表盘、数据钻取、SQL 查询编辑和数据导出等能力。通过 Metabase
Apache Doris Driver，Metabase 可以将 Apache Doris 数据库和表集成为数据源，用于查询 Doris
内部数据和外部数据，并构建可视化看板。
+该驱动是独立的 Metabase 社区驱动，未内置于 Metabase。
+
本文从用户使用场景出发，介绍如何完成以下操作：
| 使用场景 | 用户目标 | 主要操作 |
@@ -34,40 +36,63 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
| 项目 | 要求 |
|------|------|
-| Metabase | 下载并安装 Metabase 0.48.0 及以上版本。具体参见 [Metabase
安装文档](https://www.metabase.com/docs/latest/installation-and-operation/installing-metabase)
|
+| Metabase | 下载并安装 Metabase `0.59.6.3` 及以上版本。安装方法请参见 [Metabase
安装文档](https://www.metabase.com/docs/latest/installation-and-operation/installing-metabase)
|
+| Java | 运行 Metabase 需要 Java 21 |
| Apache Doris | 准备可访问的 Apache Doris 集群 |
-| Doris 驱动程序 | 下载最新的
[metabase-doris-driver](https://velodb-bi-connector-1316291683.cos.ap-hongkong.myqcloud.com/Metabase/latest/doris.metabase-driver.jar)
|
+| Doris 驱动程序 | 下载 [Metabase Doris
Driver](https://github.com/xylaaaaa/metabase-doris-driver/releases/tag/v1.0.0) |
+
+### 下载并校验驱动程序
+
+下载 Release JAR 及其校验文件：
+
+```bash
+curl -LO
https://github.com/xylaaaaa/metabase-doris-driver/releases/download/v1.0.0/doris.metabase-driver-v1.0.0.jar
+curl -LO
https://github.com/xylaaaaa/metabase-doris-driver/releases/download/v1.0.0/doris.metabase-driver-v1.0.0.jar.sha256
+sha256sum -c doris.metabase-driver-v1.0.0.jar.sha256
+```
+
+预期的 SHA-256 摘要如下：
+
+```text
+b23e82f19a7f9226343e42566e1e192b6df7a0dfc48a73d2101fc74bfec243f3
+```
### 常规部署安装驱动程序
如果 Metabase 通过常规方式部署，请按以下步骤安装 Doris 驱动程序：
-1. 下载 Doris Driver。
+1. 按照前文说明下载并校验驱动程序 Release 文件。
-2. 创建 Metabase 插件目录（如果不存在）：
+2. 如果 Metabase 插件目录不存在，请创建该目录：
```bash
- mkdir -p $path_metabase/plugins
+ mkdir -p /path/to/metabase/plugins
```
-3. 将 JAR 文件复制到插件目录：
+3. 将 Release JAR 复制到插件目录：
```bash
- cp doris.metabase-driver.jar $path_metabase/plugins
+ cp doris.metabase-driver-v1.0.0.jar
/path/to/metabase/plugins/doris.metabase-driver.jar
```
4. 重启 Metabase 服务。
+5. 检查 Metabase 启动日志，确认 `doris` 驱动程序已注册。在 **Admin Settings** > **Databases** >
**Add database** 中，应当能够看到 **Apache Doris** 数据库类型。
+
### Docker 部署安装驱动程序
-如果 Metabase 使用 Docker 启动，建议通过挂载 `doris.metabase-driver.jar` 的方式启动。Docker
容器内部的插件路径为 `/plugins/`。
+如果使用 Docker 启动 Metabase，建议通过挂载 `doris.metabase-driver.jar` 的方式启动。Docker
容器内的插件路径为 `/plugins/`。
-1. 下载 Doris Driver。
+1. 下载并校验驱动程序 Release 文件。
-2. 参考如下命令启动 Metabase：
+2. 使用符合前置要求的 Metabase 镜像启动容器：
```bash
- docker run -d -p 3000:3000 --name metabase -v
$host_path/doris.metabase-driver.jar:/plugins/doris.metabase-driver.jar
metabase/metabase
+ docker run -d \
+ -p 3000:3000 \
+ --name metabase \
+ -v
"$(pwd)/doris.metabase-driver-v1.0.0.jar:/plugins/doris.metabase-driver.jar:ro"
\
+ metabase/metabase
```
## 配置 Doris 数据源
@@ -79,22 +104,29 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
### 连接参数
-连接 Apache Doris 时需要配置以下参数：
+连接 Apache Doris 时需要配置以下字段：
| 参数 | 含义 | 示例 |
|------|------|------|
| **Display Name** | 数据源显示名称 | Doris-TPCH |
| **Host** | Doris FE 节点地址 | 127.0.0.1 |
-| **Port** | Doris Query Port（MySQL 协议端口） | 9030 |
-| **Catalog name** | Catalog 名。可选，默认为 `internal` | internal |
-| **Database name** | 数据库名。必填 | tpch |
+| **Port** | Doris Query Port（MySQL 协议端口），默认为 `9030` | 9030 |
+| **Catalog** | Catalog 名称。可选，默认为 `internal` | internal |
+| **Database (optional)** | 所选 Catalog 中的数据库。可选；留空时会发现该 Catalog 中所有可见数据库 |
tpch |
| **Username** | 用户名 | root |
| **Password** | 密码 | your_password |
+| **SSL** | 启用 JDBC TLS。该驱动会使用 MariaDB `sslMode=trust`，不会校验服务器证书或主机名 | false |
+| **Sync Schemas Include** | 可选。当 **Database (optional)** 为空时使用，以逗号分隔的数据库白名单 |
tpch |
+| **Sync Schemas Exclude** | 可选。当 **Database (optional)**
为空时使用，以逗号分隔的数据库黑名单。排除规则优先于包含规则 | information_schema |
+| **Additional JDBC connection string options** | 其他 MariaDB JDBC URL 参数 |
connectTimeout=10000 |
+
+按以下方式选择 Catalog 和数据库范围：
-数据库名称填写方式如下：
+- **内表**：将 **Catalog** 保持为 `internal`，并填写 `tpch` 等数据库。
+- **外表**：填写外部 Catalog，以及该 Catalog 中可见的数据库。
+- **多个数据库**：将 **Database (optional)** 留空。驱动程序会发现配置账号可见的数据库，并在列出其中的表之前应用包含和排除列表。
-- **查询内表**：直接填写数据库名，例如 `tpch`。系统会自动使用 `internal` Catalog。
-- **查询外表或数据湖**：填写 Catalog 配置。如果只连接内表，则无需关注此项。
+当 **Database (optional)** 为空时，驱动程序默认排除
`information_schema`、`__internal_schema` 和
`mysql`。包含和排除规则匹配时不区分大小写；如果同一数据库同时出现在两个列表中，排除规则优先。如果显式设置了 **Database
(optional)**，同步范围将限定在该数据库中，包含和排除设置不会改变同步范围。
### 配置步骤
@@ -119,7 +151,8 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
| **Display name** | Doris-TPCH |
| **Host** | 127.0.0.1 |
| **Port** | 9030 |
- | **Database name** | tpch |
+ | **Catalog** | internal |
+ | **Database (optional)** | tpch |
| **Username** | admin |
| **Password** | ****** |
@@ -127,7 +160,7 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
6. 点击 **Save** 保存配置。
-7. Metabase 会自动测试连接并同步数据库元数据。如果连接成功，会显示成功提示。
+7. Metabase 会测试连接并开始同步数据库元数据。如果连接成功，会显示成功提示。
@@ -138,7 +171,7 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
{/* 知识类型: 操作步骤 */}
{/* 适用场景: 使用 Doris TPC-H 数据在 Metabase 中创建 Question 和 Dashboard */}
-本示例使用 TPC-H 数据作为数据源。Doris TPC-H 数据源构建方式请参考 [Doris TPC-H
基准测试文档](../../lakehouse/best-practices/tpch.md)。
+本示例使用 TPC-H 数据作为数据源。Doris TPC-H 数据源构建方式请参见 [Doris TPC-H
基准测试文档](../../lakehouse/best-practices/tpch.md)。
假设需要分析不同货运方式的订单金额随时间增长曲线，用于成本分析，可以按以下流程完成可视化配置。
@@ -161,7 +194,7 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
为了计算收入（Revenue），需要使用自定义 SQL 表达式。
-1. 点击右上角切换 **view sql**，然后点击 **convert this question to SQL** 编辑 SQL。
+1. 点击右上角的 **view sql**，然后点击 **convert this question to SQL** 编辑 SQL。
@@ -201,12 +234,12 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
3. 自定义图表样式：
- - 点击 **Settings** 图标，可以调整颜色、标签、图例位置等。
- - 在 **Display** 标签页可以设置坐标轴标题、数值格式等。
+ - 点击 **Settings** 图标，可以调整颜色、标签和图例位置等。
+ - 在 **Display** 标签页中，可以设置坐标轴标题和数值格式等。
4. 图表配置完成后，点击右上角的 **Save** 保存。
-5. 输入问题名称 **my-tpch**，选择保存到的集合（Collection）。
+5. 输入问题名称 **my-tpch**，选择要保存到的集合（Collection）。
@@ -220,11 +253,26 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
-3. 调整图表位置和大小，点击右上角 **Save** 保存仪表盘。
+3. 调整图表位置和大小，点击右上角的 **Save** 保存仪表盘。
-至此，已经成功将 Metabase 连接到 Apache Doris，并完成数据分析和可视化看板制作。
+至此，已经成功将 Metabase 连接到 Apache Doris，并完成数据分析和可视化仪表盘制作。
+
+## 驱动程序能力与限制
+
+下表汇总了该驱动的能力和当前支持边界。
+
+| 能力 | 支持状态与边界 |
+|------|----------------|
+| Internal Catalog | 支持同步和查询 Doris 内部表 |
+| Native SQL | 支持。SQL 使用配置的 Doris 账号权限执行；驱动程序不强制语句只读 |
+| Query Builder | 支持分组聚合和按天分桶 |
+| External Catalog | 支持同步和查询 Doris External Catalog 中的数据；可用范围和元数据完整性取决于具体连接器 |
+| Native 模板参数 | 支持数值、文本和可选块 |
+| 复杂类型 | 顶层 `ARRAY`、`MAP`、`JSON` 和不透明复杂字段仍然可见；不展开嵌套子字段 |
+| 键与索引元数据 | 不同步主键、外键、索引和表权限 |
+| Metabase 写入功能 | 不支持数据上传、回写、Actions、数据编辑和持久化模型 |
## 高级使用场景
@@ -233,38 +281,69 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
### 使用 Catalog 访问外部数据
-Doris 支持多 Catalog 功能，可以查询外部数据源，也可以进行跨数据源查询。在 Metabase 中使用 Catalog 时，可以选择以下任一方式。
+在连接页面设置 **Catalog** 和 **Database (optional)**，以同步 Doris 外部 Catalog 中的表：
-1. 在连接配置界面配置 `Catalog`，并在 `Database` 中配置该 Catalog 下的外表数据库。例如：
-
- | 配置项 | 示例值 | 说明 |
- |--------|--------|------|
- | `catalog` | `hive_catalog` | 访问名为 `hive_catalog` 的 Catalog |
- | `database` | `warehouse` | 访问该 Catalog 下的 `warehouse` 数据库 |
+| 配置项 | 示例值 | 说明 |
+|--------|--------|------|
+| `Catalog` | `hive_catalog` | 选择名为 `hive_catalog` 的 Doris Catalog |
+| `Database (optional)` | `warehouse` | 选择该 Catalog 中的 `warehouse` 数据库 |
-2. 在 SQL 查询中显式指定 Catalog：
+在 SQL 查询中显式指定 Catalog：
- ```sql
- SELECT * FROM hive.warehouse.orders LIMIT 100;
- ```
+```sql
+SELECT * FROM hive.warehouse.orders LIMIT 100;
+```
### 使用参数化查询
-Metabase 支持在 SQL 查询中使用变量，方便创建交互式仪表盘：
+驱动程序支持基本的 Native SQL 模板参数。以下示例使用数值参数、文本参数和可选块：
```sql
SELECT
- l_shipmode,
- SUM(l_extendedprice * (1 - l_discount)) AS revenue
-FROM lineitem
-WHERE l_shipdate BETWEEN {{start_date}} AND {{end_date}}
- AND l_shipmode = {{ship_mode}}
-GROUP BY l_shipmode
+ category,
+ COUNT(*) AS row_count,
+ SUM(amount) AS total_amount
+FROM orders
+WHERE amount > {{min_amount}}
+[[AND category = {{category}}]]
+GROUP BY category
```
-保存后，可以在仪表盘中通过下拉框或日期选择器动态筛选数据。
+当 `category` 没有值时，Metabase 会移除整个可选块。
+
+| 模板能力 | 支持状态 |
+|----------|----------|
+| 数值变量 | 支持 |
+| 文本变量 | 支持 |
+| 可选块 `[[ ... ]]` | 支持 |
+| 字段过滤器 | 不支持 |
+| `{{#card-id}}` 等卡片引用 | 不支持 |
+| 动态表引用 | 不支持 |
+
+### 数据类型
+
+在元数据同步过程中，驱动程序按照下表将 Doris 类型映射为 Metabase 基础类型：
+
+| Doris 类型 | Metabase 基础类型 |
+|------------|-------------------|
+| `BOOLEAN` | `type/Boolean` |
+| `TINYINT`、`SMALLINT`、`INT`、`INTEGER`，包括 `INT(11)` 等显示宽度 | `type/Integer` |
+| `BIGINT`、`LARGEINT`，包括 `BIGINT(20)` 等显示宽度 | `type/BigInteger` |
+| `FLOAT`、`DOUBLE` | `type/Float` |
+| `DECIMAL` | `type/Decimal` |
+| `DATE`、`DATEV2` | `type/Date` |
+| `TIME`，包括小数秒精度 | `type/Time` |
+| `DATETIME`、`DATETIMEV2`、`TIMESTAMP` | `type/DateTime` |
+| `TIMESTAMPTZ` | `type/DateTimeWithTZ` |
+| `CHAR`、`VARCHAR`、`STRING`、`TEXT` | `type/Text` |
+| `JSON`、`JSONB` | `type/JSON` |
+| `ARRAY` | `type/Array` |
+| `MAP` | `type/Dictionary` |
+| `STRUCT`、`VARIANT`、`HLL`、`BITMAP` | `type/*` |
+
+`ARRAY`、`MAP`、`JSON`、`STRUCT` 或 `VARIANT` 值中的嵌套字段不会展开为 Metabase 子字段。`LARGEINT`
会映射为 `type/BigInteger`，不要求转换为字符串。
### 性能优化建议
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/connection-integration/data-integration/metabase.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/connection-integration/data-integration/metabase.md
index f6cdc35a37f..ce6a180fb9b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/connection-integration/data-integration/metabase.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/connection-integration/data-integration/metabase.md
@@ -2,7 +2,7 @@
{
"title": "Metabase",
"language": "zh-CN",
- "description": "在 Metabase 中通过 Apache Doris Driver 连接 Doris，配置数据源、使用 SQL
构建可视化仪表盘，并查看 Catalog、参数化查询和性能优化建议。",
+ "description": "使用 Doris Driver 将 Metabase 连接到 Apache
Doris，配置数据源、构建仪表盘，并使用 Catalog 和参数化 SQL。",
"keywords": [
"Metabase 连接 Doris",
"Apache Doris Metabase Driver",
@@ -17,6 +17,8 @@
Metabase 是一个开源商业智能工具，提供数据分析、数据可视化、交互式仪表盘、数据钻取、SQL 查询编辑和数据导出等能力。通过 Metabase
Apache Doris Driver，Metabase 可以将 Apache Doris 数据库和表集成为数据源，用于查询 Doris
内部数据和外部数据，并构建可视化看板。
+该驱动是独立的 Metabase 社区驱动，未内置于 Metabase。
+
本文从用户使用场景出发，介绍如何完成以下操作：
| 使用场景 | 用户目标 | 主要操作 |
@@ -34,40 +36,63 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
| 项目 | 要求 |
|------|------|
-| Metabase | 下载并安装 Metabase 0.48.0 及以上版本。具体参见 [Metabase
安装文档](https://www.metabase.com/docs/latest/installation-and-operation/installing-metabase)
|
+| Metabase | 下载并安装 Metabase `0.59.6.3` 及以上版本。安装方法请参见 [Metabase
安装文档](https://www.metabase.com/docs/latest/installation-and-operation/installing-metabase)
|
+| Java | 运行 Metabase 需要 Java 21 |
| Apache Doris | 准备可访问的 Apache Doris 集群 |
-| Doris 驱动程序 | 下载最新的
[metabase-doris-driver](https://velodb-bi-connector-1316291683.cos.ap-hongkong.myqcloud.com/Metabase/latest/doris.metabase-driver.jar)
|
+| Doris 驱动程序 | 下载 [Metabase Doris
Driver](https://github.com/xylaaaaa/metabase-doris-driver/releases/tag/v1.0.0) |
+
+### 下载并校验驱动程序
+
+下载 Release JAR 及其校验文件：
+
+```bash
+curl -LO
https://github.com/xylaaaaa/metabase-doris-driver/releases/download/v1.0.0/doris.metabase-driver-v1.0.0.jar
+curl -LO
https://github.com/xylaaaaa/metabase-doris-driver/releases/download/v1.0.0/doris.metabase-driver-v1.0.0.jar.sha256
+sha256sum -c doris.metabase-driver-v1.0.0.jar.sha256
+```
+
+预期的 SHA-256 摘要如下：
+
+```text
+b23e82f19a7f9226343e42566e1e192b6df7a0dfc48a73d2101fc74bfec243f3
+```
### 常规部署安装驱动程序
如果 Metabase 通过常规方式部署，请按以下步骤安装 Doris 驱动程序：
-1. 下载 Doris Driver。
+1. 按照前文说明下载并校验驱动程序 Release 文件。
-2. 创建 Metabase 插件目录（如果不存在）：
+2. 如果 Metabase 插件目录不存在，请创建该目录：
```bash
- mkdir -p $path_metabase/plugins
+ mkdir -p /path/to/metabase/plugins
```
-3. 将 JAR 文件复制到插件目录：
+3. 将 Release JAR 复制到插件目录：
```bash
- cp doris.metabase-driver.jar $path_metabase/plugins
+ cp doris.metabase-driver-v1.0.0.jar
/path/to/metabase/plugins/doris.metabase-driver.jar
```
4. 重启 Metabase 服务。
+5. 检查 Metabase 启动日志，确认 `doris` 驱动程序已注册。在 **Admin Settings** > **Databases** >
**Add database** 中，应当能够看到 **Apache Doris** 数据库类型。
+
### Docker 部署安装驱动程序
-如果 Metabase 使用 Docker 启动，建议通过挂载 `doris.metabase-driver.jar` 的方式启动。Docker
容器内部的插件路径为 `/plugins/`。
+如果使用 Docker 启动 Metabase，建议通过挂载 `doris.metabase-driver.jar` 的方式启动。Docker
容器内的插件路径为 `/plugins/`。
-1. 下载 Doris Driver。
+1. 下载并校验驱动程序 Release 文件。
-2. 参考如下命令启动 Metabase：
+2. 使用符合前置要求的 Metabase 镜像启动容器：
```bash
- docker run -d -p 3000:3000 --name metabase -v
$host_path/doris.metabase-driver.jar:/plugins/doris.metabase-driver.jar
metabase/metabase
+ docker run -d \
+ -p 3000:3000 \
+ --name metabase \
+ -v
"$(pwd)/doris.metabase-driver-v1.0.0.jar:/plugins/doris.metabase-driver.jar:ro"
\
+ metabase/metabase
```
## 配置 Doris 数据源
@@ -79,22 +104,29 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
### 连接参数
-连接 Apache Doris 时需要配置以下参数：
+连接 Apache Doris 时需要配置以下字段：
| 参数 | 含义 | 示例 |
|------|------|------|
| **Display Name** | 数据源显示名称 | Doris-TPCH |
| **Host** | Doris FE 节点地址 | 127.0.0.1 |
-| **Port** | Doris Query Port（MySQL 协议端口） | 9030 |
-| **Catalog name** | Catalog 名。可选，默认为 `internal` | internal |
-| **Database name** | 数据库名。必填 | tpch |
+| **Port** | Doris Query Port（MySQL 协议端口），默认为 `9030` | 9030 |
+| **Catalog** | Catalog 名称。可选，默认为 `internal` | internal |
+| **Database (optional)** | 所选 Catalog 中的数据库。可选；留空时会发现该 Catalog 中所有可见数据库 |
tpch |
| **Username** | 用户名 | root |
| **Password** | 密码 | your_password |
+| **SSL** | 启用 JDBC TLS。该驱动会使用 MariaDB `sslMode=trust`，不会校验服务器证书或主机名 | false |
+| **Sync Schemas Include** | 可选。当 **Database (optional)** 为空时使用，以逗号分隔的数据库白名单 |
tpch |
+| **Sync Schemas Exclude** | 可选。当 **Database (optional)**
为空时使用，以逗号分隔的数据库黑名单。排除规则优先于包含规则 | information_schema |
+| **Additional JDBC connection string options** | 其他 MariaDB JDBC URL 参数 |
connectTimeout=10000 |
+
+按以下方式选择 Catalog 和数据库范围：
-数据库名称填写方式如下：
+- **内表**：将 **Catalog** 保持为 `internal`，并填写 `tpch` 等数据库。
+- **外表**：填写外部 Catalog，以及该 Catalog 中可见的数据库。
+- **多个数据库**：将 **Database (optional)** 留空。驱动程序会发现配置账号可见的数据库，并在列出其中的表之前应用包含和排除列表。
-- **查询内表**：直接填写数据库名，例如 `tpch`。系统会自动使用 `internal` Catalog。
-- **查询外表或数据湖**：填写 Catalog 配置。如果只连接内表，则无需关注此项。
+当 **Database (optional)** 为空时，驱动程序默认排除
`information_schema`、`__internal_schema` 和
`mysql`。包含和排除规则匹配时不区分大小写；如果同一数据库同时出现在两个列表中，排除规则优先。如果显式设置了 **Database
(optional)**，同步范围将限定在该数据库中，包含和排除设置不会改变同步范围。
### 配置步骤
@@ -119,7 +151,8 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
| **Display name** | Doris-TPCH |
| **Host** | 127.0.0.1 |
| **Port** | 9030 |
- | **Database name** | tpch |
+ | **Catalog** | internal |
+ | **Database (optional)** | tpch |
| **Username** | admin |
| **Password** | ****** |
@@ -127,7 +160,7 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
6. 点击 **Save** 保存配置。
-7. Metabase 会自动测试连接并同步数据库元数据。如果连接成功，会显示成功提示。
+7. Metabase 会测试连接并开始同步数据库元数据。如果连接成功，会显示成功提示。
@@ -138,7 +171,7 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
{/* 知识类型: 操作步骤 */}
{/* 适用场景: 使用 Doris TPC-H 数据在 Metabase 中创建 Question 和 Dashboard */}
-本示例使用 TPC-H 数据作为数据源。Doris TPC-H 数据源构建方式请参考 [Doris TPC-H
基准测试文档](../../lakehouse/best-practices/tpch.md)。
+本示例使用 TPC-H 数据作为数据源。Doris TPC-H 数据源构建方式请参见 [Doris TPC-H
基准测试文档](../../lakehouse/best-practices/tpch.md)。
假设需要分析不同货运方式的订单金额随时间增长曲线，用于成本分析，可以按以下流程完成可视化配置。
@@ -161,7 +194,7 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
为了计算收入（Revenue），需要使用自定义 SQL 表达式。
-1. 点击右上角切换 **view sql**，然后点击 **convert this question to SQL** 编辑 SQL。
+1. 点击右上角的 **view sql**，然后点击 **convert this question to SQL** 编辑 SQL。
@@ -201,12 +234,12 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
3. 自定义图表样式：
- - 点击 **Settings** 图标，可以调整颜色、标签、图例位置等。
- - 在 **Display** 标签页可以设置坐标轴标题、数值格式等。
+ - 点击 **Settings** 图标，可以调整颜色、标签和图例位置等。
+ - 在 **Display** 标签页中，可以设置坐标轴标题和数值格式等。
4. 图表配置完成后，点击右上角的 **Save** 保存。
-5. 输入问题名称 **my-tpch**，选择保存到的集合（Collection）。
+5. 输入问题名称 **my-tpch**，选择要保存到的集合（Collection）。
@@ -220,11 +253,26 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
-3. 调整图表位置和大小，点击右上角 **Save** 保存仪表盘。
+3. 调整图表位置和大小，点击右上角的 **Save** 保存仪表盘。
-至此，已经成功将 Metabase 连接到 Apache Doris，并完成数据分析和可视化看板制作。
+至此，已经成功将 Metabase 连接到 Apache Doris，并完成数据分析和可视化仪表盘制作。
+
+## 驱动程序能力与限制
+
+下表汇总了该驱动的能力和当前支持边界。
+
+| 能力 | 支持状态与边界 |
+|------|----------------|
+| Internal Catalog | 支持同步和查询 Doris 内部表 |
+| Native SQL | 支持。SQL 使用配置的 Doris 账号权限执行；驱动程序不强制语句只读 |
+| Query Builder | 支持分组聚合和按天分桶 |
+| External Catalog | 支持同步和查询 Doris External Catalog 中的数据；可用范围和元数据完整性取决于具体连接器 |
+| Native 模板参数 | 支持数值、文本和可选块 |
+| 复杂类型 | 顶层 `ARRAY`、`MAP`、`JSON` 和不透明复杂字段仍然可见；不展开嵌套子字段 |
+| 键与索引元数据 | 不同步主键、外键、索引和表权限 |
+| Metabase 写入功能 | 不支持数据上传、回写、Actions、数据编辑和持久化模型 |
## 高级使用场景
@@ -233,38 +281,69 @@ Metabase 是一个开源商业智能工具，提供数据分析、数据可视
### 使用 Catalog 访问外部数据
-Doris 支持多 Catalog 功能，可以查询外部数据源，也可以进行跨数据源查询。在 Metabase 中使用 Catalog 时，可以选择以下任一方式。
+在连接页面设置 **Catalog** 和 **Database (optional)**，以同步 Doris 外部 Catalog 中的表：
-1. 在连接配置界面配置 `Catalog`，并在 `Database` 中配置该 Catalog 下的外表数据库。例如：
-
- | 配置项 | 示例值 | 说明 |
- |--------|--------|------|
- | `catalog` | `hive_catalog` | 访问名为 `hive_catalog` 的 Catalog |
- | `database` | `warehouse` | 访问该 Catalog 下的 `warehouse` 数据库 |
+| 配置项 | 示例值 | 说明 |
+|--------|--------|------|
+| `Catalog` | `hive_catalog` | 选择名为 `hive_catalog` 的 Doris Catalog |
+| `Database (optional)` | `warehouse` | 选择该 Catalog 中的 `warehouse` 数据库 |
-2. 在 SQL 查询中显式指定 Catalog：
+在 SQL 查询中显式指定 Catalog：
- ```sql
- SELECT * FROM hive.warehouse.orders LIMIT 100;
- ```
+```sql
+SELECT * FROM hive.warehouse.orders LIMIT 100;
+```
### 使用参数化查询
-Metabase 支持在 SQL 查询中使用变量，方便创建交互式仪表盘：
+驱动程序支持基本的 Native SQL 模板参数。以下示例使用数值参数、文本参数和可选块：
```sql
SELECT
- l_shipmode,
- SUM(l_extendedprice * (1 - l_discount)) AS revenue
-FROM lineitem
-WHERE l_shipdate BETWEEN {{start_date}} AND {{end_date}}
- AND l_shipmode = {{ship_mode}}
-GROUP BY l_shipmode
+ category,
+ COUNT(*) AS row_count,
+ SUM(amount) AS total_amount
+FROM orders
+WHERE amount > {{min_amount}}
+[[AND category = {{category}}]]
+GROUP BY category
```
-保存后，可以在仪表盘中通过下拉框或日期选择器动态筛选数据。
+当 `category` 没有值时，Metabase 会移除整个可选块。
+
+| 模板能力 | 支持状态 |
+|----------|----------|
+| 数值变量 | 支持 |
+| 文本变量 | 支持 |
+| 可选块 `[[ ... ]]` | 支持 |
+| 字段过滤器 | 不支持 |
+| `{{#card-id}}` 等卡片引用 | 不支持 |
+| 动态表引用 | 不支持 |
+
+### 数据类型
+
+在元数据同步过程中，驱动程序按照下表将 Doris 类型映射为 Metabase 基础类型：
+
+| Doris 类型 | Metabase 基础类型 |
+|------------|-------------------|
+| `BOOLEAN` | `type/Boolean` |
+| `TINYINT`、`SMALLINT`、`INT`、`INTEGER`，包括 `INT(11)` 等显示宽度 | `type/Integer` |
+| `BIGINT`、`LARGEINT`，包括 `BIGINT(20)` 等显示宽度 | `type/BigInteger` |
+| `FLOAT`、`DOUBLE` | `type/Float` |
+| `DECIMAL` | `type/Decimal` |
+| `DATE`、`DATEV2` | `type/Date` |
+| `TIME`，包括小数秒精度 | `type/Time` |
+| `DATETIME`、`DATETIMEV2`、`TIMESTAMP` | `type/DateTime` |
+| `TIMESTAMPTZ` | `type/DateTimeWithTZ` |
+| `CHAR`、`VARCHAR`、`STRING`、`TEXT` | `type/Text` |
+| `JSON`、`JSONB` | `type/JSON` |
+| `ARRAY` | `type/Array` |
+| `MAP` | `type/Dictionary` |
+| `STRUCT`、`VARIANT`、`HLL`、`BITMAP` | `type/*` |
+
+`ARRAY`、`MAP`、`JSON`、`STRUCT` 或 `VARIANT` 值中的嵌套字段不会展开为 Metabase 子字段。`LARGEINT`
会映射为 `type/BigInteger`，不要求转换为字符串。
### 性能优化建议
diff --git
a/versioned_docs/version-4.x/connection-integration/data-integration/metabase.md
b/versioned_docs/version-4.x/connection-integration/data-integration/metabase.md
index a599068d84f..b3968372954 100644
---
a/versioned_docs/version-4.x/connection-integration/data-integration/metabase.md
+++
b/versioned_docs/version-4.x/connection-integration/data-integration/metabase.md
@@ -2,7 +2,7 @@
{
"title": "Metabase",
"language": "en",
- "description": "Connect to Doris in Metabase using the Apache Doris
Driver, configure data sources, build visualization dashboards with SQL, and
explore Catalogs, parameterized queries, and performance tuning
recommendations.",
+ "description": "Connect Metabase to Apache Doris using the Doris Driver,
configure data sources, build dashboards, and use Catalog and parameterized
SQL.",
"keywords": [
"Metabase connect Doris",
"Apache Doris Metabase Driver",
@@ -17,6 +17,8 @@
Metabase is an open source business intelligence tool that provides data
analysis, data visualization, interactive dashboards, data drill-down, SQL
query editing, and data export. With the Metabase Apache Doris Driver, Metabase
can integrate Apache Doris databases and tables as data sources to query Doris
internal data and external data, and to build visualization dashboards.
+The driver is a standalone Metabase community driver and is not built into
Metabase.
+
This article starts from user scenarios and describes how to complete the
following operations:
| Scenario | User goal | Main operations |
@@ -34,40 +36,63 @@ Before you start configuration, make sure the following
environment is ready:
| Item | Requirement |
|------|------|
-| Metabase | Download and install Metabase 0.48.0 or later. For details, see
the [Metabase installation
documentation](https://www.metabase.com/docs/latest/installation-and-operation/installing-metabase)
|
+| Metabase | Download and install Metabase `0.59.6.3` or later. For
installation instructions, see the [Metabase installation
documentation](https://www.metabase.com/docs/latest/installation-and-operation/installing-metabase)
|
+| Java | Java 21 is required to run Metabase |
| Apache Doris | Prepare an accessible Apache Doris cluster |
-| Doris driver | Download the latest
[metabase-doris-driver](https://velodb-bi-connector-1316291683.cos.ap-hongkong.myqcloud.com/Metabase/latest/doris.metabase-driver.jar)
|
+| Doris driver | Download the [Metabase Doris
Driver](https://github.com/xylaaaaa/metabase-doris-driver/releases/tag/v1.0.0) |
+
+### Download and verify the driver
+
+Download the Release JAR and its checksum file:
+
+```bash
+curl -LO
https://github.com/xylaaaaa/metabase-doris-driver/releases/download/v1.0.0/doris.metabase-driver-v1.0.0.jar
+curl -LO
https://github.com/xylaaaaa/metabase-doris-driver/releases/download/v1.0.0/doris.metabase-driver-v1.0.0.jar.sha256
+sha256sum -c doris.metabase-driver-v1.0.0.jar.sha256
+```
+
+The expected SHA-256 digest is as follows:
+
+```text
+b23e82f19a7f9226343e42566e1e192b6df7a0dfc48a73d2101fc74bfec243f3
+```
### Install the driver for a regular deployment
If Metabase is deployed in the regular way, install the Doris driver as
follows:
-1. Download the Doris Driver.
+1. Download and verify the driver Release files as described above.
-2. Create the Metabase plugins directory (if it does not exist):
+2. If the Metabase plugins directory does not exist, create it:
```bash
- mkdir -p $path_metabase/plugins
+ mkdir -p /path/to/metabase/plugins
```
-3. Copy the JAR file to the plugins directory:
+3. Copy the Release JAR to the plugins directory:
```bash
- cp doris.metabase-driver.jar $path_metabase/plugins
+ cp doris.metabase-driver-v1.0.0.jar
/path/to/metabase/plugins/doris.metabase-driver.jar
```
4. Restart the Metabase service.
+5. Check the Metabase startup log to confirm that the `doris` driver is
registered. In **Admin Settings** > **Databases** > **Add database**, you
should be able to see the **Apache Doris** database type.
+
### Install the driver for a Docker deployment
-If Metabase is started with Docker, you are recommended to start it by
mounting `doris.metabase-driver.jar`. The plugin path inside the Docker
container is `/plugins/`.
+If you start Metabase with Docker, you are recommended to start it by mounting
`doris.metabase-driver.jar`. The plugin path inside the Docker container is
`/plugins/`.
-1. Download the Doris Driver.
+1. Download and verify the driver Release files.
-2. Start Metabase with a command similar to the following:
+2. Start the container with a Metabase image that meets the prerequisites:
```bash
- docker run -d -p 3000:3000 --name metabase -v
$host_path/doris.metabase-driver.jar:/plugins/doris.metabase-driver.jar
metabase/metabase
+ docker run -d \
+ -p 3000:3000 \
+ --name metabase \
+ -v
"$(pwd)/doris.metabase-driver-v1.0.0.jar:/plugins/doris.metabase-driver.jar:ro"
\
+ metabase/metabase
```
## Configure the Doris data source
@@ -79,22 +104,29 @@ After installing Metabase and `metabase-doris-driver`, you
can add a data source
### Connection parameters
-The following parameters are required when connecting to Apache Doris:
+The following fields are required when connecting to Apache Doris:
| Parameter | Meaning | Example |
|------|------|------|
| **Display Name** | Display name of the data source | Doris-TPCH |
| **Host** | Doris FE node address | 127.0.0.1 |
-| **Port** | Doris Query Port (MySQL protocol port) | 9030 |
-| **Catalog name** | Catalog name. Optional, defaults to `internal` | internal
|
-| **Database name** | Database name. Required | tpch |
+| **Port** | Doris Query Port (MySQL protocol port), defaults to `9030` | 9030
|
+| **Catalog** | Catalog name. Optional, defaults to `internal` | internal |
+| **Database (optional)** | The database in the selected Catalog. Optional;
when left empty, all visible databases in the Catalog are discovered | tpch |
| **Username** | Username | root |
| **Password** | Password | your_password |
+| **SSL** | Enable JDBC TLS. The driver uses MariaDB `sslMode=trust` and does
not verify the server certificate or hostname | false |
+| **Sync Schemas Include** | Optional. Used when **Database (optional)** is
empty. A comma-separated allowlist of databases | tpch |
+| **Sync Schemas Exclude** | Optional. Used when **Database (optional)** is
empty. A comma-separated denylist of databases. The exclude rule takes
precedence over the include rule | information_schema |
+| **Additional JDBC connection string options** | Other MariaDB JDBC URL
parameters | connectTimeout=10000 |
+
+Select the Catalog and database scope as follows:
-Fill in the database name as follows:
+- **Internal tables**: Keep **Catalog** as `internal` and fill in a database
such as `tpch`.
+- **External tables**: Fill in the external Catalog and a database visible in
that Catalog.
+- **Multiple databases**: Leave **Database (optional)** empty. The driver
discovers the databases visible to the configured account, and applies the
include and exclude lists before listing the tables in them.
-- **Querying internal tables**: Enter the database name directly, for example
`tpch`. The system automatically uses the `internal` Catalog.
-- **Querying external tables or data lakes**: Fill in the Catalog
configuration. If you only connect to internal tables, you do not need to
consider this option.
+When **Database (optional)** is empty, the driver excludes
`information_schema`, `__internal_schema`, and `mysql` by default. The include
and exclude rules are matched case-insensitively; if the same database appears
in both lists, the exclude rule takes precedence. If **Database (optional)** is
set explicitly, the sync scope is limited to that database, and the include and
exclude settings do not change the sync scope.
### Configuration steps
@@ -119,7 +151,8 @@ Fill in the database name as follows:
| **Display name** | Doris-TPCH |
| **Host** | 127.0.0.1 |
| **Port** | 9030 |
- | **Database name** | tpch |
+ | **Catalog** | internal |
+ | **Database (optional)** | tpch |
| **Username** | admin |
| **Password** | ****** |
@@ -127,7 +160,7 @@ Fill in the database name as follows:
6. Click **Save** to save the configuration.
-7. Metabase automatically tests the connection and synchronizes database
metadata. If the connection succeeds, a success message is displayed.
+7. Metabase tests the connection and starts synchronizing database metadata.
If the connection succeeds, a success message is displayed.
@@ -161,7 +194,7 @@ Suppose you need to analyze how the order amounts of
different shipping methods
To compute the revenue, you need to use a custom SQL expression.
-1. Click **view sql** in the upper right corner to switch, then click
**convert this question to SQL** to edit the SQL.
+1. Click **view sql** in the upper right corner, then click **convert this
question to SQL** to edit the SQL.
@@ -226,6 +259,21 @@ To compute the revenue, you need to use a custom SQL
expression.
You have now successfully connected Metabase to Apache Doris and completed
data analysis and visualization dashboard creation.
+## Driver capabilities and limitations
+
+The following table summarizes the driver capabilities and current support
boundaries.
+
+| Capability | Support status and boundaries |
+|------|------|
+| Internal Catalog | Supports synchronizing and querying Doris internal tables
|
+| Native SQL | Supported. SQL is executed with the permissions of the
configured Doris account; the driver does not force statements to be read-only |
+| Query Builder | Supports group aggregation and bucketing by day |
+| External Catalog | Supports synchronizing and querying data in Doris
External Catalogs; the available scope and metadata completeness depend on the
specific connector |
+| Native template parameters | Supports numeric, text, and optional blocks |
+| Complex types | Top-level `ARRAY`, `MAP`, `JSON`, and opaque complex fields
remain visible; nested subfields are not expanded |
+| Key and index metadata | Primary keys, foreign keys, indexes, and table
permissions are not synchronized |
+| Metabase write features | Data upload, write-back, Actions, data editing,
and persisted models are not supported |
+
## Advanced scenarios
{/* Knowledge type: Feature description */}
@@ -233,38 +281,69 @@ You have now successfully connected Metabase to Apache
Doris and completed data
### Use Catalog to access external data
-Doris supports the multi-Catalog feature, which can query external data
sources and perform cross-data-source queries. When using Catalog in Metabase,
you can choose either of the following options.
-
-1. Configure `Catalog` on the connection configuration page, and configure an
external table database under that Catalog in `Database`. For example:
+Set **Catalog** and **Database (optional)** on the connection page to
synchronize tables in a Doris external Catalog:
- | Configuration | Example value | Description |
- |--------|--------|------|
- | `catalog` | `hive_catalog` | Access the Catalog named `hive_catalog` |
- | `database` | `warehouse` | Access the `warehouse` database under the
Catalog |
+| Configuration | Example value | Description |
+|--------|--------|------|
+| `Catalog` | `hive_catalog` | Select the Doris Catalog named `hive_catalog` |
+| `Database (optional)` | `warehouse` | Select the `warehouse` database in the
Catalog |
-2. Specify the Catalog explicitly in the SQL query:
+Specify the Catalog explicitly in the SQL query:
- ```sql
- SELECT * FROM hive.warehouse.orders LIMIT 100;
- ```
+```sql
+SELECT * FROM hive.warehouse.orders LIMIT 100;
+```
### Use parameterized queries
-Metabase supports using variables in SQL queries, which makes it easy to
create interactive dashboards:
+The driver supports basic Native SQL template parameters. The following
example uses a numeric parameter, a text parameter, and an optional block:
```sql
SELECT
- l_shipmode,
- SUM(l_extendedprice * (1 - l_discount)) AS revenue
-FROM lineitem
-WHERE l_shipdate BETWEEN {{start_date}} AND {{end_date}}
- AND l_shipmode = {{ship_mode}}
-GROUP BY l_shipmode
+ category,
+ COUNT(*) AS row_count,
+ SUM(amount) AS total_amount
+FROM orders
+WHERE amount > {{min_amount}}
+[[AND category = {{category}}]]
+GROUP BY category
```
-After saving, you can dynamically filter data on the dashboard with dropdowns
or date pickers.
+When `category` has no value, Metabase removes the entire optional block.
+
+| Template capability | Support status |
+|----------|----------|
+| Numeric variables | Supported |
+| Text variables | Supported |
+| Optional blocks `[[ ... ]]` | Supported |
+| Field filters | Not supported |
+| Card references such as `{{#card-id}}` | Not supported |
+| Dynamic table references | Not supported |
+
+### Data types
+
+During metadata synchronization, the driver maps Doris types to Metabase base
types as shown in the following table:
+
+| Doris type | Metabase base type |
+|------------|-------------------|
+| `BOOLEAN` | `type/Boolean` |
+| `TINYINT`, `SMALLINT`, `INT`, `INTEGER`, including display widths such as
`INT(11)` | `type/Integer` |
+| `BIGINT`, `LARGEINT`, including display widths such as `BIGINT(20)` |
`type/BigInteger` |
+| `FLOAT`, `DOUBLE` | `type/Float` |
+| `DECIMAL` | `type/Decimal` |
+| `DATE`, `DATEV2` | `type/Date` |
+| `TIME`, including fractional-second precision | `type/Time` |
+| `DATETIME`, `DATETIMEV2`, `TIMESTAMP` | `type/DateTime` |
+| `TIMESTAMPTZ` | `type/DateTimeWithTZ` |
+| `CHAR`, `VARCHAR`, `STRING`, `TEXT` | `type/Text` |
+| `JSON`, `JSONB` | `type/JSON` |
+| `ARRAY` | `type/Array` |
+| `MAP` | `type/Dictionary` |
+| `STRUCT`, `VARIANT`, `HLL`, `BITMAP` | `type/*` |
+
+Nested fields inside `ARRAY`, `MAP`, `JSON`, `STRUCT`, or `VARIANT` values are
not expanded into Metabase subfields. `LARGEINT` maps to `type/BigInteger` and
does not require conversion to a string.
### Performance tuning recommendations
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
