Hive官方使用手册——新Hive CLI(Beeline CLI)

本文为自己翻译的译文，原文地址：https://cwiki.apache.org/confluence/display/Hive/HiveServer2+Clients

Hive官方使用手册——新Hive CLI(Beeline CLI)

这个页面描述了HiveServer2支持的不同客户端。其它的HiveServer2文档包含：

• HiveServer2 Overview
• Setting Up HiveServer2
• Hive Configuration Properties:  HiveServer2

Version

Introduced in Hive version 0.11. See HIVE-2935.

Beeline – Command Line Shell Beeline-命令行shell

HiveServer2 支持一个命令行shellBeeline。它是一种基于SQLline CLI 的JDBC客户端（http://sqlline.sourceforge.net/）。SQLLine的细节文档连接，它同样也适用于Beeline。

使用Beeline代替Hive CLI实现

同时支持嵌入模式和远程模式。在嵌入模式中，它运行一个嵌入的Hive（类似旧的Hive CLI）然而远程模式是通过Thrift连接一个分离的HiveServer2进程。从Hive 0.1.4版本开始，Beeline已经被HiveServer2使用，它也会为它执行的查询从HiveServer2打印日志信息到STDERR。远程HiveServer2模式是Hive产品使用的推荐模式，它更加安全并且不需要直接为用户对HDFS/metastore进行赋权。

在远程模式中HiveServer2只接受认证的Thrift 连接请求甚至在HTTP模式中也一样，信息主体班号Thrift payload

Beeline 样例

% bin/beeline 
Hive version 0.11.0-SNAPSHOT by Apache
beeline> !connect jdbc:hive2://localhost:10000 scott tiger
!connect jdbc:hive2://localhost:10000 scott tiger 
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)

 

 你也可以在命令行上指定连接参数。这意味着你能够从你的UNIX Shell history中发现连接时使用的命令。

% beeline -u jdbc:hive2://localhost:10000/default -n scott -w password_file
Hive version 0.11.0-SNAPSHOT by Apache

Connecting to jdbc:hive2://localhost:10000/default

Beeline with NoSASL connection

如果你喜欢通过NOSASL模式建立连接，你必须明确的指定认证模式。：

% bin/beeline
beeline> !connect jdbc:hive2://:/;auth=noSasl hiveuser pass 

Beeline Commands

Command	Description
!	SQLLine命令清单请访问http://sqlline.sourceforge.net/ 样例：使用 !quit 退出Beeline客户端。
!delimiter	设置在Beeline中写查询的界定符。允许使用多字符界定符，但是引号，斜杠和--是不允许的。默认是分号; 用例: !delimiter $$ Version: 3.0.0 (HIVE-10865)

Beeline Hive Commands

当使用HiveJDBC驱动时Hvie 自带的命令（和Hive CLI 命令行）也能在Beeline中运行，.

使用分号";"来结束命令，脚本中可以用"--"作为前缀来标识命令。

命令	描述
reset	重设配置为默认值。
set =	为特定的配置变量（key）设置值。 注：如果你们拼写错了变量名，CLI将不会提示错误。
set	打印一个被用户或者Hive重写的配置变量清单。
set -v	打印所有的Hadoop和Hive的配置变量。
add FILE[S] *  add JAR[S] *  add ARCHIVE[S] *	增加一个或者多个文件，jar包或者压缩包到分布式缓存的资源列表中。查阅Hive Resources获取更多信息。
add FILE[S] *  add JAR[S]  *  add ARCHIVE[S] *	自Hive 1.2.0起，增加一个或者多个文件，jar包或者压缩包到分布式缓存的资源列表中使用类似ivy://group:module:version?query_string的lvy URL。查阅Hive Resources获取更多信息。
list FILE[S]  list JAR[S]  list ARCHIVE[S]	列出已经增加到分布式缓存的资源。查阅Hive Resources获取更多信息(As of Hive 0.14.0: HIVE-7592)。
list FILE[S] *  list JAR[S] *  list ARCHIVE[S] *	检查是否给定的资源已经被添加到分布式缓存中。查阅Hive Resources获取更多信息。
delete FILE[S] *  delete JAR[S] *  delete ARCHIVE[S] *	移除分布式缓存中的一些资源。
delete FILE[S] *  delete JAR[S] *  delete ARCHIVE[S] *	自Hive 1.2.0起，移除通过 添加到分布式缓存中的资源。查阅Hive Resources获取更多信息。
reload	从Hive 0.14.0起，通过配置参数hive.reloadable.aux.jars.path（不需要重启HiveServer2）指定路径使HiveServer2 感知到任意jar包的变化。这里的变化包括增加，删除，或者更新jar包。
dfs	通过Hive shell执行一个dfs命令。
	执行一个Hive查询语句并且输出标准输出。

