背景信息

通過(guò)Hive Catalog，您可以：

• 直接查詢Hive數(shù)據(jù)，無(wú)需手動(dòng)建表。

• 使用INSERT INTO或在3.1版本及以上版本中利用異步物化視圖，對(duì)Hive數(shù)據(jù)進(jìn)行加工和建模，并導(dǎo)入到StarRocks。

• 在StarRocks中創(chuàng)建或刪除Hive數(shù)據(jù)庫(kù)表，或通過(guò)INSERT INTO將StarRocks表數(shù)據(jù)寫入Parquet（自3.2版本起）、ORC或TextFile（自3.3版本起）格式的Hive表中。

為保證正常訪問(wèn)Hive內(nèi)的數(shù)據(jù)，StarRocks集群必須能夠訪問(wèn)Hive集群的存儲(chǔ)系統(tǒng)和元數(shù)據(jù)服務(wù)。目前StarRocks支持以下存儲(chǔ)系統(tǒng)和元數(shù)據(jù)服務(wù)：

• 分布式文件系統(tǒng)（HDFS）或阿里云對(duì)象存儲(chǔ)OSS。

• 元數(shù)據(jù)服務(wù)。當(dāng)前支持的元數(shù)據(jù)服務(wù)包括數(shù)據(jù)湖構(gòu)建（DLF）和Hive Metastore（以下簡(jiǎn)稱HMS）。

使用限制?

• StarRocks查詢Hive內(nèi)的數(shù)據(jù)時(shí)，支持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內(nèi)的數(shù)據(jù)時(shí)，不支持INTERVAL、BINARY和UNION三種數(shù)據(jù)類型。此外，對(duì)于TextFile格式的Hive表，StarRocks不支持MAP、STRUCT數(shù)據(jù)類型。

• StarRocks寫入數(shù)據(jù)到Hive時(shí)，支持Parquet（3.2版本及以上）、以及ORC或TextFile（3.3版本及以上）文件格式，其中：

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

  • TextFile文件支持NO_COMPRESSION壓縮格式。

  您可以通過(guò)系統(tǒng)變量connector_sink_compression_codec來(lái)設(shè)置寫入到Hive表時(shí)的壓縮算法。

創(chuàng)建Hive Catalog

語(yǔ)法?

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

參數(shù)說(shuō)明

• catalog_name：Hive Catalog的名稱，必選參數(shù)。命名要求如下：

  • 必須由字母（a~z或A~Z）、數(shù)字（0~9）或下劃線（_）組成，并且只能以字母開頭。

  • 總長(zhǎng)度不能超過(guò)64個(gè)字符。

• comment：Hive Catalog的描述。此參數(shù)為可選。

• type：數(shù)據(jù)源的類型。設(shè)置為hive。

• GeneralParams：指定通用設(shè)置的一組參數(shù)。GeneralParams包含如下參數(shù)。

  參數(shù)	是否必須	說(shuō)明
  enable_recursive_listing	否	指定StarRocks是否遞歸讀取表或者分區(qū)目錄（包括子目錄）中文件的數(shù)據(jù)。取值范圍： true（默認(rèn)值）：表示遞歸遍歷。 false：表示只讀取表或者分區(qū)目錄當(dāng)前層級(jí)中文件的數(shù)據(jù)。

• MetastoreParams：StarRocks訪問(wèn)Hive集群元數(shù)據(jù)的相關(guān)參數(shù)配置。Hive使用的元數(shù)據(jù)類型不同，參數(shù)的配置也不同。

  • 使用DLF

    屬性	說(shuō)明
    hive.metastore.type	Hive使用的元數(shù)據(jù)類型，設(shè)置為dlf。
    dlf.catalog.id	DLF中已有的數(shù)據(jù)目錄ID。僅當(dāng)hive.metastore.type配置為dlf時(shí)需要填寫該參數(shù)。如果未配置dlf.catalog.id參數(shù)的值，則系統(tǒng)將使用默認(rèn)的DLF Catalog。

  • 使用HMS

    屬性	說(shuō)明
    hive.metastore.type	配置MetaStore類型，默認(rèn)為空，表示使用Hive MetaStore的元數(shù)據(jù)。
    hive.metastore.uris	Hive MetaStore的URI。格式為thrift://<Hive MetaStore的IP地址>:<端口號(hào)>，端口號(hào)默認(rèn)為9083。

示例

以下示例使用HDFS作為存儲(chǔ)，創(chuàng)建了一個(gè)名為hive_catalog的Hive Catalog。

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

查看Hive Catalog

您可以通過(guò)SHOW CATALOGS查詢當(dāng)前所在StarRocks里所有Catalog。

SHOW CATALOGS;

您也可以通過(guò)SHOW CREATE CATALOG查詢某個(gè)External Catalog的創(chuàng)建語(yǔ)句。例如，通過(guò)如下命令查詢Hive Cataloghive_catalog的創(chuàng)建語(yǔ)句。

