HiveServer2的客户端

本文翻译自hive官网
https://cwiki.apache.org/confluence/display/Hive/HiveServer2+Clients
前面的我都用过的，但是从kerberos认证之后，我就没使用过了。如果感觉翻译有疑问，请看源文档哈。
Beeline-一个新命令行客户端
Beeline的列子
Beeline的命令
Beeline的hive命令
Beeline命令行参数
分割符输出格式
HiveServer2的日志
JDBC
连接的urls
连接URL的格式
远程连接URL或者本地模式
当HiverServer2运行在HTTP模式中的连接URL
当在HiverServer2的SSL已经启动的时候的连接URL
使用JDBC
JDBC客户端的简单代码
运行JDBC客户端简单代码
JDBC的数据类型
对于安全的集群，JDBC的客户端设置
多用户场景和自动登录到Kerberos kdc
使用kerberos的预认证
Python客户端
Ruby客户端
与SQuirrel Sql集成
与Dbvissoftware的Dbvisualizer集成
集成其他工具的高级特征
在HTTP模式中支持Cookie的重置
在HTTP模式中可以使用双向的ssl
通过jdbc的驱动，传输http头的key-value数据

这篇文章描述了不同的支持hiveserver2的客户端
Beeline-一个新命令行客户端
hiveserver2支持一个新的shell客户端。它是基于SQLline的客户端的一个jbdc客户端。这里有详细描述documentation，也有利于理解beeline。
beeline客户端支持远程模式和本地模式。在本地模式中，它运行一个本地的hive（类似hive 客户端），然后原创模式中，通过thrift连接一个分离的hiveserver2的进程。在hive0.14之后，在Hiveserver2环境使用beeline，它也从hiverserv2中执行输出标准错误，会打印此日志信息。
ps：在远程模式中，hiveserver2仅仅只支持thrift认证的连接。甚至HTTP模式中，这个消息的body也要包含thrift.
Beeline的列子

% bin/beeline
Hive version 0.11.0-SNAPSHOT by Apache
beeline> !connect jdbc:hive2://localhost:10000 scott tiger org.apache.hive.jdbc.HiveDriver
!connect jdbc:hive2://localhost:10000 scott tiger org.apache.hive.jdbc.HiveDriver
Connecting to jdbc:hive2://localhost:10000
Connected to: Hive (version 0.10.0)
Driver: Hive (version 0.10.0-SNAPSHOT)
Transaction isolation: TRANSACTION_REPEATABLE_READ
0: jdbc:hive2://localhost:10000> show tables;
show tables;
+-------------------+
|     tab_name      |
+-------------------+
| primitives        |
| src               |
| src1              |
| src_json          |
| src_sequencefile  |
| src_thrift        |
| srcbucket         |
| srcbucket2        |
| srcpart           |
+-------------------+
9 rows selected (1.079 seconds)

ps:使用没有安全认证的beeline连接，如果你想通过 NOSASL模式连接，你必须明确的指定认证模式

% bin/beeline
beeline> !connect jdbc:hive2://<host>:<port>/<db>;auth=noSasl hiveuser pass org.apache.hive.jdbc.HiveDriver

Beeline的命令

command	description
!<’sqlline command’>	sqlline的命令，看如下连接的详细信息sqlline,!quit是退出beeline客户端

Beeline的hive命令
在hive的jdbc区中被使用的时候，hive指定命令（和hive客户端命令一样）能够在beeline客户端运行。使用”;”来区分命令。在脚本中的命令使用”–”来识别。

command	description
reset	重置默认的配置
set key value	设置特别的配置变量，如果你的配置变量的名称写错了，beeline客户端不会报错
set -v	打印出hadoop和hive的配置变量
add files filepath,add jars filepath,add archives filepath	添加一个或者多个文件，jar包，archives包到分布式缓存的资源列表中。看hive resources详情
list files,list jars,list archive	列出已经添加进分布式缓存中的资源
list files filepath,list jars filepath,list archives filepath	查看是否已经添加进分布式缓存中
delete files path,delete jars path,delete archives path	从分布式缓存中移除资源
delete/add files ivyurl,delete/add jars ivyurl,delete/add archives ivyurl	ivy是apache的依赖管理工具，从hive1.2.0之后，就是可以使用ivy来管理依赖包
reload	从hive0.14.0之后，是的hiveserver2明确的知道jar包的变化（在指定的配置文件路径中）hive.reloadable.aux.jars.path。这个变化可能是add,remove,update jar包
query string	执行hive的查询语句，然后打印结果到标准输出流

