创建Hive用户自定义函数

操作场景

当Hive的内置函数不能满足需要时，可以通过编写用户自定义函数UDF（User-Defined Functions）插入自己的处理代码并在查询中使用它们。本文为您介绍自定义函数的开发和运行。

Hive UDF介绍

按使用方法，UDF有如下分类：

• 临时函数，只能在当前会话使用，重启会话后需要重新创建。
• 永久函数，可以在多个会话中使用，不需要每次创建。

约束与限制

• 用户自定义函数需要用户控制函数中变量的内存、线程等资源的占用，如果控制不当可能会导致内存溢出、CPU使用高等问题。
• 若集群开启了Ranger鉴权，需要关闭Ranger鉴权后才能使用Python的UDF函数。关闭Ranger鉴权具体操作请参见停用Ranger鉴权。

步骤一：开发UDF

本示例中以编写一个名称为“AddDoublesUDF”的UDF为例，说明UDF的编写和使用方法。

“AddDoublesUDF”主要用来对两个及多个浮点数进行相加，在该样例中可以掌握如何编写和使用UDF。且需注意：

• 一个普通UDF必须继承自“org.apache.hadoop.hive.ql.exec.UDF”。
• 一个普通UDF必须至少实现一个evaluate()方法，evaluate函数支持重载。
• 开发自定义函数需要在工程中添加“hive-exec-*.jar”依赖包，可从Hive服务的安装目录下获取，例如在“${BIGDATA_HOME}/components/FusionInsight_HD_*/Hive/disaster/plugin/lib/”目录下获取。

以下为“AddDoublesUDF”样例代码说明，其中，xxx通常为程序开发的组织名称。

package com.xxx.bigdata.hive.example.udf;
import org.apache.hadoop.hive.ql.exec.UDF;

public class AddDoublesUDF extends UDF { 
 public Double evaluate(Double... a) { 
    Double total = 0.0; 
    // 处理逻辑部分. 
    for (int i = 0; i < a.length; i++) 
      if (a[i] != null) 
        total += a[i]; 
    return total; 
  } 
} 

将以上样例程序打包成“AddDoublesUDF.jar”（具体操作请参见Hive开发指南）。

步骤二：创建执行UDF函数的用户

1. 使用admin用户登录Manager界面，选择“集群 > 集群属性”，查看集群的“认证模式”并记录。
2. 选择“集群 > 服务 > Hive”，单击页面右上角的“更多”查看Hive是否启用Ranger鉴权。
3. 选择“系统 > 权限 > 用户”，单击“添加用户”，配置以下参数并单击“确定”，创建执行自定义函数的用户。

   表2 添加用户

   参数	示例	参数说明
   用户名	test	输入自定义用户名称。
   用户类型	人机	设置“用户类型”，包括“人机”和“机机”用户。
   密码	xxx	输入用户对应的密码。
   确认新密码	xxx	再次输入用户对应的密码。
   用户组	单击“添加”，选择“hive”和“hadoop”用户组并单击“确定”。	根据业务实际需要，在“用户组”，单击“添加”，选择一个或多个用户组添加到列表中。

4. 根据集群的认证模式及是否启用Ranger鉴权为新创建的用户赋权：
   • 集群的“认证模式”为“安全模式”：
     • “启用Ranger鉴权”按钮置灰（Hive已启用Ranger鉴权），执行5。
     • “停用Ranger鉴权”按钮置灰（Hive未启用Ranger鉴权），执行6。
   • 集群的“认证模式”为“普通模式”：
     • “启用Ranger鉴权”按钮置灰（Hive已启用Ranger鉴权），执行5。
     • “停用Ranger鉴权”按钮置灰（Hive未启用Ranger鉴权），操作结束。

5. Hive使用Ranger鉴权，需使用Ranger管理员用户（安全模式集群为rangeradmin，普通模式集群为admin）登录Ranger管理界面为用户添加Hive权限控制策略。
   1. 选择“集群 > 服务 > Ranger”，单击“Ranger Web UI”右侧的超链接登录Ranger WebUI页面。
   2. 安全模式集群需单击页面右上角的用户名，在下拉框中单击“Log Out”退出当前用户，使用rangeradmin用户重新登录Ranger管理界面。
   3. 在首页中单击“HADOOP SQL”区域的组件插件名称如“Hive”。
   4. 在“Access”页签单击“Add New Policy”，配置以下参数并单击“Add”。

      表3 新增Hive权限控制策略

      参数	示例	参数说明
      Policy Name	test_hive	输入自定义策略名称，不能与本服务内其他策略名称重复。
      database	default	将适用该策略的Hive数据库名称。 永久函数：配置要添加函数的数据库名称，例如：default。 临时函数：将“database”切换为“global”，并配置具体的函数名或设置为“*”。
      table	-	将适用该策略的Hive表名称。需切换为“udf”，并配置具体的函数名或设置为“*”。临时函数无需配置该参数。
      Allow Conditions	-	策略允许条件，配置本策略内允许的权限及例外。在“Select User”列选择新增的用户，在“Permissions”新增以下权限： 永久函数：根据实际业务需求进行授权，例如，可新增“create”、“select”和“drop”权限。 临时函数：添加“Temporary UDF Admin”权限。

