AI 助理
备案控制台
文档
输入文档关键字查找
首页 开源大数据平台 E-MapReduce EMR Serverless StarRocks 操作指南 开发指南 数据目录 Hive Catalog

Hive Catalog

更新时间：
产品详情
我的收藏

Hive Catalog是一种External Catalog，自2.3版本开始支持。

背景信息

通过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版本起开始支持。

说明

您可以通过GRANT和REVOKE操作对用户和角色进行权限的赋予和收回。

语法

切换至目标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版本起开始支持。仅支持删除空数据库。

说明

您可以通过GRANT和REVOKE操作对用户和角色进行权限的赋予和收回。

删除数据库操作并不会将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>]

参数说明

  • column_definition

    column_definition语法定义如下所示。

    col_name col_type [COMMENT 'comment']

    涉及参数说明如下表所示。

    参数

    说明

    col_name

    列名称。

    col_type

    列数据类型。

    • 当前支持如下数据类型：TINYINT、SMALLINT、INT、BIGINT、FLOAT、DOUBLE、DECIMAL、DATE、DATETIME、CHAR、VARCHAR[(length)]、ARRAY、MAP、STRUCT。

    • 不支持LARGEINT、HLL、BITMAP类型。

    说明

    所有非分区列的默认值均为NULL（即，在建表语句中指定DEFAULT "NULL"）。分区列必须在最后声明，且不能为NULL。

  • partition_desc

    partition_desc语法定义如下所示。

    PARTITION BY (par_col1[, par_col2...])

    目前StarRocks仅支持Identity Transforms。 即为每个唯一的分区值创建一个分区。

    说明

    分区列必须在最后声明，支持除FLOAT、DOUBLE、DECIMAL、DATETIME以外的数据类型，并且不支持NULL值。此外，partition_desc中声明的分区列的顺序必须与column_definition中定义的列的顺序一致。

  • PROPERTIES

    可以在PROPERTIES中通过"key" = "value"的形式声明Hive表的属性。以下列出几个常见的属性。

    属性

    描述

    location

    Managed Table所在的文件路径。使用HMS作为元数据服务时，您无需指定location参数。

    file_format

    Managed Table的文件格式。当前支持Parquet、ORC、TextFile文件格式，其中ORC和TextFile文件格式自3.3版本起支持。取值范围：parquet、orc、textfile。默认值：parquet。

    compression_codec

    Managed Table的压缩格式。该属性自3.2.3版本起弃用，此后写入Hive表时的压缩算法统一由会话变量connector_sink_compression_codec控制。

示例

以下建表语句以默认的 Parquet 格式为例。

  • 创建非分区表unpartition_tbl，包含id和score两列。

    CREATE TABLE unpartition_tbl
(
    id int,
    score double
);

  • 创建分区表partition_tbl_1，包含action、id、dt三列，并定义id和dt为分区列。

    CREATE TABLE partition_tbl_1
(
    action varchar(20),
    id int NOT NULL,
    dt date NOT NULL
)
PARTITION BY (id,dt);

  • 查询原表partition_tbl_1的数据，并根据查询结果创建分区表partition_tbl_2，定义id和dt为partition_tbl_2的分区列：

    CREATE TABLE partition_tbl_2
PARTITION BY (id, dt)
AS SELECT * from partition_tbl_1;

查看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打开。

说明

  • 您可以通过GRANT和REVOKE操作对用户和角色进行权限的赋予和收回。

  • 您可以通过会话变量connector_sink_compression_codec来指定写入Hive表时的压缩算法。

切换至目标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 }
说明

分区列不允许为NULL，因此导入时需要保证分区列有值。

参数说明

参数

说明

INTO

将数据追加写入目标表。

OVERWRITE

将数据覆盖写入目标表。

column_name

导入的目标列。可以指定一个或多个列。指定多个列时，必须用逗号 (,) 分隔。指定的列必须是目标表中存在的列，并且必须包含分区列。该参数可以与源表中的列名称不同，但顺序需一一对应。如果不指定该参数，则默认导入数据到目标表中的所有列。如果源表中的某个非分区列在目标列不存在，则写入默认值NULL。如果查询语句的结果列类型与目标列的类型不一致，会进行隐式转化，如果不能进行转化，那么INSERT INTO语句会报语法解析错误。

expression

表达式，用以为对应列赋值。

DEFAULT

为对应列赋予默认值。

query

查询语句，查询的结果会导入至目标表中。查询语句支持任意StarRocks支持的SQL查询语法。

PARTITION

导入的目标分区。需要指定目标表的所有分区列，指定的分区列的顺序可以与建表时定义的分区列的顺序不一致。指定分区时，不允许通过列名 (column_name) 指定导入的目标列。

示例

以下写入语句以默认的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。

说明

您可以通过GRANT和REVOKE操作对用户和角色进行权限的赋予和收回。

执行删除表的操作时，您必须在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侧新增分区后，需要查询这些新增分区。

说明

  • 自2.5.5版本起，StarRocks支持周期性刷新Hive元数据缓存。开启此功能后，默认每10分钟将自动刷新Hive元数据缓存，这样在大部分情况下，您无需执行手动更新。只有在新增分区后并需要立即查询这些数据时，才需手动更新。

  • REFRESH EXTERNAL TABLE只会更新FE中已缓存的表和分区。

相关文档

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

上一篇：Default Catalog下一篇：Iceberg Catalog
文档推荐