Beeline命令行参数，常用的

选项	描述
-u db_url	jdbc的url，列如:beeline -u db_url
-n username	db连接串的用户名，列如:beeline -n username
-p password	db连接串的密码，列如:beeline -p password
-d driver class	连接的驱动,列如:beeline -d org.apache.hive.jdbc.HiveDriver
-e query	被执行的查询语句，查询语句中需要使用双引号和单引号，列如:beeline -e “query_string”
-f filepath	运行文件中的脚本
–hiveconf property=value	指定配置变量的值，在hive.conf.restricted.list中列出的配置变量是不能够被–hiveconf重置的。看详情restricted list and whitelist
–hivevar name=value	hive的变量，这个可以在hive-specific设置中被指定，可以在session级别指定
–showHeader true/false	在查询结果中是否显示列的名字

分割符输出格式
在hive0.14之后，在输出SV格式上有所提升，有DSV，CSV2和TSV2。这些格式比标准的CSV（在包含特殊字符-分隔符，单引号的时候，会在每列中加单引号）好很多。从分布符区分不同，有3中输出格式，逗号-CSV2，tab-TSV2，通过delimiterForDsv属性配置-DSV。
CSV和TSV格式可以向后兼容，但是在输出的每一列中有单引号围绕。
HiveServer2的日志
在hive0.14.0之后，hiveserver2的操作日志对于beeline客户端是可见的。这些配置日志信息如下：
hive.server2.logging.operation.enabled
hive.server2.logging.operation.log.location
hive.server2.logging.operation.verbose (Hive 0.14 to 1.1)
hive.server2.logging.operation.level (Hive 1.2 onward)
在hive2.0.0中添加了日志queryid和sessionid的支持。在配置文件中使用edit/add %X{queryId} and %X{sessionId} 这种通配符查询它。
JDBC
hiveserver2有一个新的jdbc驱动，它支持本地和远程模式接入hiveserver2。
连接URL的格式
hiveserver的url格式如下:

jdbc:hive2://<host1>:<port1>,<host2>:<port2>/dbName;sess_var_list?hive_conf_list#hive_var_list

其中：
host:port1,host:port2是通过逗号分隔的服务器实列，如果开启的了HA，自动切换服务，如果为null，自动使用本地模式连接。
db_name：是数据库的名字。
sess_var_list：是通过分号区分的 key=value定义，这个是seesion级别的变量，比如user=foo;password=bar
hive_conf_list：分号分隔，设置session级别的配置变量
hive_var_list:分号分隔，设置session基本的hive变量
远程连接URL或者本地模式
Jbdc的连接url，有前缀jdbc:hive2://,驱动类为org.apache.hive.jdbc.HiveDriver,注意下这个驱动类和老的hiveserver不同。
在远程模式中，这个url格式如下:jdbc:hive2://host:port/db（默认的端口为10000）
在本地模式中，这个url格式如下: jdbc:hive2://(没有写host和端口)
当HiverServer2运行在HTTP模式中的连接URL
jbdc连接url，

jdbc:hive2://<host>:<port>/<db>;transportMode=http;httpPath=<http_endpoint>

其中
http_endpoint这个对应的HTTP endpoint配置是在hive-site.xml。默认是cliservice。这个模式是基于http传输数据的。
http传输模式的端口默认为10001
在0.14之前的版本中，使用hive.server2.transport.mode和hive.server2.thrift.http.path来分别使用，这是hive_conf_list中的一部分参数。这些版本已经弃用新版的支持了（这些都进入sess_var_list的部分了），但是现在还是可以工作。就是说这个两个参数已经是sess_var_list了。以后设置的话，要在sess_var_list中。
当在HiverServer2的SSL已经启动的时候的连接URL
jdbc连接串url：

dbc:hive2://<host>:<port>/<db>;ssl=true;sslTrustStore=<trust_store_path>;trustStorePassword=<trust_store_password>

其中
trust_store_path：是客户端truststore文件的路径
trust_store_password:是接入truststore的密码
在http模式中：

jdbc:hive2://<host>:<port>/<db>;ssl=true;sslTrustStore=<trust_store_path>;trustStorePassword=<trust_store_password>;transportMode=http;httpPath=<http_endpoint>

