Flink Hive 方言 CREATE 语句完全指南:DATABASE / TABLE / VIEW / MACRO / FUNCTION 语法与实现原理
Flink Hive 方言 CREATE 语句完全指南:DATABASE / TABLE / VIEW / MACRO / FUNCTION 语法与实现原理
Flink 通过提供 hive SQL 方言(Hive Dialect),允许用户直接使用 Hive 原生的 SQL 语法编写语句,从而减少在 Flink 与 Hive 之间切换的场景。本文以 Flink 官方文档中 Hive 方言的 CREATE 语句(create.md)为骨架,逐条解析 CREATE DATABASE、CREATE TABLE、CREATE VIEW、CREATE MACRO、CREATE FUNCTION 的完整语法、示例与注意事项,并结合 flink-connector-hive 模块中的解析器与 DDL 语义分析器实现,说明这些语句在 Flink 内部的执行路径。读完后你将能熟练地在 Flink 中编写并执行 Hive 风格的建库、建表、建视图与注册函数语句,并理解其底层工作机制。
前置条件:启用 Hive 方言
在使用任何 Hive 语法之前,需要先将当前会话切换到 Hive 方言。Flink 支持 default 与 hive 两种方言,你可以为每条语句动态切换,无需重启会话。以 SQL Client 为例:
Flink SQL> SET table.sql-dialect = hive; -- 切换到 Hive 方言
[INFO] Session property has been set.
Flink SQL> SET table.sql-dialect = default; -- 切回 Flink 默认方言
[INFO] Session property has been set.
如果使用配置了 HiveServer2 Endpoint 的 SQL Gateway,Hive 方言默认生效;在 Table API 中则通过 tableEnv.getConfig().setSqlDialect(SqlDialect.HIVE) 设置(详见 overview.md)。
使用 Hive 方言需满足两个硬性前提:
- 当前 Catalog 必须是 HiveCatalog,否则会回退到 Flink 默认方言。这一点在源码中也有强制校验:
HiveParser#parse会检查当前 Catalog 类型,若!HiveCatalogUtils.isHiveCatalog(currentCatalog)则抛出异常,提示 "Hive dialect is only supported when the current catalog is HiveCatalog"(见 HiveParser.java)。 - 需要额外引入 Hive 相关依赖(参考 Hive 依赖说明),并建议加载 HiveModule 且将其置于模块列表首位,以保证 Hive 内置函数在解析时能被优先识别。
另外需要注意,Hive 方言只支持 2 段标识符(db_name.table_name),不能为标识符指定 catalog。
目前 Hive 方言支持以下 5 类 CREATE 语句:
- CREATE DATABASE
- CREATE TABLE
- CREATE VIEW
- CREATE MACRO
- CREATE FUNCTION
CREATE DATABASE
语法说明
CREATE DATABASE 用于创建指定名称的数据库,语法如下:
CREATE (DATABASE|SCHEMA) [IF NOT EXISTS] database_name
[COMMENT database_comment]
[LOCATION hdfs_path]
[WITH DBPROPERTIES (property_name=property_value, ...)];
各子句含义:
| 子句 | 作用 |
|---|---|
DATABASE / SCHEMA |
两者等价,均可创建数据库 |
IF NOT EXISTS |
数据库已存在时不报错(不执行任何操作) |
COMMENT |
为数据库添加描述信息 |
LOCATION |
指定数据库在文件系统上的存储路径(如 HDFS 路径) |
WITH DBPROPERTIES |
附加数据库属性键值对,可被后续查询使用 |
示例
-- 最简单的建库
CREATE DATABASE db1;
-- 完整建库:注释 + 存储路径 + 自定义属性
CREATE DATABASE IF NOT EXISTS db1 COMMENT 'db1' LOCATION '/user/hive/warehouse/db1'
WITH DBPROPERTIES ('name'='example-db');
CREATE TABLE
语法说明
CREATE TABLE 用于在已存在的数据库中定义一张表,是使用频率最高的 DDL 语句,完整语法如下:
CREATE [EXTERNAL] TABLE [IF NOT EXISTS] [db_name.]table_name
[(col_name data_type [column_constraint] [COMMENT col_comment], ... [table_constraint])]
[COMMENT table_comment]
[PARTITIONED BY (col_name data_type [COMMENT col_comment], ...)]
[
[ROW FORMAT row_format]
[STORED AS file_format]
]
[LOCATION fs_path]
[TBLPROPERTIES (property_name=property_value, ...)]
[AS select_statment];
其中 data_type、row_format、file_format 等子语法展开如下:
data_type
: primitive_type
| array_type
| map_type
| struct_type
primitive_type
: TINYINT
| SMALLINT
| INT
| BIGINT
| BOOLEAN
| FLOAT
| DOUBLE
| DOUBLE PRECISION
| STRING
| BINARY
| TIMESTAMP
| DECIMAL
| DECIMAL(precision, scale)
| DATE
| VARCHAR
| CHAR
array_type
: ARRAY < data_type >
struct_type
: STRUCT < col_name : data_type [COMMENT col_comment], ...>
row_format:
: DELIMITED [FIELDS TERMINATED BY char [ESCAPED BY char]] [COLLECTION ITEMS TERMINATED BY char]
[MAP KEYS TERMINATED BY char] [LINES TERMINATED BY char]
[NULL DEFINED AS char]
| SERDE serde_name [WITH SERDEPROPERTIES (property_name=property_value, ...)]
file_format:
: SEQUENCEFILE
| TEXTFILE
| RCFILE
| ORC
| PARQUET
| AVRO
| INPUTFORMAT input_format_classname OUTPUTFORMAT output_format_classname
column_constraint:
: NOT NULL
table_constraint:
: [CONSTRAINT constraint_name] PRIMARY KEY (col_name, ...)
关键点说明:
- 数据类型:覆盖 Hive 全量基础类型(TINYINT / SMALLINT / INT / BIGINT / BOOLEAN / FLOAT / DOUBLE / STRING / BINARY / TIMESTAMP / DECIMAL / DATE / VARCHAR / CHAR 等)以及 ARRAY、MAP、STRUCT 三种复合类型,其中
DECIMAL(precision, scale)可显式指定精度与标度。 - 分区表:通过
PARTITIONED BY指定分区列,分区列在语法上附带数据类型。 - 行格式与文件格式:
ROW FORMAT DELIMITED用于纯文本文件,可指定字段/集合元素/Map 键值/行/空值分隔符;ROW FORMAT SERDE用于自定义 SerDe;STORED AS可指定 SEQUENCEFILE、TEXTFILE、RCFILE、ORC、PARQUET、AVRO 等内置存储格式,也可用INPUTFORMAT ... OUTPUTFORMAT ...指定自定义 InputFormat/OutputFormat 类。 - 约束:支持列级
NOT NULL与表级PRIMARY KEY约束声明。 - 建表即查询:
AS select_statement支持 CTAS(Create Table As Select),直接以查询结果建表。 - 外部表:
CREATE EXTERNAL TABLE创建外部表,表数据不随表删除而删除。
注意:Hive 方言暂不支持创建临时表(Create temporary table is not supported yet)。
示例
-- 创建非分区表
CREATE TABLE t1(key string, value string);
-- 创建分区表
CREATE TABLE pt1(key string, value string) PARTITIONED BY (year int, month int);
-- 指定存储格式的表
CREATE TABLE t1(key string, value string) STORED AS ORC;
-- 指定行格式的表:使用复杂类型 MAP 并自定义分隔符
CREATE TABLE t1(m MAP<BIGINT, STRING>)
ROW FROMAT DELIMITED COLLECTION ITEMS TERMINATED BY ';'
MAP KEYS TERMINATED BY ':';
-- 以查询结果建表(CTAS)
CREATE TABLE t2 AS SELECT key, COUNT(1) FROM t1 GROUP BY key;
CREATE VIEW
语法说明
CREATE VIEW 以给定名称创建视图。视图是纯逻辑对象,不关联任何物理存储;当查询引用视图时,会先展开视图定义再执行后续处理。
CREATE VIEW [IF NOT EXISTS] [db_name.]view_name [(column_name, ...) ]
[COMMENT view_comment]
[TBLPROPERTIES (property_name = property_value, ...)]
AS SELECT ...;
列名推导规则:
- 若未显式提供列名,视图列名自动取自 SELECT 表达式的输出列。
- 若 SELECT 中包含未命名的标量表达式(如
x+y),生成的视图列名形如_C0、_C1等,依此类推。 - 重命名列时可选地附带列注释,但列注释不会自动从底层表继承。
示例
CREATE VIEW IF NOT EXISTS v1
(key COMMENT 'key')
COMMENT 'View for key=1'
AS SELECT key FROM src
WHERE key = '1';
在源码层面,视图信息由 HiveParserCreateViewInfo.java 承载,DDL 语义分析器最终调用 hiveParser.analyzeCreateView(createViewInfo, context, queryState) 完成视图的语义分析与注册(见 HiveParserDDLSemanticAnalyzer.java)。
CREATE MACRO
语法说明
CREATE TEMPORARY MACRO 以给定的可选列参数列表作为输入,创建一条可复用的表达式宏。宏在当前会话期间有效:
CREATE TEMPORARY MACRO macro_name([col_name col_type, ...]) expression;
示例
-- 无参数宏:固定返回值
CREATE TEMPORARY MACRO fixed_number() 42;
-- 单参数宏:字符串长度加 2
CREATE TEMPORARY MACRO string_len_plus_two(x string) length(x) + 2;
-- 多参数宏:两数相加
CREATE TEMPORARY MACRO simple_add (x int, y int) x + y;
CREATE FUNCTION
语法说明
CREATE FUNCTION 将 UDF 实现类(class_name)注册为可调用的函数,支持临时函数与永久函数两种形态。
创建临时函数
CREATE TEMPORARY FUNCTION function_name AS class_name [USING JAR 'file_uri'];
临时函数仅在当前会话期间存在。
创建永久函数
CREATE FUNCTION [db_name.]function_name AS class_name
[USING JAR 'file_uri'];
永久函数会注册到 Hive Metastore,除非显式 DROP,否则在所有会话中均可用。
参数说明
-
[USING JAR 'file_uri']:通过该子句指定包含函数实现及其依赖的 Jar 包。file_uri可以是本地文件路径,也可以是分布式文件系统(如 HDFS)上的路径:-- 类已存在于 classpath:无需指定 Jar CREATE FUNCTION simple_udf AS 'SimpleUdf'; -- 类不在 classpath:通过本地 Jar 注册 CREATE FUNCTION simple_udf AS 'SimpleUdf' USING JAR '/tmp/SimpleUdf.jar'; -- 通过远程 Jar 注册(HDFS 路径) CREATE FUNCTION simple_udf AS 'SimpleUdf' USING JAR 'hdfs://namenode-host:port/path/SimpleUdf.jar'; -
当函数在查询中被使用时,Flink 会自动下载远程 Jar;会话退出时,下载的 Jar 会被清理删除。
底层实现:Hive 方言的解析与执行路径
上述语句并非由 Flink 默认 SQL 解析器处理,而是走了一套独立的 Hive 兼容解析链路。该链路整体位于 flink-connectors/flink-connector-hive 模块的 org.apache.flink.table.planner.delegation.hive 包下,核心组件包括:
- HiveParser.java:方言的入口解析器,实现
Parser接口。其parse(String statement)方法执行以下流程:- 先尝试用
FlinkExtendedParser解析特殊命令(如SET),使得即使在当前 Catalog 不是 HiveCatalog 时,用户也能通过 SET 语句完成方言切换; - 强制校验当前 Catalog 必须是 HiveCatalog,否则抛出异常;
- 从 HiveCatalog 获取
HiveConf,并对副本进行环境修正(如动态分区模式设为nonstrict、关闭 UDF 按需加载、执行引擎固定为mr以复用 Hive 的解析/优化逻辑); - 加载与当前 Hive 版本匹配的
HiveShim,进行变量替换(substituteVariables),并启动HiveSessionState(见 HiveSessionState.java)后进入processCmd执行真正的命令处理。
- 先尝试用
- HiveParserDDLSemanticAnalyzer.java:Hive DDL(含本文全部 CREATE 语句)的语义分析器,负责把 AST 转换为可执行的描述对象(CreateTableDesc、CreateFunctionDesc 等),并完成元数据校验。
parse/目录下的 ANTLR 语法文件(HiveASTParser.g 等):承载 Hive 方言的词法/语法规则,保证CREATE TABLE ... STORED AS ORC等 Hive 原生写法可以被正确识别。- HiveOperationExecutor.java:负责执行解析后得到的 Operation,例如
HiveShowCreateTableOperation最终会调用HiveShowTableUtils.showCreateTable生成对应的建表语句文本(见 HiveOperationExecutor.java)。
从源码结构看,Flink 通过复用 Hive 自身的 AST 解析、语义分析(QB/QBParseInfo 等中间结构)与 HiveConf 配置体系,再结合 Flink 的 Catalog 注册表与 Calcite 上下文完成方言翻译,从而在保持 Hive 语法兼容的同时,将 DDL 落到 Flink 侧的 HiveCatalog 元数据上。这也是"当前 Catalog 必须是 HiveCatalog"这一限制的根源:Hive 方言的建表/建库/注册函数本质上是向 Hive Metastore 写入元数据。
注意事项小结
- 临时表(CREATE TEMPORARY TABLE)在 Hive 方言中暂不支持。
- 永久函数与表、数据库的元数据都写入 Hive Metastore,因此要求使用 HiveCatalog 作为当前 Catalog。
- Hive 方言主要面向批(batch)模式使用,部分 Hive 特有语法(如 Sort/Cluster/Distributed By、Transform)在流模式下尚未支持(详见 overview.md 与 queries 目录)。
- 涉及远程 Jar 的 CREATE FUNCTION,在会话退出后 Flink 会自动清理下载的临时 Jar。
- 具体特性的可用性还取决于所连接的 Hive 版本,例如数据库 LOCATION 更新仅支持 Hive 2.4.0 及以上版本。
掌握以上 5 类 CREATE 语句的语法与底层机制后,你就可以在 Flink 中以 Hive 原生方言完成建库、建表、建视图、定义宏与注册函数,与现有 Hive 数仓的 SQL 资产无缝衔接。