Hive Catalog

背景信息

通过Hive Catalog，您可以：

• 直接查询Hive数据，无需手动建表。

• 使用INSERT INTO或在3.1版本及以上版本中利用异步物化视图，对Hive数据进行加工和建模，并导入到StarRocks。

• 在StarRocks中创建或删除Hive数据库表，或通过INSERT INTO将StarRocks表数据写入Parquet（自3.2版本起）、ORC或TextFile（自3.3版本起）格式的Hive表中。

为保证正常访问Hive内的数据，StarRocks集群必须能够访问Hive集群的存储系统和元数据服务。目前StarRocks支持以下存储系统和元数据服务：

• 分布式文件系统（HDFS）或阿里云对象存储OSS。

• 元数据服务。当前支持的元数据服务包括数据湖构建（DLF）和Hive Metastore（以下简称HMS）。

使用限制​

• StarRocks查询Hive内的数据时，支持Parquet、ORC、TextFile、Avro、RCFile、SequenceFile文件格式，其中：

  • Parquet文件支持SNAPPY、LZ4、ZSTD、GZIP和NO_COMPRESSION 压缩格式。自v3.1.5起，Parquet文件还支持LZO压缩格式。

  • ORC文件支持ZLIB、SNAPPY、LZO、LZ4、ZSTD和NO_COMPRESSION压缩格式。

  • TextFile文件从v3.1.5起支持LZO压缩格式。

• StarRocks查询Hive内的数据时，不支持INTERVAL、BINARY和UNION三种数据类型。此外，对于TextFile格式的Hive表，StarRocks不支持MAP、STRUCT数据类型。

• StarRocks写入数据到Hive时，支持Parquet（3.2版本及以上）、以及ORC或TextFile（3.3版本及以上）文件格式，其中：

  • Parquet和ORC文件支持NO_COMPRESSION、SNAPPY、LZ4、ZSTD和GZIP压缩格式。

  • TextFile文件支持NO_COMPRESSION压缩格式。

  您可以通过系统变量connector_sink_compression_codec来设置写入到Hive表时的压缩算法。

创建Hive Catalog

语法​

CREATE EXTERNAL CATALOG <catalog_name>
[COMMENT <comment>]
PROPERTIES
(
    "type" = "hive",
    GeneralParams,
    MetastoreParams
)

参数说明

• catalog_name：Hive Catalog的名称，必选参数。命名要求如下：

  • 必须由字母（a~z或A~Z）、数字（0~9）或下划线（_）组成，并且只能以字母开头。

  • 总长度不能超过64个字符。

• comment：Hive Catalog的描述。此参数为可选。

• type：数据源的类型。设置为hive。

• GeneralParams：指定通用设置的一组参数。GeneralParams包含如下参数。

  参数	是否必须	说明
  enable_recursive_listing	否	指定StarRocks是否递归读取表或者分区目录（包括子目录）中文件的数据。取值范围： true（默认值）：表示递归遍历。 false：表示只读取表或者分区目录当前层级中文件的数据。

• MetastoreParams：StarRocks访问Hive集群元数据的相关参数配置。Hive使用的元数据类型不同，参数的配置也不同。

  • 使用DLF

    属性	说明
    hive.metastore.type	Hive使用的元数据类型，设置为dlf。
    dlf.catalog.id	DLF中已有的数据目录ID。仅当hive.metastore.type配置为dlf时需要填写该参数。如果未配置dlf.catalog.id参数的值，则系统将使用默认的DLF Catalog。

  • 使用HMS

    属性	说明
    hive.metastore.type	配置MetaStore类型，默认为空，表示使用Hive MetaStore的元数据。
    hive.metastore.uris	Hive MetaStore的URI。格式为thrift://<Hive MetaStore的IP地址>:<端口号>，端口号默认为9083。

示例

以下示例使用HDFS作为存储，创建了一个名为hive_catalog的Hive Catalog。

CREATE EXTERNAL CATALOG hive_catalog
PROPERTIES
(
    "type" = "hive",
    "hive.metastore.uris" = "thrift://xx.xx.xx.xx:9083"
);

查看Hive Catalog

您可以通过SHOW CATALOGS查询当前所在StarRocks里所有Catalog。

SHOW CATALOGS;

您也可以通过SHOW CREATE CATALOG查询某个External Catalog的创建语句。例如，通过如下命令查询Hive Cataloghive_catalog的创建语句。

