

English|中文

Tutorials

包含启动项目和运行范例的流程引导

Setup on Linux\MacOS

在Linux\MacOS上 运行 Quicksql 非常简单，但需要确保环境预置完整，依赖的环境有：

· Java >= 1.8

· Spark >= 2.2 (必选，未来作为可选)

· Flink >= 1.9 (可选)

1. 下载并解压二进制安装包，下载地址：https://github.com/Qihoo360/Quicksql/releases；
2. 进入 conf 目录，在 quicksql-env.sh 中配置环境变量；

$ tar -zxvf ./quicksql-release-bin.tar.gz
$ cd quicksql-realease-0.7.0
$ vim ./conf/quicksql-env.sh #Set Your Basic Environment.

运行样例查询

进入 bin 目录，执行 quicksql-example 脚本。（这里使用了内嵌 Elasticsearch Server 与 Csv 数据源作一个关联过滤）

$ ./bin/quicksql-example com.qihoo.qsql.CsvJoinWithEsExample #换成选项型，并能打印 SQL 语句

如果能够显示以下结果，说明环境构建完毕，可以尝试新的操作。

+------+-------+----------+--------+------+-------+------+
|deptno|   name|      city|province|digest|   type|stu_id|
+------+-------+----------+--------+------+-------+------+
|    40|Scholar|  BROCKTON|      MA| 59498|Scholar|  null|
|    45| Master|   CONCORD|      NH| 34035| Master|  null|
|    40|Scholar|FRAMINGHAM|      MA| 65046|Scholar|  null|
+------+-------+----------+--------+------+-------+------+

运行真实查询

在 Quicksql 上运行查询前需要将连接信息以及表、字段信息采集入库。

默认元数据库使用 Sqlite，切换元数据库的方式参考部署指南，Sqlite 可以使用以下方式访问：

$ cd ./metastore/linux-x86/
$ sqlite3 ../schema.db
SQLite version 3.6.20
Enter ".help" for instructions
Enter SQL statements terminated with a ";"
sqlite> .tables
COLUMNS    DATABASE_PARAMS    DBS    TBLS  
sqlite> SELECT TBLS.DB_ID, TBL_NAME, NAME  FROM TBLS INNER JOIN DBS ON TBLS.DB_ID = DBS.DB_ID;
+------+---------------+-----------+
| DB_ID|       TBL_NAME|    DB_NAME|
+------+---------------+-----------+
|     1|    call_center|   BROCKTON|
|     2|   catalog_page|    CONCORD|
|     3|  catalog_sales| FRAMINGHAM|
+------+---------------+-----------+

当然，我们并不需要手工去插入元数据！

Quicksql 提供了众多标准数据源的采集脚本，通过脚本批量拉取元数据。

目前支持通过脚本录入元数据的数据源有Hive, MySQL, Kylin, Elasticsearch, Oracle, MongoDB。

执行方式如下（注意：-r 参数可以使用LIKE语法，['%': 全部匹配，'_': 占位匹配，'?': 可选匹配]）

$ ./bin/metadata-extract -p "<SCHEMA-JSON>" -d "<DATA-SOURCE>" -r "<TABLE-NAME-REGEX>"

（详细的SCHEMA-JSON格式参考页末）

使用示例

从MySQL 数据库中采集元数据

$ ./meta-extract -p "{\"jdbcDriver\": \"com.mysql.jdbc.Driver\", \"jdbcUrl\": \"jdbc:mysql://localhost:3306/db\", \"jdbcUser\": \"user\",\"jdbcPassword\": \"pass\"}" -d "mysql" -r "my_table"

从Elasticsearch 存储中采集元数据

$ ./meta-extract -p "{\"esNodes\": \"192.168.1.1\",\"esPort\": \"9090\",\"esUser\": \"user\",\"esPass\": \"pass\",\"esIndex\": \"index/type\"}" -d "es" -r "%"

采集成功后将返回

1970-01-01 15:09:43,119 [main] INFO  - Connecting server.....
1970-01-01 15:09:44,000 [main] INFO  - Connected successfully!!
1970-01-01 15:09:44,121 [main] INFO  - Successfully collected metadata for 2 tables!!
1970-01-01 15:09:45,622 [main] INFO  - [my_table, my_type]!!

连接信息

常见数据源采集的 JSON 结构如下

##MySQL
{
    "jdbcDriver": "com.mysql.jdbc.Driver",
    "jdbcUrl": "jdbc:mysql://localhost:3306/db",
    "jdbcUser": "USER",
    "jdbcPassword": "PASSWORD"
}
##Oracle
{
    "jdbcDriver": "oracle.jdbc.driver.OracleDriver",
    "jdbcUrl": "jdbc:oracle:thin:@localhost:1521/namespace",
    "jdbcUser": "USER",
    "jdbcPassword": "PASSWORD" 
}
##Elasticsearch
{
    "esNodes": "192.168.1.1",
    "esPort": "9000",
    "esUser": "USER",
    "esPass": "PASSWORD",
    "esIndex": "index/type"
}
##Hive(Hive元数据存在MySQL中)
{
    "jdbcDriver": "com.mysql.jdbc.Driver",
    "jdbcUrl": "jdbc:mysql://localhost:3306/db",
    "jdbcUser": "USER",
    "jdbcPassword": "PASSWORD",
    "dbName": "hive_db"
}
##Hive-Jdbc(Hive元数据通过Jdbc访问 )
{
    "jdbcDriver": "org.apache.hive.jdbc.HiveDriver",
    "jdbcUrl": "jdbc:hive2://localhost:7070/learn_kylin",
    "jdbcUser": "USER",
    "jdbcPassword": "PASSWORD",
    "dbName": "default"
}
##Kylin
{
    "jdbcDriver": "org.apache.kylin.jdbc.Driver",
    "jdbcUrl": "jdbc:kylin://localhost:7070/learn_kylin",
    "jdbcUser": "ADMIN",
    "jdbcPassword": "KYLIN",
    "dbName": "default"
}