就是说在HTTP模式下，连接串如上。
JDBC
你能够使用jdbc来接入数据的存储，步骤如下
1加载hiveserver2的jdbc驱动，在hive1.2.0之后，加载驱动使用的是Class.forName(),列如：

Class.forName("org.apache.hive.jdbc.HiveDriver");

2通过创建连接连接数据库，例如

Connection cnct = DriverManager.getConnection("jdbc:hive2://<host>:<port>", "<user>", "<password>");

默认的端口是10000,在非安全模式下，指定一个用户名就可以运行了。在安全模式下，password可以忽略的。如下：

Connection cnct = DriverManager.getConnection("jdbc:hive2://<host>:<port>", "<user>", "");

在kerberos安全模式中，用户信息是基于kerberos认证的。
3通过创建一个statement对象来提交查询语句，使用executeQuery()执行。列如:

Statement stmt = cnct.createStatement();
ResultSet rset = stmt.executeQuery("SELECT foo FROM bar");

4如果需要，就遍历这个结果集。
这些步骤在如下的一个简单的列子中。

import java.sql.SQLException;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.Statement;
import java.sql.DriverManager;

public class HiveJdbcClient {
  private static String driverName = "org.apache.hive.jdbc.HiveDriver";

  /**
   * @param args
   * @throws SQLException
   */
  public static void main(String[] args) throws SQLException {
      try {
      Class.forName(driverName);
    } catch (ClassNotFoundException e) {
      // TODO Auto-generated catch block
      e.printStackTrace();
      System.exit(1);
    }
    //replace "hive" here with the name of the user the queries should run as
    Connection con = DriverManager.getConnection("jdbc:hive2://localhost:10000/default", "hive", "");
    Statement stmt = con.createStatement();
    String tableName = "testHiveDriverTable";
    stmt.execute("drop table if exists " + tableName);
    stmt.execute("create table " + tableName + " (key int, value string)");
    // show tables
    String sql = "show tables '" + tableName + "'";
    System.out.println("Running: " + sql);
    ResultSet res = stmt.executeQuery(sql);
    if (res.next()) {
      System.out.println(res.getString(1));
    }
       // describe table
    sql = "describe " + tableName;
    System.out.println("Running: " + sql);
    res = stmt.executeQuery(sql);
    while (res.next()) {
      System.out.println(res.getString(1) + "\t" + res.getString(2));
    }

    // load data into table
    // NOTE: filepath has to be local to the hive server
    // NOTE: /tmp/a.txt is a ctrl-A separated file with two fields per line
    String filepath = "/tmp/a.txt";
    sql = "load data local inpath '" + filepath + "' into table " + tableName;
    System.out.println("Running: " + sql);
    stmt.execute(sql);

    // select * query
    sql = "select * from " + tableName;
    System.out.println("Running: " + sql);
    res = stmt.executeQuery(sql);
    while (res.next()) {
      System.out.println(String.valueOf(res.getInt(1)) + "\t" + res.getString(2));
    }

    // regular hive query
    sql = "select count(1) from " + tableName;
    System.out.println("Running: " + sql);
    res = stmt.executeQuery(sql);
    while (res.next()) {
      System.out.println(res.getString(1));
    }
  }
}

运行JDBC客户端简单代码

# Then on the command-line
$ javac HiveJdbcClient.java

# To run the program using remote hiveserver in non-kerberos mode, we need the following jars in the classpath
# from hive/build/dist/lib
#     hive-jdbc*.jar
#     hive-service*.jar
#     libfb303-0.9.0.jar
#     libthrift-0.9.0.jar
#     log4j-1.2.16.jar
#     slf4j-api-1.6.1.jar
#     slf4j-log4j12-1.6.1.jar
#     commons-logging-1.0.4.jar
#
#
# To run the program using kerberos secure mode, we need the following jars in the classpath
#     hive-exec*.jar
#     commons-configuration-1.6.jar (This is not needed with Hadoop 2.6.x and later).
#  and from hadoop
#     hadoop-core*.jar
#
# To run the program in embedded mode, we need the following additional jars in the classpath
# from hive/build/dist/lib
#     hive-exec*.jar
#     hive-metastore*.jar
#     antlr-runtime-3.0.1.jar
#     derby.jar
#     jdo2-api-2.1.jar
#     jpox-core-1.2.2.jar
#     jpox-rdbms-1.2.2.jar
# and from hadoop/build
#     hadoop-core*.jar
# as well as hive/build/dist/conf, any HIVE_AUX_JARS_PATH set, 
# and hadoop jars necessary to run MR jobs (eg lzo codec)