SHOW CREATE CATALOG hive_catalog;

切换Hive Catalog和数据库​

您可以通过如下方法切换至目标Hive Catalog和数据库：

• 先通过SET CATALOG指定当前会话生效的Hive Catalog，然后再通过USE指定数据库。

  -- 切换当前会话生效的Catalog。
  SET CATALOG <catalog_name>;
  
  -- 指定当前会话生效的数据库。
  USE <db_name>;

• 通过USE直接将会话切换到目标Hive Catalog下的指定数据库。

  USE <catalog_name>.<db_name>;

删除Hive Catalog​

您可以通过DROP CATALOG删除某个External Catalog。

例如，通过以下命令删除hive_catalog。

DROP Catalog hive_catalog;

创建Hive数据库

与StarRocks内部数据目录（Internal Catalog）一致，如果您拥有Hive Catalog的CREATE DATABASE权限，则可以通过使用CREATE DATABASE语句在该Hive Catalog内创建数据库。本功能自3.2版本起开始支持。

语法

切换至目标Hive Catalog，然后通过以下语句创建Hive数据库。

CREATE DATABASE <database_name>
[PROPERTIES ("location" = "<prefix>://<path_to_database>/<database_name.db>")]

参数说明

如果您在创建数据库时不指定location，那么系统会使用默认的<warehouse_location>/<database_name.db>作为文件路径。

location参数用于指定数据库所在的文件路径，支持HDFS和对象存储：

• HDFS：Prefix取值为hdfs。

• 阿里云OSS或OSS-HDFS：取值为oss。

删除Hive数据库

同StarRocks内部数据库一致，如果您拥有Hive数据库的DROP权限，那么您可以使用DROP DATABASE来删除该Hive数据库。本功能自3.2版本起开始支持。仅支持删除空数据库。

删除数据库操作并不会将HDFS或对象存储上的对应文件路径删除。

切换至目标Hive Catalog，然后通过以下语句删除 Hive 数据库。

DROP DATABASE <database_name>;

创建Hive表

同StarRocks内部数据库一致，如果您拥有Hive数据库的CREATE TABLE权限，那么您可以使用CREATE TABLE、CREATE TABLE AS SELECT (CTAS)、或[CREATE TABLE LIKE](../../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_LIKE.md)，在该Hive数据库下创建Managed Table。

本功能自3.2版本起开始支持，彼时只支持创建Parquet格式的Hive表。自3.3版本起，该功能还支持创建ORC及TextFile格式的Hive表。

切换至目标Hive Catalog和数据库，然后通过以下语句创建Hive的 Managed Table。

CREATE TABLE [IF NOT EXISTS] [database.]table_name
(column_definition1[, column_definition2, ...
partition_column_definition1,partition_column_definition2...])
[partition_desc]
[PROPERTIES ("key" = "value", ...)]
[AS SELECT query]
[LIKE [database.]<source_table_name>]

查看Hive表结构

您可以通过如下方法查看Hive表的表结构：

• 查看表结构

  DESC[RIBE] <catalog_name>.<database_name>.<table_name>;

• 从CREATE命令查看表结构和表文件存放位置

  SHOW CREATE TABLE <catalog_name>.<database_name>.<table_name>;

查看Hive表数据

• 方式一：直接查询表数据

  SELECT * FROM <catalog_name>.<database_name>.<table_name>;

• 方式二：逐步查看与查询

  1. 查看指定Catalog所属的Hive集群中的数据库。

     SHOW DATABASES FROM <catalog_name>;

  2. 切换Hive Catalog和数据库。

  3. 查询目标表的数据。

     SELECT count(*) FROM <table_name> LIMIT 10;

导入Hive数据

假设有一个OLAP表，表名为olap_tbl。您可以通过以下方式转换该表中的数据，并将数据导入到StarRocks中。

INSERT INTO default_catalog.olap_db.olap_tbl SELECT * FROM hive_table;

赋予Hive表和视图的权限​

您可以通过GRANT来赋予角色某个Hive Catalog内所有表和视图的查询权限。命令语法如下所示。

GRANT SELECT ON ALL TABLES IN ALL DATABASES TO ROLE <role_name>

例如，通过如下命令创建角色hive_role_table，切换至 Hive Cataloghive_catalog，然后把hive_catalog内所有表和视图的查询权限都赋予hive_role_table。