注意：Shell 中双引号是特殊字符，传 JSON 参数时需要做转义！！

从命令行提交查询

从命令行查询是 Quicksql 提供的最基本的查询方式之一。

像 Hive 和 MySQL 一样，使用quicksql.sh -e "YOUR SQL"就可以完成查询，结果集将打印在终端上。

使用示例

1. 一个简单的查询，将在 Quicksql 内核中被执行；

$ ./bin/quicksql.sh -e "SELECT 1"

想让它跑在 Spark 或 Flink 计算引擎上？可以使用 runner 参数；

$ ./bin/quicksql.sh -e "SELECT 1" --runner spark|flink

1. 一个 Elasticsearch 数据源查询，将由 Quicksql 建立 RestClient 连接执行；

$ ./bin/quicksql.sh -e "SELECT approx_count_distinct(city), state FROM geo_mapping GROUP BY state LIMIT 10"

想让计算结果落地到存储？可以尝试 INSERT INTO 语法：

$ ./bin/quicksql.sh -e  "INSERT INTO \`hdfs://cluster:9000/hello/world\` IN HDFS SELECT approx_count_distinct(city), state FROM geo_mapping GROUP BY state LIMIT 10"

其他参数

以上实例提供了基本的查询方式，如果对计算引擎需要指定其他参数可以参考下表：

Property Name	Default	Meaning
-e	--	配置查询的SQL语句，查询时必填。
-h|--help	--	命令参数的详细描述
--runner	dynamic	设置执行器类型,包括 dynamic, jdbc, spark, flink
--master	yarn-client	设置引擎执行模式
--worker_memory	1G	执行器的内存大小配置
--driver_memory	3G	控制器的内存大小配置
--worker_num	20	执行器的并行度

注意：

​ (1) 在 quicksql-env.sh 中可以设置 runner、master、worker_memory 等参数的默认值；

​ (2) 在非分布式执行中，即使设置了 master、worker_memory 等参数也不会生效；

从应用提交查询

Quicksql 支持使用 Client/Server 模式的 JDBC 连接进行查询，用户的应用可以通过引入 Driver 包与 Server 建立连接进行联邦查询。

Server 端

启动 Server

$ ./bin/quicksql-server.sh start -P 5888 -R spark -M yarn-client

启动参数包括 start|stop|restart|status，-P/-R/-M 为可选项，分别对应端口号，执行引擎和任务调度方式，

-P：指定 server 端口号，默认为 5888

-R：指定执行引擎，支持 Spark/Flink

-M：指定 spark 任务资源调度方式，yarn-client 或 yarn-cluster 等，默认为 local[1]

Client 端

应用接入

项目 pom 文件引入 quicksql-client 和 avatica 依赖包

<dependency>
    <groupId>com.qihoo.qsql</groupId>
    <artifactId>qsql</artifactId>
    <version>0.6</version>
</dependency>
<dependency>
    <groupId>org.apache.calcite.avatica</groupId>
    <artifactId>avatica-server</artifactId>
    <version>1.12.0</version>
</dependency>

Java代码示例：

 public static void main(String[] args) throws SQLException, ClassNotFoundException {
        Class.forName("com.qihoo.qsql.client.Driver"); //注入Drvier

        Properties properties = new Properties();
        properties.setProperty("runner","jdbc");
        String url = "jdbc:quicksql:url=http://localhost:5888";
        Connection connection = DriverManager.getConnection(url,properties);
        Statement pS = connection.createStatement();
        String sql = "select * from (values ('a', 1), ('b', 2))";
        ResultSet rs =  pS.executeQuery(sql);
        while (rs.next()) {
            System.out.println(rs.getString(1));
            System.out.println(rs.getString(2));
        }
        rs.close();
        pS.close();
}

1. 注入 quicksql Driver ：com.qihoo.qsql.client.Driver

2. properties 配置项包含参数

​ runner：指定执行引擎， 包括 dynamic, jdbc, spark, flink

​ acceptedResultsNum ： 执行查询返回数据的最大条数

​ appName：启动的 spark/flink 实例名

1. 连接 server 的 url : jdbc:quicksql:url=http:// + server 服务器域名或 ip 地址 + server 启动端口号（在 server 的日志文件 里有url信息）

2. 其他操作与普通 jdbc 查询相同，包括 Connection， Statement，ResultSet，ResultSetMetaData 等类的操作，以及结果的遍历。

---

Last update: January 14, 2020