Beeline 命令行选项

Beeline CLI支持以下这些命令行选项:

选项	描述
-u	用于JDBC URL连接。 用例：beeline -u db_URL
-r	重新连接到最近使用过的URL（如果用户有预先使过的用的，用!connect生成URL，用!save 生成beeline.properties.file）。 用例: beeline -r   Version: 2.1.0 (HIVE-13670)
-n	连接时使用的用户名。 用例: beeline -n valid_user
-p	连接时使用的密码。 用例: beeline -p valid_password 可选的密码模式: 从Hive 2.2.0开始参数-p选项是可选的。 用例 : beeline -p [valid_password] 如果密码不是在-p之后提供的，Beeline将在初始化连接时提示输入密码。当密码提供后Beeline会用它来初始化连接而不提示。
-d	配置使用的驱动类 用例: beeline -d driver_class
-e	应该执行的查询。查询语句两端用单引号和双引号。这个选项被使用多次。 用例: beeline -e "query_string" 支持运行复杂的SQL语句，在一个语句中通过使用分号分隔。 (HIVE-9877) Bug fix (null pointer exception): 0.13.0 (HIVE-5765) Bug fix (--headerInterval not honored): 0.14.0 (HIVE-7647) Bug fix (running -e in background): 1.3.0 and 2.0.0 (HIVE-6758); workaround available for earlier versions
-f	需要被执行的脚本文件。 用例: beeline -f filepath Version: 0.12.0 (HIVE-4268) 注：如果脚本里面包含tabs，版本0.12.0中查询编译失败，这个bug已经在0.13.0版本修复了。 (HIVE-6359). Bug fix (running -f in background): 1.3.0 and 2.0.0 (HIVE-6758); workaround available for earlier versions
-i (or) --init	初始化需要的初始文件。 用例: beeline -i /tmp/initfile 单个文件: Version: 0.14.0 (HIVE-6561) 多个文件: Version: 2.1.0 (HIVE-11336)
-w (or) --password-file	从文件中读取密码。 Version: 1.2.0 (HIVE-7175)
-a (or) --authType	jdbc的认证类型是一个身份认证属性。 Version: 0.13.0 (HIVE-5155)
--property-file	读取配置属性的文件 用例: beeline --property-file /tmp/a Version: 2.2.0 (HIVE-13964)
--hiveconf property=value	为给定的配置属性赋值。 在hive.conf.restricted.list列表中的属性不能通过hiveconf的方式重置。 (see Restricted List and Whitelist). 用例: beeline --hiveconf prop1=value1 Version: 0.13.0 (HIVE-6173)
--hivevar name=value	Hive的变量名和变量值。这是一个Hive指定的设置，在这变量能够在会话级别被设置和被Hive命令和查询引用。 用例: beeline --hivevar var1=value1
--color=[true/false]	控制颜色是否被用来展示。默认是false 用例: beeline --color=true (不支持分隔的值输出方式。See HIVE-9770)
--showHeader=[true/false]	展示列名是否在查询结果中。默认是true。 用例: beeline --showHeader=false
--headerInterval=ROWS	当输出为表格时，重新显示列头时他们之间的间隔，用行数计算。默认值为100 用例: beeline --headerInterval=50 (不支持分隔的值输出方式。See HIVE-9770)
--fastConnect=[true/false]	连接时，跳过为HiveQL语法的tab键自动补全功能而构建所有表和列的清单，默认为true不构建该列表。 用例: beeline --fastConnect=false
--autoCommit=[true/false]	允许或者禁止自动事务执行。默认是false 用例: beeline --autoCommit=true
--verbose=[true/false]	展示冗长的报错信息和调试信息（true）或者不展示（false），默认是false 用例: beeline --verbose=true
--showWarnings=[true/false]	Default is false.连接时，在执行任意HiveQL命令后展示警告信息。默认是false。 用例: beeline --showWarnings=true
--showDbInPrompt=[true/false]	在提示符里面展示当前数据库名字。默认是false。 用例: beeline --showDbInPrompt=true Version: 2.2.0 (HIVE-14123)
--showNestedErrs=[true/false]	展示内部错误，默认是false。 用例: beeline --showNestedErrs=true
--numberFormat=[pattern]	用一个小数格式的模板来格式化数字。 用例: beeline --numberFormat="#,###,##0.00"
--force=[true/false]	出错后继续运行脚本（true），或者不运行（false）。默认是false。 用例: beeline--force=true
--maxWidth=MAXWIDTH	当输出格式是表格时，在截断数据前展示的最大宽度。默认是查询时的终端的当前宽度，然后回到80。 用例: beeline --maxWidth=150
--maxColumnWidth=MAXCOLWIDTH	当输出是表格时，最大列宽，Hive 2.2.0以后默认是50，之前的版本是15。 用例: beeline --maxColumnWidth=25
--silent=[true/false]	是（true）否（false）减少展示的信息量。它也会停止展示HiveServer2（Hive 0.14及之后的版本）的查询和命令（Hive 1.2.0及之后的版本）日志信息，默认是false。 用例: beeline --silent=true
--autosave=[true/false]	自动保存参数选择（true）或者不保存（false）。默认是false。 用例: beeline --autosave=true
--outputformat=[table/vertical/csv/tsv/dsv/csv2/tsv2]	结果展示的模式。默认是表格。查阅下方的Separated-Value Output Formats获取更多信息和推荐选项。 用例: beeline --outputformat=tsv 版本号: dsv/csv2/tsv2 added in 0.14.0 (HIVE-8615)
--truncateTable=[true/false]	如果是true，那么当表格超出终端显示宽度时，截断表格的列在终端上展示。 版本号: 0.14.0 (HIVE-6928)
--delimiterForDSV= DELIMITER	用于输出格式中划分值的界定符。默认是‘|’ 版本号: 0.14.0 (HIVE-7390)
--isolation=LEVEL	设置事务隔离级别为TRANSACTION_READ_COMMITTED或者TRANSACTION_SERIALIZABLE.  可以查阅Java连接文档中“Field Detail”那一章节。 用例: beeline --isolation=TRANSACTION_SERIALIZABLE
--nullemptystring=[true/false]	使用历史的打印空字符null的形式(true)还是使用当前打印空值的方式(false)，默认是false。 用例: beeline --nullemptystring=false Version: 0.13.0 (HIVE-4485)
--incremental=[true/false]	从Hive 2.3版本往后默认是true，在它之前是默认为false。当设置为false时，为了最佳的展示列宽，完整的结果集会在展示之前被收集然后缓存起来。当设置为true时，结果集一旦被抓取到就会立即展示， 为了在展示列的填充额外消耗更少的延迟和内存。当你在客户端遭遇一个内存溢出时，推荐设置--incremental=true (因为抓取到的结果集非常大)。
--incrementalBufferRows=NUMROWS	当打印行到标准输出时，保存在缓存中的行数，默认是1000。只有当 --incremental=true 和 --outputformat=table才适用。 用例: beeline --incrementalBufferRows=1000 Version: 2.3.0 (HIVE-14170)
--maxHistoryRows=NUMROWS	存储Beeline 历史记录的最大行数。 Version: 2.3.0 (HIVE-15166)
--delimiter=;	设置Beeline的查询语句分隔符。允许用多个字符的分隔符，但是引号，斜杠和--是不允许的，默认是分号; 用例: beeline --delimiter=$$ Version: 3.0.0 (HIVE-10865)
--convertBinaryArrayToString=[true/false]	展示二进制列数据为字符串或者位矩阵。   用例: beeline --convertBinaryArrayToString=true   Version: 3.0.0 (HIVE-14786)
--help	展示一个帮助信息。 用例: beeline --help