SHOW CREATE CATALOG hive_catalog;

切換Hive Catalog和數(shù)據(jù)庫(kù)?

您可以通過(guò)如下方法切換至目標(biāo)Hive Catalog和數(shù)據(jù)庫(kù)：

• 先通過(guò)SET CATALOG指定當(dāng)前會(huì)話生效的Hive Catalog，然后再通過(guò)USE指定數(shù)據(jù)庫(kù)。

  -- 切換當(dāng)前會(huì)話生效的Catalog。
  SET CATALOG <catalog_name>;
  
  -- 指定當(dāng)前會(huì)話生效的數(shù)據(jù)庫(kù)。
  USE <db_name>;

• 通過(guò)USE直接將會(huì)話切換到目標(biāo)Hive Catalog下的指定數(shù)據(jù)庫(kù)。

  USE <catalog_name>.<db_name>;

刪除Hive Catalog?

您可以通過(guò)DROP CATALOG刪除某個(gè)External Catalog。

例如，通過(guò)以下命令刪除hive_catalog。

DROP Catalog hive_catalog;

創(chuàng)建Hive數(shù)據(jù)庫(kù)

與StarRocks內(nèi)部數(shù)據(jù)目錄（Internal Catalog）一致，如果您擁有Hive Catalog的CREATE DATABASE權(quán)限，則可以通過(guò)使用CREATE DATABASE語(yǔ)句在該Hive Catalog內(nèi)創(chuàng)建數(shù)據(jù)庫(kù)。本功能自3.2版本起開始支持。

語(yǔ)法

切換至目標(biāo)Hive Catalog，然后通過(guò)以下語(yǔ)句創(chuàng)建Hive數(shù)據(jù)庫(kù)。

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

參數(shù)說(shuō)明

如果您在創(chuàng)建數(shù)據(jù)庫(kù)時(shí)不指定location，那么系統(tǒng)會(huì)使用默認(rèn)的<warehouse_location>/<database_name.db>作為文件路徑。

location參數(shù)用于指定數(shù)據(jù)庫(kù)所在的文件路徑，支持HDFS和對(duì)象存儲(chǔ)：

• HDFS：Prefix取值為hdfs。

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

刪除Hive數(shù)據(jù)庫(kù)

同StarRocks內(nèi)部數(shù)據(jù)庫(kù)一致，如果您擁有Hive數(shù)據(jù)庫(kù)的DROP權(quán)限，那么您可以使用DROP DATABASE來(lái)刪除該Hive數(shù)據(jù)庫(kù)。本功能自3.2版本起開始支持。僅支持刪除空數(shù)據(jù)庫(kù)。

刪除數(shù)據(jù)庫(kù)操作并不會(huì)將HDFS或?qū)ο蟠鎯?chǔ)上的對(duì)應(yīng)文件路徑刪除。

切換至目標(biāo)Hive Catalog，然后通過(guò)以下語(yǔ)句刪除 Hive 數(shù)據(jù)庫(kù)。

DROP DATABASE <database_name>;

創(chuàng)建Hive表

同StarRocks內(nèi)部數(shù)據(jù)庫(kù)一致，如果您擁有Hive數(shù)據(jù)庫(kù)的CREATE TABLE權(quán)限，那么您可以使用CREATE TABLE、CREATE TABLE AS SELECT (CTAS)、或[CREATE TABLE LIKE](../../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_LIKE.md)，在該Hive數(shù)據(jù)庫(kù)下創(chuàng)建Managed Table。

本功能自3.2版本起開始支持，彼時(shí)只支持創(chuàng)建Parquet格式的Hive表。自3.3版本起，該功能還支持創(chuàng)建ORC及TextFile格式的Hive表。

切換至目標(biāo)Hive Catalog和數(shù)據(jù)庫(kù)，然后通過(guò)以下語(yǔ)句創(chuàng)建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表結(jié)構(gòu)

您可以通過(guò)如下方法查看Hive表的表結(jié)構(gòu)：

• 查看表結(jié)構(gòu)

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

• 從CREATE命令查看表結(jié)構(gòu)和表文件存放位置

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

查看Hive表數(shù)據(jù)

• 方式一：直接查詢表數(shù)據(jù)

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

• 方式二：逐步查看與查詢

  1. 查看指定Catalog所屬的Hive集群中的數(shù)據(jù)庫(kù)。

     SHOW DATABASES FROM <catalog_name>;

  2. 切換Hive Catalog和數(shù)據(jù)庫(kù)。

  3. 查詢目標(biāo)表的數(shù)據(jù)。

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

導(dǎo)入Hive數(shù)據(jù)

假設(shè)有一個(gè)OLAP表，表名為olap_tbl。您可以通過(guò)以下方式轉(zhuǎn)換該表中的數(shù)據(jù)，并將數(shù)據(jù)導(dǎo)入到StarRocks中。

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

