创建 Hive 外部表

在表（Table）维度建立 ByteHouse 表到 Hive 表的映射。源表 schema 变更不会直接同步，如果有变更，需删除 ByteHouse 中的外表重新创建一个外表。

创建 Hive 外部数据库

在数据库（Database）维度建立 ByteHouse Database 到 Hive Database 的映射。建立库映射之后不需要再手动建立表映射，可自动同步数据库下的表映射，可以感知 Hive 表的新增和删除，源表 schema 变更可直接同步至 ByteHouse 中。

创建 Hive 外部 Catalog

在数据目录（Catalog）维度建立 ByteHouse Catalog 到 Hive Catalog 的映射。建立 Catalog 映射之后不需要再手动建立库、表映射，可自动同步 Catalog 下的库、表映射，可以感知 Hive 库、表的新增和删除，源表 schema 变更可直接同步至 ByteHouse 中。创建 Hive 外部 Catalog 的操作详情请参见 Hive Catalog。

建表描述

demo_db.hive_table：在 ByteHouse 的指定数据库中创建 Hive 外表，支持自定义表名。
建表时，系统将自动退到并创建 Hive 表的列名和类型以及 Partition By key, Cluster By key 等信息。列默认建立 Nullable 类型， 列类型映射规则见下文的通用参考：列类型映射章节。

引擎参数（Engine）

• 引擎类型固定为 CnchHive。
• thrift://hive_thrift_server_ip:port：Hive Metastore 服务的连接地址，其中 <hive_thrift_server_ip> 为 Hive Thrift 服务器的 IP 地址，<port> 为端口号，您可参考您使用的 Hive 服务的官方文档获取连接地址信息。示例：thrift://101.xxx.xx.xxx:9083。
• default：指定当前创建的外表映射到 Hive 中的源数据库名称。
• test_table：指定当前创建的外表映射到 Hive 中的源表名称。

设置参数（SETTINGS）

• meta_type：固定为 hive。
• Hive 使用的 S3 兼容对象存储服务的信息：
  • endpoint：S3 兼容对象存储的 endpoint。
  • ak_id：S3 兼容对象存储的 Access Key ID。
  • ak_secret：S3 兼容对象存储的 Secret Access Key。

建表描述

demo_db.hive_las_table：在 ByteHouse 的指定数据库中创建 Hive 外表，支持自定义表名。
建表时，系统将自动退到并创建 Hive 表的列名和类型以及 Partition By key, Cluster By key 等信息。列默认建立 Nullable 类型， 列类型映射规则见下文的通用参考：列类型映射章节。

引擎参数（Engine）

• 引擎类型固定为 CnchHive。
• thrift://lakeformation.las.region.ivolces.com:48869：指定您使用的 LAS 所在地域的访问域名。您可根据您所在的地域，使用链接地址中 Endpoint 列的内容填写该参数。
• default：指定当前创建的外表映射到 Hive 中的源数据库名称。
• test_table：指定当前创建的外表映射到 Hive 中的源表名称。

设置参数（SETTINGS）

• meta_type：固定为 lf。
• LAS 使用的数据存储 TOS 信息：
  • endpoint：TOS 的 endpoint，获取方式请参见地域及访问域名中 S3 Endpoint 列内容，请根据您的实际地域信息填写。
  • ak_id：TOS 的 Access Key ID，获取方式请参见 AccessKey（密钥）管理。
  • ak_secret：TOS 的 Secret Access Key，获取方式请参见 AccessKey（密钥）管理。
• LAS 的认证参数：
  • lf_metastore_url：指定您使用的 LAS 所在地域的访问域名。您可根据您所在的地域，使用链接地址中 Endpoint 列的内容填写该参数。
  • lf_metastore_region：LAS 所处的地域，获取方式请参见地域和可用区选型。
  • lf_metastore_ak_id：LAS 的 Access Key ID，获取方式请参见 AccessKey（密钥）管理。
  • lf_metastore_ak_secret：LAS 的 Secret Access Key，获取方式请参见 AccessKey（密钥）管理。
  • lf_metastore_catalog = 'hive_catalog'：表示创建的外表映射到 LAS 中名为 hive_catalog 的数据目录。使用时请修改为Hive 中实际的数据目录的名称，以火山引擎 LAS 为例，您可登录 LAS 控制台，在左侧导航栏中选择数据湖 > 元数据管理，查看并获取所需的数据目录名称。

DROP 语句

（可选）以下命令用于确保在创建新数据库前，同名的旧数据库已被移除，以避免创建冲突。在生产环境中请谨慎使用此命令。

建库描述

hive_db：在 ByteHouse 中创建 Hive 外部数据库 ，支持自定义库名。

引擎参数（Engine）

• 引擎类型固定为 Hive。
• thrift://hive_thrift_server_ip:port：Hive 元数据存储服务（metastore）的连接地址，其中 <hive_thrift_server_ip> 为 Hive Thrift 服务器的 IP 地址，<port> 为端口号，您可参考您使用的 Hive 服务的官方文档获取连接地址信息。示例：thrift://101.xxx.xx.xxx:9083。
• default：指定当前创建的外部数据库映射到 Hive 中的源数据库名称。

设置参数（SETTINGS）

• meta_type：固定为 hive。
• Hive 使用的 S3 兼容对象存储服务的信息：
  • endpoint：S3 兼容对象存储的 endpoint。
  • ak_id：S3 兼容对象存储的 Access Key ID。
  • ak_secret：S3 兼容对象存储的 Secret Access Key。