输出格式

在Beeline中，结果可以被展示位多种格式。格式可以在 outputformat 参数中设置。

下面是支持的输出格式:

• table
• vertical
• xmlattr
• xmlelements
• separated-value formats (csv, tsv, csv2, tsv2, dsv)

table

结果会被展示位一个表格。结果中行对应表中的一行，每行使用分隔符将不同列的取值分开。这是默认的格式

  Example

vertical

结果集中的每行被展示位一个Key-value格式的块，其中key是列名。

  Example

xmlattr

结果被展示为一个XML文件的格式，其中每行结果对应XML中的元素。结果中一行的取值对应结果元素中不同属性，每个属性的名字对应列名。

  Example

xmlelements

结果被展示为一个XML格式，其中每行就是XML中的一个元素“result”。每行的取值就是其子元素。

  Example

Separated-Value Output Formats

一行的取值被不同的分隔符分开。
有五种 separated-value 输出格式可用：csv, tsv, csv2, tsv2 and dsv.

csv2, tsv2, dsv

从 Hive 0.14 开始引入的SV输出格式包括：dsv，csv2和tsv2。
这三格式只是数据cell之间使用了不同的分隔符，csv2使用的是逗号，tsv2使用的是tab空格，dsv是可配置的。

对于dsv格式，分隔符可以通过用参数 delimiterForDSV 进行设置，默认是 '|'。
这里是支持单个字符的分隔符的。

  Example

Quoting in csv2, tsv2 and dsv Formats

如果引号没被废弃，一个值包含特殊符号（例如分隔符或者双引号）或者跨越多行需要用双引号包含起来。
内含双引号是通过一个前置双引号进行转义。

