# 共享 Hive 元数据

OushuDB 支持共享 Hive 的元数据，利用自身的执行器无缝使用 Hive 存储在 HDFS 上的数据。

## 前提条件 —— 准备 Hive 环境

OushuDB 为了访问 Hive 元数据，需要 Hive 开启基于 Thrfit 模式的 HiveMetastore（HMS） 服务或提供 HiveServer2 服务。若希望 OushuDB 以 Kerberos 方式访问 Hive，需要在 OushuDB Main 节点上部署 Kerberos 服务，并提供对应的 keytab 和 principal。

## 使用说明
### 建立 Hive Schema

OushuDB 会将 Hive 元数据映射成 Tablespace，并通过将其 Database 绑定在 Tablespace 后，以 Schema 的形式存在。

OushuDB 在配置 hive 连接信息时支持 MetaStore 地址连接以及配置文件两种方式
```sql
-- Hive MetaStore方式
CREATE TABLESPACE <tablespace_name> LOCATION 'hive://hive.metastore.uri&database=databasename';

-- 配置文件方式, 会以 username 作为 key 在配置文件中加载连接协议等配置
CREATE TABLESPACE <tablespace_name> LOCATION 'hive://user=username&database=databasename';
CREATE SCHEMA <schema_name> TABLESPACE <tablespace_name>;
```
其中 hive.metastore.uri 即为 HMS 的 Thrfit 服务地址，databasename 为 Hive 中需要映射的数据库名称。

### 使用 Hive Schema

Hive Schema 与 OushuDB 的其他 Schema 行为一致，用户可以通过 fully qualified name 来访问 Hive 的表，也可以将 Hive Schema 添加到 search_path 后以 unqualified name 访问。

### 跨 Hive 数据库查询

OushuDB 支持跨 Hive Database 的联合查询。
用户可以将多个 Hive Database 映射成 OushuDB Tablespace 后使用。


### 以 Kerberos 方式访问

OushuDB 通过配置文件 hdfs-client.xml 来统一管理所有访问外部服务所需要的 Kerberos 配置。用户需要在此文件中以 hive.metastore.uri 为服务地址配置 keytab、principal等相关信息。

### hdfs-client.xml 配置
```xml
<property>
    <name><username>.hms.hive.security.authentication</name>
    <value>kerberos</value>
    <description>username 为创建 tablespace 时指定的，该配置项指定通过 hms 连接带有 kerberos 配置的 hive</description>
<property>
<property>
    <name><username>.hms.hive.security.keytab</name>
    <value></value>
    <description>hms keytab 文件路径</description>
</property>
<property>
    <name><username>.hms.hive.security.principal</name>
    <value></value>
    <description>hms principal 名称</description>
</property>
<property>
    <name><username>.hms.hive.connection.url</name>
    <value></value>
    <description>hms 连接地址，可配置多个，通过逗号分割 ip:port,ip:port</description>
</property>


<property>
    <name><username>.hs2.hive.security.authentication</name>
    <value>kerberos</value>
    <description>username 为创建 tablespace 时指定的，该配置项指定通过 hs2 连接带有 kerberos 配置的 hive</description>
<property>
<property>
    <name><username>.hs2.hive.security.keytab</name>
    <value></value>
    <description>hs2 keytab 文件路径</description>
</property>
<property>
    <name><username>.hs2.hive.security.principal</name>
    <value></value>
    <description>hs2 principal 名称</description>
</property>
<property>
    <name><username>.hs2.hive.connection.url</name>
    <value></value>
    <description>hs2 连接地址，可配置多个，通过逗号分割 ip:port,ip:port</description>
</property>
```

### 示例

假设 HMS 的 Thrfit 服务地址为 localhost:9083，我们通过 OushuDB 查询 Hive 的 dbtest 数据库中名为 t 的表：
```sql
    CREATE TABLESPACE hfs LOCATION 'hive://localhost:9083&database=dbtest';
    CREATE SCHEMA hs TABLESPACE hts;
    SELECT * from hs.t;
```
###注意事项

* OushuDB 仅支持访问 Hive 的 ORC、 PARQUET、TEXT 和 CSV 表格式。
* OushuDB 不支持访问事务表、ACID 表。
* OushuDB 仅支持标量的基本数据类型：smallint, int, bigint, boolean, float, double, string, binary, timestamp, decimal, date, varchar, char。
* OushuDB 无法保证自身事务与 Hive 事务的并发。
* OushuDB 仅支持读操作。
* 仅 OushuDB 提供的 psql 可以通过 description 函数来获取 Hive 表的信息。
* OushuDB 以数据库软件安装用户身份访问 hive 的 HDFS 文件，需要对数据库软件安装用户进行授权。
* 访问开启 Kerberos 的 HMS 服务需要提供三段的 Service Principal 而不是两段的 User Principal。此两种 Principal 是独立的，不能相互替代。通常 Service Principal 中第二段的 instance 在 hive-site.xml 为 _HOST 需要手工替换为目标 HMS 服务的域名。此域名可以通过 host 命令获得。