MySQL 外表--ByteHouse 企业版-火山引擎

文档中心

ByteHouse 企业版

外表

MySQL 外表

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

背景信息

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

说明

如需使用本功能，请提工单联系ByteHouse团队开通网络权限。

MySQL 数据映射方式

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

数据映射方式	数据映射说明
创建 MySQL 外部表	在表维度建立 ByteHouse 表到 MySQL 表的映射。源表 schema 变更不会直接同步，如果有变更，需删除 ByteHouse 中的外表重新创建一个外表。
创建 MySQL 外部数据库	在 Database 维度建立 ByteHouse Database 到 MySQL Database 的映射。建立库映射之后不需要再手动建立表映射，可自动同步数据库下的表映射，可以感知 MySQL 表的新增和删除，源表 schema 变更可直接同步至 ByteHouse 中。

费用说明

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

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

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

前提条件

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

使用限制

当前 MySQL 外表访问的网络要求如下：
- 私网访问需要使用 Private Link 方式打通，如需使用该方式，请联系 ByteHouse 团队开通。
- 公网访问需要配置 ByteHouse 公网 IP，详情请参考获取集群连接信息。

创建 MySQL 外部表

CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster](
    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 可以省略，`[]` 表示该字段可省略。 [ON CLUSTER cluster]：指定数据表所在的集群名称。 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：可选，将`INSERT INTO`查询转换为`REPLACE INTO`的标志。 `0` - 查询被执行为 `INSERT INTO`。 `1` - 查询被执行为 `REPLACE INTO`。 on_duplicate_clause：可选，添加 `ON DUPLICATE KEY on_duplicate_clause` 表达式到 `INSERT` 查询。使用此项时，需要设置 `replace_query = 0` 。如果你同时设置`replace_query = 1`和`on_duplicate_clause`，ByteHouse 将产生异常。此时，简单的 `WHERE` 子句（例如 `=, !=, >, >=, <, <=`）是在 MySQL 服务器上执行。其余条件以及 `LIMIT` 采样约束语句仅在对 MySQL 的查询完成后才在 ByteHouse 中执行。 `MySQL` 引擎不支持可为空数据类型，因此，当从 MySQL 表中读取数据时，`NULL` 将转换为指定列类型的默认值（通常为0或空字符串）。

参数

配置说明

数据表描述

[db.]table_name：填写 MySQL 外表的数据库名和表名。如果您在创建 MySQL 外部表之前执行了 USE DATABASE db 命令，则此处的 db 可以省略，[] 表示该字段可省略。
[ON CLUSTER cluster]：指定数据表所在的集群名称。
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：可选，将INSERT INTO查询转换为REPLACE INTO的标志。
- 0 - 查询被执行为 INSERT INTO。
- 1 - 查询被执行为 REPLACE INTO。
on_duplicate_clause：可选，添加 ON DUPLICATE KEY on_duplicate_clause 表达式到 INSERT 查询。使用此项时，需要设置 replace_query = 0 。如果你同时设置replace_query = 1和on_duplicate_clause，ByteHouse 将产生异常。

此时，简单的 WHERE 子句（例如 =, !=, >, >=, <, <=）是在 MySQL 服务器上执行。
其余条件以及 LIMIT 采样约束语句仅在对 MySQL 的查询完成后才在 ByteHouse 中执行。
MySQL 引擎不支持可为空数据类型，因此，当从 MySQL 表中读取数据时，NULL 将转换为指定列类型的默认值（通常为0或空字符串）。

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

DROP TABLE IF EXISTS demo_db.mysql_table ON CLUSTER demo; 

-- 创建 MySQL 外表，需要确保同步的表 DDL 和 ByteHouse 保持一致
CREATE TABLE demo_db.mysql_table ON CLUSTER demo(
    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 ON CLUSTER demo;

创建 MySQL 外部数据库

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

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

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

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

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

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

查询外表

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

SELECT * FROM demo_db.mysql_table LIMIT 10;

删除外部库表

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

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

删除外部数据表

DROP TABLE demo_db.mysql_table ON CLUSTER demo

最近更新时间：2026.05.26 12:43:35

这个页面对您有帮助吗？

有用

无用

ByteHouse 企业版

MySQL 数据映射方式 #

费用说明 #

MySQL 数据映射方式

费用说明