hive那些事－02:hive中的man

######################
在linux下我们查看命令帮助可以用man xxx; xxx -h;
在mysql中,我们可以help xxx来查看文档;
............
那在hive中呢?我怎样知道当前有哪些表?有哪些函数,这些函数怎么用?hiveQL的语法?.....
你可以查看hive的wiki找到这些信息，但如果脱机呢?
我想我们应该了解下hive的那些自带的man,元芳,你怎么看?
###############################################################
我假设你已经知道这些了：
show tables;  //显示当前可用的表;
show functions;// 显示当前可用的函数;
desc xxxtable;//显示当前表的结构;
desc function xxxfunctionname;//显示函数的用法;
那来个比较有意思的，看下面的语句：

 
看吧，这个显示了datediff这个函数的用法,甚至还有一个示例，看着有点mysql中的help的意思了吧。
但，等等，你会同时发现2个问题：1.我怎么知道desc function 后面可以加extended的呢? 2.这些提示是怎么出来的呢,我自定义UDF的时候如果也可以这样不是也很好?

那我想我就分别解释一下这2个问题：
##################问题1
=>
hive中使用了一种类SQL的语言，称之为hiveQL;
hiveQL 是一种遵守 SQL-92 标准的SQL方言，但就跟mysql,oracle等一样，没有哪家数据库厂商是实现了所有SQL-92标准的，基本上各个厂商采取的作法是：遵守基本的SQL标准，然后砍下一些标准，再加上自己的一些扩展，基本是SQL标准的一个超子集。
hiveQL由于来自FB，FB大量采用mysql，因此实际上hiveQL更接近于mysql的SQL。
=>
hive实际上是MR的一种DSL，而这种DSL的语法嫁接于SQL语法。
提到DSL(领域专用语言),简单的如awk、sed等linux命令，大到SQL等.
提到DSL就得提到编译原理，提到编译中的词法解析、语法解析、AST...这些东西;
那在linux/c领域有些响亮的工具可以做这些:lex&&yacc ;flex&&bison;
在java领域对等的工具包，比较出色的有2个：antlr 、javacc
hadoop领域的2个主流DSL：hive采用的是antlr，Pig采用的是javacc.
基本上：antlr会更成熟、社区更活跃一些;主流的java DSL这块采用antlr的会更多一点：像hibernate、hive;当然由于javacc可以做到0运行时环境依赖等优势，因此如lucene、 pig则选择了它;当然你如果足够牛，裸写lexer,parser我也没意见，呵呵。
DSL/antlr是个很大的话题，我想基本上知道这些就足够了:
antlr/javacc是做词法解析、语法解析、生成AST等一系列编译相关的东东用的,antlr通常通过.g文件定义,javacc通常通过.jj文件定义规则;
那我们来找一下hive的语法文件:


 
我们在hive的源码下面找到了2个antlr定义文件，上面那个是跟metastore相关的,我们以后再说;
下面那个Hive.g则定义了HiveQL的词法、语法、AST生成，然后antlr根据这个文件自动生成Lexer、Parser这些东西。
你可以简单的vi这个文件查看它的内容，基本上如果你懂些简单的(E)BNF就能看懂这些东西，那antlr本身提供了一个工具来查看、调试这个文件，以desc这个语法，它看起来是这个样子：


 
部分1就是原始的文件内容，部分2是工具给我们的一个图形化显示；这都不重要，重要的是：我们知道了desc这个语法应该写成什么样子：
中间的那个规则：(KW_DESCRIBE|KW_DESC) KW_FUNCTION KW_EXTENDED? (name=descFuncNames)
定义了这样一个语法：以describe或desc关键字开头，然后接function关键字，然后有一个可选的extended关键字，最后是一个函数的名称;那么它用来做什么呢？它是怎么实现的呢？这些以后我们会详细的说。
到这里，我们可以回答第1个问题啦，那就是.g文件定义了hiveQL可用的语法，通过.g我可以清楚的知道我在hiveQL中能使用哪些语句.
##################问题2
回答问题2最好的办法是，我们看看datediff这个函数是怎么实现的:


 
如同定义普通的UDF一样，它继承某个约定的类，然后实现某些约定的方法，然后一切就可以了；但你发现上面的那段注解@Description是不是很眼 熟，没错hive是通过@Description注解来实现desc中的提示功能的；那今后你自己定义一个UDF的时候，除了N多书上写的那些套路外，应 该也加个@Description注解，这样别人就可以知道你这个函数做什么用的和怎样用了；那你还会发现注解中的extended对应于desc中的 extened，呵呵~，恭喜你，你都会抢答了！！

注解是个好东西，注解基本横扫了javaWeb的SSH领域，日常工作中我们也可以把配置文件甚至一些文件的生成交给自定义注解来做；当然hive为我们展示了注解的另一个有趣应用：通过注解来实现文档化;我想你如果做开源项目，这个比/docs目录会是个更好的方案;

###########################################################
那刀了这么多，我们可以不可以给hive实现个类似mysql中的help系统呢？这样我就不用一会desc函数，一会查看.g文件，有时还翻看wiki了呢？
当然可以，我目前提供如三个套餐：
1.最小侵入性的:通过扩展hive脚本，加一个比如-man的选项，由这个选项负责对.g文件进行索引这样，你写个脚本就能搞定;
2.侵入性最大的：我们扩展一下.g文件，让它支持HELP语法，然后实现HELP语法。在后续的文章中我会讲如何扩展语法，但仅仅目前的需求，这个有点小题大做了；
3.一种取巧的方式：我们可以把help的内容定义成UDF这样，那统一的借助hive自有的体系，我们就可以实现我们想提示的任何东西了。
上段代码：


 
然后你可以在REPL环境中执行那2句话，或者在.hiverc中定义：


 
然后我们看看效果：


 
呵呵，有点土，连个参数都不支持，每个语法都搞一个很累...........
亲，友情提示，只为演示原理和你可以怎样搞的目的啊。至少它能工作了，不是嘛？
注，方法3只为展示注解以及你可以这样做，但有点牵强；实际上单从文档化的角度，我们实际更应该使用1。
今天就到这~
那今后就不要再问：这个hiveQL哪个语法错了，这个方法怎么用了之类的话题了。你自己可以查的，你行的！~