MySQL 外表--ByteHouse云数仓版-火山引擎

文档中心

立即注册

ByteHouse云数仓版

外表

MySQL 外表

本文将介绍创建 MySQL 外部数据库和外部表的语法及使用方法。

背景信息

ByteHouse 通过支持 MySQL 外表的方式，借助 MySQL 引擎对存储在远程 MySQL 服务器上的数据执行数据查询。

MySQL 数据映射方式

对于 MySQL 数据表，当前 ByteHouse 支持创建 MySQL 外表、创建 MySQL 外部数据库、创建 MySQL 外部 Catalog 三种方式实现 ByteHouse 与 MySQL 的数据映射。

数据映射方式	数据映射说明
创建 MySQL 外部表	在表维度建立 ByteHouse 表到 MySQL 表的映射。源表 schema 变更不会直接同步，如果有变更，需删除 ByteHouse 中的外表重新创建一个外表。
创建 MySQL 外部数据库	在 Database 维度建立 ByteHouse Database 到 MySQL Database 的映射。建立库映射之后不需要再手动建立表映射，可自动同步数据库下的表映射，可以感知 MySQL 表的新增和删除，源表 schema 变更可直接同步至 ByteHouse 中。
创建 MySQL 外部 Catalog	在数据目录（Catalog）唯独建立 ByteHouse Catalog 到 MySQL Catalog 的映射。建立 Catalog 映射之后不需要再手动建立库、表映射，可自动同步 Catalog 下的库、表映射，可以感知 Paimon 库、表的新增和删除，源表 schema 变更可直接同步至 ByteHouse 中。创建 MySQL 外部 Catalog 的操作详情请参见 MySQL Catalog。

费用说明

外部表的功能旨在提供除 ByteHouse 内部表以外的其他数据的处理能力。通过一条简单的 DDL 语句，即可在 ByteHouse 上创建一张外部表，建立 ByteHouse 表与外部数据源的关联。

外部表在 ByteHouse 侧只会产生计算费用，遵循 ByteHouse 计算资源计费规则。
使用外部表功能时，外部表的数据不会复制一份存在 ByteHouse 上并产生存储费用。存储费用请关注外部数据源存储侧计费规则。
使用 ByteHouse 外部表访问外部数据源时，外部数据源可能会产生计算、访问、数据传输等费用，具体以外部数据源计费方式为准，请关注相应产品的说明。前提条件

在执行 MySQL 外表的创建、查询、更新、删除操作前，请确保您已获得该库、表对应的读写权限。

前提条件

在执行 MySQL 外表的查询或管理操作前，请确保您已获得该表对应的读写权限。

使用限制

当前 MySQL 外表访问的网络要求如下：
- 私网访问需要使用 Private Link 方式打通，如需使用该方式，请联系 ByteHouse 团队开通。
- 公网访问需要配置 ByteHouse 公网 IP，设置详情请参考设置网络信息。
若您所在的网络环境存在访问限制，请将 ByteHouse 服务 IP 地址加入白名单，详情请参考设置 IP 白名单。

创建 MySQL 外部表

CREATE TABLE [IF NOT EXISTS] [db.]table_name (
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1] [TTL expr1],
    name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2] [TTL expr2],
    ...
) ENGINE = MySQL('host:port', 'database', 'table', 'user', 'password'[, replace_query, 'on_duplicate_clause']);

