This is an automated email from the ASF dual-hosted git repository. cdutz pushed a commit to branch chrisdutz-patch-1 in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
commit 4f637abd0927b329e9e417b09070538745f72a15 Author: Christofer Dutz <[email protected]> AuthorDate: Mon Aug 14 11:47:39 2023 +0200 Update QuickStart.md Updated the English translation a bit (And added some questions in comments prefixed with "TODO") --- src/UserGuide/V1.2.x/QuickStart/QuickStart.md | 122 ++++++++++++++++---------- 1 file changed, 77 insertions(+), 45 deletions(-) diff --git a/src/UserGuide/V1.2.x/QuickStart/QuickStart.md b/src/UserGuide/V1.2.x/QuickStart/QuickStart.md index 4d74ab7..c325e3a 100644 --- a/src/UserGuide/V1.2.x/QuickStart/QuickStart.md +++ b/src/UserGuide/V1.2.x/QuickStart/QuickStart.md @@ -21,47 +21,49 @@ # Quick Start -This short guide will walk you through the basic process of using IoTDB. For a more-complete guide, please visit our website's [User Guide](../IoTDB-Introduction/What-is-IoTDB.md). +This short guide will walk you through the basic process of using IoTDB. For a more comprehensive guide, please visit our website's [User Guide](../IoTDB-Introduction/What-is-IoTDB.md). ## Prerequisites To use IoTDB, you need to have: -1. Java >= 1.8 (Please make sure the environment path has been set) -2. Set the max open files num as 65535 to avoid "too many open files" problem. +1. Java >= 1.8 (Please make sure the environments PATH variable has been set to include the Java bin directory) +2. Set the max number of open files to at least 65535 in order to avoid "too many open files" problem. <!-- TODO: We should note how to actually do this --> ## Installation -IoTDB provides you three installation methods, you can refer to the following suggestions, choose one of them: +IoTDB can be installev using one of the following three installation methods: * 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. +* Installation from binary files. Download the binary distribution from the official website. This is the recommended method, in which you will get a binary released package which you can use out-of-the-box. <!-- TODO: From the Apache point of view the binary distributions are "convenience" ... actually the reccommended way would be to compile, as the ASF only formally distributes sources --> * Using Docker：The path to the dockerfile is [github](https://github.com/apache/iotdb/blob/master/docker/src/main) - ## Download -You can download the binary file from: +You can download the binary distribution from: [Download Page](https://iotdb.apache.org/Download/) ## Configurations -Configuration files are under "conf" folder +Configuration files are located in the `conf` folder * environment config module (`datanode-env.bat`, `datanode-env.sh`), * system config module (`iotdb-datanode.properties`) * log config module (`logback.xml`). -For more, see [Config](../Reference/DataNode-Config-Manual.md) in detail. +For more information, please go to [Config](../Reference/DataNode-Config-Manual.md). ## Start -You can go through the following step to test the installation, if there is no error after execution, the installation is completed. +You can go through the following step to test the installation. +If there is no error after execution, the installation is completed. + +### Starting IoTDB -### Start IoTDB -IoTDB is a database based on distributed system. To launch IoTDB, you can first start standalone mode (i.e. 1 ConfigNode and 1 DataNode) to check. +IoTDB is designed as distributed database. You can however start it in a single node `standalone mode`. +In order to test your configuration, you can first start everything in `standalone mode` (i.e. 1 ConfigNode and 1 DataNode) to check everything works as expected. -Users can start IoTDB standalone mode by the start-standalone script under the sbin folder. +Users can start IoTDB in standalone mode by using the `start-standalone` script under the `sbin` folder. ``` # Unix/OS X @@ -72,17 +74,23 @@ Users can start IoTDB standalone mode by the start-standalone script under the s > sbin\start-standalone.bat ``` -Note: Currently, To run standalone mode, you need to ensure that all addresses are set to 127.0.0.1, If you need to access the IoTDB from a machine different from the one where the IoTDB is located, please change the configuration item `dn_rpc_address` to the IP of the machine where the IoTDB lives. And replication factors set to 1, which is by now the default setting. -Besides, it's recommended to use SimpleConsensus in this mode, since it brings additional efficiency. -### Use Cli +Note: In order to run IoTDB in standalone mode, you need to ensure that all addresses are set to 127.0.0.1. +If you need to access the IoTDB from a different machine, please change the configuration item `dn_rpc_address` to the public IP of the machine where IoTDB is running and be sure to set `replication factors` to 1, which is currently the default setting. +It is recommended to use `SimpleConsensus` in this mode, as this has performance advantages in this mode of operation. + +### Using the Command Line Interfave (CLI) + +IoTDB offers several ways to interact with server, here we introduce basic steps of using the `CLI tool` to insert and query data. -IoTDB offers different ways to interact with server, here we introduce basic steps of using Cli tool to insert and query data. +After installing IoTDB, there is a pre-configured default user named `root`, its default password is also set to `root`. +Users can use this default credentials to login to IoTDB from the `CLI`. +Please use the `start-cli` scriopt in the `sbin` folder in order to start the `CLI`. -After installing IoTDB, there is a default user 'root', its default password is also 'root'. Users can use this -default user to login Cli to use IoTDB. The startup script of Cli is the start-cli script in the folder sbin. When executing the script, user should assign -IP, PORT, USER_NAME and PASSWORD. The default parameters are "-h 127.0.0.1 -p 6667 -u root -pw -root". +When executing the script, user should assign: `HOST/IP`, `PORT`, `USER_NAME` and `PASSWORD`. -Here is the command for starting the Cli: +The default parameters are `-h 127.0.0.1 -p 6667 -u root -pw root`. + +Here are the commands for starting the CLI: ``` # Unix/OS X @@ -92,7 +100,8 @@ Here is the command for starting the Cli: > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root ``` -The command line client is interactive so if everything is ready you should see the welcome logo and statements: +The command line interface is interactive. +If everything setup correctly, you should see the IoTDB logo and welcome statement: ``` _____ _________ ______ ______ @@ -109,15 +118,21 @@ IoTDB> ### Basic commands for IoTDB -Now, let us introduce the way of creating timeseries, inserting data and querying data. +Next, let us go a bit more into detail to how to create a timeseries, insert data into it and how to query data from it. + +Data in IoTDB is organized as a set of timeseries, in each timeseries there are some timestamp-data pairs. +Every timeseries is belongs to a database. + +All commands are executed in an SQL-like syntax we call `IoTDB SQL`. -The data in IoTDB is organized as timeseries, in each timeseries there are some data-time pairs, and every timeseries is owned by a database. Before defining a timeseries, we should define a database using create DATABASE, and here is an example: +Before defining a timeseries, we should define the database it should belong to using `CREATE DATABASE`. +Here's is an example on how to do that: ``` -IoTDB> create database root.ln +IoTDB> CREATE DATABASE root.ln ``` -We can also use SHOW DATABASES to check created databases: +We can also use `SHOW DATABASES` to list all databases present: ``` IoTDB> SHOW DATABASES @@ -129,14 +144,20 @@ IoTDB> SHOW DATABASES Database number = 1 ``` -After the database is set, we can use CREATE TIMESERIES to create new timeseries. When we create a timeseries, we should define its data type and the encoding scheme. We create two timeseries as follow: +After the database is created, we can use `CREATE TIMESERIES` to create new timeseries. +When we create a timeseries, we should define its structure as well as the data types used for each field as well as their encoding scheme. + +We can create two timeseries the following way: ``` IoTDB> CREATE TIMESERIES root.ln.wf01.wt01.status WITH DATATYPE=BOOLEAN, ENCODING=PLAIN IoTDB> CREATE TIMESERIES root.ln.wf01.wt01.temperature WITH DATATYPE=FLOAT, ENCODING=RLE ``` -To query the specific timeseries, use SHOW TIMESERIES \<Path\>. \<Path\> represents the path of the timeseries. Its default value is null, which means querying all the timeseries in the system(the same as using "SHOW TIMESERIES root"). Here are the examples: +To query a specific timeseries, use the `SHOW TIMESERIES \<Path\>` command. `\<Path\>` represents the path of the timeseries. +Its default value is null, which means that we're querying all timeseries in the system (the same as using `SHOW TIMESERIES root`). + +Here are some examples: 1. Query all timeseries in the system: @@ -151,7 +172,7 @@ IoTDB> SHOW TIMESERIES Total timeseries number = 2 ``` -2. Query a specific timeseries(root.ln.wf01.wt01.status): +2. Query a specific timeseries (root.ln.wf01.wt01.status): ``` IoTDB> SHOW TIMESERIES root.ln.wf01.wt01.status @@ -163,14 +184,19 @@ IoTDB> SHOW TIMESERIES root.ln.wf01.wt01.status Total timeseries number = 1 ``` -Insert timeseries data is the basic operation of IoTDB, you can use ‘INSERT’ command to finish this. Before insert you should assign the timestamp and the suffix path name: +Insertion of timeseries data is the probably most basic operation of IoTDB. +You can use the `INSERT` command to do this. + +Here come some examples on how to do that. +Please note that in the `INTO` part we tell IoTDB which timeseries to store the data in as well as which fields we'll be storing. +Also note that a timestamp field is mandatory for this step: ``` IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status) values(100,true); IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status,temperature) values(200,false,20.71) ``` -The data we’ve just inserted displays like this: +The data we’ve just inserted will then look like this if we query it: ``` IoTDB> SELECT status FROM root.ln.wf01.wt01 @@ -183,7 +209,7 @@ IoTDB> SELECT status FROM root.ln.wf01.wt01 Total line number = 2 ``` -We can also query several timeseries data at once like this: +We can also query several timeseries fields at once like this: ``` IoTDB> SELECT * FROM root.ln.wf01.wt01 @@ -196,7 +222,7 @@ IoTDB> SELECT * FROM root.ln.wf01.wt01 Total line number = 2 ``` -The commands to exit the Cli are: +The commands to exit the CLI are: ``` IoTDB> quit @@ -204,11 +230,11 @@ or IoTDB> exit ``` -For more on what commands are supported by IoTDB SQL, see [SQL Reference](../Reference/SQL-Reference.md). +For more information on which commands are supported by `IoTDB SQL`, please see [SQL Reference](../Reference/SQL-Reference.md). -### Stop IoTDB +### Stopping IoTDB -The server can be stopped with ctrl-C or the following script: +The server can be stopped using `ctrl-C` or by running the following script: ``` # Unix/OS X @@ -217,26 +243,32 @@ The server can be stopped with ctrl-C or the following script: # Windows > sbin\stop-standalone.bat ``` -Note: In Linux, please add the "sudo" as far as possible, or else the stopping process may fail. -More explanations are in Cluster/Cluster-setup.md. +Note: In Linux, please add the `sudo` as far as possible, or else the stopping process may fail. <!-- TODO: Actually running things as `root` is considered a bad practice from security perspective. Is there a reson for requiring root? I don't think we're using any privileged ports or resources. --> -### Administration management +More explanations on running IoTDB in a clustered environment are available at [Cluster-Setup](Cluster/Cluster-setup.md). -There is a default user in IoTDB after the initial installation: root, and the default password is root. This user is an administrator user, who cannot be deleted and has all the privileges. Neither can new privileges be granted to the root user nor can privileges owned by the root user be deleted. +### Administration -You can alter the password of root using the following command： +When installing IoTDB, there is a default user which is automatically pre-configured. +Its username is `root`, and the default password for it is also `root`. +This user is a user with administrative privileges, who cannot be deleted and has all privileges assigned to it. +Neither can new privileges be granted to the root user nor can privileges owned by it be revoked. + +We strongly reccomend you change the default password. +You do this using the following command： ``` ALTER USER <username> SET PASSWORD <password>; Example: IoTDB > ALTER USER root SET PASSWORD 'newpwd'; ``` -More about administration management：[Administration Management](https://iotdb.apache.org/UserGuide/V1.0.x/Administration-Management/Administration.html) - +More about administration options：[Administration Management](https://iotdb.apache.org/UserGuide/V1.0.x/Administration-Management/Administration.html) ## Basic configuration -The configuration files is in the `conf` folder, includes: +The configuration files are located in the `conf` directory. + +The most important ones being: -* environment configuration (`datanode-env.bat`, `datanode-env.sh`), +* environment variable configuration (`datanode-env.bat`, `datanode-env.sh`), * system configuration (`iotdb-datanode.properties`) * log configuration (`logback.xml`).