$ java -cp $CLASSPATH HiveJdbcClient

上面也了连个中模式下，运行需要的jar包。
或者，你可以通过脚本方式运行，在提交jar文件到客户端前，你需要构建你的classpath和准好好数据文件。这个脚本添加所有的依赖jar包，为了在本地模式也可以可以hiveserver2。

#!/bin/bash
HADOOP_HOME=/your/path/to/hadoop
HIVE_HOME=/your/path/to/hive

echo -e '1\x01foo' > /tmp/a.txt
echo -e '2\x01bar' >> /tmp/a.txt

HADOOP_CORE=$(ls $HADOOP_HOME/hadoop-core*.jar)
CLASSPATH=.:$HIVE_HOME/conf:$(hadoop classpath)

for i in ${HIVE_HOME}/lib/*.jar ; do
    CLASSPATH=$CLASSPATH:$i
done

java -cp $CLASSPATH HiveJdbcClient

JDBC的数据类型
下面是表中的字段数据类型：

hive类型	java类型	说明
tinyint	byte	1字节
smallint	short	2字节
int	int	4字节
bigint	long	8字节
float	double	7位数字
double	double	15位数字
decimal	java.math.bigdecimal	固定精度的10进制
boolean	boolean	0 or 1
string	string	字符串
timestamp	java.sql.timestamp	日期和时间值
binray	string	binary
复杂类型
array	string-json	数组
map	string-json	key-value值
struct	string-json	类似结构体

对于安全的集群，JDBC的客户端设置
当使用kerberso认证连接hiveserver2的时候，连接url格式如下：

jdbc:hive2://<host>:<port>/<db>;principal=<Server_Principal_of_HiveServer2>

在连接hiverserver2的时候，客户端需要拥有一个认证的kerberos ticket。
注意：如果你在端口后面没有”/”，jdbc驱动不会解析hostname,还会终止hiveserver2，使用本地模式连接。如果你指定了hostname，确保你在端口后面，有”/”.
在LDAP（轻量级目录访问协议）中，CUSTOM和PAM认证，客户端需要一个认证的用户米和密码，jdbc来连接。

jdbc:hive://hostname/dbname;sasl.qop=auth-int

看详情setting up hiveserver2
多用户场景和自动登录到Kerberos kdc
在当前使用kerberos的方式中，在连接之前，在ticket缓存中，你需要拥有一个认证的kerberos ticket。Kerberos需要3种方式登录（kinit,key tab和ticketcache），一个kerberos用户的限制登录一个客户端。这些限制限制了在中间系统中和多用户场景中的使用。在多用户场景张，客户端需要自动登录到kerberos的kdc。
解决多用户场景限制的一种方式是，安全代理用户（详情hive-515）。在hive0.13.0之后，有2个组件支持代理用户：
1通过oozie来管理连接的token。这个是hadoop生态圈组件的共性。
2直接使用代理接入到hadoop用户的权限中。这个能是有权限的用户直接指定一个交替的seesion用户-在连接的时候。如果连接用户拥有hadoop级别的权限（模拟的请求userid）,hiveserver2将会给这个请求用户运行一个session。
还有种方式是使用 pre-authenticated Kerberos（详看hive-6486）。在这种模式中，住hive0.13.0，这个jbdc的驱动客户端使用pre-authenticated Kerberos来认证用户连接hiveserver2。这能使中间系统如在运行hive客户端那样运行查询语句。
使用kerberos的预认证
使用预认证，你需要做下面几个改变：
1增加hive-exec*.jar到classpath中，（commons-configuration-1.6.jar and hadoop-core*.jar不需要）
2增加auth=kerberos和kerberosAuthType=fromSubject的jdbc连接串的属性
3使用Subject.doAs()，打开连接。
下面是简单的代码使用，详情看hive-6486和test case：

static Connection getConnection( Subject signedOnUserSubject ) throws Exception{
       Connection conn = (Connection) Subject.doAs(signedOnUserSubject, new PrivilegedExceptionAction<Object>()
           {
               public Object run()
               {
                       Connection con = null;
                       String JDBC_DB_URL = "jdbc:hive2://HiveHost:10000/default;" ||
                                              "principal=hive/localhost.localdomain@EXAMPLE.COM;" ||
                                              "kerberosAuthType=fromSubject";
                       try {
                               Class.forName(JDBC_DRIVER);
                               con =  DriverManager.getConnection(JDBC_DB_URL);
                       } catch (SQLException e) {
                               e.printStackTrace();
                       } catch (ClassNotFoundException e) {
                               e.printStackTrace();
                       }
                       return con;
               }
           });
       return conn;
}

Python客户端
python客户端的驱动在github，安装，请看setting up hiverserver2:python client driver
Ruby客户端
ruby的客户端驱动在github上，https://github.com/forward3d/rbhive
与SQuirrel Sql集成
SQuirrel Sql是一个开源的java客户端工具，能够使用任意的jdbc连接数据库。
1下载，安装，运行SQuirrel SQL，SQuirrel SQL website
输入driver的名字和url

Name: Hive
Example URL: jdbc:hive2://localhost:10000/default

3选择extra class path->add来增加下面的jar包，在本地hive和分布式hadoop环境中。

HIVE_HOME/lib/hive-jdbc-*-standalone.jar
HADOOP_HOME/share/hadoop/common/hadoop-common-*.jar

4选择listDriver，会让SQuirrel使用jdbc驱动解析你的jar包，可能会花几分钟。再class name中填入hive的驱动来连接hiveserver2

org.apache.hive.jdbc.HiveDriver

5点击OK来完成驱动的注册
6选择Aliases->add alias来创建连接hiveserver2实列的别名
a.在Name方框中填入连接的别名
b.从”Driver”中,选择hive的驱动
c.修改url,连接hiveserver2实列
d.输入用户名和密码点击ok保存连接别名
e.双击别名，点击连接来连接上hiveserver2
当连接已经建立了，你将会在日志客户端看到错误。可能会有一个警告:the driver is not jdbc3.0兼容。这是因为jdbc的元数据apiyet-to-be-implemented ，这个可以忽略。为了测试连接，在命名行运行show tables.
注意，当查询开始时，对于取消的支持还没有做。
与Dbvissoftware的Dbvisualizer集成
Dbvisualizer是一个基于jdbc的数据库管理和分析的工具。
1下载，安装，运行免费的或者购买pro.https://www.dbvis.com/
2根据github来做。
集成其他工具的高级特征
下面这些特性，在hive1.2.0之后就支持了。
在HTTP模式中支持Cookie的重置
hive-9709介绍了jdbc驱动的cookie缓存支持。
jdbc的连接url，下成下面这样是有效的。

jdbc:hive2://<host>:<port>/<db>?transportMode=http;httpPath=<http_endpoint>;cookieAuth=true;cookieName=<cookie_name>

cookieAuth模式设为为true。
cookieName：如果安逸的cookies的key匹配上了cookieName，那么jdbc驱动不会发送任何登录凭证和kerberos ticket给服务器。这个客户端可以单独发送cookie给服务器认证。默认的cookieName是hive.server2.auth(这个是hiveserver2的cookie名字)。
为了运行cookie的replay，cookieAuth=false必须使用在url中。
在HTTP模式中可以使用双向的ssl
hive-10447能够使jdbc驱动，在hhtp模式中，支持双向的ssl。注意hiveserver2当前是不支持双向的ssl的。这个特性，在中间服务器中， 比如knox,且knox需要客户端支持双向的ssl，才是可用的。
jdbc，url

jdbc:hive2://<host>:<port>/<db>;ssl=true;twoWay=true;sslTrustStore=<trust_store_path>;trustStorePassword=<trust_store_password>;sslKeyStore=<key_store_path>;keyStorePassword=<key_store_password>?transportMode=http;httpPath=<http_endpoint>

trust_store_path:是客户端truststore文件的路径，不能为null。
trust_store_password：是访问truststore的密码。
key_store_path:是是客户端keystore文件的路径，不能为null。
key_store_password:是接入keystore的密码
通过jdbc的驱动，传输http头的key-value数据
这个特性在hive1.2.0之后才有
hive-10339介绍了一个客户端的选项，用来用户自定义http的header,头信息被发送到底层服务器上。
jdbc的url：

jdbc:hive2://<host>:<port>/<db>;transportMode=http;httpPath=<http_endpoint>;http.header.<name1>=<value1>;http.header.<name2>=<value2>

在上面的url被指定，beeline将会调用底层的request来增加一个http的header，header中设置 name1,value1和name2,value2.当用户需要在http中发送验证信息时，这个功能是很有用的，比如通过beeline来验证的Knox。

http.header.USERNAME=<value1>;http.header.PASSWORD=<value2>