E-MapReduce：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支援以下儲存系統和中繼資料服務：

• Distributed File System（HDFS）或阿里雲Object Storage Service。

• 中繼資料服務。當前支援的中繼資料服務包括資料湖構建DLF 1.0（舊版）和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
)

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

CREATE EXTERNAL CATALOG hive_catalog
PROPERTIES
(
    "type" = "hive",
    "hive.metastore.type" = "dlf",
    "dlf.catalog.id" = "sr_dlf"
);

查看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版本起開始支援。

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

刪除Hive資料庫

同StarRocks內部資料庫一致，如果您擁有Hive資料庫的DROP許可權，那麼您可以使用DROP DATABASE來刪除該Hive資料庫。本功能自3.2版本起開始支援。僅支援刪除空資料庫。

刪除資料庫操作並不會將HDFS或Object Storage Service上的對應檔案路徑刪除。

切換至目標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 }

刪除Hive表

同StarRocks內表一致，如果您擁有Hive表的DROP許可權，那麼您可以使用DROP TABLE來刪除該Hive表。本功能自3.2版本起開始支援。注意當前只支援刪除Hive的Managed Table。

執行刪除表的操作時，您必須在DROP TABLE語句中指定FORCE關鍵字。該操作不會刪除表對應的檔案路徑，但是會刪除HDFS或Object Storage Service上的表資料。請您謹慎執行該操作。

切換至目標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概述。