可以通过设置系统变量 disable.quoting.for.sv 为true来禁用引号。 
如果引号被禁用, 那么双引号不用来包围值（甚至他们包含特殊字符）和内嵌式双引号是无法避免的。
默认引号是禁用的。

  Example

csv, tsv

csv,tsv是两种不同的格式只是值之间的分隔符不同而已,csv是逗号，tsv是tab空格。
数值总是被单引号包围,即使引号通过系统变量sable.quoting.for.sv 被禁用了。
这些输出格式无法避免内含单引号的情况。
请注意这些格式都是被弃用的，只是为维护向后的兼容性。

  Example

HiveServer2 日志

从Hive 0.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)

 HIVE-11488 (Hive 2.0.0) 增加了对HiveServer2日志文件的日志查询ID和会话ID的支持。启用它，可以编辑、增加%X{queryId} 和 %X{sessionId} 到日志配置文件的格式模式字符串.

取消查询

如果有一个查询正在运行，同时用户输入了 CTRL+C 在Beeline shell界面, 那么Beeline进程将会尝试取消查询并且关闭到HiveServer2的Socket连接。这个行为只有当设置 hive.server2.close.session.on.disconnect 为 true 才会被启用。从Hive 2.2.0 (HIVE-15626)开始Beeline不再推出命令行窗口当用户输出了 CTRL+C取消了当前正在运行的查询。 如果用户想要退出命令行窗口，用户需要在查询被取消后再按一次CTRL+C 。然而，没有正在运行的查询时，第一次按的 CTRL+C 将会退出Beeline 窗口。这个行为类似于Hive CLI对CTRL+C的处理方式。

!quit 是推荐的退出Beeline窗口的命令

终端脚本里的后台查询

Beeline能够在不连接批处理终端的情况下使用nohup和disown命令自动运行脚本。

一些版本的Beeline客户端可能需要一个工作区来支持nohup命令很好的将进程放进后台运行而不停止它。See HIVE-11717, HIVE-6758.

以下的环境变量可以被更新:

export HADOOP_CLIENT_OPTS="$HADOOP_CLIENT_OPTS -Djline.terminal=jline.UnsupportedTerminal"

使用nohup和&将会把进程放进后台并允许终端断开连接而Beeline进程持续运行。

nohup beeline --silent=true --showHeader=true --outputformat=dsv -f query.hql /tmp/output.log 2> /tmp/error.log &

JDBC

Hive HiveServer2 有一个JDBC驱动。它支持嵌入式的和远程连接HiveServer2。远程HiveServer2模式是推荐模式，它更加安全而且不需要直接的HDFS或者元数据的用户使用权限。

连接 URLs

连接 URL 格式

HiveServer2 URL 是一个类似下面语法的字符串：

jdbc:hive2://:,:/dbName;initFile=;sess_var_list?hive_conf_list#hive_var_list

where

• :,: 是一个服务实例或者一个用逗号分隔的服务实例列表（动态服务发现启用）。如果为空，将会使用嵌入的服务器。
• dbName 初始化数据库的名称。
•  脚本文件的路径 (Hive 2.2.0 and later). 这里的脚本是SQL脚本，它将会在连接建立后被执行。此参数可以为空。
• sess_var_list 是一个以分号分隔的列表，列表里面是会话变量的key=value对 (e.g., user=foo;password=bar).
• hive_conf_list 是一个以分号分隔的列表，列表里面是当前会话的Hive配置变量的key=value对。
• hive_var_list 是一个以分号分隔的列表，列表里面是当前会话的Hive变量的key=value对。

 远程或者嵌入模式的连接 URL

JDBC连接URL格式的前缀是 jdbc:hive2://  而驱动是 org.apache.hive.jdbc.HiveDriver。注意这里不同于旧的HiveServer。

• 对于远程模式, URL 格式是 jdbc:hive2://:/;initFile= (默认的HiveServer2端口 is 10000).
• 对于一个嵌入的服务, URL格式是 jdbc:hive2:///;initFile= (没有主机或者端口号).

参数 initFile 是 Hive 2.2.0 和之后版本所支持的。

当使用HTTP Mode连接HiveServer2连接 URL

JDBC 连接 URL:  jdbc:hive2://:/;transportMode=http;httpPath=, where:

•  是相应的HTTP 端的配置在hive-site.xml. 默认值是cliservice。
• HTTP传输模式的端口默认是10001。

Versions earlier than 0.14

In versions earlier than 0.14 these parameters used to be called hive.server2.transport.mode and hive.server2.thrift.http.path respectively and were part of the hive_conf_list. These versions have been deprecated in favour of the new versions (which are part of the sess_var_list) but continue to work for now.

