Hive Catalog是一種External Catalog,自2.3版本開始支持。
背景信息
通過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版本起開始支持。
您可以通過GRANT和REVOKE操作對用戶和角色進行權限的賦予和收回。
語法
切換至目標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ù)庫。
您可以通過GRANT和REVOKE操作對用戶和角色進行權限的賦予和收回。
刪除數(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>]
參數(shù)說明
column_definition
column_definition
語法定義如下所示。col_name col_type [COMMENT 'comment']
涉及參數(shù)說明如下表所示。
參數(shù)
說明
col_name
列名稱。
col_type
列數(shù)據(jù)類型。
當前支持如下數(shù)據(jù)類型:TINYINT、SMALLINT、INT、BIGINT、FLOAT、DOUBLE、DECIMAL、DATE、DATETIME、CHAR、VARCHAR[(length)]、ARRAY、MAP、STRUCT。
不支持LARGEINT、HLL、BITMAP類型。
說明所有非分區(qū)列的默認值均為
NULL
(即,在建表語句中指定DEFAULT "NULL"
)。分區(qū)列必須在最后聲明,且不能為NULL
。partition_desc
partition_desc
語法定義如下所示。PARTITION BY (par_col1[, par_col2...])
目前StarRocks僅支持Identity Transforms。 即為每個唯一的分區(qū)值創(chuàng)建一個分區(qū)。
說明分區(qū)列必須在最后聲明,支持除FLOAT、DOUBLE、DECIMAL、DATETIME以外的數(shù)據(jù)類型,并且不支持NULL值。此外,partition_desc中聲明的分區(qū)列的順序必須與column_definition中定義的列的順序一致。
PROPERTIES
可以在
PROPERTIES
中通過"key" = "value"
的形式聲明Hive表的屬性。以下列出幾個常見的屬性。屬性
描述
location
Managed Table所在的文件路徑。使用HMS作為元數(shù)據(jù)服務時,您無需指定
location
參數(shù)。file_format
Managed Table的文件格式。當前支持Parquet、ORC、TextFile文件格式,其中ORC和TextFile文件格式自3.3版本起支持。取值范圍:
parquet
、orc
、textfile
。默認值:parquet
。compression_codec
Managed Table的壓縮格式。該屬性自3.2.3版本起棄用,此后寫入Hive表時的壓縮算法統(tǒng)一由會話變量connector_sink_compression_codec控制。
示例
以下建表語句以默認的 Parquet 格式為例。
創(chuàng)建非分區(qū)表
unpartition_tbl
,包含id
和score
兩列。CREATE TABLE unpartition_tbl ( id int, score double );
創(chuàng)建分區(qū)表
partition_tbl_1
,包含action
、id
、dt
三列,并定義id
和dt
為分區(qū)列。CREATE TABLE partition_tbl_1 ( action varchar(20), id int NOT NULL, dt date NOT NULL ) PARTITION BY (id,dt);
查詢原表
partition_tbl_1
的數(shù)據(jù),并根據(jù)查詢結果創(chuàng)建分區(qū)表partition_tbl_2
,定義id
和dt
為partition_tbl_2
的分區(qū)列: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表數(shù)據(jù)
方式一:直接查詢表數(shù)據(jù)
SELECT * FROM <catalog_name>.<database_name>.<table_name>;
方式二:逐步查看與查詢
查看指定Catalog所屬的Hive集群中的數(shù)據(jù)庫。
SHOW DATABASES FROM <catalog_name>;
查詢目標表的數(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打開。
您可以通過GRANT和REVOKE操作對用戶和角色進行權限的賦予和收回。
您可以通過會話變量connector_sink_compression_codec來指定寫入Hive表時的壓縮算法。
切換至目標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 }
分區(qū)列不允許為NULL
,因此導入時需要保證分區(qū)列有值。
參數(shù)說明
參數(shù) | 說明 |
INTO | 將數(shù)據(jù)追加寫入目標表。 |
OVERWRITE | 將數(shù)據(jù)覆蓋寫入目標表。 |
column_name | 導入的目標列??梢灾付ㄒ粋€或多個列。指定多個列時,必須用逗號 ( |
expression | 表達式,用以為對應列賦值。 |
DEFAULT | 為對應列賦予默認值。 |
query | 查詢語句,查詢的結果會導入至目標表中。查詢語句支持任意StarRocks支持的SQL查詢語法。 |
PARTITION | 導入的目標分區(qū)。需要指定目標表的所有分區(qū)列,指定的分區(qū)列的順序可以與建表時定義的分區(qū)列的順序不一致。指定分區(qū)時,不允許通過列名 ( |
示例
以下寫入語句以默認的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。
您可以通過GRANT和REVOKE操作對用戶和角色進行權限的賦予和收回。
執(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ū)。
自2.5.5版本起,StarRocks支持周期性刷新Hive元數(shù)據(jù)緩存。開啟此功能后,默認每10分鐘將自動刷新Hive元數(shù)據(jù)緩存,這樣在大部分情況下,您無需執(zhí)行手動更新。只有在新增分區(qū)后并需要立即查詢這些數(shù)據(jù)時,才需手動更新。
REFRESH EXTERNAL TABLE
只會更新FE中已緩存的表和分區(qū)。
相關文檔
Hive更多介紹,請參見Hive概述。