Quick Start

Outline

  • Quick Start
  • Prerequisites
    • Installation
      • Installation from source code
    • Configure
    • Start
      • Start Server
      • Start Client
      • Have a try
      • Stop Server

This short guide will walk you through the basic process of using IoTDB. For a more-complete guide, please visit our website’s documents.

Prerequisites

To use IoTDB, you need to have:

  1. Java >= 1.8 (Please make sure the environment path has been set)
  2. Maven >= 3.0 (If you want to compile and install IoTDB from source code)

Installation

IoTDB provides you two installation methods, you can refer to the following suggestions, choose one of them:

  • Installation from source code. If you need to modify the code yourself, you can use this method.
  • Installation from binary files. Download the binary files from the official website. This is the recommended method, in which you will get a binary released package which is out-of-the-box.(Comming Soon…)

Here in the Quick Start, we give a brief introduction of using source code to install IoTDB. For further information, please refer to Chapter 4 of the User Guide.

Installation from source code

You can get the released source code from https://iotdb.apache.org/Download/, or from the git repository https://github.com/apache/incubator-iotdb/tree/master

Now suppose your directory is like this:

  1. > pwd
  2. /workspace/incubator-iotdb
  4. > ls -l
  5. incubator-iotdb/     <-- root path
  6. |
  7. +- server/
  8. |
  9. +- jdbc/
  10. |
  11. +- client/
  12. |
  13. ...
  14. |
  15. +- pom.xml

Let $IOTDB_HOME = /workspace/incubator-iotdb/server/target/iotdb-server-{project.version}

Let $IOTDB_CLI_HOME = /workspace/incubator-iotdb/client/target/iotdb-client-{project.version}

Note:

  • if IOTDB_HOME is not explicitly assigned, then by default IOTDB_HOME is the direct parent directory of sbin/start-server.sh on Unix/OS X (or that of sbin\start-server.bat on Windows).

  • if IOTDB_CLI_HOME is not explicitly assigned, then by default IOTDB_CLI_HOME is the direct parent directory of sbin/start-client.sh on Unix/OS X (or that of sbin\start-client.bat on Windows).

If you are not the first time that building IoTDB, remember deleting the following files:

  1. > rm -rf $IOTDB_HOME/data/
  2. > rm -rf $IOTDB_HOME/lib/

Then under the root path of incubator-iotdb, you can build IoTDB using Maven:

  1. > pwd
  2. /workspace/incubator-iotdb
  4. # Unix/OS X
  5. > mvn clean package -pl server -am -Dmaven.test.skip=true
  7. # Windows
  8. > mvn clean package -pl server -am '-Dmaven.test.skip=true'

Note: If you are a Windows user, you should use quoting '-Dmaven.test.skip=true' in the following commands.

If successful, you will see the the following text in the terminal:

  1. [INFO] ------------------------------------------------------------------------
  2. [INFO] Reactor Summary:
  3. [INFO]
  4. [INFO] Apache IoTDB (incubating) Project Parent POM ....... SUCCESS [  6.405 s]
  5. [INFO] TsFile ............................................. SUCCESS [ 10.435 s]
  6. [INFO] Service-rpc ........................................ SUCCESS [  4.170 s]
  7. [INFO] IoTDB Jdbc ......................................... SUCCESS [  3.252 s]
  8. [INFO] IoTDB Server ....................................... SUCCESS [  8.072 s]
  9. [INFO] ------------------------------------------------------------------------
  10. [INFO] BUILD SUCCESS
  11. [INFO] ------------------------------------------------------------------------

Otherwise, you may need to check the error statements and fix the problems.

After building, the IoTDB project will be at the subfolder named iotdb. The folder will include the following contents:

  1. $IOTDB_HOME/
  2. |
  3. +- sbin/       <-- script files
  4. |
  5. +- conf/      <-- configuration files
  6. |
  7. +- lib/       <-- project dependencies

Configure

Before starting to use IoTDB, you need to config the configuration files first. For your convenience, we have already set the default config in the files.

In total, we provide users three kinds of configurations module:

  • environment config module (iotdb-env.sh(Linux or OSX), iotdb-env.bat(Windows))
  • system config module (tsfile-format.properties, iotdb-engine.properties)
  • log config module (logback.xml)

The configuration files of the three configuration items are located in the IoTDB installation directory: $IOTDB_HOME/conf folder. For more, you are advised to check Chapter 4 of the User Guide to give you the details.

Start

Start Server

After that we start the server. Running the startup script:

  1. # Unix/OS X
  2. > $IOTDB_HOME/sbin/start-server.sh
  4. # Windows
  5. > $IOTDB_HOME\sbin\start-server.bat

Start Client

Now let’s trying to read and write some data from IoTDB using our Client. To start the client, you need to explicit the server’s IP and PORT as well as the USER_NAME and PASSWORD.

  1. # You can first build cli project
  2. > pwd
  3. /workspace/incubator-iotdb
  5. > mvn clean package -pl client -am -Dmaven.test.skip=true
  7. # Unix/OS X
  8. > $IOTDB_CLI_HOME/sbin/start-client.sh -h <IP> -p <PORT> -u <USER_NAME>
  10. # Windows
  11. > $IOTDB_CLI_HOME\sbin\start-client.bat -h <IP> -p <PORT> -u <USER_NAME>

NOTE: In the system, we set a default user in IoTDB named ‘root’. The default password for ‘root’ is ‘root’. You can use this default user if you are making the first try or you didn’t create users by yourself.