在HiveServer2启用SSL时的连接URL

JDBC 连接 URL:  jdbc:hive2://:/;ssl=true;sslTrustStore=;trustStorePassword=, where:

• 是客户端的 信任库文件存放路径。
• 是信任库的密码

HTTP 模式:  jdbc:hive2://:/;ssl=true;sslTrustStore=;trustStorePassword=;transportMode=http;httpPath=.

For versions earlier than 0.14, see the version note above.

当启用 ZooKeeper 服务发现时的连接URL

以ZooKeeper为基础的服务发现是在Hive 0.14.0版本启用高可用后引进的并且随着HiveServer2进行了升级。一个JDBC URL指定需要被用来使用这些特性。

在Hive 2.0.0 and 1.3.0 (unreleased, HIVE-11581)将来的变化中, 没有额外的配置参数例如认证模式，传输模式，或者SSL参数需要被指定，而它们会从ZooKeeper伴随主机名进入中恢复。 

JDBC 连接URL: jdbc:hive2:///;serviceDiscoveryMode=zooKeeper;zooKeeperNamespace=hiveserver2 .

和hive.zookeeper.quorum 在hive-site.xml/hivserver2-site.xml里面被HiveServer2使用的配置参数相同。

查询需要的额外运行参数能够被提供，它通过下面的URL提供，通过在后面追加一个前置? .

JDBC 连接URL: jdbc:hive2:///;serviceDiscoveryMode=zooKeeper;zooKeeperNamespace=hiveserver2?tez.queue.name=hive1&hive.server2.thrift.resultset.serialize.in.tasks=true 

用户URL的名字建立连接

从Hive 2.1.0 (HIVE-13670)起, Beeline 现在也支持通过环境变量命名的URL连接字符串。如果你尝试对一个看起来不像URL的名字执行 !connect , 那么Beeline将会尝试查看是否有一个环境变量叫BEELINE_URL_。例如，如果你指定 !connect blue, 它将会查找BEELINE_URL_BLUE然后用它来建立连接。这样听起来更加方便系统管理员为用户指定环境变量，用户也不需要每次连接都键入全部URL。

重新连接

习惯上，!reconnect 努力刷新一个已经建立的连接。它不会在!close 被执行后再运行。从Hive 2.1.0 (HIVE-13670)起, Beeline 会记住上一次成功连接的URL, 甚至在一次 !close 被执行后仍然可以重新建立连接。另外，如果用户执行一次 !save, 那么这个会保存在beeline.properties 文件中, 这也允许了!reconnect 通过复杂的Beeline会话重新连接这个被保存的最后连接URL。这也允许使用 beeline -r  在启动时的命令行窗口中执行重新连接。.

使用hive-site.xml 自动连接HiveServer2

从Hive 2.2.0 (HIVE-14063)起, BeeLine 增加了对使用存放在安装路径中的hive-site.xml生成一个基于hive配置文件和用户额外配置文件的连接URL。不是所有的URL配置都能够从hive-site.xml中得到，因此为了更好的使用这个特性，用户需要创建一个Hadoop xml格式的配置文件“beeline-hs2-connection.xml”。这个文件用来提供用户指定好的连接参数。BeeLine 会在${user.home}/.beeline/ (Unix based OS) 或者 ${user.home}\beeline\ （Windows环境）目录中查找该文件。如果上述路径中不存在该文件，Beeline会按照${HIVE_CONF_DIR} 和 /etc/hive/conf (Check HIVE-16335 which fixes this location from /etc/conf/hive in Hive 2.2.0) 这个顺序查找该文件。一旦文件被找到，Beeline 会结合beeline-hs2-connection.xml 和路径中hive-site.xml来决定 连接URL。

beeline-hs2-connection.xml中的连接属性必须有前缀“beeline.hs2.connection.”后面是url的属性名称。例如：为了提供属性ssl，beeline-hs2-connection.xml中的属性关键字应该是“beeline.hs2.connection.ssl”。 下方beeline.hs2.connection.xml的样例提供了Beeline连接URL的用户名和密码的值。在这个案例中剩下的例如HS2主机名和端口信息，kerberos配置属性，SSL属性，传输模式等会从路径里的hive-site.xml文件中获取。如果密码是空，beeline.hs2.connection.password 应该被删掉。在大部分案例中下面beeline-hs2-connection.xml的配置值 和路径中正确的hive-site.xml应该准备好来保证HiveServer2的连接。

 

"1.0" ?>
"text/xsl"  href= "configuration.xsl" ?>


 beeline.hs2.connection.user
 hive


 beeline.hs2.connection.password
 hive

