背景信息

通過Hive Catalog，您可以：

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

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

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

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

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

• 元數(shù)據(jù)服務。當前支持的元數(shù)據(jù)服務包括數(shù)據(jù)湖構建（DLF）和Hive Metastore（以下簡稱HMS）。

使用限制?

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

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

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

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

  您可以通過系統(tǒng)變量connector_sink_compression_codec來設置寫入到Hive表時的壓縮算法。

創(chuàng)建Hive Catalog

語法?

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

參數(shù)說明

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

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

  • 總長度不能超過64個字符。

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

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

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

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

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

  • 使用DLF

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

  • 使用HMS

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

示例

以下示例使用HDFS作為存儲，創(chuàng)建了一個名為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的創(chuàng)建語句。例如，通過如下命令查詢Hive Cataloghive_catalog的創(chuàng)建語句。

SHOW CREATE CATALOG hive_catalog;

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

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

• 先通過SET CATALOG指定當前會話生效的Hive Catalog，然后再通過USE指定數(shù)據(jù)庫。

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

• 通過USE直接將會話切換到目標Hive Catalog下的指定數(shù)據(jù)庫。

  USE <catalog_name>.<db_name>;

刪除Hive Catalog?

您可以通過DROP CATALOG刪除某個External Catalog。

例如，通過以下命令刪除hive_catalog。

DROP Catalog hive_catalog;

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

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

語法

切換至目標Hive Catalog，然后通過以下語句創(chuàng)建Hive數(shù)據(jù)庫。

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

參數(shù)說明

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

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

• HDFS：Prefix取值為hdfs。

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

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

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

刪除數(shù)據(jù)庫操作并不會將HDFS或對象存儲上的對應文件路徑刪除。

切換至目標Hive Catalog，然后通過以下語句刪除 Hive 數(shù)據(jù)庫。

DROP DATABASE <database_name>;

創(chuàng)建Hive表

同StarRocks內部數(shù)據(jù)庫一致，如果您擁有Hive數(shù)據(jù)庫的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數(shù)據(jù)庫下創(chuàng)建Managed Table。

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

切換至目標Hive Catalog和數(shù)據(jù)庫，然后通過以下語句創(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表結構

您可以通過如下方法查看Hive表的表結構：

• 查看表結構

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

• 從CREATE命令查看表結構和表文件存放位置

  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ù)庫。

     SHOW DATABASES FROM <catalog_name>;

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

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

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

導入Hive數(shù)據(jù)

假設有一個OLAP表，表名為olap_tbl。您可以通過以下方式轉換該表中的數(shù)據(jù)，并將數(shù)據(jù)導入到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>

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

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

-- 切換到數(shù)據(jù)目錄 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表中插入數(shù)據(jù)

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

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

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

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

語法

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ù)說明

示例

以下寫入語句以默認的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按指定列順序插入一個包含簡單計算的SELECT查詢的結果數(shù)據(jù)。

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

• 向表partition_tbl_1中插入一個從其自身讀取數(shù)據(jù)的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的分區(qū)插入一個 SELECT 查詢的結果數(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內表一致，如果您擁有Hive表的DROP權限，那么您可以使用DROP TABLE來刪除該Hive表。本功能自3.2版本起開始支持。注意當前只支持刪除Hive的Managed Table。

執(zhí)行刪除表的操作時，您必須在DROP TABLE語句中指定FORCE關鍵字。該操作不會刪除表對應的文件路徑，但是會刪除HDFS或對象存儲上的表數(shù)據(jù)。請您謹慎執(zhí)行該操作。

切換至目標Hive Catalog和數(shù)據(jù)庫，然后通過以下語句刪除Hive表。

DROP TABLE <table_name> FORCE

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

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

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

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

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

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

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

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

相關文檔

Hive更多介紹，請參見Hive概述。