diff --git a/docs/UserGuide/Ecosystem Integration/Zeppelin-IoTDB.md b/docs/UserGuide/Ecosystem Integration/Zeppelin-IoTDB.md new file mode 100644 index 000000000000..fc8edf574065 --- /dev/null +++ b/docs/UserGuide/Ecosystem Integration/Zeppelin-IoTDB.md @@ -0,0 +1,184 @@ + + +# 1. Outline + +- What's Zeppelin + +- IoTDB Zeppelin-Interpreter + - System Requirements + - Build Interpreter + - Install Interpreter + - Running Zeppelin and IoTDB +- Use Zeppelin-IoTDB +- Configuration + + + +# 2. What's Zeppelin + +Zeppelin is a web-based notebook that enables interactive data analytics. You can connect to data sources and perform interactive operations with SQL, Scala, etc. The operations can be saved as documents, just like Jupyter. Zeppelin has already supported many data sources, including Spark, ElasticSearch, Cassandra, and InfluxDB. Now, we have enabled Zeppelin to operate IoTDB via SQL. + +![iotdb-note-snapshot](https://user-images.githubusercontent.com/5548915/102752947-520a3e80-43a5-11eb-8fb1-8fac471c8c7e.png) + + + +# 3. Zeppelin-IoTDB Interpreter + +## System Requirements + +| IoTDB Version | Java Version | Zeppelin Version | +| :-----------: | :-----------: | :--------------: | +| >=`0.12.0-SNAPSHOT` | >=`1.8.0_271` | `>=0.9.0` | + +You can install IoTDB according to [IoTDB Quick Start](https://iotdb.apache.org/UserGuide/Master/Get%20Started/QuickStart.html). Suppose IoTDB is placed at `$IoTDB_HOME`. + +You can download [Zeppelin](https://zeppelin.apache.org/download.html#) and unpack the binary package directly or [build Zeppelin from source](https://zeppelin.apache.org/docs/latest/setup/basics/how_to_build.html). Suppose Zeppelin is placed at `$Zeppelin_HOME`. + + + +## 3.2 Build Interpreter + +``` + cd $IoTDB_HOME + mvn clean package -pl zeppelin-interpreter -am -DskipTests +``` + +The interpreter will be in the folder: + +``` + $IoTDB_HOME/zeppelin-interpreter/target/zeppelin-{version}-SNAPSHOT-jar-with-dependencies.jar +``` + + + +## 3.3 Install Interpreter + +Once you have built your interpreter, create a new folder under the Zeppelin interpreter directory and put the built interpreter into it. + +``` + cd $IoTDB_HOME + mkdir -p $Zeppelin_HOME/interpreter/iotdb + cp $IoTDB_HOME/zeppelin-interpreter/target/zeppelin-{version}-SNAPSHOT-jar-with-dependencies.jar $Zeppelin_HOME/interpreter/iotdb +``` + + + +## 3.4 Running Zeppelin and IoTDB + +Go to `$Zeppelin_HOME` and start Zeppelin by running: + +``` + ./bin/zeppelin-daemon.sh start +``` + +or in Windows: + +``` + .\bin\zeppelin.cmd +``` + +Go to `$IoTDB_HOME` and [start IoTDB server](https://github.com/apache/iotdb#start-iotdb): + +``` + # Unix/OS X + > nohup sbin/start-server.sh >/dev/null 2>&1 & + or + > nohup sbin/start-server.sh -c -rpc_port >/dev/null 2>&1 & + + # Windows + > sbin\start-server.bat -c -rpc_port +``` + + + +# 4. Use Zeppelin-IoTDB + +Wait for Zeppelin server to start, then visit http://127.0.0.1:8080/ + +In the interpreter page: + +1. Click the `Create new node` button +2. Set the note name +3. Configure your interpreter + +Now you are ready to use your interpreter. + +![iotdb-create-note](https://user-images.githubusercontent.com/5548915/102752945-5171a800-43a5-11eb-8614-53b3276a3ce2.png) + +We provide some simple SQL to show the use of Zeppelin-IoTDB interpreter: + +```sql + SET STORAGE GROUP TO root.ln.wf01.wt01; + CREATE TIMESERIES root.ln.wf01.wt01.status WITH DATATYPE=BOOLEAN, ENCODING=PLAIN; + CREATE TIMESERIES root.ln.wf01.wt01.temperature WITH DATATYPE=FLOAT, ENCODING=PLAIN; + CREATE TIMESERIES root.ln.wf01.wt01.hardware WITH DATATYPE=INT32, ENCODING=PLAIN; + + INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) + VALUES (1, 1.1, false, 11); + + INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) + VALUES (2, 2.2, true, 22); + + INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) + VALUES (3, 3.3, false, 33); + + INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) + VALUES (4, 4.4, false, 44); + + INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) + VALUES (5, 5.5, false, 55); + + + SELECT * + FROM root.ln.wf01.wt01 + WHERE time >= 1 + AND time <= 6; +``` + +The screenshot is as follows: + +![iotdb-note-snapshot2](https://user-images.githubusercontent.com/5548915/102752948-52a2d500-43a5-11eb-9156-0c55667eb4cd.png) + +You can also design more fantasy documents referring to [[1]](https://zeppelin.apache.org/docs/0.9.0-SNAPSHOT/usage/display_system/basic.html) and others. + +The above demo notebook can be found at `$IoTDB_HOME/zeppelin-interpreter/Zeppelin-IoTDB-Demo.zpln`. + + + +# 5. Configuration + +You can configure the connection parameters in http://127.0.0.1:8080/#/interpreter : + +![iotdb-configuration](https://user-images.githubusercontent.com/5548915/102752940-50407b00-43a5-11eb-94fb-3e3be222183c.png) + +The parameters you can configure are as follows: + +| Property | Default | Description | +| ---------------------------- | --------- | ------------------------------- | +| iotdb.host | 127.0.0.1 | IoTDB server host to connect to | +| iotdb.port | 6667 | IoTDB server port to connect to | +| iotdb.username | root | Username for authentication | +| iotdb.password | root | Password for authentication | +| iotdb.fetchSize | 10000 | Query fetch size | +| iotdb.zoneId | | Zone Id | +| iotdb.enable.rpc.compression | FALSE | Whether enable rpc compression | +| iotdb.time.display.type | default | The time format to display | diff --git a/docs/zh/UserGuide/Ecosystem Integration/Zeppelin-IoTDB.md b/docs/zh/UserGuide/Ecosystem Integration/Zeppelin-IoTDB.md new file mode 100644 index 000000000000..65e5ecd59e01 --- /dev/null +++ b/docs/zh/UserGuide/Ecosystem Integration/Zeppelin-IoTDB.md @@ -0,0 +1,186 @@ + + +# 概要 + +* Zeppelin简介 +* IoTDB Zeppelin 解释器 + * 系统环境要求 + * 编译解释器 + * 安装解释器 + * 启动Zeppelin和IoTDB +* 使用Zeppelin-IoTDB解释器 +* 解释器配置项 + + + +# 2. Zeppelin简介 + +Apache Zeppelin 是一个基于网页的交互式数据分析系统。用户可以通过Zeppelin连接数据源并使用SQL、Scala等进行交互式操作。操作可以保存为文档（类似于Jupyter）。Zeppelin支持多种数据源，包括Spark、ElasticSearch、Cassandra和InfluxDB等等。现在，IoTDB已经支持使用Zeppelin进行操作。样例如下： + +![iotdb-note-snapshot](https://user-images.githubusercontent.com/5548915/102752947-520a3e80-43a5-11eb-8fb1-8fac471c8c7e.png) + + + +# 3. Zeppelin-IoTDB解释器 + +## 系统环境需求 + +| IoTDB 版本 | Java 版本 | Zeppelin 版本 | +| :--------: | :-----------: | :-----------: | +| >=`0.12.0-SNAPSHOT` | >=`1.8.0_271` | `>=0.9.0` | + +> 用户需要首先安装IoTDB：[IoTDB Quick Start](https://iotdb.apache.org/UserGuide/Master/Get%20Started/QuickStart.html). 假设 IoTDB 安装在 `$IoTDB_HOME`. +> +> 用户可以下载 [Zeppelin](https://zeppelin.apache.org/download.html#) 并解压二进制文件，或 [从源码构建Zeppelin](https://zeppelin.apache.org/docs/latest/setup/basics/how_to_build.html). 假设 Zeppelin 安装在 `$Zeppelin_HOME`. + + + +## 3.2 编译解释器 + +运行如下命令编译IoTDB Zeppelin解释器。 + +```shell +cd $IoTDB_HOME +mvn clean package -pl zeppelin-interpreter -am -DskipTests +``` + +编译后的解释器位于如下目录： + +```shell +$IoTDB_HOME/zeppelin-interpreter/target/zeppelin-{version}-SNAPSHOT-jar-with-dependencies.jar +``` + + + +## 3.3 安装解释器 + +当你编译好了解释器，在Zeppelin的解释器目录下创建一个新的文件夹`iotdb`，并将IoTDB解释器放入其中。 + +```shell +cd $IoTDB_HOME +mkdir -p $Zeppelin_HOME/interpreter/iotdb +cp $IoTDB_HOME/zeppelin-interpreter/target/zeppelin-{version}-SNAPSHOT-jar-with-dependencies.jar $Zeppelin_HOME/interpreter/iotdb +``` + + + +## 3.4 启动 Zeppelin 和 IoTDB + +进入 `$Zeppelin_HOME` 并运行Zeppelin： + +```shell +# Unix/OS X +> ./bin/zeppelin-daemon.sh start + +# Windows +> .\bin\zeppelin.cmd +``` + + + +进入 `$IoTDB_HOME` 并运行IoTDB： + +```shell +# Unix/OS X +> nohup sbin/start-server.sh >/dev/null 2>&1 & +or +> nohup sbin/start-server.sh -c -rpc_port >/dev/null 2>&1 & + +# Windows +> sbin\start-server.bat -c -rpc_port +``` + + + +# 4. 使用 Zeppelin-IoTDB解释器 + +当Zeppelin启动后，访问 [http://127.0.0.1:8080/](http://127.0.0.1:8080/) + +通过如下步骤创建一个新的笔记本页面: + +1. 点击 `Create new node` 按钮 +2. 设置笔记本名 +3. 选择解释器为iotdb + +现在可以开始使用Zeppelin操作IoTDB了。 + +![iotdb-create-note](https://user-images.githubusercontent.com/5548915/102752945-5171a800-43a5-11eb-8614-53b3276a3ce2.png) + +我们提供了一些简单的SQL来展示Zeppelin-IoTDB解释器的使用： + +```sql +SET STORAGE GROUP TO root.ln.wf01.wt01; +CREATE TIMESERIES root.ln.wf01.wt01.status WITH DATATYPE=BOOLEAN, ENCODING=PLAIN; +CREATE TIMESERIES root.ln.wf01.wt01.temperature WITH DATATYPE=FLOAT, ENCODING=PLAIN; +CREATE TIMESERIES root.ln.wf01.wt01.hardware WITH DATATYPE=INT32, ENCODING=PLAIN; + +INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) +VALUES (1, 1.1, false, 11); + +INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) +VALUES (2, 2.2, true, 22); + +INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) +VALUES (3, 3.3, false, 33); + +INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) +VALUES (4, 4.4, false, 44); + +INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) +VALUES (5, 5.5, false, 55); + + +SELECT * +FROM root.ln.wf01.wt01 +WHERE time >= 1 + AND time <= 6; +``` + +样例如下： + +![iotdb-note-snapshot2](https://user-images.githubusercontent.com/5548915/102752948-52a2d500-43a5-11eb-9156-0c55667eb4cd.png) + +用户也可以参考 [[1]](https://zeppelin.apache.org/docs/0.9.0-SNAPSHOT/usage/display_system/basic.html) 编写更丰富多彩的文档。 + +以上样例放置于 `$IoTDB_HOME/zeppelin-interpreter/Zeppelin-IoTDB-Demo.zpln` + + + +# 5. 解释器配置项 + +进入页面 [http://127.0.0.1:8080/#/interpreter](http://127.0.0.1:8080/#/interpreter) 并配置IoTDB的连接参数： + +![iotdb-configuration](https://user-images.githubusercontent.com/5548915/102752940-50407b00-43a5-11eb-94fb-3e3be222183c.png) + +可配置参数默认值和解释如下： + +| 属性 | 默认值 | 描述 | +| ---------------------------- | --------- | -------------------------------- | +| iotdb.host | 127.0.0.1 | IoTDB 主机名 | +| iotdb.port | 6667 | IoTDB 端口 | +| iotdb.username | root | 用户名 | +| iotdb.password | root | 密码 | +| iotdb.fetchSize | 10000 | 查询结果分批次返回时，每一批数量 | +| iotdb.zoneId | | 时区ID | +| iotdb.enable.rpc.compression | FALSE | 是否允许rpc压缩 | +| iotdb.time.display.type | default | 时间戳的展示格式 | + diff --git a/zeppelin-interpreter/README.md b/zeppelin-interpreter/README.md deleted file mode 100644 index 5df4d549094d..000000000000 --- a/zeppelin-interpreter/README.md +++ /dev/null @@ -1,186 +0,0 @@ - - - - -# What's Zeppelin - -Zeppelin is a web-based notebook that enables interactive data analytics. You can connect to data sources and perform interactive operations with SQL, Scala, etc. The operations can be saved as documents, just like Jupyter. Zeppelin has already supported many data sources, including Spark, ElasticSearch, Cassandra, and InfluxDB. Now, we have enabled Zeppelin to operate IoTDB via SQL. - -![image-20201124145203621](https://tva1.sinaimg.cn/large/0081Kckwly1gl09mzzfhzj314q0q70xo.jpg) - - - -# IoTDB zeppelin-interpreter - -## Environment - -To use IoTDB and Zeppelin, you need to have: - -1. Java >= 1.8.0_271 (Please make sure the environment path has been set. You can run `java -version` to confirm the current Java version. -2. IoTDB >= 0.11.0-SNAPSHOT. -3. Zeppelin >= 0.8.2 - -You can install IoTDB according to [IoTDB Quick Start](http://iotdb.apache.org/UserGuide/V0.10.x/Get%20Started/QuickStart.html). IoTDB is placed at `$IoTDB_HOME`. - -You can download [Zeppelin](https://zeppelin.apache.org/download.html#) and unpack the binary package directly or [build Zeppelin from source](https://zeppelin.apache.org/docs/latest/setup/basics/how_to_build.html). Zeppelin is placed at `$Zeppelin_HOME`. - - - -## Build interpreter - -```shell -cd $IoTDB_HOME -mvn clean package -pl zeppelin-interpreter -am -DskipTests -``` - -The interpreter will be in the folder: - -```shell -$IoTDB_HOME/zeppelin-interpreter/target/zeppelin-{version}-SNAPSHOT.jar -``` - - - -## Install interpreter - -Once you have built your interpreter, create a new folder under the Zeppelin interpreter directory and put the built interpreter into it. - -```shell -cd $IoTDB_HOME -mkdir -p $Zeppelin_HOME/interpreter/iotdb -cp $IoTDB_HOME/zeppelin-interpreter/target/zeppelin-{version}-SNAPSHOT.jar $Zeppelin_HOME/interpreter/iotdb -``` - - - -## Configure your interpreter - -To configure your interpreter you need to follow these steps: - -1. If it's the first start, create `conf/zeppelin-site.xml` by copying `conf/zeppelin-site.xml.template` to `conf/zeppelin-site.xml`. - -2. Append your interpreter class name to `zeppelin.interpreters` property in `conf/zeppelin-site.xml`. If the property `zeppelin.interpreters` doesn't exist yet, add it directly. - - ```xml - - ... - - zeppelin.interpreters - org.apache.iotdb.zeppelin.IoTDBInterpreter - - ... - - ``` - -## Running Zeppelin and IoTDB - -Go to `$Zeppelin_HOME` and start Zeppelin by running: - -```shell -./bin/zeppelin-daemon.sh start -``` - -or in Windows: -```shell -./bin/zeppelin.cmd -``` - -Go to `$IoTDB_HOME` and [start IoTDB server](https://github.com/apache/iotdb#start-iotdb): - -```shell -# Unix/OS X -> nohup sbin/start-server.sh >/dev/null 2>&1 & -or -> nohup sbin/start-server.sh -c -rpc_port >/dev/null 2>&1 & - -# Windows -> sbin\start-server.bat -c -rpc_port -``` - -## Zeppelin to IoTDB - -Wait for Zeppelin server to start, then visit http://localhost:8080/ - -In the interpreter page: - -1. Click the `Create new node` button -2. Set the note name -3. Configure your interpreter - -Now you are ready to use your interpreter. - -![image-20201123112330976](https://tva1.sinaimg.cn/large/0081Kckwly1gl09n7cpibj30sz0opagn.jpg) - - - -# Use IoTDB-Zeppelin - -We provide some simple SQL to show the use of Zeppelin-IoTDB-interpreter: - -```sql -SET STORAGE GROUP TO root.ln.wf01.wt01; -CREATE TIMESERIES root.ln.wf01.wt01.status WITH DATATYPE=BOOLEAN, ENCODING=PLAIN; -CREATE TIMESERIES root.ln.wf01.wt01.temperature WITH DATATYPE=FLOAT, ENCODING=PLAIN; -CREATE TIMESERIES root.ln.wf01.wt01.hardware WITH DATATYPE=INT32, ENCODING=PLAIN; - -INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) -VALUES (1, 1.1, false, 11); - -INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) -VALUES (2, 2.2, true, 22); - -INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) -VALUES (3, 3.3, false, 33); - -INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) -VALUES (4, 4.4, false, 44); - -INSERT INTO root.ln.wf01.wt01 (timestamp, temperature, status, hardware) -VALUES (5, 5.5, false, 55); - - -SELECT * -FROM root.ln.wf01.wt01 -WHERE time >= 1 - AND time <= 6; -``` - -The screenshot is as follows: - -![image-20201124142635276](https://tva1.sinaimg.cn/large/0081Kckwly1gl09nd3vimj30pj0nz0w3.jpg) - -You can also design more fantasy documents referring to [[1]](https://zeppelin.apache.org/docs/0.9.0-SNAPSHOT/usage/display_system/basic.html) and others. - -The above demo notebook can be found at `./IoTDB-Zeppelin-Demo.zpln`. - - - -# IoTDB-Zeppelin Configuration - -You can configure the connection parameters in [http://localhost:8080/#/interpreter](http://localhost:8080/#/interpreter) : - -![image-20201212141528183](https://tva1.sinaimg.cn/large/0081Kckwly1gll1pgn3k9j31kx0u045o.jpg) - - - - - diff --git a/zeppelin-interpreter/pom.xml b/zeppelin-interpreter/pom.xml index 60704695402c..222a95e13e37 100644 --- a/zeppelin-interpreter/pom.xml +++ b/zeppelin-interpreter/pom.xml @@ -110,16 +110,32 @@ - maven-enforcer-plugin + maven-compiler-plugin + 3.3 + + 1.8 + 1.8 + - maven-dependency-plugin - - - maven-resources-plugin - - - maven-shade-plugin + maven-assembly-plugin + ${maven.assembly.version} + + + jar-with-dependencies + + + + + make-assembly + + package + + + single + + +