为了防止参数在 beeline-hs2-connection.xml 和hive-site.xml中同时出现, 优先选用beeline-hs2-connection.xml中参数值。例如瞎忙的beeline-hs2-connection.xml file 提供了  在kerberos认证被启用的环境中BeeLine 的principal值。在这个案例中连接被建立时beeline.hs2.connection.principal的值覆盖hive-site.xml 中的HiveConf.ConfVars.HIVE_SERVER2_KERBEROS_PRINCIPAL 值。

"1.0" ?>
"text/xsl"  href= "configuration.xsl" ?>


 beeline.hs2.connection.hosts
 localhost: 10000


 beeline.hs2.connection.principal
 hive/dummy-hostname @domain .com

以防beeline.hs2.connection.hosts, beeline.hs2.connection.hiveconf 和beeline.hs2.connection.hivevar 参数值是一个逗号分隔的列表。例如下面的beeline-hs2-connection.xml 以逗号分隔的格式提供了hiveconf 和hivevar 值清单。

"1.0" ?>
"text/xsl"  href= "configuration.xsl" ?>


 beeline.hs2.connection.user
 hive


 beeline.hs2.connection.hiveconf
 hive.cli.print.current.db= true , hive.cli.print.header= true


 beeline.hs2.connection.hivevar
 testVarName1=value1, testVarName2=value2

当beeline-hs2-connection.xml 已经存在同时没有其他参数被提供，Beeline自动连接由配置文件生成的URL。当连接参数(-u, -n or -p)被提供，Beeline将使用它们而不是用beeline-hs2-connection.xml中的值来建立连接。去除或者重命名beeline-hs2-connection.xml禁用这个特性。

使用JDBC

你可以通过JDBC的方式在一个关系型数据库或者其它表格型格式中使用数据存储。

1. 加载HiveServer2 JDBC驱动。自1.2.0起应用不在需要使用Class.forName()明确的加载JDBC驱动程序。
   
   例如:

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

2.  通过一个Connection对象用JDBC驱动连接数据库。
   
   例如:

   Connection cnct = DriverManager.getConnection("jdbc:hive2://:", "", "");
   

   默认  值是10000。不安全的配置方法中，指定一个运行时用的 ，忽略 的取值。

   Connection cnct = DriverManager.getConnection("jdbc:hive2://:", "", "");
   

   Kerberos的认证安全模式中，用户信息是基于Kerberos的认证信息。

3. 通过创建一个 Statement 对象提交SQL给数据库并且使用它的方法 executeQuery()。
   
   样例:

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

4. 处理结果集，如果有必要的话。

步骤见下面的样例代码截图。

JDBC Client Sample Code

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 (use hadoop-common*.jar for Hadoop 2.x)
#
# 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

可选的是，您可以运行以下bash脚本，它将在调用客户机之前生成数据文件并构建类路径。该脚本添加了在嵌入式模式中使用HiveServer2所需的所有额外jar。

#!/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数据类型

下表列出了用于HiveServer2 JDBC的数据类型。

Hive Type	Java Type	Specification
TINYINT	byte	signed or unsigned 1-byte integer
SMALLINT	short	signed 2-byte integer
INT	int	signed 4-byte integer
BIGINT	long	signed 8-byte integer
FLOAT	double	single-precision number (approximately 7 digits)
DOUBLE	double	double-precision number (approximately 15 digits)
DECIMAL	java.math.BigDecimal	fixed-precision decimal value
BOOLEAN	boolean	a single bit (0 or 1)
STRING	String	character string or variable-length character string
TIMESTAMP	java.sql.Timestamp	date and time value
BINARY	String	binary data
Complex Types
ARRAY	String – json encoded	values of one data type
MAP	String – json encoded	key-value pairs
STRUCT	String – json encoded	structured values

用于安全集群的JDBC客户端设置

当使用Kerberos身份验证连接到HiveServer2时，URL格式为:

jdbc:hive2://:/;principal=

客户端需要在连接之前在票据缓存中有一个有效的Kerberos票据。

注意:如果在端口号之后没有“/”，jdbc驱动程序不会解析主机名，并在嵌入式模式下运行HS2。因此，如果您指定一个主机名，请确保在端口号之后有一个“/”或“/ ”。

在LDAP、定制或PAM身份验证的情况下，客户机需要将有效的用户名和密码传递给JDBC连接API。

To use sasl.qop, add the following to the sessionconf part of your Hive JDBC hive connection string, e.g.

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

有关更多信息，请参见Setting Up HiveServer2.

KDC多用户场景和编程登录到Kerberos KDC

在当前使用Kerberos的方法中，您需要在连接之前在票据缓存中拥有一个有效的Kerberos票据。这需要一个静态登录(使用kinit、key tab或ticketcache)和每个客户端一个Kerberos用户的限制。在客户机希望以编程方式登录Kerberos KDC的场景中，这些限制条件限制了中间件系统和其他多用户场景的使用。