-- 创建角色 hive_role_table。
CREATE ROLE hive_role_table;

-- 切换到数据目录 hive_catalog。
SET CATALOG hive_catalog;

-- 把hive_catalog内所有表和视图的查询权限赋予hive_role_table。
GRANT SELECT ON ALL TABLES IN ALL DATABASES TO ROLE hive_role_table;

向Hive表中插入数据

同StarRocks内表一致，如果您拥有Hive表（Managed Table或External Table）的INSERT权限，那么您可以使用INSERT将StarRocks表数据写入到该Hive表中。

本功能自3.2版本起开始支持，彼时只支持写入到Parquet格式的Hive表。自3.3版本起，该功能还支持写入到ORC及TextFile格式的Hive表。

需要注意的是，写数据到External Table的功能默认是关闭的，您需要通过系统变量ENABLE_WRITE_HIVE_EXTERNAL_TABLE打开。

切换至目标Hive Catalog和数据库，然后通过如下语法将StarRocks表数据写入到Parquet格式的Hive表中。

语法

INSERT {INTO | OVERWRITE} <table_name>
[ (column_name [, ...]) ]
{ VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }

-- 向指定分区写入数据。
INSERT {INTO | OVERWRITE} <table_name>
PARTITION (par_col1=<value> [, par_col2=<value>...])
{ VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }

参数说明

示例

以下写入语句以默认的Parquet格式为例。

• 向表partition_tbl_1中插入如下三行数据。

  INSERT INTO partition_tbl_1 VALUES("buy", 1, "2023-09-01"),("sell", 2, "2023-09-02"),("buy", 3, "2023-09-03");

• 向表partition_tbl_1按指定列顺序插入一个包含简单计算的SELECT查询的结果数据。

  INSERT INTO partition_tbl_1 (id, action, dt) SELECT 1+1, 'buy', '2023-09-03';

• 向表partition_tbl_1中插入一个从其自身读取数据的SELECT查询的结果。

  INSERT INTO partition_tbl_1 SELECT 'buy', 1, date_add(dt, INTERVAL 2 DAY)FROM partition_tbl_1WHERE id=1;

• 向表partition_tbl_2中dt='2023-09-01'、id=1的分区插入一个 SELECT 查询的结果数据。

  • 方式1

    INSERT INTO partition_tbl_2 SELECT 'order', 1, '2023-09-01';

  • 方式2

    INSERT INTO partition_tbl_2 partition(dt='2023-09-01',id=1) SELECT 'order';

• 将表partition_tbl_1中dt='2023-09-01'、id=1的分区下所有action列值全部覆盖为close：

  • 方式1

    INSERT OVERWRITE partition_tbl_1 SELECT 'close', 1, '2023-09-01';

  • 方式2

    INSERT OVERWRITE partition_tbl_1 partition(dt='2023-09-01',id=1) SELECT 'close';

删除Hive表

同StarRocks内表一致，如果您拥有Hive表的DROP权限，那么您可以使用DROP TABLE来删除该Hive表。本功能自3.2版本起开始支持。注意当前只支持删除Hive的Managed Table。

执行删除表的操作时，您必须在DROP TABLE语句中指定FORCE关键字。该操作不会删除表对应的文件路径，但是会删除HDFS或对象存储上的表数据。请您谨慎执行该操作。

切换至目标Hive Catalog和数据库，然后通过以下语句删除Hive表。

DROP TABLE <table_name> FORCE

手动或自动更新元数据缓存

StarRocks默认会缓存Hive的元数据，并以异步模式自动更新这些缓存，以提升查询性能。如果对Hive表进行结构变更或其他更新，您可以使用以下命令手动更新该表的元数据，以确保StarRocks能及时生成高效的查询计划。

REFRESH EXTERNAL TABLE <table_name> [PARTITION ('partition_name', ...)]

以下情况适合执行手动更新元数据：

• 已有分区内的数据文件发生变更，例如执行过INSERT OVERWRITE ... PARTITION ...命令。

• Hive表的Schema发生变更。

• Hive表被DROP后重建一个同名Hive表。

• 创建Hive Catalog时在PROPERTIES中指定"enable_cache_list_names" = "true"，此时在Hive侧新增分区后，需要查询这些新增分区。

相关文档

Hive更多介绍，请参见Hive概述。