DROP 语句

（可选）以下命令用于确保在创建新数据库前，同名的旧数据库已被移除，以避免创建冲突。在生产环境中请谨慎使用此命令。

建库描述

hive_db_las：在 ByteHouse 中创建 Hive 外部数据库 ，支持自定义库名。

引擎参数（Engine）

• 引擎类型固定为 Hive。
• thrift://lakeformation.las.region.ivolces.com:48869：指定您使用的 LAS 所在地域的访问域名。您可根据您所在的地域，使用链接地址中 Endpoint 列的内容填写该参数。
• default：指定当前创建的外表映射到 Hive 中的源数据库名称。

设置参数（SETTINGS）

• meta_type：固定为 lf。
• LAS 使用的数据存储 TOS （火山引擎对象存储服务）信息：
  • endpoint：TOS 的 endpoint，获取方式请参见地域及访问域名中 S3 Endpoint 列内容，请根据您的实际地域信息填写。
  • ak_id：TOS 的 Access Key ID，获取方式请参见 AccessKey（密钥）管理。
  • ak_secret：TOS 的 Secret Access Key，获取方式请参见 AccessKey（密钥）管理。
• LAS 的认证参数：
  • lf_metastore_url：指定您使用的 LAS 所在地域的访问域名。您可根据您所在的地域，使用链接地址中 Endpoint 列的内容填写该参数。
  • lf_metastore_region：LAS 所处的地域，获取方式请参见地域和可用区选型，请根据您所处的地域填写。
  • lf_metastore_ak_id：LAS 的 Access Key ID，获取方式请参见 AccessKey（密钥）管理。
  • lf_metastore_ak_secret：LAS 的 Secret Access Key，获取方式请参见 AccessKey（密钥）管理。
  • lf_metastore_catalog = 'hive_catalog'：表示创建的外部数据库映射到 LAS 中名为 hive_catalog 的数据目录。使用时请修改为Hive 中实际的数据目录的名称，以火山引擎 LAS 为例，您可登录 LAS 控制台，在左侧导航栏中选择数据湖 > 元数据管理，查看并获取所需的数据目录名称。

数据库及表描述

database.table：指定需查询的数据库和表名称。此处的数据库可以是仅创建 Hive 外部表所在的 ByteHouse 数据库，也可以是 Hive 外部数据库。

写入参数描述

• VALUES：填写需插入的数值，填写格式为 (val1, val2, ...), (val1, val2, ...),...，示例如下：

  INSERT INTO demo_db.hive_las_table VALUES (1, 'a', '2021-07-27'), (2, 'b', '2021-07-27')
  

• SELECT：使用 SELECT 查询的结果写入数据，可按照 SELECT 语句的语法填写，示例如下：

  # SELECT 源表中的所有数据插入目标表
  INSERT INTO demo_db.hive_las_table SELECT * FROM example_table
  
  # SELECT 源表中的指定数据插入目标表
  INSERT INTO demo_db.hive_las_table SELECT s,d,n FROM example_table
  

数据库及表描述

database.table：指定需查询的数据库和表名称。此处的数据库可以是仅创建 Hive 外部表所在的 ByteHouse 数据库，也可以是 Hive 外部数据库。

写入参数描述

• VALUES：填写需插入的数值，填写格式为 (val1, val2, ...), (val1, val2, ...),...，示例如下：

  INSERT OVERWRITE demo_db.hive_las_table VALUES (1, 'a', '2021-07-27'), (2, 'b', '2021-07-27')
  

• SELECT：使用 SELECT 查询的结果写入数据，可按照 SELECT 语句的语法填写，示例如下：

  # SELECT 源表中的所有数据插入目标表
  INSERT OVERWRITE demo_db.hive_las_table SELECT * FROM example_table
  
  # SELECT 源表中的指定数据插入目标表
  INSERT OVERWRITE demo_db.hive_las_table SELECT s,d,n FROM example_table
  

bsp_mode

Bool

0（关闭）

设置为 1 表示启用 BSP 模式。启用 BSP 模式后，查询会分阶段执行。阶段之间会使用 shuffle 连接。在失败时会进行任务级别的重试。

distributed_max_parallel_size

UInt64

等于 worker 数量

当单个查询占用内存较大时，通过调大此参数可以增加算子的并行度，减少单个并行度处理数据的数量，减少单位时间内存使用量。必须在启用 bsp_mode 时，distributed_max_parallel_size 的值才能超出 worker 的数量。建议设置为 worker 个数的倍数。

bsp_max_retry_num

UInt64

不同版本默认值不同

任务最大的重试次数。ByteHouse 从 2.0.4 版本开始支持设置 bsp_max_retry_num 参数。不同版本的默认值如下：
ByteHouse 2.0.4/2.1 版本中以 query 粒度记，默认为 5 次。ByteHouse 2.2 版本中以 segment 粒度记，默认为 3 次。
您可通过 ByteHouse 控制台>租户管理>基本信息路径，查看当前 ByteHouse 的版本。

INT/INTEGER

Nullable INT/INTEGER

无

BIGINT

Nullable BIGINT

无

TIMESTAMP

Nullable DateTime

无

STRING

Nullable String

无

VARCHAR

Nullable FixedString

内部转换为 FixedString

CHAR

Nullable FixedString

内部转换为 FixedString

DOUBLE

Nullable DOUBLE

无

FLOAT

Nullable FLOAT

无

DECIMAL

Nullable DECIMAL

无

MAP

Nullable Map

无

ARRAY

Nullable Array

无