解决多用户场景问题的一种方法是使用安全代理用户(参见HIVE-5155)。从Hive 0.13.0开始，支持安全代理用户有两个组件:

• 特权Hadoop用户的直接代理访问(HIVE-5155)。这使得特权用户可以在连接期间直接指定备用会话用户。如果连接用户有Hadoop级别的特权来模拟请求的用户id，那么HiveServer2将会按照请求的用户运行会话。
• 基于委托标记的Oozie连接(Oozie -1457)。这是Hadoop生态系统组件的常见机制。Hadoop生态系统中的代理用户特权与用户名和主机相关。也就是说，特定主机的某些用户可以使用此特权。如果您从一个授权的(受祝福的)机器连接，并且稍后需要从另一个非受祝福的机器上连接，则需要使用Hive中的委托令牌。您从一个受祝福的机器上获得授权令牌，并使用来自非受祝福机器的委托令牌连接。主要用例是Oozie，它从服务器机器获取一个委托令牌，然后从Hadoop任务节点获取另一个连接。
  
  
• 如果您只是将JDBC连接作为来自单个受祝福机器的特权用户，那么直接代理访问就是更简单的方法。您可以通过使用hive.server2.proxy.user=参数将需要在JDBC URL中模拟的用户传递给用户。
  
  样例详情参见ProxyAuthTest.java.
  
  从0.13.0开始支持使用HiveServer2二进制传输模式 hive.server2.transport.mode ;在HIVE-13169中加入了HTTP传输模式的支持，这应该是Hive 2.1.0的一部分。

另一种方法是使用预验证的Kerberos主体(参见 HIVE-6486)。在这个方法中，从Hive 0.13.0开始，Hive JDBC客户端可以使用预先验证的subject来验证它的HiveServer2。这使得中间件系统能够在用户运行客户端时运行查询。

使用具有预认证主题的Kerberos

要使用预认证的主题，您需要以下更改。

1. 添加hive-exec *。除了常规的Hive JDBC jar (common -configuration-1.6)之外，jar到类路径。jar和hadoop核心*。jar不需要)。
2. 增加 auth=kerberos 和 kerberosAuthType=fromSubject JDBC URL 属性，除此之外附上“principal" url 属性。
3. 在Subject.doAs()里打开连接。

下面的代码片段说明了用法(一个完整的test case请参考HIVE-6486 ):