6. Hive使用Manager角色鉴权，需创建具有Hive管理员权限的用户才能执行永久函数和临时函数。
   1. 在Manager页面首页，选择“系统 > 权限 > 角色”，单击“添加角色”，配置以下参数并单击“确定”：
      • 角色名称：填写角色名称，例如：test_role。
      • 配置资源权限：在“配置资源权限”列表中单击“待操作的集群名称 > Hive”，勾选“Hive管理员权限”。
   2. 单击“用户”，单击3新创建的用户所在行的“修改”。
   3. 在修改用户页面，单击“角色”右侧的添加，添加新创建的具有Hive管理员权限的角色，单击“确定”。

步骤三：运行UDF

1. 将步骤一：开发UDF打包的“AddDoublesUDF.jar”上传至客户端安装节点，例如“opt”目录下。
2. 以客户端安装用户登录安装客户端的节点，上传1中的“AddDoublesUDF.jar”到HDFS指定目录下，例如“/user/hive_examples_jars”，且创建函数的用户与使用函数的用户都需要具有该文件的可读权限。
   1. 切换至客户端安装目录并配置环境变量：

      切换至客户端安装目录：

      cd 客户端安装目录

      配置环境变量：

      source bigdata_env

   2. 认证用户。
      • 集群已开启Kerberos认证（安全模式）：

        kinit 业务用户

      • 集群未开启Kerberos认证（普通模式）：

        export HADOOP_USER_NAME=业务用户

   3. 上传UDF Jar包至HDFS目录中：

      hdfs dfs -put /opt /user/hive_examples_jars

      修改权限：

      hdfs dfs -chmod 777 /user/hive_examples_jars

3. 登录Hive客户端。
   • 集群已开启Kerberos认证（安全模式），执行如下命令：

     beeline

     如果用户绑定了Hive管理员角色，在每个beeline的维护操作会话中，都需要执行以下命令切换成admin角色再执行后续操作：

     set role admin;

   • 集群未开启Kerberos认证（普通模式），执行如下命令：

     beeline -n Hive业务用户

4. 在Hive Server中执行以下命令创建自定义函数：
   • 创建永久函数：

     CREATE FUNCTION addDoubles AS 'com.xxx.bigdata.hive.example.udf.AddDoublesUDF' using jar 'hdfs://hacluster/user/hive_examples_jars/AddDoublesUDF.jar';

     其中addDoubles是该函数的名称，用于SELECT查询中使用；xxx通常为程序开发的组织名称。

   • 创建临时函数：

     CREATE TEMPORARY FUNCTION addDoubles AS 'com.xxx.bigdata.hive.example.udf.AddDoublesUDF' using jar 'hdfs://hacluster/user/hive_examples_jars/AddDoublesUDF.jar';

     • addDoubles是该函数的名称，用于SELECT查询中使用。
     • 关键字TEMPORARY说明该函数只在当前这个Hive Server的会话过程中定义使用。

5. 在Hive Server中执行以下命令使用该函数：

   SELECT addDoubles(1,2,3);

   如果重新连接客户端再使用函数出现“[Error 10011]”错误，可执行reload function;命令后再使用该函数。例如，报错信息如下：

   Error: Error while compiling statement: FAILED: SemanticException [Error 10011]: Line 1:7 ...

6. 在Hive Server中执行以下命令删除该函数：

   DROP FUNCTION addDoubles;

相关文档

• 如果在Hive客户端中使用Spark创建UDF函数或多个HiveServer之间使用UDF报错“ERROR 10011”、“invalid function”，处理该故障的具体操作请参见使用UDF函数时提示“Invalid function”。
• 创建Hive永久UDF函数时报错用户权限不足，处理该故障的具体操作请参见在beeline客户端创建UDF时报错。
• 如需在Hive自定义函数中操作本地文件，具体操作请参见如何在Hive自定义函数中操作本地文件。
• 如需删除所有HiveServer中的永久函数，具体操作请参见如何删除所有HiveServer中的永久函数。