参数	配置说明
数据表描述	[db.]table_name：填写 MySQL 外表的数据库名和表名。如果您在创建 MySQL 外部表之前执行了 `USE DATABASE db` 命令，则此处的 db 可以省略，`[]` 表示该字段可省略。 name1 [type1] ：MySQL 表的列名及列的数据类型。列名需与 MySQL 源表保持一致。 ByteHouse 兼容了 MySQL 5.7 和 MySQL 8.0 常用功能和语法，更多数据类型兼容性的介绍请参见基本数据类型。 [DEFAULT DEFAULT：可选，为列设置默认值表达式。 MATERIALIZED：可选，为列设置物化视图表达式。 ALIAS expr1：可选，为列设置别名表达式。 [TTL expr1]：可选，为列设置生命周期表达式。
引擎参数（Engine）	host:port：填写 MySQL 服务器地址。注意该 host:port 需要支持公网访问。 database：填写 MySQL 数据库的名称。 table：填写 MySQL 表的名称。 user：填写 MySQL 数据库用户名。 password：填写 MySQL 用户密码。 replace_query：可选，可选值为 0 或 1，用于控制写入时的冲突处理：取值 1：开启 REPLACE 模式，写入时若主键 / 唯一键冲突，直接替换 MySQL 源表的现有数据；取值 0（默认）：关闭 REPLACE 模式，冲突时返回报错。 on_duplicate_clause：可选，自定义冲突处理子句（仅当 `replace_query=0` 时生效），需符合 MySQL 的 `ON DUPLICATE KEY UPDATE` 语法。示例：`'ON DUPLICATE KEY UPDATE name=VALUES(name), age=VALUES(age)'`；需确保 MySQL 源表存在主键 / 唯一键，否则该子句无效。

参数

配置说明

数据表描述

[db.]table_name：填写 MySQL 外表的数据库名和表名。如果您在创建 MySQL 外部表之前执行了 USE DATABASE db 命令，则此处的 db 可以省略，[] 表示该字段可省略。
name1 [type1] ：MySQL 表的列名及列的数据类型。
- 列名需与 MySQL 源表保持一致。
- ByteHouse 兼容了 MySQL 5.7 和 MySQL 8.0 常用功能和语法，更多数据类型兼容性的介绍请参见基本数据类型。
[DEFAULT
- DEFAULT：可选，为列设置默认值表达式。
- MATERIALIZED：可选，为列设置物化视图表达式。
- ALIAS expr1：可选，为列设置别名表达式。
[TTL expr1]：可选，为列设置生命周期表达式。

引擎参数（Engine）

host:port：填写 MySQL 服务器地址。
注意
该 host:port 需要支持公网访问。
database：填写 MySQL 数据库的名称。
table：填写 MySQL 表的名称。
user：填写 MySQL 数据库用户名。
password：填写 MySQL 用户密码。
replace_query：可选，可选值为 0 或 1，用于控制写入时的冲突处理：
- 取值 1：开启 REPLACE 模式，写入时若主键 / 唯一键冲突，直接替换 MySQL 源表的现有数据；
- 取值 0（默认）：关闭 REPLACE 模式，冲突时返回报错。
on_duplicate_clause：可选，自定义冲突处理子句（仅当 replace_query=0 时生效），需符合 MySQL 的 ON DUPLICATE KEY UPDATE 语法。
- 示例：'ON DUPLICATE KEY UPDATE name=VALUES(name), age=VALUES(age)'；
- 需确保 MySQL 源表存在主键 / 唯一键，否则该子句无效。

示例
使用时，请使用实际的连接地址、数据库、表、用户名和密码替换命令中的示例。

DROP TABLE IF EXISTS demo_db.mysql_table; 

-- 创建 MySQL 外表，需要确保同步的表 DDL 和 ByteHouse 保持一致
CREATE TABLE demo_db.mysql_table(
    id Int32,
    name String
) ENGINE = MySQL('127.x.x.1:3306', 'test_db', 'test_tb', 'demo_user', 'password');

-- 查看建表语句
SHOW CREATE TABLE demo_db.mysql_table;

创建 MySQL 外部数据库

通过创建 ByteHouse 外部数据库，在 Database 维度建立 ByteHouse Database 到 MySQL Database 的映射。建立库映射之后不需要再手动建立表映射，可自动同步数据库下的表映射。

CREATE DATABASE [IF NOT EXISTS] database_name
ENGINE = MySQL('host:port', 'database', 'user', 'password');

参数	配置说明
数据库描述	自定义外部数据库名称。
引擎参数（Engine）	host:port：填写 MySQL 服务器地址。注意该 host:port 需要支持公网访问。如需私网访问，请联系 ByteHouse 团队开通 Private Link。 database：填写 MySQL 数据库的名称。 user：填写 MySQL 数据库用户名。 password：填写 MySQL 用户密码。

示例
使用时，请使用实际的连接地址、数据库、用户名和密码替换命令中的占位符。

-- 创建 MySQL 外部数据库
CREATE DATABASE mysql_db
ENGINE = MySQL('127.x.x.1:3306', 'test_db', 'demo_user', 'password');

-- 查询建库语句
SHOW CREATE DATABASE mysql_db;

查询外表

外表的查询和普通表的查询操作一致。

SELECT * FROM demo_db.mysql_table LIMIT 10;

删除外部库表

外部库表的删除操作和普通表的删除操作一致。

删除外部数据库
注意
删除外部数据库后，外部数据库下的所有外部表也将同时被删除，请谨慎操作。
```
DROP DATABASE mysql_db
```
删除外部数据表
```
DROP TABLE demo_db.mysql_table
```

最近更新时间：2026.01.08 15:53:45

这个页面对您有帮助吗？

有用

无用

ByteHouse云数仓版

MySQL 数据映射方式 #

费用说明 #

MySQL 数据映射方式

费用说明