static  Connection getConnection( Subject signedOnUserSubject )  throws  Exception{
       Connection conn = (Connection) Subject.doAs(signedOnUserSubject,  new  PrivilegedExceptionAction()             {                 public  Object run()                 {                         Connection con =  null ;                         String JDBC_DB_URL =  "jdbc:hive2://HiveHost:10000/default;"  ||                                                "principal=hive/[email protected];"  ||                                                "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; }
           {
               public  Object run()
               {
                       Connection con =  null ;
                       String JDBC_DB_URL =  "jdbc:hive2://HiveHost:10000/default;"  ||
                                              "principal=hive/[email protected];"  ||
                                              "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 Client

在github有一个可用的Python客户端。 查阅 Setting Up HiveServer2: Python Client Driver获取安装和使用信息。

Ruby Client

Ruby客户端驱动在github上的地址是 https://github.com/forward3d/rbhive.

Integration with SQuirrel SQL Client 

1. 从SQuirrel SQL website上可以找到下载，安装和开始使用SQuirrel SQL客户端的方法
2. 点击选择 'Drivers -> New Driver...' 来注册Hive的HiveServer2的驱动。

   1. 输入驱动名字和样例URL:

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

3. 点击选择'Extra Class Path -> Add' 来增加你本地或者Hadoop分布式系统上的Jar包。

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

   Version information

   Hive JDBC standalone jars are used in Hive 0.14.0 onward (HIVE-538); for previous versions of Hive, use HIVE_HOME/build/dist/lib/*.jar instead.

   The hadoop-common jars are for Hadoop 2.0; for previous versions of Hadoop, use HADOOP_HOME/hadoop-*-core.jar instead.

4. 输入'List Drivers'. 这个将会使用SQuirrel列出你的JDBC驱动的jar包，这个过程可能需要数秒钟。在'Class Name'输入框选择HiveServer2的驱动：

   org.apache.hive.jdbc.HiveDriver

5. 点击'OK' 完成驱动注册。 

6. 选择'Aliases -> Add Alias...' 创建你的HiveServer2的连接实例别名。
   1. 在'Name'输入框输入你指定的名字。
   2. 在‘Driver' 下拉列表中选择Hive驱动。
   3. 修改样例URL指向你的HiveSever2实例。
   4. 输入用户名和密码点击‘OK’保存连接别名。
   5. 为了连接HiveServer2,双击Hive别名然后点击连接。

当连接建立的时候，你可能会看到一些错误和警告不兼容JDBC 3.0信息在日志终端里面。这些警报是由于JDBC元数据API的尚未实现的部分，可以安全地忽略。 要测试连接，请在控制台中 SHOW TABLES 并单击run图标。

还要注意：当查询正在运行时，目前不知支持“Cancel”按钮。

Integration with SQL Developer

使用JDBC连接Oracle SQLDeveloper是可用的。

https://community.hortonworks.com/articles/1887/connect-oracle-sql-developer-to-hive.html

Integration with DbVisSoftware's DbVisualizer

1. 免费下载，安装和启动 DbVisualizer 或者购买 DbVisualizer Pro 请参见 https://www.dbvis.com/.
2. 请遵循 github上的指导说明。

和其他工具结合的高级特性

在HTTP模式下支持Cookie重放

Version 1.2.0 and later

This option is available starting in Hive 1.2.0.

HIVE-9709 引入了对JDBC驱动程序的支持，以支持cookie重放。默认是打开这个功能，因此传入的cookie可以被发送回服务器进行身份验证。

启用时的JDBC连接URL应该如下所示:

jdbc:hive2://:/?transportMode=http;httpPath=;cookieAuth=true;cookieName=

• 在默认情况下，cookieAuth被设置为true。
• cookieName: 如果任何传入的cookie键与cookieName的值相匹配，JDBC驱动程序将不会向服务器发送任何登录凭据或者Kerberos票据。客户端将只将cookie单独发送回服务器进行身份验证。cookieName的默认值是hive.server2.auth(这是HiveServer2 cookie名称)。
• 为了关闭cookie重放，cookieAuth=false必须在JDBC URL中使用。
• 重要提示: 作为HIVE-9709的一部分, 我们将Hive的http-client和http-core组件升级为4.4。为了避免冲突存在于HttpComponents升级版本和用户安装的其他任何版本之间(如Apache Hadoop 2.6提供的一个使用http客户端和http-core组件版本的4.2.5)，客户端将设置CLASSPATH路径，这样Beeline相关jar包会出现在Hadoop库的jar包之前。这是通过在使用hive-jdbc之前设置 HADOOP_USER_CLASSPATH_FIRST=true来实现的。事实上，我们在bin/beeline.sh里面这么干！

Using 2-way SSL in HTTP Mode 

Version 1.2.0 and later

This option is available starting in Hive 1.2.0.

HIVE-10447使JDBC驱动程序能够在HTTP模式中支持双向SSL。请注意，HiveServer2目前不支持双向SSL。因此，当有一个中间服务器(如Knox)需要客户端支持2路SSL时，这个特性就很方便了。

JDBC连接URL:

jdbc:hive2://:/;ssl=true;twoWay=true;sslTrustStore=;trustStorePassword=;sslKeyStore=;keyStorePassword=?transportMode=http;httpPath=

•  是客户机信任存储文件存在的路径。这是一个强制的非空字段。
•  是访问信任库的密码。
• 是客户的密钥库文件存在的路径。这是一个强制的非空字段。
• 是访问密钥存储库的密码。

对于较早于0.14的版本，请参阅上面的版本说明。

Passing HTTP Header Key/Value Pairs via JDBC Driver

Version 1.2.0 and later

This option is available starting in Hive 1.2.0.

HIVE-10339 为客户端提供了一个选项，用于提供可以发送到底层服务器的自定义HTTP头(Hive 1.2.0和更高版本)。

JDBC 连接 URL:

jdbc:hive2://:/;transportMode=http;httpPath=;http.header.=;http.header.=

当指定上述URL时，Beeline将调用底层请求，将HTTP头集设置为 and  和另一个HTTP头集设置为 and 。当终端用户需要在HTTP头中将身份发送到诸如Knox这样的中间服务器，例如：http.header.USERNAME=;http.header.PASSWORD=。

For versions earlier than 0.14, see the version note above. 

Passing Custom HTTP Cookie Key/Value Pairs via JDBC Driver

在Hive版本3.0.0中HIVE-18447为客户提供了一个选项，用于提供可以发送到底层服务器的自定义HTTP cookie。一些身份验证机制(如单点登录)需要能够将cookie传递给一些中间身份验证服务，比如通过JDBC驱动程序的Knox。

JDBC连接URL: 

jdbc:hive2://:/;transportMode=http;httpPath=;http.cookie.=;http.cookie.=

当指定上述URL时，Beeline将调用底层请求，在请求头中添加HTTP cookie，并将其设置为= and =。

Hive语言手册目录