The command line client is interactive so if everything is ready you should see the welcome logo and statements:

  1.  _____       _________  ______   ______
  2. |_   _|     |  _   _  ||_   _ `.|_   _ \
  3.   | |   .--.|_/ | | \_|  | | `. \ | |_) |
  4.   | | / .'`\ \  | |      | |  | | |  __'.
  5.  _| |_| \__. | _| |_    _| |_.' /_| |__) |
  6. |_____|'.__.' |_____|  |______.'|_______/  version x.x.x
  9. IoTDB> login successfully
  10. IoTDB>

Have a try

Now, you can use IoTDB SQL to operate IoTDB, and when you’ve had enough fun, you can input ‘quit’ or ‘exit’ command to leave the client.

But lets try something slightly more interesting:

  1. IoTDB> SET STORAGE GROUP TO root.ln
  2. execute successfully.
  3. IoTDB> CREATE TIMESERIES root.ln.wf01.wt01.status WITH DATATYPE=BOOLEAN, ENCODING=PLAIN
  4. execute successfully.

Till now, we have already create a table called root.vehicle and add a column called d0.s0 in the table. Let’s take a look at what we have done by ‘SHOW TIMESERIES’ command.

  1. IoTDB> SHOW TIMESERIES
  2. ===  Timeseries Tree  ===
  4. {
  5.     "root":{
  6.         "ln":{
  7.             "wf01":{
  8.                 "wt01":{
  9.                     "status":{
  10.                         "args":"{}",
  11.                         "StorageGroup":"root.ln",
  12.                         "DataType":"BOOLEAN",
  13.                         "Compressor":"UNCOMPRESSED",
  14.                         "Encoding":"PLAIN"
  15.                     }
  16.                 }
  17.             }
  18.         }
  19.     }
  20. }

For a further try, create a timeseries again and use SHOW TIMESERIES to check result.

  1. IoTDB> CREATE TIMESERIES root.ln.wf01.wt01.temperature WITH DATATYPE=FLOAT, ENCODING=RLE
  2. IoTDB> SHOW TIMESERIES
  3. ===  Timeseries Tree  ===
  5. {
  6.     "root":{
  7.         "ln":{
  8.             "wf01":{
  9.                 "wt01":{
  10.                     "temperature":{
  11.                         "args":"{}",
  12.                         "StorageGroup":"root.ln",
  13.                         "DataType":"FLOAT",
  14.                         "Compressor":"UNCOMPRESSED",
  15.                         "Encoding":"RLE"
  16.                     },
  17.                     "status":{
  18.                         "args":"{}",
  19.                         "StorageGroup":"root.ln",
  20.                         "DataType":"BOOLEAN",
  21.                         "Compressor":"UNCOMPRESSED",
  22.                         "Encoding":"PLAIN"
  23.                     }
  24.                 }
  25.             }
  26.         }
  27.     }
  28. }

Now, for your conveniect, SHOW TIMESERIES clause also supports extention syntax, the pattern is (for further details, check Chapter 5 of the User Guide):

  1. SHOW TIMESERIES <PATH>

Here is the example:

  1. IoTDB> SHOW TIMESERIES root.ln.wf01.wt01
  2. +------------------------------+--------------+--------+--------+
  3. |                    Timeseries| Storage Group|DataType|Encoding|
  4. +------------------------------+--------------+--------+--------+
  5. |      root.ln.wf01.wt01.status|       root.ln| BOOLEAN|   PLAIN|
  6. | root.ln.wf01.wt01.temperature|       root.ln|   FLOAT|     RLE|
  7. +------------------------------+--------------+--------+--------+
  8. Total timeseries number = 2
  9. Execute successfully.

We can also use SHOW STORAGE GROUP to check created storage group:

  1. IoTDB> show storage group
  2. +-----------------------------------+
  3. |                      Storage Group|
  4. +-----------------------------------+
  5. |                            root.ln|
  6. +-----------------------------------+
  7. Total storage group number = 1
  8. Execute successfully.
  9. It costs 0.006s

Insert timeseries data is the basic operation of IoTDB, you can use ‘INSERT’ command to finish this:

  1. IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status) values(100,true);
  2. execute successfully.
  3. IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status,temperature) values(200,false,20.71)
  4. execute successfully.

The data we’ve just inserted displays like this:

  1. IoTDB> SELECT status FROM root.ln.wf01.wt01
  2. +-----------------------+------------------------+
  3. |                   Time|root.ln.wf01.wt01.status|
  4. +-----------------------+------------------------+
  5. |1970-01-01T08:00:00.100|                    true|
  6. |1970-01-01T08:00:00.200|                   false|
  7. +-----------------------+------------------------+
  8. record number = 1
  9. execute successfully.

We can also query several timeseries data at once like this:

  1. IoTDB> SELECT * FROM root.ln.wf01.wt01
  2. +-----------------------+--------------------------+-----------------------------+
  3. |                   Time|  root.ln.wf01.wt01.status|root.ln.wf01.wt01.temperature|
  4. +-----------------------+--------------------------+-----------------------------+
  5. |1970-01-01T08:00:00.100|                      true|                         null|
  6. |1970-01-01T08:00:00.200|                     false|                        20.71|
  7. +-----------------------+--------------------------+-----------------------------+

If your session looks similar to what’s above, congrats, your IoTDB is operational!

For more on what commands are supported by IoTDB SQL, see Chapter 5 of the User Guide. It will give you help.

Stop Server

The server can be stopped with ctrl-C or the following script:

  1. # Unix/ OS X
  2. > $IOTDB_HOME/bin/stop-server.sh
  4. # Windows
  5. > $IOTDB_HOME\bin\stop-server.bat