賦予Hive表和視圖的權(quán)限?

您可以通過(guò)GRANT來(lái)賦予角色某個(gè)Hive Catalog內(nèi)所有表和視圖的查詢權(quán)限。命令語(yǔ)法如下所示。

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

例如，通過(guò)如下命令創(chuàng)建角色hive_role_table，切換至 Hive Cataloghive_catalog，然后把hive_catalog內(nèi)所有表和視圖的查詢權(quán)限都賦予hive_role_table。

-- 創(chuàng)建角色 hive_role_table。
CREATE ROLE hive_role_table;

-- 切換到數(shù)據(jù)目錄 hive_catalog。
SET CATALOG hive_catalog;

-- 把hive_catalog內(nèi)所有表和視圖的查詢權(quán)限賦予hive_role_table。
GRANT SELECT ON ALL TABLES IN ALL DATABASES TO ROLE hive_role_table;

向Hive表中插入數(shù)據(jù)

同StarRocks內(nèi)表一致，如果您擁有Hive表（Managed Table或External Table）的INSERT權(quán)限，那么您可以使用INSERT將StarRocks表數(shù)據(jù)寫入到該Hive表中。

本功能自3.2版本起開始支持，彼時(shí)只支持寫入到Parquet格式的Hive表。自3.3版本起，該功能還支持寫入到ORC及TextFile格式的Hive表。

需要注意的是，寫數(shù)據(jù)到External Table的功能默認(rèn)是關(guān)閉的，您需要通過(guò)系統(tǒng)變量ENABLE_WRITE_HIVE_EXTERNAL_TABLE打開。

切換至目標(biāo)Hive Catalog和數(shù)據(jù)庫(kù)，然后通過(guò)如下語(yǔ)法將StarRocks表數(shù)據(jù)寫入到Parquet格式的Hive表中。

語(yǔ)法

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

-- 向指定分區(qū)寫入數(shù)據(jù)。
INSERT {INTO | OVERWRITE} <table_name>
PARTITION (par_col1=<value> [, par_col2=<value>...])
{ VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query }

參數(shù)說(shuō)明

示例

以下寫入語(yǔ)句以默認(rèn)的Parquet格式為例。

• 向表partition_tbl_1中插入如下三行數(shù)據(jù)。

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

• 向表partition_tbl_1按指定列順序插入一個(gè)包含簡(jiǎn)單計(jì)算的SELECT查詢的結(jié)果數(shù)據(jù)。

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

• 向表partition_tbl_1中插入一個(gè)從其自身讀取數(shù)據(jù)的SELECT查詢的結(jié)果。

  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的分區(qū)插入一個(gè) SELECT 查詢的結(jié)果數(shù)據(jù)。

  • 方式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的分區(qū)下所有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內(nèi)表一致，如果您擁有Hive表的DROP權(quán)限，那么您可以使用DROP TABLE來(lái)刪除該Hive表。本功能自3.2版本起開始支持。注意當(dāng)前只支持刪除Hive的Managed Table。

執(zhí)行刪除表的操作時(shí)，您必須在DROP TABLE語(yǔ)句中指定FORCE關(guān)鍵字。該操作不會(huì)刪除表對(duì)應(yīng)的文件路徑，但是會(huì)刪除HDFS或?qū)ο蟠鎯?chǔ)上的表數(shù)據(jù)。請(qǐng)您謹(jǐn)慎執(zhí)行該操作。

切換至目標(biāo)Hive Catalog和數(shù)據(jù)庫(kù)，然后通過(guò)以下語(yǔ)句刪除Hive表。

DROP TABLE <table_name> FORCE

手動(dòng)或自動(dòng)更新元數(shù)據(jù)緩存

StarRocks默認(rèn)會(huì)緩存Hive的元數(shù)據(jù)，并以異步模式自動(dòng)更新這些緩存，以提升查詢性能。如果對(duì)Hive表進(jìn)行結(jié)構(gòu)變更或其他更新，您可以使用以下命令手動(dòng)更新該表的元數(shù)據(jù)，以確保StarRocks能及時(shí)生成高效的查詢計(jì)劃。

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

以下情況適合執(zhí)行手動(dòng)更新元數(shù)據(jù)：

• 已有分區(qū)內(nèi)的數(shù)據(jù)文件發(fā)生變更，例如執(zhí)行過(guò)INSERT OVERWRITE ... PARTITION ...命令。

• Hive表的Schema發(fā)生變更。

• Hive表被DROP后重建一個(gè)同名Hive表。

• 創(chuàng)建Hive Catalog時(shí)在PROPERTIES中指定"enable_cache_list_names" = "true"，此時(shí)在Hive側(cè)新增分區(qū)后，需要查詢這些新增分區(qū)。

相關(guān)文檔

Hive更多介紹，請(qǐng)參見Hive概述。