You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by qi...@apache.org on 2023/12/15 13:16:21 UTC
(iotdb-docs) branch main updated: Update QuickStart.md (#62)
This is an automated email from the ASF dual-hosted git repository.
qiaojialin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 89a7d7a Update QuickStart.md (#62)
89a7d7a is described below
commit 89a7d7a72795b69f60f280031b13612bbd6280b3
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Fri Dec 15 14:16:16 2023 +0100
Update QuickStart.md (#62)
---
.../Master/API/Programming-CSharp-Native-API.md | 96 +++---
.../Master/API/Programming-Cpp-Native-API.md | 307 ++++++++++--------
.../Master/API/Programming-Go-Native-API.md | 11 +-
src/UserGuide/Master/API/Programming-JDBC.md | 31 +-
.../Master/API/Programming-Java-Native-API.md | 167 +++++-----
src/UserGuide/Master/API/Programming-Kafka.md | 2 +-
src/UserGuide/Master/API/Programming-MQTT.md | 62 ++--
.../Master/API/Programming-NodeJS-Native-API.md | 91 +++---
.../Master/API/Programming-Python-Native-API.md | 134 ++++----
.../Master/API/Programming-Rust-Native-API.md | 84 +++--
src/UserGuide/Master/API/Programming-TsFile-API.md | 349 +++++++++------------
src/UserGuide/Master/QuickStart/QuickStart.md | 2 +-
.../Master/User-Manual/Operate-Metadata.md | 2 +-
src/UserGuide/Master/stage/Interface-Comparison.md | 8 +-
.../Master/stage/Operate-Metadata/Template.md | 2 +-
.../V0.13.x/API/Programming-Cpp-Native-API.md | 2 +-
src/UserGuide/V0.13.x/Operate-Metadata/Template.md | 2 +-
src/UserGuide/V1.0.x/API/Interface-Comparison.md | 8 +-
.../V1.0.x/API/Programming-Cpp-Native-API.md | 2 +-
.../V1.0.x/API/Programming-Python-Native-API.md | 4 +-
src/UserGuide/V1.0.x/Operate-Metadata/Template.md | 2 +-
src/UserGuide/V1.1.x/API/Interface-Comparison.md | 8 +-
.../V1.1.x/API/Programming-Cpp-Native-API.md | 2 +-
.../V1.1.x/API/Programming-Python-Native-API.md | 4 +-
src/UserGuide/V1.1.x/Operate-Metadata/Template.md | 2 +-
.../V1.2.x/API/Programming-Cpp-Native-API.md | 210 ++++++++-----
.../V1.2.x/API/Programming-Python-Native-API.md | 4 +-
src/UserGuide/V1.2.x/QuickStart/QuickStart.md | 122 ++++---
.../V1.2.x/User-Manual/Operate-Metadata.md | 2 +-
src/UserGuide/V1.2.x/stage/Interface-Comparison.md | 8 +-
.../V1.2.x/stage/Operate-Metadata/Template.md | 2 +-
.../Master/API/Programming-Cpp-Native-API.md | 4 +-
.../V0.13.x/API/Programming-Cpp-Native-API.md | 2 +-
.../V1.1.x/API/Programming-Cpp-Native-API.md | 2 +-
.../V1.2.x/API/Programming-Cpp-Native-API.md | 2 +-
35 files changed, 902 insertions(+), 840 deletions(-)
diff --git a/src/UserGuide/Master/API/Programming-CSharp-Native-API.md b/src/UserGuide/Master/API/Programming-CSharp-Native-API.md
index 9c7463a..c6ad62c 100644
--- a/src/UserGuide/Master/API/Programming-CSharp-Native-API.md
+++ b/src/UserGuide/Master/API/Programming-CSharp-Native-API.md
@@ -21,6 +21,8 @@
# C# Native API
+The Git repository for the C# Native API client is located [here](https://github.com/apache/iotdb-client-csharp/)
+
## Installation
### Install from NuGet Package
@@ -31,7 +33,7 @@ We have prepared Nuget Package for C# users. Users can directly install the clie
dotnet add package Apache.IoTDB
```
-Note that the `Apache.IoTDB` package only supports versions greater than `.net framework 4.6.1`.
+Note that the `Apache.IoTDB` package only supports versions of the `.net framework 4.6.1` greater than `4.6.1`.
## Prerequisites
@@ -40,9 +42,9 @@ Note that the `Apache.IoTDB` package only supports versions greater than `.net f
## How to Use the Client (Quick Start)
-Users can quickly get started by referring to the use cases under the Apache-IoTDB-Client-CSharp-UserCase directory. These use cases serve as a useful resource for getting familiar with the client's functionality and capabilities.
+Users can quickly get started by referring to the use cases under the [Apache-IoTDB-Client-CSharp-UserCase](https://github.com/apache/iotdb-client-csharp/tree/main/Apache-IoTDB-Client-CSharp-UserCase) directory in the [iotdb-client-csharp Git repository](https://github.com/apache/iotdb-client-csharp). These use cases serve as a useful resource for getting familiar with the client's functionality and capabilities.
-For those who wish to delve deeper into the client's usage and explore more advanced features, the samples directory contains additional code samples.
+For those who wish to delve deeper into the client's usage and explore more advanced features, the [samples](https://github.com/apache/iotdb-client-csharp/tree/main/samples/Apache.IoTDB.Samples) directory in the same repository contains additional code samples.
## Developer environment requirements for iotdb-client-csharp
@@ -101,7 +103,7 @@ await session_pool.InsertTabletAsync(tablet);
await session_pool.Close();
```
-## **Row Record**
+### **Row Record**
- Encapsulate and abstract the `record` data in **IoTDB**
- e.g.
@@ -114,12 +116,12 @@ await session_pool.Close();
```csharp
var rowRecord =
- new RowRecord(long timestamps, List<object> values, List<string> measurements);
+ new RowRecord(long timestamp, List<object> values, List<string> measurements);
```
### **Tablet**
-- A data structure similar to a table, containing several non empty data blocks of a device's rows。
+- A data structure similar to a table, containing several non-empty data blocks of a device's rows。
- e.g.
| time | status | temperature |
@@ -135,61 +137,59 @@ var tablet =
Tablet(string deviceId, List<string> measurements, List<List<object>> values, List<long> timestamps);
```
-
-
## **API**
### **Basic API**
-| api name | parameters | notes | use example |
-| -------------- | ------------------------- | ------------------------ | ----------------------------- |
-| Open | bool | open session | session_pool.Open(false) |
-| Close | null | close session | session_pool.Close() |
-| IsOpen | null | check if session is open | session_pool.IsOpen() |
-| OpenDebugMode | LoggingConfiguration=null | open debug mode | session_pool.OpenDebugMode() |
-| CloseDebugMode | null | close debug mode | session_pool.CloseDebugMode() |
-| SetTimeZone | string | set time zone | session_pool.GetTimeZone() |
-| GetTimeZone | null | get time zone | session_pool.GetTimeZone() |
+| api name | parameters | notes | use example |
+| -------------- | ------------------------- | ------------------------ |------------------------------------|
+| Open | bool | open session | session_pool.Open(false) |
+| Close | null | close session | session_pool.Close() |
+| IsOpen | null | check if session is open | session_pool.IsOpen() |
+| OpenDebugMode | LoggingConfiguration=null | open debug mode | session_pool.OpenDebugMode() |
+| CloseDebugMode | null | close debug mode | session_pool.CloseDebugMode() |
+| SetTimeZone | string | set time zone | session_pool.SetTimeZone("+08:00") |
+| GetTimeZone | null | get time zone | session_pool.GetTimeZone() |
### **Record API**
-| api name | parameters | notes | use example |
-| ----------------------------------- | ----------------------------- | ----------------------------------- | ------------------------------------------------------------ |
-| InsertRecordAsync | string, RowRecord | insert single record | session_pool.InsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", new RowRecord(1, values, measures)); |
-| InsertRecordsAsync | List\<string\>, List\<RowRecord\> | insert records | session_pool.InsertRecordsAsync(device_id, rowRecords) |
-| InsertRecordsOfOneDeviceAsync | string, List\<RowRecord\> | insert records of one device | session_pool.InsertRecordsOfOneDeviceAsync(device_id, rowRecords) |
-| InsertRecordsOfOneDeviceSortedAsync | string, List\<RowRecord\> | insert sorted records of one device | InsertRecordsOfOneDeviceSortedAsync(deviceId, sortedRowRecords); |
-| TestInsertRecordAsync | string, RowRecord | test insert record | session_pool.TestInsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", rowRecord) |
-| TestInsertRecordsAsync | List\<string\>, List\<RowRecord\> | test insert record | session_pool.TestInsertRecordsAsync(device_id, rowRecords) |
+| api name | parameters | notes | use example |
+|-------------------------------------|-----------------------------------|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| InsertRecordAsync | string, RowRecord | insert single record | session_pool.InsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", new RowRecord(1, values, measures)); |
+| InsertRecordsAsync | List\<string\>, List\<RowRecord\> | insert records | session_pool.InsertRecordsAsync(device_ids, rowRecords) |
+| InsertRecordsOfOneDeviceAsync | string, List\<RowRecord\> | insert records of one device | session_pool.InsertRecordsOfOneDeviceAsync(device_id, rowRecords) |
+| InsertRecordsOfOneDeviceSortedAsync | string, List\<RowRecord\> | insert sorted records of one device | InsertRecordsOfOneDeviceSortedAsync(deviceId, sortedRowRecords); |
+| TestInsertRecordAsync | string, RowRecord | test insert record | session_pool.TestInsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", rowRecord) |
+| TestInsertRecordsAsync | List\<string\>, List\<RowRecord\> | test insert record | session_pool.TestInsertRecordsAsync(device_ids, rowRecords) |
### **Tablet API**
-| api name | parameters | notes | use example |
-| ---------------------- | ------------ | -------------------- | -------------------------------------------- |
-| InsertTabletAsync | Tablet | insert single tablet | session_pool.InsertTabletAsync(tablet) |
+| api name | parameters | notes | use example |
+| ---------------------- |----------------| -------------------- |----------------------------------------------|
+| InsertTabletAsync | Tablet | insert single tablet | session_pool.InsertTabletAsync(tablet) |
| InsertTabletsAsync | List\<Tablet\> | insert tablets | session_pool.InsertTabletsAsync(tablets) |
-| TestInsertTabletAsync | Tablet | test insert tablet | session_pool.TestInsertTabletAsync(tablet) |
+| TestInsertTabletAsync | Tablet | test insert tablet | session_pool.TestInsertTabletAsync(tablet) |
| TestInsertTabletsAsync | List\<Tablet\> | test insert tablets | session_pool.TestInsertTabletsAsync(tablets) |
### **SQL API**
-| api name | parameters | notes | use example |
-| ----------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------ |
-| ExecuteQueryStatementAsync | string | execute sql query statement | session_pool.ExecuteQueryStatementAsync("select * from root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE where time<15"); |
+| api name | parameters | notes | use example |
+| ----------------------------- | ---------- | ------------------------------ |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ExecuteQueryStatementAsync | string | execute sql query statement | session_pool.ExecuteQueryStatementAsync("select * from root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE where time<15"); |
| ExecuteNonQueryStatementAsync | string | execute sql nonquery statement | session_pool.ExecuteNonQueryStatementAsync( "create timeseries root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE.status with datatype=BOOLEAN,encoding=PLAIN") |
### **Scheam API**
-| api name | parameters | notes | use example |
-| -------------------------- | ------------------------------------------------------------ | --------------------------- | ------------------------------------------------------------ |
-| SetStorageGroup | string | set storage group | session_pool.SetStorageGroup("root.97209_TEST_CSHARP_CLIENT_GROUP_01") |
-| CreateTimeSeries | string, TSDataType, TSEncoding, Compressor | create time series | session_pool.InsertTabletsAsync(tablets) |
-| DeleteStorageGroupAsync | string | delete single storage group | session_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP_01") |
-| DeleteStorageGroupsAsync | List\<string\> | delete storage group | session_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP") |
-| CreateMultiTimeSeriesAsync | List\<string\>, List\<TSDataType\> , List\<TSEncoding\> , List\<Compressor\> | create multi time series | session_pool.CreateMultiTimeSeriesAsync(ts_path_lst, data_type_lst, encoding_lst, compressor_lst); |
-| DeleteTimeSeriesAsync | List\<string\> | delete time series | |
-| DeleteTimeSeriesAsync | string | delete time series | |
-| DeleteDataAsync | List\<string\>, long, long | delete data | session_pool.DeleteDataAsync(ts_path_lst, 2, 3) |
+| api name | parameters | notes | use example |
+| -------------------------- |------------------------------------------------------------------------------| --------------------------- |------------------------------------------------------------------------------------------------------------------|
+| SetStorageGroup | string | set storage group | session_pool.SetStorageGroup("root.97209_TEST_CSHARP_CLIENT_GROUP_01") |
+| CreateTimeSeries | string, TSDataType, TSEncoding, Compressor | create time series | session_pool.CreateTimeSeries("root.97209_TEST_CSHARP_CLIENT_GROUP_01", data_type, encoding, compressor) |
+| DeleteStorageGroupAsync | string | delete single storage group | session_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP_01") |
+| DeleteStorageGroupsAsync | List\<string\> | delete storage group | session_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP") |
+| CreateMultiTimeSeriesAsync | List\<string\>, List\<TSDataType\> , List\<TSEncoding\> , List\<Compressor\> | create multi time series | session_pool.CreateMultiTimeSeriesAsync(ts_path_lst, data_type_lst, encoding_lst, compressor_lst); |
+| DeleteTimeSeriesAsync | List\<string\> | delete time series | session_pool.DeleteTimeSeriesAsync(ts_path_lst) |
+| DeleteTimeSeriesAsync | string | delete time series | session_pool.DeleteTimeSeriesAsync("root.97209_TEST_CSHARP_CLIENT_GROUP_01") |
+| DeleteDataAsync | List\<string\>, long, long | delete data | session_pool.DeleteDataAsync(ts_path_lst, 2, 3) |
### **Other API**
@@ -203,11 +203,15 @@ var tablet =
## SessionPool
-To implement concurrent client requests, we provide a `SessionPool` for the native interface. Since `SessionPool` itself is a superset of `Session`, when `SessionPool` is a When the `pool_size` parameter is set to 1, it reverts to the original `Session`
+In order to execute concurrent client requests, we provide a `SessionPool` for the native interface.
+Since `SessionPool` itself is a superset of `Session`, as soon as `SessionPool` is instantiated with a `pool_size` parameter set to 1, it reverts to the original `Session`.
-We use the `ConcurrentQueue` data structure to encapsulate a client queue to maintain multiple connections with the server. When the `Open()` interface is called, a specified number of clients are created in the queue, and synchronous access to the queue is achieved through the `System.Threading.Monitor` class.
+We use the `ConcurrentQueue` data structure to encapsulate a client queue to maintain multiple connections with the server.
+When the `Open()` interface is called, a specified number of clients are created and stored in the queue.
+Synchronous access to the queue is achieved through the `System.Threading.Monitor` class.
-When a request occurs, it will try to find an idle client connection from the Connection pool. If there is no idle connection, the program will need to wait until there is an idle connection
+When a request is executed, it will try to find an idle client connection from the Connection pool.
+If there is no idle connection, the program will wait until there is an idle connection available and use that.
-When a connection is used up, it will automatically return to the pool and wait for the next time it is used up
+When a connection is finished executing a request, it will automatically be returned to the pool and be available for processing other requests.
diff --git a/src/UserGuide/Master/API/Programming-Cpp-Native-API.md b/src/UserGuide/Master/API/Programming-Cpp-Native-API.md
index e43a45f..6302bfc 100644
--- a/src/UserGuide/Master/API/Programming-Cpp-Native-API.md
+++ b/src/UserGuide/Master/API/Programming-Cpp-Native-API.md
@@ -22,14 +22,16 @@
# C++ Native API
## Dependencies
+
- Java 8+
-- Maven 3.5+
+- Maven 3.9+ (optional when using `mvnw` command)
- Flex
- Bison 2.7+
- Boost 1.56+
- OpenSSL 1.0+
- GCC 5.5.0+
+> Even if we'll be building a C++ application, we still need `Maven` for the build and that requires `Java`
## Installation From Source Code
@@ -37,50 +39,46 @@
- **MAC**
- 1. Install Bison ：Bison 2.3 is preinstalled on OSX, but this version is too low.
-
- When building Thrift with Bison 2.3, the following error would pop out:
- ```invalid directive: '%code'```
-
- For such case, please update `Bison`:
+ 1. Install Homebrew, as we'll be installing all dependencies via that.
+ ```shell
+ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+ ```
+ 2. Make sure java ist installed, if not:
+ ```shell
+ brew install java
+ ```
+ Please pay attention to the output of the installation process.
+ It will probably note that you need to create a symlink:
+ 1. On Intel-based models:
+ ```shell
+ sudo ln -sfn /usr/local/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk
+ ```
+ 2. On Arm-based models
+ ```shell
+ sudo ln -sfn /opt/homebrew/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk
+ ```
+ 3. Install Bison：Bison 2.3 is preinstalled on OSX, but this version is outdated, and we need a newer version.
```shell
brew install bison
- brew link bison --force
```
-
- Then, you need to tell the OS where the new bison is.
-
- For Bash users:
- ```shell
- echo 'export PATH="/usr/local/opt/bison/bin:$PATH"' >> ~/.bash_profile
- ```
-
- For zsh users:
- ```shell
- echo 'export PATH="/usr/local/opt/bison/bin:$PATH"' >> ~/.zshrc
- ```
-
- 2. Install Boost ：Please make sure a relative new version of Boost is ready on your machine.
- If no Boost available, install the latest version of Boost:
- ```shell
- brew install boost
- brew link boost
- ```
-
- 3. OpenSSL ：Make sure the Openssl libraries has been install on your Mac. The default Openssl include file search path is "/usr/local/opt/openssl/include".
-
- If Openssl header files can not be found when building Thrift, please add option`-Dopenssl.include.dir=""`.
-
+ 4. Install Boost：Please make sure a relative new version of Boost is ready on your machine.
+ If no Boost available, install the latest version of Boost:
+ ```shell
+ brew install boost
+ ```
+ 5. OpenSSL ：Make sure the Openssl header files and libraries have been installed on your Mac. The default Openssl include file search path is "/usr/local/opt/openssl/include".
+ ```shell
+ brew install openssl
+ ```
- **Ubuntu 20**
To install all dependencies, run:
```shell
- sudo apt-get install gcc-9 g++-9 libstdc++-9-dev bison flex libboost-all-dev libssl-dev zlib1g-dev
+ sudo apt install default-jdk bison flex libboost-all-dev libssl-dev
```
-
- **CentOS 7.x**
Some packages can be installed using Yum:
@@ -91,87 +89,93 @@
The version of gcc and boost installed by yum is too low, therefore you should compile or download these binary packages by yourself.
-
- **Windows**
- 1. Building environment
- * Install `MS Visual Studio`(recommend 2019 version): remember to install Visual Studio C/C++ IDE and compiler(supporting CMake, Clang, MinGW).
- * Download and install [CMake](https://cmake.org/download/) .
+ 1. Install Chocolatey, as we'll be installing all dependencies via that: [Installation Instructions](https://chocolatey.org/install)
- 2. Download and install `Flex` & `Bison`
- * Download [Win_Flex_Bison](https://sourceforge.net/projects/winflexbison/) .
- * After downloaded, please rename the executables to `flex.exe` and `bison.exe` and add them to "PATH" environment variables.
+ 2. Make sure Java is installed, if not:
+ ```shell
+ choco install openjdk
+ ```
+ > Note on Windows running on aarch64 machines, the chocolatey script has been seen to install an x86_64 version of the JDK instead, which will still work, but at a low-performance, as it'll be running in emulation-mode. Currently, however aarch64 is a bit of a problem and will hopefully be fully supported in future versions of the cmake-maven-plugin.
- 3. Install `Boost`
- * Download [Boost](https://www.boost.org/users/download/) .
- * Then build `Boost` by executing bootstrap.bat and b2.exe.
+ 3. Install Visual Studio 19 2022:
+ ```shell
+ choco install visualstudio2022community
+ choco install visualstudio2022buildtools
+ choco install visualstudio2022-workload-nativedesktop
+ ```
+
+ 4. Install Flex and Bison:
+ ```shell
+ choco install winflexbison
+ ```
- 4. Install `OpenSSL`
- * Download and install [OpenSSL](http://slproweb.com/products/Win32OpenSSL.html) .
+ 5. Install `Boost`:
+ ```shell
+ choco install boost-msvc-14.2
+ ```
+ 6. Install `OpenSSL`:
+ ```shell
+ choco install openssl
+ ```
### Compile
-You can download the source code from:
+You can download the source code from the [IoTDB Website](https://iotdb.apache.org/Download/) or clone the GIT repository:
```shell
git clone https://github.com/apache/iotdb.git
```
-The default dev branch is the master branch, If you want to use a released version (eg. `rel/0.13`):
+The default dev branch is the master branch, If you want to use a released version (e.g. `0.13.3` or `1.2.0`), be sure to check out the corresponding tag:
```shell
-git checkout rel/0.13
+git checkout v0.13.3
```
+(Please note that we are using a `Go` compatible naming schema for our release tags, which prefixes the version by a `v`)
-Under the root path of iotdb:
-
-- Mac & Linux
- ```shell
- mvn package -P compile-cpp -pl example/client-cpp-example -am -DskipTest
- ```
+> If you want to use the `maven-wrapper` which will automatically fetch the right version of `Maven`, replace `mvn` with `./mvnw` on Mac and Linux and `mvnw.cmd` on Windows systems.
-- Windows
- ```shell
- mvn package -P compile-cpp -pl iotdb-client/client-cpp,iotdb-core/datanode,example/client-cpp-example -am -Dcmake.generator="your cmake generator" -Dboost.include.dir=${your boost header folder} -Dboost.library.dir=${your boost lib (stage) folder} -DskipTests
- ```
- - When building client-cpp project, use `-Dcmake.generator=""` option to specify a Cmake generator. E.g. `-Dcmake.generator="Visual Studio 16 2019"` (`cmake --help` shows a long list of supported Cmake generators.)
- - To help CMake find your Boost libraries on windows, you should set `-DboostIncludeDir="C:\Program Files (x86)\boost_1_78_0" -DboostLibraryDir="C:\Program Files (x86)\boost_1_78_0\stage\lib"` to your mvn build command.
- ``
+In order to compile the project, execute the following command in the root path of the project:
-If the compilation finishes successfully, the packaged zip file will be placed under `client-cpp/target/client-cpp-1.3.0-SNAPSHOT-cpp-${os}.zip`
+```shell
+mvn package -P with-cpp -pl example/client-cpp-example, -am -DskipTest
+```
+As soon as the compilation finishes successfully, the packaged zip file containing the library will be placed under `iotdb-client/client-cpp/target/client-cpp-{iotdb-version}-cpp-${os}-${aarch}.zip` and the example demonstrating the use of the library will be located at: `example/client-cpp-example/target/SessionExample` and `example/client-cpp-example/target/AllignedTimeseriesSessionExample`.
## Native APIs
-Here we show the commonly used interfaces and their parameters in the Native API:
+Here we demonstrate the most commonly used interfaces and their parameters in the Native API:
### Initialization
-- Open a Session
-```cpp
-void open();
-```
+- Open a Session:
+ ```cpp
+ void open();
+ ```
-- Open a session, with a parameter to specify whether to enable RPC compression
-```cpp
-void open(bool enableRPCCompression);
-```
-Notice: this RPC compression status of client must comply with that of IoTDB server
+- Open a session, with a parameter controlling if RPC compression should be used:
+ ```cpp
+ void open(bool enableRPCCompression);
+ ```
+ Notice: The RPC compression setting of the client is required to match that of the IoTDB server
-- Close a Session
-```cpp
-void close();
-```
+- Close a session:
+ ```cpp
+ void close();
+ ```
### Data Definition Interface (DDL)
#### Database Management
-- CREATE DATABASE
+- Create database:
```cpp
void setStorageGroup(const std::string &storageGroupId);
```
-- Delete one or several databases
+- Delete one or several databases:
```cpp
void deleteStorageGroup(const std::string &storageGroup);
void deleteStorageGroups(const std::vector<std::string> &storageGroups);
@@ -179,7 +183,7 @@ void deleteStorageGroups(const std::vector<std::string> &storageGroups);
#### Timeseries Management
-- Create one or multiple timeseries
+- Create one or multiple timeseries:
```cpp
void createTimeseries(const std::string &path, TSDataType::TSDataType dataType, TSEncoding::TSEncoding encoding,
CompressionType::CompressionType compressor);
@@ -194,7 +198,7 @@ void createMultiTimeseries(const std::vector<std::string> &paths,
std::vector<std::string> *measurementAliasList);
```
-- Create aligned timeseries
+- Create aligned timeseries:
```cpp
void createAlignedTimeseries(const std::string &deviceId,
const std::vector<std::string> &measurements,
@@ -203,35 +207,35 @@ void createAlignedTimeseries(const std::string &deviceId,
const std::vector<CompressionType::CompressionType> &compressors);
```
-- Delete one or several timeseries
+- Delete one or several timeseries:
```cpp
void deleteTimeseries(const std::string &path);
void deleteTimeseries(const std::vector<std::string> &paths);
```
-- Check whether the specific timeseries exists.
+- Check whether a specific timeseries exists:
```cpp
bool checkTimeseriesExists(const std::string &path);
```
#### Schema Template
-- Create a schema template
+- Create a schema template:
```cpp
void createSchemaTemplate(const Template &templ);
```
-- Set the schema template named `templateName` at path `prefixPath`.
+- Set the schema template named `templateName` at path `prefixPath`:
```cpp
void setSchemaTemplate(const std::string &template_name, const std::string &prefix_path);
```
-- Unset the schema template
+- Unset the schema template:
```cpp
void unsetSchemaTemplate(const std::string &prefix_path, const std::string &template_name);
```
-- After measurement template created, you can edit the template with belowed APIs.
+- After a schema template was created, you can edit the template with following functions:
```cpp
// Add aligned measurements to a template
void addAlignedMeasurementsInTemplate(const std::string &template_name,
@@ -265,7 +269,7 @@ void addUnalignedMeasurementsInTemplate(const std::string &template_name,
void deleteNodeInTemplate(const std::string &template_name, const std::string &path);
```
-- You can query measurement templates with these APIS:
+- You can query schema templates with these APIs:
```cpp
// Return the amount of measurements inside a template
int countMeasurementsInTemplate(const std::string &template_name);
@@ -282,84 +286,124 @@ std::vector<std::string> showMeasurementsInTemplate(const std::string &template_
// Return all measurements paths under the designated patter inside template
std::vector<std::string> showMeasurementsInTemplate(const std::string &template_name, const std::string &pattern);
```
-
-
-### Data Manipulation Interface (DML)
+### Data Manipulation Interface (DMI)
#### Insert
-> It is recommended to use insertTablet to help improve write efficiency.
-
-- Insert a Tablet，which is multiple rows of a device, each row has the same measurements
- - Better Write Performance
- - Support null values: fill the null value with any value, and then mark the null value via BitMap
+- Insert one record, which contains multiple measurement value of a given device and timestamp:
```cpp
-void insertTablet(Tablet &tablet);
+void insertRecord(const std::string &deviceId,
+ int64_t time,
+ const std::vector<std::string> &measurements,
+ const std::vector<char *> &values);
```
-- Insert multiple Tablets
-```cpp
-void insertTablets(std::unordered_map<std::string, Tablet *> &tablets);
-```
-
-- Insert a Record, which contains multiple measurement value of a device at a timestamp
-```cpp
-void insertRecord(const std::string &deviceId, int64_t time, const std::vector<std::string> &measurements,
- const std::vector<TSDataType::TSDataType> &types, const std::vector<char *> &values);
-```
-
-- Insert multiple Records
+- Insert multiple Records for multiple devices (With type info in the `typesList` parameter the server doesn't need to do type inference, which results in better performance):
```cpp
void insertRecords(const std::vector<std::string> &deviceIds,
const std::vector<int64_t> ×,
const std::vector<std::vector<std::string>> &measurementsList,
- const std::vector<std::vector<TSDataType::TSDataType>> &typesList,
const std::vector<std::vector<char *>> &valuesList);
```
-- Insert multiple Records that belong to the same device. With type info the server has no need to do type inference, which leads a better performance
+- Insert multiple Records for the same device:
```cpp
void insertRecordsOfOneDevice(const std::string &deviceId,
std::vector<int64_t> ×,
std::vector<std::vector<std::string>> &measurementsList,
- std::vector<std::vector<TSDataType::TSDataType>> &typesList,
std::vector<std::vector<char *>> &valuesList);
```
-#### Insert with type inference
-
-Without type information, server has to do type inference, which may cost some time.
+All of the above versions require the server to figure out the data-types of each value, which comes with quite a performance-cost, therefore all of the above are also available in a version without type-inference:
```cpp
-void insertRecord(const std::string &deviceId, int64_t time, const std::vector<std::string> &measurements,
+void insertRecord(const std::string &deviceId,
+ int64_t time,
+ const std::vector<std::string> &measurements,
+ const std::vector<TSDataType::TSDataType> &types,
const std::vector<std::string> &values);
void insertRecords(const std::vector<std::string> &deviceIds,
const std::vector<int64_t> ×,
const std::vector<std::vector<std::string>> &measurementsList,
+ const std::vector<std::vector<TSDataType::TSDataType>> &typesList,
const std::vector<std::vector<std::string>> &valuesList);
void insertRecordsOfOneDevice(const std::string &deviceId,
std::vector<int64_t> ×,
std::vector<std::vector<std::string>> &measurementsList,
+ std::vector<std::vector<TSDataType::TSDataType>> &typesList,
const std::vector<std::vector<std::string>> &valuesList);
```
+For even better performance, it is recommended to use Tablets to help improve write efficiency.
+
+- Insert a Tablet，which inserts multiple rows of data for a given device. Each row has the same structure:
+ - Better write performance
+ - Support null values: Fill the null value with any value, and then mark the null value via BitMap
+```cpp
+void insertTablet(Tablet &tablet);
+```
+
+- Insert multiple Tablets
+```cpp
+void insertTablets(std::unordered_map<std::string, Tablet *> &tablets);
+```
+
#### Insert data into Aligned Timeseries
-The Insert of aligned timeseries uses interfaces like `insertAlignedXXX`, and others are similar to the above interfaces:
+The insertion of aligned timeseries is performed by functions such as `insertAlignedXXX` however semantically they align to the non-aligned versions of the previous chapter:
+
+```cpp
+ void insertAlignedRecord(const std::string &deviceId,
+ int64_t time,
+ const std::vector<std::string> &measurements,
+ const std::vector<std::string> &values);
+
+ void insertAlignedRecord(const std::string &deviceId,
+ int64_t time,
+ const std::vector<std::string> &measurements,
+ const std::vector<TSDataType::TSDataType> &types,
+ const std::vector<char *> &values);
+
+ void insertAlignedRecords(const std::vector<std::string> &deviceIds,
+ const std::vector<int64_t> ×,
+ const std::vector<std::vector<std::string>> &measurementsList,
+ const std::vector<std::vector<std::string>> &valuesList);
+
+ void insertAlignedRecords(const std::vector<std::string> &deviceIds,
+ const std::vector<int64_t> ×,
+ const std::vector<std::vector<std::string>> &measurementsList,
+ const std::vector<std::vector<TSDataType::TSDataType>> &typesList,
+ const std::vector<std::vector<char *>> &valuesList);
+
+ void insertAlignedRecordsOfOneDevice(const std::string &deviceId,
+ std::vector<int64_t> ×,
+ std::vector<std::vector<std::string>> &measurementsList,
+ std::vector<std::vector<TSDataType::TSDataType>> &typesList,
+ std::vector<std::vector<char *>> &valuesList);
-- insertAlignedRecord
-- insertAlignedRecords
-- insertAlignedRecordsOfOneDevice
-- insertAlignedTablet
-- insertAlignedTablets
+ void insertAlignedRecordsOfOneDevice(const std::string &deviceId,
+ std::vector<int64_t> ×,
+ std::vector<std::vector<std::string>> &measurementsList,
+ std::vector<std::vector<TSDataType::TSDataType>> &typesList,
+ std::vector<std::vector<char *>> &valuesList,
+ bool sorted);
+
+ void insertAlignedTablet(Tablet &tablet);
+
+ void insertAlignedTablet(Tablet &tablet,
+ bool sorted);
+
+ void insertAlignedTablets(std::unordered_map<std::string, Tablet *> &tablets,
+ bool sorted = false);
+```
#### Delete
-- Delete data before or equal to a timestamp of one or several timeseries
+- Delete data with timestamps before or equal to a given timestamp of one or several timeseries:
```cpp
void deleteData(const std::string &path, int64_t time);
void deleteData(const std::vector<std::string> &deviceId, int64_t time);
@@ -368,24 +412,28 @@ void deleteData(const std::vector<std::string> &deviceId, int64_t time);
### IoTDB-SQL Interface
- Execute query statement
+
+Query statements return data.
+
```cpp
-void executeNonQueryStatement(const std::string &sql);
+unique_ptr<SessionDataSet> executeQueryStatement(const std::string &sql);
```
+Non-Query statements don't return data (Delete, Create, ... statements)
+
- Execute non query statement
```cpp
void executeNonQueryStatement(const std::string &sql);
```
-
## Examples
-The sample code of using these interfaces is in:
+The sample code for using these interfaces is located in:
- `example/client-cpp-example/src/SessionExample.cpp`
-- `example/client-cpp-example/src/AlignedTimeseriesSessionExample.cpp` （使用对齐时间序列）
+- `example/client-cpp-example/src/AlignedTimeseriesSessionExample.cpp`
-If the compilation finishes successfully, the example project will be placed under `example/client-cpp-example/target`
+As soon as the compilation finishes, the example project will be located at `example/client-cpp-example/target`
## FAQ
@@ -395,7 +443,6 @@ If errors occur when compiling thrift source code, try to downgrade your xcode-c
see https://stackoverflow.com/questions/63592445/ld-unsupported-tapi-file-type-tapi-tbd-in-yaml-file/65518087#65518087
-
### on Windows
When Building Thrift and downloading packages via "wget", a possible annoying issue may occur with
@@ -404,6 +451,6 @@ error message looks like:
Failed to delete cached file C:\Users\Administrator\.m2\repository\.cache\download-maven-plugin\index.ser
```
Possible fixes:
-- Try to delete the ".m2\repository\\.cache\" directory and try again.
+- Try to delete the ".m2\repository\.cache\" directory and try again.
- Add "\<skipCache>true\</skipCache>" configuration to the download-maven-plugin maven phase that complains this error.
diff --git a/src/UserGuide/Master/API/Programming-Go-Native-API.md b/src/UserGuide/Master/API/Programming-Go-Native-API.md
index 894e677..f21d2b2 100644
--- a/src/UserGuide/Master/API/Programming-Go-Native-API.md
+++ b/src/UserGuide/Master/API/Programming-Go-Native-API.md
@@ -21,18 +21,17 @@
# Go Native API
+The Git repository for the Go Native API client is located [here](https://github.com/apache/iotdb-client-go/)
+
## Dependencies
* golang >= 1.13
* make >= 3.0
* curl >= 7.1.1
- * thrift 0.13.x
+ * thrift 0.15.x
* Linux、Macos or other unix-like systems
* Windows+bash (WSL、cygwin、Git Bash)
-
-
-
## Installation
* go mod
@@ -52,10 +51,10 @@ go run session_example.go
* GOPATH
```sh
-# get thrift 0.13.0
+# get thrift 0.15.0
go get github.com/apache/thrift
cd $GOPATH/src/github.com/apache/thrift
-git checkout 0.13.0
+git checkout 0.15.0
mkdir -p $GOPATH/src/iotdb-client-go-example/session_example
cd $GOPATH/src/iotdb-client-go-example/session_example
diff --git a/src/UserGuide/Master/API/Programming-JDBC.md b/src/UserGuide/Master/API/Programming-JDBC.md
index 78aa804..ddfa8d6 100644
--- a/src/UserGuide/Master/API/Programming-JDBC.md
+++ b/src/UserGuide/Master/API/Programming-JDBC.md
@@ -27,15 +27,15 @@ PLEASE USE [JAVA NATIVE API](https://iotdb.apache.org/UserGuide/Master/API/Progr
## Dependencies
-* JDK >= 1.8
-* Maven >= 3.6
+* JDK >= 1.8+
+* Maven >= 3.9+
## Installation
In root directory:
```shell
-mvn clean install -pl iotdb-client/jdbc -am -Dmaven.test.skip=true
+mvn clean install -pl iotdb-client/jdbc -am -DskipTests
```
## Use IoTDB JDBC with Maven
@@ -52,7 +52,7 @@ mvn clean install -pl iotdb-client/jdbc -am -Dmaven.test.skip=true
## Coding Examples
-This chapter provides an example of how to open a database connection, execute a SQL query, and display the results.
+This chapter provides an example of how to open a database connection, execute an SQL query, and display the results.
It requires including the packages containing the JDBC classes needed for database programming.
@@ -113,40 +113,40 @@ public class JDBCExample {
//Execute insert statements in batch
- statement.addBatch("insert into root.demo(timestamp,s0) values(1,1);");
- statement.addBatch("insert into root.demo(timestamp,s0) values(1,1);");
- statement.addBatch("insert into root.demo(timestamp,s0) values(2,15);");
- statement.addBatch("insert into root.demo(timestamp,s0) values(2,17);");
- statement.addBatch("insert into root.demo(timestamp,s0) values(4,12);");
+ statement.addBatch("INSERT INTO root.demo(timestamp,s0) VALUES(1,1);");
+ statement.addBatch("INSERT INTO root.demo(timestamp,s0) VALUES(1,1);");
+ statement.addBatch("INSERT INTO root.demo(timestamp,s0) VALUES(2,15);");
+ statement.addBatch("INSERT INTO root.demo(timestamp,s0) VALUES(2,17);");
+ statement.addBatch("INSERT INTO root.demo(timestamp,s0) values(4,12);");
statement.executeBatch();
statement.clearBatch();
//Full query statement
- String sql = "select * from root.demo";
+ String sql = "SELECT * FROM root.demo";
ResultSet resultSet = statement.executeQuery(sql);
System.out.println("sql: " + sql);
outputResult(resultSet);
//Exact query statement
- sql = "select s0 from root.demo where time = 4;";
+ sql = "SELECT s0 FROM root.demo WHERE time = 4;";
resultSet= statement.executeQuery(sql);
System.out.println("sql: " + sql);
outputResult(resultSet);
//Time range query
- sql = "select s0 from root.demo where time >= 2 and time < 5;";
+ sql = "SELECT s0 FROM root.demo WHERE time >= 2 AND time < 5;";
resultSet = statement.executeQuery(sql);
System.out.println("sql: " + sql);
outputResult(resultSet);
//Aggregate query
- sql = "select count(s0) from root.demo;";
+ sql = "SELECT COUNT(s0) FROM root.demo;";
resultSet = statement.executeQuery(sql);
System.out.println("sql: " + sql);
outputResult(resultSet);
//Delete time series
- statement.execute("delete timeseries root.demo.s0");
+ statement.execute("DELETE timeseries root.demo.s0");
//close connection
statement.close();
@@ -209,4 +209,5 @@ The parameter `version` can be used in the url:
````java
String url = "jdbc:iotdb://127.0.0.1:6667?version=V_1_0";
````
-The parameter `version` represents the SQL semantic version used by the client, which is used to be compatible with the SQL semantics of 0.12 when upgrading 0.13. The possible values are: `V_0_12`, `V_0_13`, `V_1_0`.
+The parameter `version` represents the SQL semantic version used by the client, which is used in order to be compatible with the SQL semantics of `0.12` when upgrading to `0.13`.
+The possible values are: `V_0_12`, `V_0_13`, `V_1_0`.
diff --git a/src/UserGuide/Master/API/Programming-Java-Native-API.md b/src/UserGuide/Master/API/Programming-Java-Native-API.md
index 921d3ea..4b55318 100644
--- a/src/UserGuide/Master/API/Programming-Java-Native-API.md
+++ b/src/UserGuide/Master/API/Programming-Java-Native-API.md
@@ -25,8 +25,8 @@
### Dependencies
-* JDK >= 1.8
-* Maven >= 3.6
+* JDK >= 1.8+
+* Maven >= 3.9+
### How to install
@@ -47,15 +47,15 @@ In root directory:
## Syntax Convention
-- **IoTDB-SQL interface:** The input SQL parameter needs to conform to the [syntax conventions](../Syntax-Conventions/Literal-Values.md) and be escaped for JAVA strings. For example, you need to add a backslash before the double-quotes. (That is: after JAVA escaping, it is consistent with the SQL statement executed on the command line.)
+- **IoTDB-SQL interface:** The input SQL parameter needs to conform to the [syntax conventions](../stage/Syntax-Conventions/Literal-Values.md) and be escaped for JAVA strings. For example, you need to add a backslash before the double-quotes. (That is: after JAVA escaping, it is consistent with the SQL statement executed on the command line.)
- **Other interfaces:**
- - The node names in path or path prefix as parameter: The node names which should be escaped by backticks (`) in the SQL statement, escaping is required here.
- - Identifiers (such as template names) as parameters: The identifiers which should be escaped by backticks (`) in the SQL statement, and escaping is not required here.
+ - The node names in path or path prefix: The node names are required to be escaped by backticks (`) in the SQL statement.
+ - Identifiers (such as template names): The identifiers are required to be escaped by backticks (`) in the SQL statement.
- **Code example for syntax convention could be found at:** `example/session/src/main/java/org/apache/iotdb/SyntaxConventionRelatedExample.java`
## Native APIs
-Here we show the commonly used interfaces and their parameters in the Native API:
+In this section we will demonstrate the commonly used interfaces and their parameters in the Native API:
### Initialization
@@ -91,7 +91,7 @@ session =
.build();
```
-Version represents the SQL semantic version used by the client, which is used to be compatible with the SQL semantics of 0.12 when upgrading 0.13. The possible values are: `V_0_12`, `V_0_13`, `V_1_0`.
+`Version` represents the SQL semantic version used by the client, which is used to be compatible with the SQL semantics of `0.12` when upgrading `0.13`. The possible values are: `V_0_12`, `V_0_13`, `V_1_0`.
* Open a Session
@@ -99,13 +99,13 @@ Version represents the SQL semantic version used by the client, which is used to
void open()
```
-* Open a session, with a parameter to specify whether to enable RPC compression
+* Open a session, with a parameter specifying whether to enable RPC compression
``` java
void open(boolean enableRPCCompression)
```
-Notice: this RPC compression status of client must comply with that of IoTDB server
+Notice: The RPC compression setting of the client is required to match that of the IoTDB server
* Close a Session
@@ -113,11 +113,11 @@ Notice: this RPC compression status of client must comply with that of IoTDB ser
void close()
```
-### Data Definition Interface (DDL Interface)
+### Data Definition Interface (DDI)
#### Database Management
-* CREATE DATABASE
+* Create database
``` java
void setStorageGroup(String storageGroupId)
@@ -169,8 +169,8 @@ boolean checkTimeseriesExists(String path)
#### Schema Template
-
-Create a schema template for massive identical devices will help to improve memory performance. You can use Template, InternalNode and MeasurementNode to depict the structure of the template, and use belowed interface to create it inside session.
+Creation of a schema-templates will help to improve performance when ingesting data of a large number of identical devices.
+You can use Template, InternalNode and MeasurementNode types to describe the structure of the template, and use `createSchemaTemplate` to create it inside the current session.
``` java
public void createSchemaTemplate(Template template);
@@ -203,7 +203,7 @@ Class MeasurementNode extends Node {
}
```
-We strongly suggest you implement templates only with flat-measurement (like object 'flatTemplate' in belowed snippet), since tree-structured template may not be a long-term supported feature in further version of IoTDB.
+> We strongly recommend you create only flat templates and don't make use of the ability to create hierarchical structures as tree-structured templates may not be supported in further version of IoTDB.
A snippet of using above Method and Class：
@@ -221,46 +221,47 @@ template.addToTemplate(nodeSpeed);
createSchemaTemplate(flatTemplate);
```
-You can query measurement inside templates with these APIS:
+You can query measurements inside templates with these APIS:
```java
// Return the amount of measurements inside a template
-public int countMeasurementsInTemplate(String templateName);
+int countMeasurementsInTemplate(String templateName);
-// Return true if path points to a measurement, otherwise returne false
-public boolean isMeasurementInTemplate(String templateName, String path);
+// Returns true if path points to a measurement, otherwise it returns false
+boolean isMeasurementInTemplate(String templateName, String path);
-// Return true if path exists in template, otherwise return false
-public boolean isPathExistInTemplate(String templateName, String path);
+// Returns true if path exists in template, otherwise it returns false
+boolean isPathExistInTemplate(String templateName, String path);
-// Return all measurements paths inside template
-public List<String> showMeasurementsInTemplate(String templateName);
+// Return all measurement paths inside a given template
+List<String> showMeasurementsInTemplate(String templateName);
-// Return all measurements paths under the designated patter inside template
-public List<String> showMeasurementsInTemplate(String templateName, String pattern);
+// Return all measurement paths matching the designated pattern inside a given template
+List<String> showMeasurementsInTemplate(String templateName, String pattern);
```
-To implement schema template, you can set the measurement template named 'templateName' at path 'prefixPath'.
+To use a schema template, you can set the measurement template named `templateName` at path `prefixPath`.
-**Please notice that, we strongly recommend not setting templates on the nodes above the database to accommodate future updates and collaboration between modules.**
+> **Please notice that, we strongly recommend not setting templates on the nodes above the database to accommodate future updates and collaboration between modules.**
``` java
void setSchemaTemplate(String templateName, String prefixPath)
```
-Before setting template, you should firstly create the template using
+Before using a template, you should first create the template using the following example:
``` java
void createSchemaTemplate(Template template)
```
-After setting template to a certain path, you can use the template to create timeseries on given device paths through the following interface, or you can write data directly to trigger timeseries auto creation using schema template under target devices.
+After assigning template to a certain path, you can use the template to create a timeseries for given device paths using the following call:
``` java
void createTimeseriesUsingSchemaTemplate(List<String> devicePathList)
```
+Alternatively you can write data directly without creating the timeseies firs hereby triggering the timeseries auto-creation, which automatically uses the template assigned to the provided path.
-After setting template to a certain path, you can query for info about template using belowed interface in session:
+After setting template to a certain path, you can query for info about template using the interface in the following example:
``` java
/** @return All template names. */
@@ -273,25 +274,26 @@ public List<String> showPathsTemplateSetOn(String templateName);
public List<String> showPathsTemplateUsingOn(String templateName)
```
-If you are ready to get rid of schema template, you can drop it with belowed interface. Make sure the template to drop has been unset from MTree.
+If you to remove a schema template, you can drop it with following interface.
+Make sure the template you are trying to remove has been unset from MTree and is no longer used.
``` java
void unsetSchemaTemplate(String prefixPath, String templateName);
public void dropSchemaTemplate(String templateName);
```
-Unset the measurement template named 'templateName' from path 'prefixPath'. When you issue this interface, you should assure that there is a template named 'templateName' set at the path 'prefixPath'.
-
-Attention: Unsetting the template named 'templateName' from node at path 'prefixPath' or descendant nodes which have already inserted records using template is **not supported**.
+Unset the schema template named `templateName` from path `prefixPath`.
+When you issue this interface, you should assure that there is a template named `templateName` set at the path `prefixPath`.
+> Attention: Unsetting a template from node a path or descendant nodes which already contain data referencing this template is **not supported**
-### Data Manipulation Interface (DML Interface)
+### Data Manipulation Interface (DMI)
#### Insert
It is recommended to use insertTablet to help improve write efficiency.
-* Insert a Tablet，which is multiple rows of a device, each row has the same measurements
+* Insert a Tablet，which contains multiple rows for a device. Each row has the same measurements:
* **Better Write Performance**
* **Support batch write**
* **Support null values**: fill the null value with any value, and then mark the null value via BitMap
@@ -325,7 +327,7 @@ public class Tablet {
void insertTablets(Map<String, Tablet> tablet)
```
-* Insert a Record, which contains multiple measurement value of a device at a timestamp. This method is equivalent to providing a common interface for multiple data types of values. Later, the value can be cast to the original type through TSDataType.
+* Insert a Record, which contains multiple measurement values for a device at a given time.
The correspondence between the Object type and the TSDataType type is shown in the following table.
@@ -339,44 +341,56 @@ void insertTablets(Map<String, Tablet> tablet)
| TEXT | String, Binary |
``` java
-void insertRecord(String deviceId, long time, List<String> measurements,
- List<TSDataType> types, List<Object> values)
+void insertRecord(String deviceId,
+ long time,
+ List<String> measurements,
+ List<TSDataType> types,
+ List<Object> values)
```
* Insert multiple Records
``` java
-void insertRecords(List<String> deviceIds, List<Long> times,
- List<List<String>> measurementsList, List<List<TSDataType>> typesList,
+void insertRecords(List<String> deviceIds,
+ List<Long> times,
+ List<List<String>> measurementsList,
+ List<List<TSDataType>> typesList,
List<List<Object>> valuesList)
```
-* Insert multiple Records that belong to the same device.
- With type info the server has no need to do type inference, which leads a better performance
+
+* Insert multiple Records that belong to the same device.
``` java
-void insertRecordsOfOneDevice(String deviceId, List<Long> times,
- List<List<String>> measurementsList, List<List<TSDataType>> typesList,
+void insertRecordsOfOneDevice(String deviceId,
+ List<Long> times,
+ List<List<String>> measurementsList,
+ List<List<TSDataType>> typesList,
List<List<Object>> valuesList)
```
#### Insert with type inference
-When the data is of String type, we can use the following interface to perform type inference based on the value of the value itself. For example, if value is "true" , it can be automatically inferred to be a boolean type. If value is "3.2" , it can be automatically inferred as a flout type. Without type information, server has to do type inference, which may cost some time.
+If type-information is not present, all values will be converted to their `String` representation.
+The server then performs type inference to guess the datatype, based on this string-representation.
+For example, if value string equals "true", it can be automatically inferred to be a `Boolean` type. If string value is "3.2", it can be automatically inferred as a `Float` type.
+However, please keep in mind, that this process of guessing the type for a given value comes at a performance cost.
-* Insert a Record, which contains multiple measurement value of a device at a timestamp
+The following variants demonstrate the insertion of data, using type inference:
+
+* Insert a Record, which contains multiple measurement values for a device at given times:
``` java
void insertRecord(String prefixPath, long time, List<String> measurements, List<String> values)
```
-* Insert multiple Records
+* Insert multiple Records:
``` java
void insertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList, List<List<String>> valuesList)
```
-* Insert multiple Records that belong to the same device.
+* Insert multiple Records that belong to the same device:
``` java
void insertStringRecordsOfOneDevice(String deviceId, List<Long> times,
@@ -385,7 +399,7 @@ void insertStringRecordsOfOneDevice(String deviceId, List<Long> times,
#### Insert of Aligned Timeseries
-The Insert of aligned timeseries uses interfaces like insertAlignedXXX, and others are similar to the above interfaces:
+The insertion of aligned timeseries uses interfaces like `insertAlignedXXX`, and others similar to the above interfaces:
* insertAlignedRecord
* insertAlignedRecords
@@ -396,7 +410,7 @@ The Insert of aligned timeseries uses interfaces like insertAlignedXXX, and othe
#### Delete
-* Delete data before or equal to a timestamp of one or several timeseries
+* Delete data with timestamps before or equal to a given timestamp of one or several timeseries:
``` java
void deleteData(String path, long time)
@@ -406,16 +420,16 @@ void deleteData(List<String> paths, long time)
#### Query
* Time-series raw data query with time range:
- - The specified query time range is a left-closed right-open interval, including the start time but excluding the end time.
+ - The specified query time-range is a left-closed right-open interval, including the start time but excluding the end time.
``` java
SessionDataSet executeRawDataQuery(List<String> paths, long startTime, long endTime);
```
* Last query:
- - Query the last data, whose timestamp is greater than or equal LastTime.
+ - Query the last data, whose timestamp is greater than or equal lastTime.
``` java
- SessionDataSet executeLastDataQuery(List<String> paths, long LastTime);
+ SessionDataSet executeLastDataQuery(List<String> paths, long lastTime);
```
- Query the latest point of the specified series of single device quickly, and support redirection;
If you are sure that the query path is valid, set 'isLegalPathNodes' to true to avoid performance penalties from path verification.
@@ -454,19 +468,24 @@ SessionDataSet executeAggregationQuery(
* Execute query statement
+Query statements return data.
+
``` java
SessionDataSet executeQueryStatement(String sql)
```
* Execute non query statement
+Non-Query statements don't return data (Delete, Create, ... statements)
+
``` java
void executeNonQueryStatement(String sql)
```
### Write Test Interface (to profile network cost)
-These methods **don't** insert data into database and server just return after accept the request.
+These methods **don't** insert data into database.
+The server just return after accepting the request.
* Test the network and client cost of insertRecord
@@ -502,44 +521,40 @@ void testInsertTablets(Map<String, Tablet> tablets)
### Coding Examples
-To get more information of the following interfaces, please view session/src/main/java/org/apache/iotdb/session/Session.java
-
-The sample code of using these interfaces is in example/session/src/main/java/org/apache/iotdb/SessionExample.java，which provides an example of how to open an IoTDB session, execute a batch insertion.
+To get more information about the following methods, please have a look at [Session.java](https://github.com/apache/iotdb/blob/master/iotdb-client/session/src/main/java/org/apache/iotdb/session/Session.java).
-For examples of aligned timeseries and measurement template, you can refer to `example/session/src/main/java/org/apache/iotdb/AlignedTimeseriesSessionExample.java`
+The sample code for using these methods is located in [SessionExample.java](https://github.com/apache/iotdb/blob/master/example/session/src/main/java/org/apache/iotdb/SessionExample.java)，which provides an example of how to open an IoTDB session and execute a batch insertion.
+For examples of aligned timeseries and schema template, you can refer to [AlignedTimeseriesSessionExample.java](https://github.com/apache/iotdb/blob/master/example/session/src/main/java/org/apache/iotdb/AlignedTimeseriesSessionExample.java).
## Session Pool for Native API
-We provide a connection pool (`SessionPool) for Native API.
-Using the interface, you need to define the pool size.
+We provide a connection pool (`SessionPool`) for Native API.
+When creating such a SessionPool, you need to define the pool size.
-If you can not get a session connection in 60 seconds, there is a warning log but the program will hang.
+If you can not get a session connection within 60 seconds, a warning will be logged but the program will hang.
If a session has finished an operation, it will be put back to the pool automatically.
-If a session connection is broken, the session will be removed automatically and the pool will try
-to create a new session and redo the operation.
-You can also specify an url list of multiple reachable nodes when creating a SessionPool, just as you would when creating a Session. To ensure high availability of clients in distributed cluster.
-For query operations:
+If a session connection is broken, the session will be removed automatically and the pool will try to create a new session and redo the operation.
+
+You can also specify an url list of multiple reachable nodes when creating a SessionPool, just as you would, when creating a Session to ensure high availability of clients in distributed cluster environments.
-1. When using SessionPool to query data, the result set is `SessionDataSetWrapper`;
-2. Given a `SessionDataSetWrapper`, if you have not scanned all the data in it and stop to use it,
-you have to call `SessionPool.closeResultSet(wrapper)` manually;
-3. When you call `hasNext()` and `next()` of a `SessionDataSetWrapper` and there is an exception, then
-you have to call `SessionPool.closeResultSet(wrapper)` manually;
-4. You can call `getColumnNames()` of `SessionDataSetWrapper` to get the column names of query result;
+For query operations:
-Examples: ```session/src/test/java/org/apache/iotdb/session/pool/SessionPoolTest.java```
+1. When using SessionPool to query data, the result set is `SessionDataSetWrapper`.
+2. Given a `SessionDataSetWrapper`, if you have not scanned all the data in it and stop to use it, you have to call `SessionPool.closeResultSet(wrapper)` manually.
+3. When you call `hasNext()` and `next()` of a `SessionDataSetWrapper` and there is an exception, then you have to call `SessionPool.closeResultSet(wrapper)` manually.
+4. You can call `getColumnNames()` of `SessionDataSetWrapper` to get the column names of query result.
-Or `example/session/src/main/java/org/apache/iotdb/SessionPoolExample.java`
+Examples: [SessionPoolTest.java](https://github.com/apache/iotdb/blob/master/iotdb-client/session/src/test/java/org/apache/iotdb/session/pool/SessionPoolTest.java)
+Or: [SessionPoolExample.java](https://github.com/apache/iotdb/blob/master/example/session/src/main/java/org/apache/iotdb/SessionPoolExample.java)
## Cluster information related APIs (only works in the cluster mode)
-Cluster information related APIs allow users get the cluster info like where a database will be
-partitioned to, the status of each node in the cluster.
+Cluster information related APIs allow users to retrieve information about the cluster like where a database will be persisted to or the status of each node in the cluster.
-To use the APIs, add dependency in your pom file:
+To use the APIs, please add the following dependency in your pom file:
```xml
<dependencies>
diff --git a/src/UserGuide/Master/API/Programming-Kafka.md b/src/UserGuide/Master/API/Programming-Kafka.md
index a03f318..0a04144 100644
--- a/src/UserGuide/Master/API/Programming-Kafka.md
+++ b/src/UserGuide/Master/API/Programming-Kafka.md
@@ -21,7 +21,7 @@
# Kafka
-[Apache Kafka](https://kafka.apache.org/) is an open-source distributed event streaming platform used by thousands of companies for high-performance data pipelines, streaming analytics, data integration, and mission-critical applications.
+[Apache Kafka](https://kafka.apache.org/) is an open-source distributed event streaming platform used by thousands of companies for high-performance data pipelines, streaming analytics, data integration, and mission-critical applications.
## Coding Example
diff --git a/src/UserGuide/Master/API/Programming-MQTT.md b/src/UserGuide/Master/API/Programming-MQTT.md
index 46e9eca..8a0f1d5 100644
--- a/src/UserGuide/Master/API/Programming-MQTT.md
+++ b/src/UserGuide/Master/API/Programming-MQTT.md
@@ -18,6 +18,7 @@
under the License.
-->
+
# MQTT Protocol
[MQTT](http://mqtt.org/) is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol.
@@ -25,17 +26,19 @@ It was designed as an extremely lightweight publish/subscribe messaging transpor
It is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium.
IoTDB supports the MQTT v3.1(an OASIS Standard) protocol.
-IoTDB server includes a built-in MQTT service that allows remote devices send messages into IoTDB server directly.
+IoTDB server includes a built-in MQTT service that allows remote devices to send messages to an IoTDB server directly.
<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; margin-right:auto; display:block;" src="https://alioss.timecho.com/docs/img/github/78357432-0c71cf80-75e4-11ea-98aa-c43a54d469ce.png">
-
## Built-in MQTT Service
-The Built-in MQTT Service provide the ability of direct connection to IoTDB through MQTT. It listen the publish messages from MQTT clients
- and then write the data into storage immediately.
-The MQTT topic corresponds to IoTDB timeseries.
-The messages payload can be format to events by `PayloadFormatter` which loaded by java SPI, and the default implementation is `JSONPayloadFormatter`.
-The default `json` formatter support two json format and its json array. The following is an MQTT message payload example:
+The built-in MQTT Service provides the ability of a direct connection to IoTDB using MQTT.
+It listens for publish messages from MQTT clients and then writes the data into storage immediately.
+The MQTT topic is directly mapped to the IoTDB timeseries used for persisting the data.
+The messages payload can be formatted to events by using the `PayloadFormatter` which loaded by Java SPI.
+The default implementation is `JSONPayloadFormatter`.
+The default `json` formatter supports both accepting single json objects as well as arrays of json objects.
+
+The following are two examples of valid MQTT message payloads:
```json
{
@@ -59,19 +62,21 @@ or json array of the above two.
<img style="width:100%; max-width:800px; max-height:600px; margin-left:auto; margin-right:auto; display:block;" src="https://alioss.timecho.com/docs/img/github/78357469-1bf11880-75e4-11ea-978f-a53996667a0d.png">
## MQTT Configurations
+
The IoTDB MQTT service load configurations from `${IOTDB_HOME}/${IOTDB_CONF}/iotdb-common.properties` by default.
-Configurations are as follows:
+The `IoTDB MQTT service` loads it's configuration from `${IOTDB_HOME}/${IOTDB_CONF}/iotdb-datanode.properties` per default.
-| NAME | DESCRIPTION | DEFAULT |
-| ------------- |:-------------:|:------:|
-| enable_mqtt_service | whether to enable the mqtt service | false |
-| mqtt_host | the mqtt service binding host | 127.0.0.1 |
-| mqtt_port | the mqtt service binding port | 1883 |
-| mqtt_handler_pool_size | the handler pool size for handing the mqtt messages | 1 |
-| mqtt_payload_formatter | the mqtt message payload formatter | json |
-| mqtt_max_message_size | the max mqtt message size in byte| 1048576 |
+The configuration options of this file are as follows:
+| NAME | DESCRIPTION | DEFAULT |
+|------------------------|:--------------------------------------------------:|:---------:|
+| enable_mqtt_service | whether to enable the mqtt service | false |
+| mqtt_host | the mqtt service binding host | 127.0.0.1 |
+| mqtt_port | the mqtt service binding port | 1883 |
+| mqtt_handler_pool_size |the handler pool size for handing the mqtt messages | 1 |
+| mqtt_payload_formatter | the mqtt message payload formatter | json |
+| mqtt_max_message_size | the max mqtt message size in byte | 1048576 |
## Coding Examples
The following is an example which a mqtt client send messages to IoTDB server.
@@ -103,8 +108,9 @@ connection.disconnect();
## Customize your MQTT Message Format
-If you do not like the above Json format, you can customize your MQTT Message format by just writing several lines
-of codes. An example can be found in `example/mqtt-customize` project.
+If you need a special format, you can customize your MQTT Message format by writing a few lines of codes.
+
+An example can be found in [example/mqtt-customize](https://github.com/apache/iotdb/tree/master/example/mqtt-customize) module.
Steps:
* Create a java project, and add dependency:
@@ -115,9 +121,7 @@ Steps:
<version>1.1.0-SNAPSHOT</version>
</dependency>
```
-* Define your implementation which implements `org.apache.iotdb.db.protocol.mqtt.PayloadFormatter`
-e.g.,
-
+* Create your implementation class which implements the `org.apache.iotdb.db.protocol.mqtt.PayloadFormatter` interface:
```java
package org.apache.iotdb.mqtt.server;
@@ -162,17 +166,15 @@ public class CustomizedJsonPayloadFormatter implements PayloadFormatter {
}
}
```
-* modify the file in `src/main/resources/META-INF/services/org.apache.iotdb.db.protocol.mqtt.PayloadFormatter`:
- clean the file and put your implementation class name into the file.
- In this example, the content is: `org.apache.iotdb.mqtt.server.CustomizedJsonPayloadFormatter`
-* compile your implementation as a jar file: `mvn package -DskipTests`
-
+* Update or create a file: `src/main/resources/META-INF/services/org.apache.iotdb.db.protocol.mqtt.PayloadFormatter` containing the fully qualified class name of your formatter.
+ (In the previous example, this would be adding a single line with this content: `org.apache.iotdb.mqtt.server.CustomizedJsonPayloadFormatter`)
+* compile your implementation into a jar file: `mvn package -DskipTests`
Then, in your server:
-* Create ${IOTDB_HOME}/ext/mqtt/ folder, and put the jar into this folder.
-* Update configuration to enable MQTT service. (`enable_mqtt_service=true` in `conf/iotdb-datanode.properties`)
-* Set the value of `mqtt_payload_formatter` in `conf/iotdb-datanode.properties` as the value of getName() in your implementation
- , in this example, the value is `CustomizedJson`
+* Create an `${IOTDB_HOME}/ext/mqtt/` folder, and put the jar into this directory.
+* Update configuration to enable MQTT service in `conf/iotdb-datanode.properties` by setting `enable_mqtt_service=true`.
+* Set the value of `mqtt_payload_formatter` in `conf/iotdb-datanode.properties` to the value you are returning in your implementation of getName().
+ (In this example, the value would be: `CustomizedJson`)
* Launch the IoTDB server.
* Now IoTDB will use your implementation to parse the MQTT message.
diff --git a/src/UserGuide/Master/API/Programming-NodeJS-Native-API.md b/src/UserGuide/Master/API/Programming-NodeJS-Native-API.md
index cae3f91..35c7964 100644
--- a/src/UserGuide/Master/API/Programming-NodeJS-Native-API.md
+++ b/src/UserGuide/Master/API/Programming-NodeJS-Native-API.md
@@ -19,72 +19,57 @@
-->
-
# Node.js Native API
-IoTDB uses Thrift as a cross language RPC framework, so access to IoTDB can be achieved through the interface provided by Thrift. This document will introduce how to generate a native Node.js interface that can access IoTDB.
+Apache IoTDB uses Thrift as a cross-language RPC-framework so access to IoTDB can be achieved through the interfaces provided by Thrift.
+This document will introduce how to generate a native Node.js interface that can be used to access IoTDB.
## Dependents
* JDK >= 1.8
* Node.js >= 16.0.0
- * thrift 0.14.1
* Linux、Macos or like unix
* Windows+bash
-Thrift (0.14.1 or higher) must be installed to compile Thrift files into Node.js code. The following is the official installation tutorial, and in the end, you should receive a Thrift executable file.
-```
-http://thrift.apache.org/docs/install/
-```
-
-
-## Compile the Thrift library and generate the Node.js native interface
-
-1. Find the pom.xml file in the root directory of the IoTDB source code folder.
-2. Open the pom.xml file and find the following content:
-
-```xml
-<execution>
- <id>generate-thrift-sources-java</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>java</generator>
- <thriftExecutable>${thrift.exec.absolute.path}</thriftExecutable>
- <thriftSourceRoot>${basedir}/src/main/thrift</thriftSourceRoot>
- </configuration>
-</execution>
-```
-3. Referring to this setting, add the following content to the pom.xml file to generate the native interface for Node.js:
-
-```xml
-<execution>
- <id>generate-thrift-sources-nodejs</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>js:node</generator>
- <thriftExecutable>${thrift.exec.absolute.path}</thriftExecutable>
- <thriftSourceRoot>${basedir}/src/main/thrift</thriftSourceRoot>
- <includes>**/common.thrift,**/client.thrift</includes>
- <outputDirectory>${project.build.directory}/generated-sources-nodejs</outputDirectory>
- </configuration>
-</execution>
-```
-
-4. In the root directory of the IoTDB source code folder，run `mvn clean generate-sources`，
-
-This command will automatically delete the files in `iotdb/iotdb-protocol/thrift/target` and `iotdb/iotdb-protocol/thrift-commons/target`, and repopulate the folder with the newly generated throttle file.
-
+## Generate the Node.js native interface
+
+1. Find the `pom.xml` file in the root directory of the IoTDB source code folder.
+2. Open the `pom.xml` file and find the following content:
+ ```xml
+ <execution>
+ <id>generate-thrift-sources-python</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>compile</goal>
+ </goals>
+ <configuration>
+ <generator>py</generator>
+ <outputDirectory>${project.build.directory}/generated-sources-python/</outputDirectory>
+ </configuration>
+ </execution>
+ ```
+3. Duplicate this block and change the `id`, `generator` and `outputDirectory` to this:
+ ```xml
+ <execution>
+ <id>generate-thrift-sources-nodejs</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>compile</goal>
+ </goals>
+ <configuration>
+ <generator>js:node</generator>
+ <outputDirectory>${project.build.directory}/generated-sources-nodejs/</outputDirectory>
+ </configuration>
+ </execution>
+ ```
+4. In the root directory of the IoTDB source code folder，run `mvn clean generate-sources`.
+
+This command will automatically delete the files in `iotdb/iotdb-protocol/thrift/target` and `iotdb/iotdb-protocol/thrift-commons/target`, and repopulate the folder with the newly generated files.
+The newly generated JavaScript sources will be located in `iotdb/iotdb-protocol/thrift/target/generated-sources-nodejs` in the various modules of the `iotdb-protocol` module.
## Using the Node.js native interface
-copy `iotdb/iotdb-protocol/thrift/target/generated-sources-nodejs/` and `iotdb/iotdb-protocol/thrift-commons/target/generated-sources-nodejs/` in your project。
-
+Simply copy the files in `iotdb/iotdb-protocol/thrift/target/generated-sources-nodejs/` and `iotdb/iotdb-protocol/thrift-commons/target/generated-sources-nodejs/` into your project.
## rpc interface
diff --git a/src/UserGuide/Master/API/Programming-Python-Native-API.md b/src/UserGuide/Master/API/Programming-Python-Native-API.md
index 4905cf0..8bbadb4 100644
--- a/src/UserGuide/Master/API/Programming-Python-Native-API.md
+++ b/src/UserGuide/Master/API/Programming-Python-Native-API.md
@@ -21,17 +21,11 @@
# Python Native API
-## Requirements
-
-You have to install thrift (>=0.13) before using the package.
-
-
-
## How to use (Example)
First, download the package: `pip3 install apache-iotdb`
-You can get an example of using the package to read and write data at here: [Example](https://github.com/apache/iotdb/blob/master/client-py/SessionExample.py)
+You can see an example of how to use the package to read and write data here: [Example](https://github.com/apache/iotdb/blob/master/client-py/SessionExample.py)
An example of aligned timeseries: [Aligned Timeseries Session Example](https://github.com/apache/iotdb/blob/master/client-py/SessionAlignedTimeseriesExample.py)
@@ -87,7 +81,7 @@ session = Session.init_from_node_urls(
session.open(enable_rpc_compression=False)
```
-Notice: this RPC compression status of client must comply with that of IoTDB server
+Notice: The RPC compression setting of the client is required to match that of the IoTDB server
* Close a Session
@@ -96,7 +90,11 @@ session.close()
```
## Managing Session through SessionPool
-Utilizing SessionPool to manage sessions eliminates the need to worry about session reuse. When the number of session connections reaches the maximum capacity of the pool, requests for acquiring a session will be blocked, and you can set the blocking wait time through parameters. After using a session, it should be returned to the SessionPool using the `putBack` method for proper management.
+Utilizing `SessionPool` to manage sessions eliminates the need to worry about session reuse.
+When the number of session connections reaches the maximum capacity of the pool, requests for acquiring a session will block.
+You can set a timeout after which new requests are considered unsuccessful.
+
+After using a session, it should always be returned to the SessionPool using the `putBack` method for proper management.
### Create SessionPool
@@ -110,7 +108,9 @@ wait_timeout_in_ms = 3000
# # Create the connection pool
session_pool = SessionPool(pool_config, max_pool_size, wait_timeout_in_ms)
```
-### Create a SessionPool using distributed nodes.
+
+### Create a SessionPool using distributed nodes
+
```python
pool_config = PoolConfig(node_urls=node_urls=["127.0.0.1:6667", "127.0.0.1:6668", "127.0.0.1:6669"], user_name=username,
password=password, fetch_size=1024,
@@ -118,6 +118,7 @@ pool_config = PoolConfig(node_urls=node_urls=["127.0.0.1:6667", "127.0.0.1:6668"
max_pool_size = 5
wait_timeout_in_ms = 3000
```
+
### Acquiring a session through SessionPool and manually calling PutBack after use
```python
@@ -132,7 +133,7 @@ session_pool.put_back(session)
session_pool.close()
```
-## Data Definition Interface (DDL Interface)
+## Data Definition Interface (DDI)
### Database Management
@@ -188,13 +189,12 @@ session.check_time_series_exists(path)
### Insert
-It is recommended to use insertTablet to help improve write efficiency.
+It is recommended to use `insertTablet` to help improve write efficiency.
-* Insert a Tablet，which is multiple rows of a device, each row has the same measurements
+* Insert a Tablet，which is multiple rows of data for one device, each row has the same measurements
* **Better Write Performance**
* **Support null values**: fill the null value with any value, and then mark the null value via BitMap (from v0.13)
-
We have two implementations of Tablet in Python API.
* Normal Tablet
@@ -227,12 +227,12 @@ session.insert_tablet(tablet_)
* Numpy Tablet
Comparing with Tablet, Numpy Tablet is using [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) to record data.
-With less memory footprint and time cost of serialization, the insert performance will be better.
+With less memory footprint and time cost of serialization, therefore the insert performance will be better.
**Notice**
-1. time and numerical value columns in Tablet is ndarray
-2. recommended to use the specific dtypes to each ndarray, see the example below
- (if not, the default dtypes are also ok).
+1. time and numerical value columns in Tablet is `ndarray`
+2. recommended to use the specific `dtypes` to each `ndarray`, see the example below
+ (if not, the default `dtypes` are also ok).
```python
import numpy as np
@@ -303,7 +303,7 @@ session.insert_records(
```
* Insert multiple Records that belong to the same device.
- With type info the server has no need to do type inference, which leads a better performance
+ With type info the server has no need to do type inference, which results in a better performance.
```python
@@ -312,7 +312,10 @@ session.insert_records_of_one_device(device_id, time_list, measurements_list, da
### Insert with type inference
-When the data is of String type, we can use the following interface to perform type inference based on the value of the value itself. For example, if value is "true" , it can be automatically inferred to be a boolean type. If value is "3.2" , it can be automatically inferred as a flout type. Without type information, server has to do type inference, which may cost some time.
+If type-information is not present, all values will be converted to their `String` representation.
+The server then performs type inference to guess the datatype, based on this string-representation.
+For example, if value string equals "true", it can be automatically inferred to be a `Boolean` type. If string value is "3.2", it can be automatically inferred as a `Float` type.
+However, please keep in mind, that this process of guessing the type for a given value comes at a performance cost.
* Insert a Record, which contains multiple measurement value of a device at a timestamp
@@ -322,7 +325,7 @@ session.insert_str_record(device_id, timestamp, measurements, string_values)
### Insert of Aligned Timeseries
-The Insert of aligned timeseries uses interfaces like insert_aligned_XXX, and others are similar to the above interfaces:
+The insertion of aligned timeseries uses interfaces such as `insert_aligned_XXX`, and others are similar to the above interfaces:
* insert_aligned_record
* insert_aligned_records
@@ -339,7 +342,7 @@ The Insert of aligned timeseries uses interfaces like insert_aligned_XXX, and ot
session.execute_query_statement(sql)
```
-* Execute non query statement
+* Execute non-query statement
```python
session.execute_non_query_statement(sql)
@@ -352,8 +355,11 @@ session.execute_statement(sql)
```
## Schema Template
+
### Create Schema Template
-The step for creating a metadata template is as follows
+
+The process of creating a schema template is as follows
+
1. Create the template class
2. Adding MeasurementNode
3. Execute create schema template function
@@ -429,16 +435,15 @@ session.show_paths_template_using_on(template_name)
```
### Drop Schema Template
-Delete an existing metadata template，dropping an already set template is not supported
+
+Delete an existing schema template，dropping an already set template is not supported
```python
session.drop_schema_template("template_python")
```
-
## Pandas Support
-To easily transform a query result to a [Pandas Dataframe](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html)
-the SessionDataSet has a method `.todf()` which consumes the dataset and transforms it to a pandas dataframe.
+To easily transform a query result to a [Pandas Dataframe](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html) the `SessionDataSet` has a method `.todf()` which consumes the dataset and transforms it to a pandas dataframe.
Example:
@@ -462,10 +467,9 @@ session.close()
df = ...
```
-
## IoTDB Testcontainer
-The Test Support is based on the lib `testcontainers` (https://testcontainers-python.readthedocs.io/en/latest/index.html) which you need to install in your project if you want to use the feature.
+The Test Support is based on the lib `testcontainers` (https://testcontainers-python.readthedocs.io/en/latest/index.html) which you need to install in your project if you want to use this feature.
To start (and stop) an IoTDB Database in a Docker container simply do:
```python
@@ -480,17 +484,16 @@ class MyTestCase(unittest.TestCase):
session.close()
```
-by default it will load the image `apache/iotdb:latest`, if you want a specific version just pass it like e.g. `IoTDBContainer("apache/iotdb:0.12.0")` to get version `0.12.0` running.
+Per default, it will load the image `apache/iotdb:latest`, if you want a specific version just pass it like e.g. `IoTDBContainer("apache/iotdb:0.12.0")` to get version `0.12.0`.
## IoTDB DBAPI
-IoTDB DBAPI implements the Python DB API 2.0 specification (https://peps.python.org/pep-0249/), which defines a common
-interface for accessing databases in Python.
+IoTDB DBAPI implements the `Python DB API 2.0` specification (https://peps.python.org/pep-0249/), which defines a common interface for accessing databases in Python.
### Examples
+ Initialization
-The initialized parameters are consistent with the session part (except for the sqlalchemy_mode).
+The initialization parameters are consistent with the session part (except for the sqlalchemy_mode).
```python
from iotdb.dbapi import connect
@@ -510,7 +513,7 @@ for row in cursor.fetchall():
+ execute SQL with parameter
-IoTDB DBAPI supports pyformat style parameters
+IoTDB DBAPI supports `pyformat` style parameters
```python
cursor.execute("SELECT ** FROM root WHERE time < %(time)s",{"time":"2017-11-01T00:08:00.000"})
for row in cursor.fetchall():
@@ -537,13 +540,20 @@ conn.close()
```
## IoTDB SQLAlchemy Dialect (Experimental)
-The SQLAlchemy dialect of IoTDB is written to adapt to Apache Superset.
+
+The `SQLAlchemy` dialect of IoTDB is written to adapt to `Apache Superset`.
+
This part is still being improved.
-Please do not use it in the production environment!
+
+Please do not use it in production environments!
+
### Mapping of the metadata
-The data model used by SQLAlchemy is a relational data model, which describes the relationships between different entities through tables.
-While the data model of IoTDB is a hierarchical data model, which organizes the data through a tree structure.
+
+The data model used by `SQLAlchemy` is a relational data model, which describes the relationships between different entities through tables.
+In contrast to that the data model of IoTDB is a hierarchical data model, which organizes the data through a tree structure.
+
In order to adapt IoTDB to the dialect of SQLAlchemy, the original data model in IoTDB needs to be reorganized.
+
Converting the data model of IoTDB into the data model of SQLAlchemy.
The metadata in the IoTDB are：
@@ -560,11 +570,11 @@ The metadata in the SQLAlchemy are：
The mapping relationship between them is：
-| The metadata in the SQLAlchemy | The metadata in the IoTDB |
-| -------------------- | -------------------------------------------- |
-| Schema | Database |
-| Table | Path ( from database to entity ) + Entity |
-| Column | Measurement |
+| The metadata in the SQLAlchemy | The metadata in the IoTDB |
+|--------------------------------|-------------------------------------------|
+| Schema | Database |
+| Table | Path ( from database to entity ) + Entity |
+| Column | Measurement |
The following figure shows the relationship between the two more intuitively:
@@ -626,48 +636,33 @@ for row in res:
print(row)
```
-
## Developers
### Introduction
-This is an example of how to connect to IoTDB with python, using the thrift rpc interfaces. Things are almost the same on Windows or Linux, but pay attention to the difference like path separator.
-
-
+This is an example of how to connect to IoTDB with python, using the thrift rpc interfaces.
+Things are almost the same on Windows or Linux, but pay attention to the difference like path separator.
### Prerequisites
Python3.7 or later is preferred.
-You have to install Thrift (0.11.0 or later) to compile our thrift file into python code. Below is the official tutorial of installation, eventually, you should have a thrift executable.
-
-```
-http://thrift.apache.org/docs/install/
-```
-
Before starting you need to install `requirements_dev.txt` in your python environment, e.g. by calling
```shell
pip install -r requirements_dev.txt
```
-
-
### Compile the thrift library and Debug
-In the root of IoTDB's source code folder, run `mvn clean generate-sources -pl iotdb-client/client-py -am`.
+In the root of IoTDB´s source code folder, run `mvn clean generate-sources -pl iotdb-client/client-py -am`.
This will automatically delete and repopulate the folder `iotdb/thrift` with the generated thrift files.
This folder is ignored from git and should **never be pushed to git!**
-**Notice** Do not upload `iotdb/thrift` to the git repo.
-
-
-
-
### Session Client & Example
-We packed up the Thrift interface in `client-py/src/iotdb/Session.py` (similar with its Java counterpart), also provided an example file `client-py/src/SessionExample.py` of how to use the session module. please read it carefully.
-
+The IoTDB session-interface is available in `client-py/src/iotdb/Session.py` (similar to its Java counterpart).
+We also provide an example in `client-py/src/SessionExample.py` which demonstrates how to use the session module.
Or, another simple example:
@@ -684,8 +679,6 @@ zone = session.get_time_zone()
session.close()
```
-
-
### Tests
Please add your custom tests in `tests` folder.
@@ -694,30 +687,22 @@ To run all defined tests just type `pytest .` in the root folder.
**Notice** Some tests need docker to be started on your system as a test instance is started in a docker container using [testcontainers](https://testcontainers-python.readthedocs.io/en/latest/index.html).
-
-
### Futher Tools
[black](https://pypi.org/project/black/) and [flake8](https://pypi.org/project/flake8/) are installed for autoformatting and linting.
Both can be run by `black .` or `flake8 .` respectively.
-
-
## Releasing
To do a release just ensure that you have the right set of generated thrift files.
-Then run linting and auto-formatting.
+Then run `linting` and `auto-formatting`.
Then, ensure that all tests work (via `pytest .`).
Then you are good to go to do a release!
-
-
### Preparing your environment
First, install all necessary dev dependencies via `pip install -r requirements_dev.txt`.
-
-
### Doing the Release
There is a convenient script `release.sh` to do all steps for a release.
@@ -729,4 +714,3 @@ Namely, these are
* Run Tests via pytest
* Build
* Release to pypi
-
diff --git a/src/UserGuide/Master/API/Programming-Rust-Native-API.md b/src/UserGuide/Master/API/Programming-Rust-Native-API.md
index a5bbacf..f58df68 100644
--- a/src/UserGuide/Master/API/Programming-Rust-Native-API.md
+++ b/src/UserGuide/Master/API/Programming-Rust-Native-API.md
@@ -19,11 +19,10 @@
-->
-
# Rust Native API Native API
-IoTDB uses Thrift as a cross language RPC framework, so access to IoTDB can be achieved through the interface provided by Thrift. This document will introduce how to generate a native Rust interface that can access IoTDB.
-
+IoTDB uses Thrift as a cross language RPC framework, so access to IoTDB can be achieved through the interface provided by Thrift.
+This document will introduce how to generate a native Rust interface that can access IoTDB.
## Dependents
@@ -39,56 +38,47 @@ Thrift (0.14.1 or higher) must be installed to compile Thrift files into Rust co
http://thrift.apache.org/docs/install/
```
-
## Compile the Thrift library and generate the Rust native interface
-1. Find the pom.xml file in the root directory of the IoTDB source code folder.
-2. Open the pom.xml file and find the following content:
-
-```xml
-<execution>
- <id>generate-thrift-sources-java</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>java</generator>
- <thriftExecutable>${thrift.exec.absolute.path}</thriftExecutable>
- <thriftSourceRoot>${basedir}/src/main/thrift</thriftSourceRoot>
- </configuration>
-</execution>
-```
-3. Referring to this setting, add the following content to the pom.xml file to generate the native interface for Rust:
-
-```xml
-<execution>
- <id>generate-thrift-sources-rust</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>compile</goal>
- </goals>
- <configuration>
- <generator>rs</generator>
- <thriftExecutable>${thrift.exec.absolute.path}</thriftExecutable>
- <thriftSourceRoot>${basedir}/src/main/thrift</thriftSourceRoot>
- <includes>**/common.thrift,**/client.thrift</includes>
- <outputDirectory>${project.build.directory}/generated-sources-rust</outputDirectory>
- </configuration>
-</execution>
-```
-
-
-4. In the root directory of the IoTDB source code folder，run `mvn clean generate-sources`，
-
-This command will automatically delete the files in `iotdb/iotdb-protocol/thrift/target` and `iotdb/iotdb-protocol/thrift-commons/target`, and repopulate the folder with the newly generated throttle file.
+1. Find the `pom.xml` file in the root directory of the IoTDB source code folder.
+2. Open the `pom.xml` file and find the following content:
+ ```xml
+ <execution>
+ <id>generate-thrift-sources-python</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>compile</goal>
+ </goals>
+ <configuration>
+ <generator>py</generator>
+ <outputDirectory>${project.build.directory}/generated-sources-python/</outputDirectory>
+ </configuration>
+ </execution>
+ ```
+3. Duplicate this block and change the `id`, `generator` and `outputDirectory` to this:
+ ```xml
+ <execution>
+ <id>generate-thrift-sources-rust</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>compile</goal>
+ </goals>
+ <configuration>
+ <generator>rs</generator>
+ <outputDirectory>${project.build.directory}/generated-sources-rust/</outputDirectory>
+ </configuration>
+ </execution>
+ ```
+4. In the root directory of the IoTDB source code folder，run `mvn clean generate-sources`.
+
+This command will automatically delete the files in `iotdb/iotdb-protocol/thrift/target` and `iotdb/iotdb-protocol/thrift-commons/target`, and repopulate the folder with the newly generated files.
+The newly generated Rust sources will be located in `iotdb/iotdb-protocol/thrift/target/generated-sources-rust` in the various modules of the `iotdb-protocol` module.
## Using the Rust native interface
-copy `iotdb/iotdb-protocol/thrift/target/generated-sources-rust/` and `iotdb/iotdb-protocol/thrift-commons/target/generated-sources-rust/` in your project。
-
+Copy `iotdb/iotdb-protocol/thrift/target/generated-sources-rust/` and `iotdb/iotdb-protocol/thrift-commons/target/generated-sources-rust/` into your project。
-## rpc interface
+## RPC interface
```
// open a session
diff --git a/src/UserGuide/Master/API/Programming-TsFile-API.md b/src/UserGuide/Master/API/Programming-TsFile-API.md
index d1fceaf..4ee7b4d 100644
--- a/src/UserGuide/Master/API/Programming-TsFile-API.md
+++ b/src/UserGuide/Master/API/Programming-TsFile-API.md
@@ -21,43 +21,29 @@
# TsFile API
-TsFile is a file format of Time Series used in IoTDB. This session introduces the usage of this file format.
-
-
+`TsFile` is a file format of time series used in IoTDB.
+This document introduces the usage of this file format.
## TsFile library Installation
-There are two ways to use TsFile in your own project.
-
-* Use as jars: Compile the source codes and build to jars
-
-```shell
-git clone https://github.com/apache/iotdb.git
-cd iotdb-core/tsfile
-mvn clean package -Dmaven.test.skip=true
-```
-
-Then, all the jars are in folder named `target/`. Import `target/tsfile-0.12.0-jar-with-dependencies.jar` to your project.
-
-* Use as a maven dependency:
+There are several ways to use TsFile in your own project.
+* Build from source and use the jars:
+ ```shell
+ git clone https://github.com/apache/iotdb.git
+ cd iotdb-core/tsfile
+ mvn clean package -DskipTests
+ ```
+ Then, all the jars are located in the folder named `target/`. Import `target/tsfile-0.12.0-jar-with-dependencies.jar` into your project.
+* Build from source and use as maven dependency:
Compile source codes and deploy to your local repository in three steps:
-
* Get the source codes
-
```shell
git clone https://github.com/apache/iotdb.git
- ```
-
- * Compile the source codes and deploy
-
- ```shell
cd iotdb-core/tsfile
- mvn clean install -Dmaven.test.skip=true
+ mvn clean install -DskipTests
```
-
- * add dependencies into your project:
-
+ * Add the following dependency into your project:
```xml
<dependency>
<groupId>org.apache.iotdb</groupId>
@@ -65,18 +51,33 @@ Then, all the jars are in folder named `target/`. Import `target/tsfile-0.12.0-j
<version>1.0.0</version>
</dependency>
```
-
-
- Or, you can download the dependencies from official Maven repository:
-
- * First, find your maven `settings.xml` on path: `${username}\.m2\settings.xml`
- , add this `<profile>` to `<profiles>`:
+* Download the convenience binaries available from Maven-Central:
+ * (If you want to reference the latest SNAPSHOT versions, you need to execute this step)
+ Add the `Apache Snapshot Repository` to your projects main `pom.xml`:
+ ```xml
+ <repositories>
+ <repository>
+ <id>apache.snapshots</id>
+ <name>Apache Development Snapshot Repository</name>
+ <url>https://repository.apache.org/content/repositories/snapshots/</url>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ </repository>
+ </repositories>
+ ```
+ Alternately, find or create your maven `settings.xml` located at: `${username}\.m2\settings.xml`, add this `<profile>` to `<profiles>`:
```xml
- <profile>
- <id>allow-snapshots</id>
- <activation><activeByDefault>true</activeByDefault></activation>
- <repositories>
- <repository>
+ <profile>
+ <id>allow-snapshots</id>
+ <activation>
+ <activeByDefault>true</activeByDefault>
+ </activation>
+ <repositories>
+ <repository>
<id>apache.snapshots</id>
<name>Apache Development Snapshot Repository</name>
<url>https://repository.apache.org/content/repositories/snapshots/</url>
@@ -86,187 +87,150 @@ Then, all the jars are in folder named `target/`. Import `target/tsfile-0.12.0-j
<snapshots>
<enabled>true</enabled>
</snapshots>
- </repository>
- </repositories>
- </profile>
+ </repository>
+ </repositories>
+ </profile>
```
- * Then add dependencies into your project:
-
+ * Then add dependency into your project:
```xml
- <dependency>
- <groupId>org.apache.iotdb</groupId>
- <artifactId>tsfile</artifactId>
- <version>1.0.0</version>
- </dependency>
+ <dependency>
+ <groupId>org.apache.iotdb</groupId>
+ <artifactId>tsfile</artifactId>
+ <version>1.0.0</version>
+ </dependency>
```
-
-
## TsFile Usage
This section demonstrates the detailed usages of TsFile.
-Time-series Data
Time-series data is considered as a sequence of quadruples. A quadruple is defined as (device, measurement, time, value).
-* **measurement**: A physical or formal measurement that a time-series data takes, e.g., the temperature of a city, the
-sales number of some goods or the speed of a train at different times. As a traditional sensor (like a thermometer) also
- takes a single measurement and produce a time-series, we will use measurement and sensor interchangeably below.
-
-* **device**: A device refers to an entity that takes several measurements (producing multiple time-series), e.g.,
-a running train monitors its speed, oil meter, miles it has run, current passengers each is conveyed to a time-series dataset.
-
-
-**One Line of Data**: In many industrial applications, a device normally contains more than one sensor and these sensors
- may have values at the same timestamp, which is called one line of data.
-
-Formally, one line of data consists of a `device_id`, a timestamp which indicates the milliseconds since January 1,
- 1970, 00:00:00, and several data pairs composed of `measurement_id` and corresponding `value`. All data pairs in one
- line belong to this `device_id` and have the same timestamp. If one of the `measurements` does not have a `value`
- in the `timestamp`, use a space instead(Actually, TsFile does not store null values). Its format is shown as follow:
-
-```
-device_id, timestamp, <measurement_id, value>...
-```
-
-An example is illustrated as follow. In this example, the data type of two measurements are `INT32`, `FLOAT` respectively.
-
-```
-device_1, 1490860659000, m1, 10, m2, 12.12
-```
+* **measurement**: A physical or formal measurement that a time-series data takes, e.g. the temperature of a city, the sales number of some goods or the speed of a train at different times.
+ As a traditional sensor (like a thermometer) also produces a single measurement which we can use to create a time-series, we will use measurement and sensor interchangeably below.
+* **device**: A device refers to an entity that produces one or multiple measurements (producing multiple time-series), e.g.,
+ a running train monitors its speed, oil meter, miles it has run, current passengers.
+ Each is persisted to a time-series dataset.
+* **Row of Data**: In many industrial applications, a device normally contains more than one sensor and these sensors may have values at the same timestamp, which is called `row of data`.
+ Formally, a `row of data` consists of a `device_id`, a `timestamp` which indicates the milliseconds since `January 1, 1970, 00:00:00`, and several data pairs composed of `measurement_id` and corresponding `value`.
+ All data pairs in a line of data belong to the same `device_id` and have the same timestamp.
+ If one of the `measurements` does not have a `value` in the `timestamp`, a space is used instead (Actually, TsFile does not actually store `null` values).
+ Its format is shown as follows:
+ ```
+ device_id, timestamp, <measurement_id, value>...
+ ```
+ An example is illustrated as follows.
+ In this example, the data type of two measurements are `INT32`, `FLOAT` respectively.
+ ```
+ device_1, 1490860659000, m1, 10, m2, 12.12
+ ```
### Write TsFile
-A TsFile is generated by the following three steps and the complete code is given in the section "Example for writing TsFile".
-
-1. construct a `TsFileWriter` instance.
-
- Here are the available constructors:
-
- * Without pre-defined schema
-
- ```java
- public TsFileWriter(File file) throws IOException
- ```
- * With pre-defined schema
-
- ```java
- public TsFileWriter(File file, Schema schema) throws IOException
- ```
- This one is for using the HDFS file system. `TsFileOutput` can be an instance of class `HDFSOutput`.
-
- ```java
- public TsFileWriter(TsFileOutput output, Schema schema) throws IOException
- ```
-
- If you want to set some TSFile configuration on your own, you could use param `config`. For example:
-
- ```java
- TSFileConfig conf = new TSFileConfig();
- conf.setTSFileStorageFs("HDFS");
- TsFileWriter tsFileWriter = new TsFileWriter(file, schema, conf);
- ```
-
- In this example, data files will be stored in HDFS, instead of local file system. If you'd like to store data files in local file system, you can use `conf.setTSFileStorageFs("LOCAL")`, which is also the default config.
-
- You can also config the ip and rpc port of your HDFS by `config.setHdfsIp(...)` and `config.setHdfsPort(...)`. The default ip is `localhost` and default rpc port is `9000`.
+A `TsFile` is generated by the following steps (The complete code is given in [TsFile examples module](https://github.com/apache/iotdb/tree/master/example/tsfile)):
- **Parameters:**
-
- * file : The TsFile to write
+1. Construct a `TsFileWriter` instance.
+2. Define the `Schema` for the `TSFile` (However a pre-defined Schema can also be passed directly to the constructor in step 1).
+3. Write data to the `TsFileWriter`.
+4. Close the `TsFileWriter` (When using a Java try-with-resources block, Java will take care of closing the TsFileWriter).
- * schema : The file schemas, will be introduced in next part.
+#### Construct an `TsFileWriter` instance.
- * config : The config of TsFile.
+Here are the available constructors:
+* Without pre-defined schema:
+ ```java
+ TsFileWriter(File file) throws IOException
+ ```
+* With pre-defined schema:
+ ```java
+ TsFileWriter(File file, Schema schema) throws IOException
+ ```
+* Providing a `TsFileOutput` instead of a File with a schema (useful when using the HDFS file system as `TsFileOutput` can be an instance of class `HDFSOutput`):
+ ```java
+ TsFileWriter(TsFileOutput output, Schema schema) throws IOException
+ ```
+* If you want to set some TSFile configuration on your own, you could use param `config`. For example:
+ ```java
+ TSFileConfig conf = new TSFileConfig();
+ conf.setTSFileStorageFs("HDFS");
+ TsFileWriter tsFileWriter = new TsFileWriter(file, schema, conf);
+ ```
+ In this example, data files will be stored in HDFS, instead of local file system.
+ If you'd like to store data files in local file system, you can use `conf.setTSFileStorageFs("LOCAL")`, which is also the default config.
+ You can configure the `ip` and `rpc port` of your HDFS by setting `config.setHdfsIp(...)` and `config.setHdfsPort(...)`. The default ip is `localhost` and default rpc port is `9000`.
-2. add measurements
-
- Or you can make an instance of class `Schema` first and pass this to the constructor of class `TsFileWriter`
+**Parameters:**
- The class `Schema` contains a map whose key is the name of one measurement schema, and the value is the schema itself.
-
- Here are the interfaces:
-
- ```java
- // Create an empty Schema or from an existing map
- public Schema()
- public Schema(Map<String, MeasurementSchema> measurements)
- // Use this two interfaces to add measurements
- public void registerMeasurement(MeasurementSchema descriptor)
- public void registerMeasurements(Map<String, MeasurementSchema> measurements)
- // Some useful getter and checker
- public TSDataType getMeasurementDataType(String measurementId)
- public MeasurementSchema getMeasurementSchema(String measurementId)
- public Map<String, MeasurementSchema> getAllMeasurementSchema()
- public boolean hasMeasurement(String measurementId)
- ```
-
- You can always use the following interface in `TsFileWriter` class to add additional measurements:
+* file : The TsFile to write
+* schema : The file schemas, will be introduced in next part.
+* config : The config of TsFile.
- ```java
- public void addMeasurement(MeasurementSchema measurementSchema) throws WriteProcessException
- ```
+#### Construct a `Schema` instance.
- The class `MeasurementSchema` contains the information of one measurement, there are several constructors:
- ```java
- public MeasurementSchema(String measurementId, TSDataType type, TSEncoding encoding)
- public MeasurementSchema(String measurementId, TSDataType type, TSEncoding encoding, CompressionType compressionType)
- public MeasurementSchema(String measurementId, TSDataType type, TSEncoding encoding, CompressionType compressionType,
- Map<String, String> props)
- ```
-
- **Parameters:**
-
- * measurementID: The name of this measurement, typically the name of the sensor.
-
- * type: The data type, now support six types: `BOOLEAN`, `INT32`, `INT64`, `FLOAT`, `DOUBLE`, `TEXT`;
-
- * encoding: The data encoding.
-
- * compression: The data compression.
+The class `Schema` contains a map whose key is the name of one measurement schema, and the value is the schema itself.
+Here are the most important methods:
+```java
+// Create an empty Schema or from an existing map
+public Schema()
+public Schema(Map<String, MeasurementSchema> measurements)
+// Use this two interfaces to add measurements
+public void registerMeasurement(MeasurementSchema descriptor)
+public void registerMeasurements(Map<String, MeasurementSchema> measurements)
+// Some useful getter and checker
+public TSDataType getMeasurementDataType(String measurementId)
+public MeasurementSchema getMeasurementSchema(String measurementId)
+public Map<String, MeasurementSchema> getAllMeasurementSchema()
+public boolean hasMeasurement(String measurementId)
+```
+The class `MeasurementSchema` contains the information of one measurement, there are several constructors:
- * props: Properties for special data types.Such as `max_point_number` for `FLOAT` and `DOUBLE`, `max_string_length` for
- `TEXT`. Use as string pairs into a map such as ("max_point_number", "3").
+```java
+public MeasurementSchema(String measurementId, TSDataType type, TSEncoding encoding)
+public MeasurementSchema(String measurementId, TSDataType type, TSEncoding encoding, CompressionType compressionType)
+public MeasurementSchema(String measurementId, TSDataType type, TSEncoding encoding, CompressionType compressionType, Map<String, String> props)
+```
+**Parameters:**
+
+* measurementID: The name of this measurement, typically the name of the sensor.
+* type: The data type, now support six types: `BOOLEAN`, `INT32`, `INT64`, `FLOAT`, `DOUBLE`, `TEXT`;
+* encoding: The data encoding.
+* compressionType: The data compression type.
+* props: A map of properties for special data types, such as `max_point_number` for `FLOAT` and `DOUBLE`, `max_string_length` for `TEXT`. Use as string pairs into a map such as ("max_point_number", "3").
- > **Notice:** Although one measurement name can be used in multiple deltaObjects, the properties cannot be changed. I.e.
- it's not allowed to add one measurement name for multiple times with different type or encoding.
- Here is a bad example:
+> **Notice:** Although one measurement name can be used in multiple deltaObjects, the properties cannot be changed. I.e. it is not allowed to add one measurement name for multiple times with different type or encoding. Here is a bad example:
- ```java
- // The measurement "sensor_1" is float type
- addMeasurement(new MeasurementSchema("sensor_1", TSDataType.FLOAT, TSEncoding.RLE));
-
- // This call will throw a WriteProcessException exception
- addMeasurement(new MeasurementSchema("sensor_1", TSDataType.INT32, TSEncoding.RLE));
- ```
- ```
-
- ```
-
-3. insert and write data continually.
+```java
+List<MeasurementSchema> measurementSchemas = new ArrayList<>();
+// The measurement "sensor_1" is float type
+measurementSchemas.add(new MeasurementSchema("sensor_1", TSDataType.FLOAT, TSEncoding.RLE));
+measurementSchemas.add(new MeasurementSchema("sensor_1", TSDataType.INT32, TSEncoding.RLE));
+```
+#### Insert and write data
- Use this interface to create a new `TSRecord`(a timestamp and device pair).
-
- ```java
- public TSRecord(long timestamp, String deviceId)
- ```
- ```
- Then create a `DataPoint`(a measurement and value pair), and use the addTuple method to add the DataPoint to the correct
- TsRecord.
+Use this interface to create a new `TSRecord`(a timestamp and device pair).
- Use this method to write
+```java
+ TSRecord tsRecord = new TSRecord(time, deviceId);
+```
+Then create a `DataPoint`(a measurement and value pair), and use the `addTuple` method to add the `DataPoint` to the current `TsRecord`.
+```java
+ DataPoint dPoint = new LongDataPoint("sensor_1", 42);
+ tsRecord.addTuple(dPoint);
+```
+> Notice: there are implementations of `DataPoint` for each of IoTDBs supported data types: `BooleanDataPoint`, `DoubleDataPoint`, `FloatDataPoint`, `IntDataPoint`, `LongDataPoint` and `StringDataPoint`.
- ```java
- public void write(TSRecord record) throws IOException, WriteProcessException
- ```
+As soon as the TSRecord is finished, write it to file with the following command:
+```java
+ tsFileWriter.write(tsRecord);
+```
-4. call `close` to finish this writing process.
+#### Call `close` to finish this writing process
- ```java
- public void close() throws IOException
- ```
+```java
+ tsFileWriter.close();
+```
We are also able to write data into a closed TsFile.
@@ -276,7 +240,7 @@ We are also able to write data into a closed TsFile.
public ForceAppendTsFileWriter(File file) throws IOException
```
-2. call `doTruncate` truncate the part of Metadata
+2. Call `doTruncate()` to truncate the part of Metadata
3. Then use `ForceAppendTsFileWriter` to construct a new `TsFileWriter`
@@ -285,8 +249,6 @@ public TsFileWriter(TsFileIOWriter fileWriter) throws IOException
```
Please note, we should redo the step of adding measurements before writing new data to the TsFile.
-
-
### Example for writing a TsFile
You should install TsFile to your local maven repository.
@@ -307,8 +269,6 @@ You could write data into a closed TsFile by using **ForceAppendTsFileWriter**.
A more thorough example can be found at `/example/tsfile/src/main/java/org/apache/iotdb/tsfile/TsFileForceAppendWrite.java`
-
-
### Interface for Reading TsFile
* Definition of Path
@@ -380,7 +340,6 @@ We create one or more filter expressions and may use binary filter operators to
* BinaryExpression.and(Expression, Expression): Choose the value satisfy for both expressions.
* BinaryExpression.or(Expression, Expression): Choose the value satisfy for at least one expression.
-
Filter Expression Examples
diff --git a/src/UserGuide/Master/QuickStart/QuickStart.md b/src/UserGuide/Master/QuickStart/QuickStart.md
index 4d74ab7..e8b182b 100644
--- a/src/UserGuide/Master/QuickStart/QuickStart.md
+++ b/src/UserGuide/Master/QuickStart/QuickStart.md
@@ -129,7 +129,7 @@ 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 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 follows:
```
IoTDB> CREATE TIMESERIES root.ln.wf01.wt01.status WITH DATATYPE=BOOLEAN, ENCODING=PLAIN
diff --git a/src/UserGuide/Master/User-Manual/Operate-Metadata.md b/src/UserGuide/Master/User-Manual/Operate-Metadata.md
index 7f10fe7..ea5d184 100644
--- a/src/UserGuide/Master/User-Manual/Operate-Metadata.md
+++ b/src/UserGuide/Master/User-Manual/Operate-Metadata.md
@@ -317,7 +317,7 @@ Note: The `schema` keyword in the following statements can be omitted.
### Create Schema Template
-The SQL syntax for creating a metadata template is as follows:
+The SQL syntax for creating a schema template is as follows:
```sql
CREATE SCHEMA TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
diff --git a/src/UserGuide/Master/stage/Interface-Comparison.md b/src/UserGuide/Master/stage/Interface-Comparison.md
index e50780b..4907b82 100644
--- a/src/UserGuide/Master/stage/Interface-Comparison.md
+++ b/src/UserGuide/Master/stage/Interface-Comparison.md
@@ -26,17 +26,17 @@ This chapter mainly compares the differences between Java Native API and python
| Order | API name and function | Java API [...]
-| ----- | ------------------------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
+| ----- |---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
| 1 | Initialize session | `Session.Builder.build(); Session.Builder().host(String host).port(int port).build(); Session.Builder().nodeUrls(List<String> nodeUrls).build(); Session.Builder().fetchSize(int fetchSize).username(String username).password(String password).thriftDefaultBufferSize(int thriftDefaultBufferSize).thriftMaxFrameSize(int thriftMaxFrameSize).enableRedirection(boolean enableCacheLeader).version(Version version).build();` [...]
| 2 | Open session | `void open() void open(boolean enableRPCCompression)` [...]
| 3 | Close session | `void close()` [...]
-| 4 | Create Database | `void setStorageGroup(String storageGroupId)` [...]
-| 5 | Delete database | `void deleteStorageGroup(String storageGroup) void deleteStorageGroups(List<String> storageGroups)` [...]
+| 4 | Create Database | `void setStorageGroup(String storageGroupId)` [...]
+| 5 | Delete database | `void deleteStorageGroup(String storageGroup) void deleteStorageGroups(List<String> storageGroups)` [...]
| 6 | Create timeseries | `void createTimeseries(String path, TSDataType dataType,TSEncoding encoding, CompressionType compressor, Map<String, String> props,Map<String, String> tags, Map<String, String> attributes, String measurementAlias) void createMultiTimeseries(List<String> paths, List<TSDataType> dataTypes,List<TSEncoding> encodings, List<CompressionType> compressors,List<Map<String, String>> propsList, List<Map<String, String>> tagsList,Li [...]
| 7 | Create aligned timeseries | `void createAlignedTimeseries(String prefixPath, List<String> measurements,List<TSDataType> dataTypes, List<TSEncoding> encodings,CompressionType compressor, List<String> measurementAliasList);` [...]
| 8 | Delete timeseries | `void deleteTimeseries(String path) void deleteTimeseries(List<String> paths)` [...]
| 9 | Detect whether the timeseries exists | `boolean checkTimeseriesExists(String path)` [...]
-| 10 | Metadata template | `public void createSchemaTemplate(Template template);` [...]
+| 10 | Schema template | `public void createSchemaTemplate(Template template);` [...]
| 11 | Insert tablet | `void insertTablet(Tablet tablet) void insertTablets(Map<String, Tablet> tablets)` [...]
| 12 | Insert record | `void insertRecord(String prefixPath, long time, List<String> measurements,List<TSDataType> types, List<Object> values) void insertRecords(List<String> deviceIds,List<Long> times,List<List<String>> measurementsList,List<List<TSDataType>> typesList,List<List<Object>> valuesList) void insertRecordsOfOneDevice(String deviceId, List<Long> times,List<List<Object>> valuesList)` [...]
| 13 | Write with type inference | `void insertRecord(String prefixPath, long time, List<String> measurements, List<String> values) void insertRecords(List<String> deviceIds, List<Long> times,List<List<String>> measurementsList, List<List<String>> valuesList) void insertStringRecordsOfOneDevice(String deviceId, List<Long> times,List<List<String>> measurementsList, List<List<String>> valuesList)` [...]
diff --git a/src/UserGuide/Master/stage/Operate-Metadata/Template.md b/src/UserGuide/Master/stage/Operate-Metadata/Template.md
index 25768b4..68757a2 100644
--- a/src/UserGuide/Master/stage/Operate-Metadata/Template.md
+++ b/src/UserGuide/Master/stage/Operate-Metadata/Template.md
@@ -27,7 +27,7 @@ Note: The `schema` keyword in the following statements can be omitted.
## Create Schema Template
-The SQL syntax for creating a metadata template is as follows:
+The SQL syntax for creating a schema template is as follows:
```sql
CREATE SCHEMA TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
diff --git a/src/UserGuide/V0.13.x/API/Programming-Cpp-Native-API.md b/src/UserGuide/V0.13.x/API/Programming-Cpp-Native-API.md
index 1ff757a..a346674 100644
--- a/src/UserGuide/V0.13.x/API/Programming-Cpp-Native-API.md
+++ b/src/UserGuide/V0.13.x/API/Programming-Cpp-Native-API.md
@@ -369,7 +369,7 @@ void deleteData(const std::vector<std::string> &deviceId, int64_t time);
- Execute query statement
```cpp
-void executeNonQueryStatement(const std::string &sql);
+unique_ptr<SessionDataSet> executeQueryStatement(const std::string &sql);
```
- Execute non query statement
diff --git a/src/UserGuide/V0.13.x/Operate-Metadata/Template.md b/src/UserGuide/V0.13.x/Operate-Metadata/Template.md
index 9229eba..0748073 100644
--- a/src/UserGuide/V0.13.x/Operate-Metadata/Template.md
+++ b/src/UserGuide/V0.13.x/Operate-Metadata/Template.md
@@ -27,7 +27,7 @@ Note: The `schema` keyword in the following statements can be omitted.
## Create Schema Template
-The SQL syntax for creating a metadata template is as follows:
+The SQL syntax for creating a schema template is as follows:
```sql
CREATE SCHEMA? TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
diff --git a/src/UserGuide/V1.0.x/API/Interface-Comparison.md b/src/UserGuide/V1.0.x/API/Interface-Comparison.md
index e50780b..4907b82 100644
--- a/src/UserGuide/V1.0.x/API/Interface-Comparison.md
+++ b/src/UserGuide/V1.0.x/API/Interface-Comparison.md
@@ -26,17 +26,17 @@ This chapter mainly compares the differences between Java Native API and python
| Order | API name and function | Java API [...]
-| ----- | ------------------------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
+| ----- |---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
| 1 | Initialize session | `Session.Builder.build(); Session.Builder().host(String host).port(int port).build(); Session.Builder().nodeUrls(List<String> nodeUrls).build(); Session.Builder().fetchSize(int fetchSize).username(String username).password(String password).thriftDefaultBufferSize(int thriftDefaultBufferSize).thriftMaxFrameSize(int thriftMaxFrameSize).enableRedirection(boolean enableCacheLeader).version(Version version).build();` [...]
| 2 | Open session | `void open() void open(boolean enableRPCCompression)` [...]
| 3 | Close session | `void close()` [...]
-| 4 | Create Database | `void setStorageGroup(String storageGroupId)` [...]
-| 5 | Delete database | `void deleteStorageGroup(String storageGroup) void deleteStorageGroups(List<String> storageGroups)` [...]
+| 4 | Create Database | `void setStorageGroup(String storageGroupId)` [...]
+| 5 | Delete database | `void deleteStorageGroup(String storageGroup) void deleteStorageGroups(List<String> storageGroups)` [...]
| 6 | Create timeseries | `void createTimeseries(String path, TSDataType dataType,TSEncoding encoding, CompressionType compressor, Map<String, String> props,Map<String, String> tags, Map<String, String> attributes, String measurementAlias) void createMultiTimeseries(List<String> paths, List<TSDataType> dataTypes,List<TSEncoding> encodings, List<CompressionType> compressors,List<Map<String, String>> propsList, List<Map<String, String>> tagsList,Li [...]
| 7 | Create aligned timeseries | `void createAlignedTimeseries(String prefixPath, List<String> measurements,List<TSDataType> dataTypes, List<TSEncoding> encodings,CompressionType compressor, List<String> measurementAliasList);` [...]
| 8 | Delete timeseries | `void deleteTimeseries(String path) void deleteTimeseries(List<String> paths)` [...]
| 9 | Detect whether the timeseries exists | `boolean checkTimeseriesExists(String path)` [...]
-| 10 | Metadata template | `public void createSchemaTemplate(Template template);` [...]
+| 10 | Schema template | `public void createSchemaTemplate(Template template);` [...]
| 11 | Insert tablet | `void insertTablet(Tablet tablet) void insertTablets(Map<String, Tablet> tablets)` [...]
| 12 | Insert record | `void insertRecord(String prefixPath, long time, List<String> measurements,List<TSDataType> types, List<Object> values) void insertRecords(List<String> deviceIds,List<Long> times,List<List<String>> measurementsList,List<List<TSDataType>> typesList,List<List<Object>> valuesList) void insertRecordsOfOneDevice(String deviceId, List<Long> times,List<List<Object>> valuesList)` [...]
| 13 | Write with type inference | `void insertRecord(String prefixPath, long time, List<String> measurements, List<String> values) void insertRecords(List<String> deviceIds, List<Long> times,List<List<String>> measurementsList, List<List<String>> valuesList) void insertStringRecordsOfOneDevice(String deviceId, List<Long> times,List<List<String>> measurementsList, List<List<String>> valuesList)` [...]
diff --git a/src/UserGuide/V1.0.x/API/Programming-Cpp-Native-API.md b/src/UserGuide/V1.0.x/API/Programming-Cpp-Native-API.md
index 3108634..e13fad6 100644
--- a/src/UserGuide/V1.0.x/API/Programming-Cpp-Native-API.md
+++ b/src/UserGuide/V1.0.x/API/Programming-Cpp-Native-API.md
@@ -369,7 +369,7 @@ void deleteData(const std::vector<std::string> &deviceId, int64_t time);
- Execute query statement
```cpp
-void executeNonQueryStatement(const std::string &sql);
+unique_ptr<SessionDataSet> executeQueryStatement(const std::string &sql);
```
- Execute non query statement
diff --git a/src/UserGuide/V1.0.x/API/Programming-Python-Native-API.md b/src/UserGuide/V1.0.x/API/Programming-Python-Native-API.md
index 48d4250..aef8cdd 100644
--- a/src/UserGuide/V1.0.x/API/Programming-Python-Native-API.md
+++ b/src/UserGuide/V1.0.x/API/Programming-Python-Native-API.md
@@ -260,7 +260,7 @@ session.execute_statement(sql)
### Schema Template
#### Create Schema Template
-The step for creating a metadata template is as follows
+The step for creating a schema template is as follows
1. Create the template class
2. Adding child Node，InternalNode and MeasurementNode can be chose
3. Execute create schema template function
@@ -339,7 +339,7 @@ session.show_paths_template_using_on(template_name)
```
#### Drop Schema Template
-Delete an existing metadata template，dropping an already set template is not supported
+Delete an existing schema template，dropping an already set template is not supported
```python
session.drop_schema_template("template_python")
```
diff --git a/src/UserGuide/V1.0.x/Operate-Metadata/Template.md b/src/UserGuide/V1.0.x/Operate-Metadata/Template.md
index 686156b..848944c 100644
--- a/src/UserGuide/V1.0.x/Operate-Metadata/Template.md
+++ b/src/UserGuide/V1.0.x/Operate-Metadata/Template.md
@@ -27,7 +27,7 @@ Note: The `schema` keyword in the following statements can be omitted.
## Create Schema Template
-The SQL syntax for creating a metadata template is as follows:
+The SQL syntax for creating a schema template is as follows:
```sql
CREATE SCHEMA TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
diff --git a/src/UserGuide/V1.1.x/API/Interface-Comparison.md b/src/UserGuide/V1.1.x/API/Interface-Comparison.md
index e50780b..69f4752 100644
--- a/src/UserGuide/V1.1.x/API/Interface-Comparison.md
+++ b/src/UserGuide/V1.1.x/API/Interface-Comparison.md
@@ -26,17 +26,17 @@ This chapter mainly compares the differences between Java Native API and python
| Order | API name and function | Java API [...]
-| ----- | ------------------------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
+| ----- |---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
| 1 | Initialize session | `Session.Builder.build(); Session.Builder().host(String host).port(int port).build(); Session.Builder().nodeUrls(List<String> nodeUrls).build(); Session.Builder().fetchSize(int fetchSize).username(String username).password(String password).thriftDefaultBufferSize(int thriftDefaultBufferSize).thriftMaxFrameSize(int thriftMaxFrameSize).enableRedirection(boolean enableCacheLeader).version(Version version).build();` [...]
| 2 | Open session | `void open() void open(boolean enableRPCCompression)` [...]
| 3 | Close session | `void close()` [...]
-| 4 | Create Database | `void setStorageGroup(String storageGroupId)` [...]
-| 5 | Delete database | `void deleteStorageGroup(String storageGroup) void deleteStorageGroups(List<String> storageGroups)` [...]
+| 4 | Create Database | `void setStorageGroup(String storageGroupId)` [...]
+| 5 | Delete database | `void deleteStorageGroup(String storageGroup) void deleteStorageGroups(List<String> storageGroups)` [...]
| 6 | Create timeseries | `void createTimeseries(String path, TSDataType dataType,TSEncoding encoding, CompressionType compressor, Map<String, String> props,Map<String, String> tags, Map<String, String> attributes, String measurementAlias) void createMultiTimeseries(List<String> paths, List<TSDataType> dataTypes,List<TSEncoding> encodings, List<CompressionType> compressors,List<Map<String, String>> propsList, List<Map<String, String>> tagsList,Li [...]
| 7 | Create aligned timeseries | `void createAlignedTimeseries(String prefixPath, List<String> measurements,List<TSDataType> dataTypes, List<TSEncoding> encodings,CompressionType compressor, List<String> measurementAliasList);` [...]
| 8 | Delete timeseries | `void deleteTimeseries(String path) void deleteTimeseries(List<String> paths)` [...]
| 9 | Detect whether the timeseries exists | `boolean checkTimeseriesExists(String path)` [...]
-| 10 | Metadata template | `public void createSchemaTemplate(Template template);` [...]
+| 10 | Schema template | `public void createSchemaTemplate(Template template);` [...]
| 11 | Insert tablet | `void insertTablet(Tablet tablet) void insertTablets(Map<String, Tablet> tablets)` [...]
| 12 | Insert record | `void insertRecord(String prefixPath, long time, List<String> measurements,List<TSDataType> types, List<Object> values) void insertRecords(List<String> deviceIds,List<Long> times,List<List<String>> measurementsList,List<List<TSDataType>> typesList,List<List<Object>> valuesList) void insertRecordsOfOneDevice(String deviceId, List<Long> times,List<List<Object>> valuesList)` [...]
| 13 | Write with type inference | `void insertRecord(String prefixPath, long time, List<String> measurements, List<String> values) void insertRecords(List<String> deviceIds, List<Long> times,List<List<String>> measurementsList, List<List<String>> valuesList) void insertStringRecordsOfOneDevice(String deviceId, List<Long> times,List<List<String>> measurementsList, List<List<String>> valuesList)` [...]
diff --git a/src/UserGuide/V1.1.x/API/Programming-Cpp-Native-API.md b/src/UserGuide/V1.1.x/API/Programming-Cpp-Native-API.md
index 5bce978..1add31b 100644
--- a/src/UserGuide/V1.1.x/API/Programming-Cpp-Native-API.md
+++ b/src/UserGuide/V1.1.x/API/Programming-Cpp-Native-API.md
@@ -369,7 +369,7 @@ void deleteData(const std::vector<std::string> &deviceId, int64_t time);
- Execute query statement
```cpp
-void executeNonQueryStatement(const std::string &sql);
+unique_ptr<SessionDataSet> executeQueryStatement(const std::string &sql);
```
- Execute non query statement
diff --git a/src/UserGuide/V1.1.x/API/Programming-Python-Native-API.md b/src/UserGuide/V1.1.x/API/Programming-Python-Native-API.md
index 7daf09f..d330607 100644
--- a/src/UserGuide/V1.1.x/API/Programming-Python-Native-API.md
+++ b/src/UserGuide/V1.1.x/API/Programming-Python-Native-API.md
@@ -326,7 +326,7 @@ session.execute_statement(sql)
### Schema Template
#### Create Schema Template
-The step for creating a metadata template is as follows
+The step for creating a schema template is as follows
1. Create the template class
2. Adding child Node，InternalNode and MeasurementNode can be chose
3. Execute create schema template function
@@ -405,7 +405,7 @@ session.show_paths_template_using_on(template_name)
```
#### Drop Schema Template
-Delete an existing metadata template，dropping an already set template is not supported
+Delete an existing schema template，dropping an already set template is not supported
```python
session.drop_schema_template("template_python")
```
diff --git a/src/UserGuide/V1.1.x/Operate-Metadata/Template.md b/src/UserGuide/V1.1.x/Operate-Metadata/Template.md
index 194bb4e..d6ead76 100644
--- a/src/UserGuide/V1.1.x/Operate-Metadata/Template.md
+++ b/src/UserGuide/V1.1.x/Operate-Metadata/Template.md
@@ -27,7 +27,7 @@ Note: The `schema` keyword in the following statements can be omitted.
## Create Schema Template
-The SQL syntax for creating a metadata template is as follows:
+The SQL syntax for creating a schema template is as follows:
```sql
CREATE SCHEMA TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
diff --git a/src/UserGuide/V1.2.x/API/Programming-Cpp-Native-API.md b/src/UserGuide/V1.2.x/API/Programming-Cpp-Native-API.md
index e43a45f..dd38ce2 100644
--- a/src/UserGuide/V1.2.x/API/Programming-Cpp-Native-API.md
+++ b/src/UserGuide/V1.2.x/API/Programming-Cpp-Native-API.md
@@ -30,19 +30,18 @@
- OpenSSL 1.0+
- GCC 5.5.0+
-
## Installation From Source Code
### Install CPP Dependencies
- **MAC**
- 1. Install Bison ：Bison 2.3 is preinstalled on OSX, but this version is too low.
+ 1. Install Bison ：Bison 2.3 is preinstalled on OSX, but this version is outdated, and we need a newer version.
- When building Thrift with Bison 2.3, the following error would pop out:
+ When building Thrift with Bison 2.3, the following error would be shown in the build output:
```invalid directive: '%code'```
- For such case, please update `Bison`:
+ In such a case, please update `Bison`:
```shell
brew install bison
brew link bison --force
@@ -67,7 +66,7 @@
brew link boost
```
- 3. OpenSSL ：Make sure the Openssl libraries has been install on your Mac. The default Openssl include file search path is "/usr/local/opt/openssl/include".
+ 3. OpenSSL ：Make sure the Openssl libraries has been installed on your Mac. The default Openssl include file search path is "/usr/local/opt/openssl/include".
If Openssl header files can not be found when building Thrift, please add option`-Dopenssl.include.dir=""`.
@@ -100,11 +99,11 @@
2. Download and install `Flex` & `Bison`
* Download [Win_Flex_Bison](https://sourceforge.net/projects/winflexbison/) .
- * After downloaded, please rename the executables to `flex.exe` and `bison.exe` and add them to "PATH" environment variables.
+ * After downloading, please rename the executables to `flex.exe` and `bison.exe` and add the directory containing them to the `PATH` environment variable.
3. Install `Boost`
* Download [Boost](https://www.boost.org/users/download/) .
- * Then build `Boost` by executing bootstrap.bat and b2.exe.
+ * Then build `Boost` by executing `bootstrap.bat` and `b2.exe`.
4. Install `OpenSSL`
* Download and install [OpenSSL](http://slproweb.com/products/Win32OpenSSL.html) .
@@ -112,66 +111,66 @@
### Compile
-You can download the source code from:
+You can download the source code from the [IoTDB Website](https://iotdb.apache.org/Download/) or clone the GIT repository:
```shell
git clone https://github.com/apache/iotdb.git
```
-The default dev branch is the master branch, If you want to use a released version (eg. `rel/0.13`):
+The default dev branch is the master branch, If you want to use a released version (e.g. `0.13.3` or `1.2.0`), be sure to check out the corresponding tag:
```shell
-git checkout rel/0.13
+git checkout v0.13.3
```
+(Please note that we are using a `Go` compatible naming schema for our release tags, which prefixes the version by a `v`)
Under the root path of iotdb:
-- Mac & Linux
+- Mac & Linux:
```shell
mvn package -P compile-cpp -pl example/client-cpp-example -am -DskipTest
```
-- Windows
+- Windows:
```shell
mvn package -P compile-cpp -pl iotdb-client/client-cpp,iotdb-core/datanode,example/client-cpp-example -am -Dcmake.generator="your cmake generator" -Dboost.include.dir=${your boost header folder} -Dboost.library.dir=${your boost lib (stage) folder} -DskipTests
```
- - When building client-cpp project, use `-Dcmake.generator=""` option to specify a Cmake generator. E.g. `-Dcmake.generator="Visual Studio 16 2019"` (`cmake --help` shows a long list of supported Cmake generators.)
- - To help CMake find your Boost libraries on windows, you should set `-DboostIncludeDir="C:\Program Files (x86)\boost_1_78_0" -DboostLibraryDir="C:\Program Files (x86)\boost_1_78_0\stage\lib"` to your mvn build command.
+ - When building the client-cpp project, use the `-Dcmake.generator=""` option to specify a Cmake generator. E.g. `-Dcmake.generator="Visual Studio 16 2019"` (`cmake --help` shows a long list of supported Cmake generators.)
+ - To help CMake find your Boost libraries on windows, you should also append `-DboostIncludeDir="C:\Program Files (x86)\boost_1_78_0" -DboostLibraryDir="C:\Program Files (x86)\boost_1_78_0\stage\lib"` to your mvn build command.
``
-If the compilation finishes successfully, the packaged zip file will be placed under `client-cpp/target/client-cpp-1.3.0-SNAPSHOT-cpp-${os}.zip`
-
+As soon as the compilation finishes successfully, the packaged zip file will be placed under `client-cpp/target/client-cpp-1.3.0-SNAPSHOT-cpp-${os}.zip`
## Native APIs
-Here we show the commonly used interfaces and their parameters in the Native API:
+Here we demonstrate the most commonly used interfaces and their parameters in the Native API:
### Initialization
-- Open a Session
-```cpp
-void open();
-```
+- Open a Session:
+ ```cpp
+ void open();
+ ```
-- Open a session, with a parameter to specify whether to enable RPC compression
-```cpp
-void open(bool enableRPCCompression);
-```
-Notice: this RPC compression status of client must comply with that of IoTDB server
+- Open a session, with a parameter controlling if RPC compression should be used:
+ ```cpp
+ void open(bool enableRPCCompression);
+ ```
+ Notice: The RPC compression setting of the client is required to match that of the IoTDB server
-- Close a Session
-```cpp
-void close();
-```
+- Close a session:
+ ```cpp
+ void close();
+ ```
### Data Definition Interface (DDL)
#### Database Management
-- CREATE DATABASE
+- Create database:
```cpp
void setStorageGroup(const std::string &storageGroupId);
```
-- Delete one or several databases
+- Delete one or several databases:
```cpp
void deleteStorageGroup(const std::string &storageGroup);
void deleteStorageGroups(const std::vector<std::string> &storageGroups);
@@ -179,7 +178,7 @@ void deleteStorageGroups(const std::vector<std::string> &storageGroups);
#### Timeseries Management
-- Create one or multiple timeseries
+- Create one or multiple timeseries:
```cpp
void createTimeseries(const std::string &path, TSDataType::TSDataType dataType, TSEncoding::TSEncoding encoding,
CompressionType::CompressionType compressor);
@@ -194,7 +193,7 @@ void createMultiTimeseries(const std::vector<std::string> &paths,
std::vector<std::string> *measurementAliasList);
```
-- Create aligned timeseries
+- Create aligned timeseries:
```cpp
void createAlignedTimeseries(const std::string &deviceId,
const std::vector<std::string> &measurements,
@@ -203,35 +202,35 @@ void createAlignedTimeseries(const std::string &deviceId,
const std::vector<CompressionType::CompressionType> &compressors);
```
-- Delete one or several timeseries
+- Delete one or several timeseries:
```cpp
void deleteTimeseries(const std::string &path);
void deleteTimeseries(const std::vector<std::string> &paths);
```
-- Check whether the specific timeseries exists.
+- Check whether a specific timeseries exists:
```cpp
bool checkTimeseriesExists(const std::string &path);
```
#### Schema Template
-- Create a schema template
+- Create a schema template:
```cpp
void createSchemaTemplate(const Template &templ);
```
-- Set the schema template named `templateName` at path `prefixPath`.
+- Set the schema template named `templateName` at path `prefixPath`:
```cpp
void setSchemaTemplate(const std::string &template_name, const std::string &prefix_path);
```
-- Unset the schema template
+- Unset the schema template:
```cpp
void unsetSchemaTemplate(const std::string &prefix_path, const std::string &template_name);
```
-- After measurement template created, you can edit the template with belowed APIs.
+- After a schema template was created, you can edit the template with following functions:
```cpp
// Add aligned measurements to a template
void addAlignedMeasurementsInTemplate(const std::string &template_name,
@@ -265,7 +264,7 @@ void addUnalignedMeasurementsInTemplate(const std::string &template_name,
void deleteNodeInTemplate(const std::string &template_name, const std::string &path);
```
-- You can query measurement templates with these APIS:
+- You can query schema templates with these APIs:
```cpp
// Return the amount of measurements inside a template
int countMeasurementsInTemplate(const std::string &template_name);
@@ -282,84 +281,124 @@ std::vector<std::string> showMeasurementsInTemplate(const std::string &template_
// Return all measurements paths under the designated patter inside template
std::vector<std::string> showMeasurementsInTemplate(const std::string &template_name, const std::string &pattern);
```
-
-
-### Data Manipulation Interface (DML)
+### Data Manipulation Interface (DMI)
#### Insert
-> It is recommended to use insertTablet to help improve write efficiency.
-
-- Insert a Tablet，which is multiple rows of a device, each row has the same measurements
- - Better Write Performance
- - Support null values: fill the null value with any value, and then mark the null value via BitMap
-```cpp
-void insertTablet(Tablet &tablet);
-```
-
-- Insert multiple Tablets
-```cpp
-void insertTablets(std::unordered_map<std::string, Tablet *> &tablets);
-```
-
-- Insert a Record, which contains multiple measurement value of a device at a timestamp
+- Insert one record, which contains multiple measurement value of a given device and timestamp:
```cpp
-void insertRecord(const std::string &deviceId, int64_t time, const std::vector<std::string> &measurements,
- const std::vector<TSDataType::TSDataType> &types, const std::vector<char *> &values);
+void insertRecord(const std::string &deviceId,
+ int64_t time,
+ const std::vector<std::string> &measurements,
+ const std::vector<char *> &values);
```
-- Insert multiple Records
+- Insert multiple Records for multiple devices (With type info in the `typesList` parameter the server doesn't need to do type inference, which results in better performance):
```cpp
void insertRecords(const std::vector<std::string> &deviceIds,
const std::vector<int64_t> ×,
const std::vector<std::vector<std::string>> &measurementsList,
- const std::vector<std::vector<TSDataType::TSDataType>> &typesList,
const std::vector<std::vector<char *>> &valuesList);
```
-- Insert multiple Records that belong to the same device. With type info the server has no need to do type inference, which leads a better performance
+- Insert multiple Records for the same device:
```cpp
void insertRecordsOfOneDevice(const std::string &deviceId,
std::vector<int64_t> ×,
std::vector<std::vector<std::string>> &measurementsList,
- std::vector<std::vector<TSDataType::TSDataType>> &typesList,
std::vector<std::vector<char *>> &valuesList);
```
-#### Insert with type inference
-
-Without type information, server has to do type inference, which may cost some time.
+All of the above versions require the server to figure out the data-types of each value, which comes with quite a performance-cost, therefore all of the above are also available in a version without type-inference:
```cpp
-void insertRecord(const std::string &deviceId, int64_t time, const std::vector<std::string> &measurements,
+void insertRecord(const std::string &deviceId,
+ int64_t time,
+ const std::vector<std::string> &measurements,
+ const std::vector<TSDataType::TSDataType> &types,
const std::vector<std::string> &values);
void insertRecords(const std::vector<std::string> &deviceIds,
const std::vector<int64_t> ×,
const std::vector<std::vector<std::string>> &measurementsList,
+ const std::vector<std::vector<TSDataType::TSDataType>> &typesList,
const std::vector<std::vector<std::string>> &valuesList);
void insertRecordsOfOneDevice(const std::string &deviceId,
std::vector<int64_t> ×,
std::vector<std::vector<std::string>> &measurementsList,
+ std::vector<std::vector<TSDataType::TSDataType>> &typesList,
const std::vector<std::vector<std::string>> &valuesList);
```
+For even better performance, it is recommended to use Tablets to help improve write efficiency.
+
+- Insert a Tablet，which inserts multiple rows of data for a given device. Each row has the same structure:
+ - Better write performance
+ - Support null values: Fill the null value with any value, and then mark the null value via BitMap
+```cpp
+void insertTablet(Tablet &tablet);
+```
+
+- Insert multiple Tablets
+```cpp
+void insertTablets(std::unordered_map<std::string, Tablet *> &tablets);
+```
+
#### Insert data into Aligned Timeseries
-The Insert of aligned timeseries uses interfaces like `insertAlignedXXX`, and others are similar to the above interfaces:
+The insertion of aligned timeseries is performed by functions such as `insertAlignedXXX` however semantically they align to the non-aligned versions of the previous chapter:
+
+```cpp
+ void insertAlignedRecord(const std::string &deviceId,
+ int64_t time,
+ const std::vector<std::string> &measurements,
+ const std::vector<std::string> &values);
+
+ void insertAlignedRecord(const std::string &deviceId,
+ int64_t time,
+ const std::vector<std::string> &measurements,
+ const std::vector<TSDataType::TSDataType> &types,
+ const std::vector<char *> &values);
+
+ void insertAlignedRecords(const std::vector<std::string> &deviceIds,
+ const std::vector<int64_t> ×,
+ const std::vector<std::vector<std::string>> &measurementsList,
+ const std::vector<std::vector<std::string>> &valuesList);
-- insertAlignedRecord
-- insertAlignedRecords
-- insertAlignedRecordsOfOneDevice
-- insertAlignedTablet
-- insertAlignedTablets
+ void insertAlignedRecords(const std::vector<std::string> &deviceIds,
+ const std::vector<int64_t> ×,
+ const std::vector<std::vector<std::string>> &measurementsList,
+ const std::vector<std::vector<TSDataType::TSDataType>> &typesList,
+ const std::vector<std::vector<char *>> &valuesList);
+
+ void insertAlignedRecordsOfOneDevice(const std::string &deviceId,
+ std::vector<int64_t> ×,
+ std::vector<std::vector<std::string>> &measurementsList,
+ std::vector<std::vector<TSDataType::TSDataType>> &typesList,
+ std::vector<std::vector<char *>> &valuesList);
+
+ void insertAlignedRecordsOfOneDevice(const std::string &deviceId,
+ std::vector<int64_t> ×,
+ std::vector<std::vector<std::string>> &measurementsList,
+ std::vector<std::vector<TSDataType::TSDataType>> &typesList,
+ std::vector<std::vector<char *>> &valuesList,
+ bool sorted);
+
+ void insertAlignedTablet(Tablet &tablet);
+
+ void insertAlignedTablet(Tablet &tablet,
+ bool sorted);
+
+ void insertAlignedTablets(std::unordered_map<std::string, Tablet *> &tablets,
+ bool sorted = false);
+```
#### Delete
-- Delete data before or equal to a timestamp of one or several timeseries
+- Delete data with timestamps before or equal to a given timestamp of one or several timeseries:
```cpp
void deleteData(const std::string &path, int64_t time);
void deleteData(const std::vector<std::string> &deviceId, int64_t time);
@@ -368,24 +407,28 @@ void deleteData(const std::vector<std::string> &deviceId, int64_t time);
### IoTDB-SQL Interface
- Execute query statement
+
+Query statements return data.
+
```cpp
-void executeNonQueryStatement(const std::string &sql);
+unique_ptr<SessionDataSet> executeQueryStatement(const std::string &sql);
```
+Non-Query statements don't return data (Delete, Create, ... statements)
+
- Execute non query statement
```cpp
void executeNonQueryStatement(const std::string &sql);
```
-
## Examples
-The sample code of using these interfaces is in:
+The sample code for using these interfaces is located in:
- `example/client-cpp-example/src/SessionExample.cpp`
-- `example/client-cpp-example/src/AlignedTimeseriesSessionExample.cpp` （使用对齐时间序列）
+- `example/client-cpp-example/src/AlignedTimeseriesSessionExample.cpp`
-If the compilation finishes successfully, the example project will be placed under `example/client-cpp-example/target`
+As soon as the compilation finishes, the example project will be located at `example/client-cpp-example/target`
## FAQ
@@ -395,15 +438,16 @@ If errors occur when compiling thrift source code, try to downgrade your xcode-c
see https://stackoverflow.com/questions/63592445/ld-unsupported-tapi-file-type-tapi-tbd-in-yaml-file/65518087#65518087
-
### on Windows
When Building Thrift and downloading packages via "wget", a possible annoying issue may occur with
error message looks like:
+
```shell
Failed to delete cached file C:\Users\Administrator\.m2\repository\.cache\download-maven-plugin\index.ser
```
+
Possible fixes:
-- Try to delete the ".m2\repository\\.cache\" directory and try again.
+- Try to delete the ".m2\repository\.cache\" directory and try again.
- Add "\<skipCache>true\</skipCache>" configuration to the download-maven-plugin maven phase that complains this error.
diff --git a/src/UserGuide/V1.2.x/API/Programming-Python-Native-API.md b/src/UserGuide/V1.2.x/API/Programming-Python-Native-API.md
index 4905cf0..0cc1c5e 100644
--- a/src/UserGuide/V1.2.x/API/Programming-Python-Native-API.md
+++ b/src/UserGuide/V1.2.x/API/Programming-Python-Native-API.md
@@ -353,7 +353,7 @@ session.execute_statement(sql)
## Schema Template
### Create Schema Template
-The step for creating a metadata template is as follows
+The step for creating a schema template is as follows
1. Create the template class
2. Adding MeasurementNode
3. Execute create schema template function
@@ -429,7 +429,7 @@ session.show_paths_template_using_on(template_name)
```
### Drop Schema Template
-Delete an existing metadata template，dropping an already set template is not supported
+Delete an existing schema template，dropping an already set template is not supported
```python
session.drop_schema_template("template_python")
```
diff --git a/src/UserGuide/V1.2.x/QuickStart/QuickStart.md b/src/UserGuide/V1.2.x/QuickStart/QuickStart.md
index dec3bea..7d08ee4 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 installed 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](../stage/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 is set up 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 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 along with 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.
+In the `INTO` part we tell IoTDB which timeseries we want to store the data in as well as which fields we'll be filling.
+Please note, that the timestamp field is mandatory for this step and that we don't necessarily have to fill all fields defined of the timeseries we're inserting into:
```
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](../SQL-Manual/SQL-Manual.md).
+For more information on which commands are supported by `IoTDB SQL`, please see [SQL Reference](../SQL-Manual/SQL-Manual.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](../stage/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 recommend 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](../User-Manual/Security-Management.md)
-
+More about administration options：[Administration Management](../User-Manual/Security-Management.md)
## 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`).
diff --git a/src/UserGuide/V1.2.x/User-Manual/Operate-Metadata.md b/src/UserGuide/V1.2.x/User-Manual/Operate-Metadata.md
index e1b1606..e29a98c 100644
--- a/src/UserGuide/V1.2.x/User-Manual/Operate-Metadata.md
+++ b/src/UserGuide/V1.2.x/User-Manual/Operate-Metadata.md
@@ -317,7 +317,7 @@ Note: The `schema` keyword in the following statements can be omitted.
### Create Schema Template
-The SQL syntax for creating a metadata template is as follows:
+The SQL syntax for creating a schema template is as follows:
```sql
CREATE SCHEMA TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
diff --git a/src/UserGuide/V1.2.x/stage/Interface-Comparison.md b/src/UserGuide/V1.2.x/stage/Interface-Comparison.md
index e50780b..4907b82 100644
--- a/src/UserGuide/V1.2.x/stage/Interface-Comparison.md
+++ b/src/UserGuide/V1.2.x/stage/Interface-Comparison.md
@@ -26,17 +26,17 @@ This chapter mainly compares the differences between Java Native API and python
| Order | API name and function | Java API [...]
-| ----- | ------------------------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
+| ----- |---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
| 1 | Initialize session | `Session.Builder.build(); Session.Builder().host(String host).port(int port).build(); Session.Builder().nodeUrls(List<String> nodeUrls).build(); Session.Builder().fetchSize(int fetchSize).username(String username).password(String password).thriftDefaultBufferSize(int thriftDefaultBufferSize).thriftMaxFrameSize(int thriftMaxFrameSize).enableRedirection(boolean enableCacheLeader).version(Version version).build();` [...]
| 2 | Open session | `void open() void open(boolean enableRPCCompression)` [...]
| 3 | Close session | `void close()` [...]
-| 4 | Create Database | `void setStorageGroup(String storageGroupId)` [...]
-| 5 | Delete database | `void deleteStorageGroup(String storageGroup) void deleteStorageGroups(List<String> storageGroups)` [...]
+| 4 | Create Database | `void setStorageGroup(String storageGroupId)` [...]
+| 5 | Delete database | `void deleteStorageGroup(String storageGroup) void deleteStorageGroups(List<String> storageGroups)` [...]
| 6 | Create timeseries | `void createTimeseries(String path, TSDataType dataType,TSEncoding encoding, CompressionType compressor, Map<String, String> props,Map<String, String> tags, Map<String, String> attributes, String measurementAlias) void createMultiTimeseries(List<String> paths, List<TSDataType> dataTypes,List<TSEncoding> encodings, List<CompressionType> compressors,List<Map<String, String>> propsList, List<Map<String, String>> tagsList,Li [...]
| 7 | Create aligned timeseries | `void createAlignedTimeseries(String prefixPath, List<String> measurements,List<TSDataType> dataTypes, List<TSEncoding> encodings,CompressionType compressor, List<String> measurementAliasList);` [...]
| 8 | Delete timeseries | `void deleteTimeseries(String path) void deleteTimeseries(List<String> paths)` [...]
| 9 | Detect whether the timeseries exists | `boolean checkTimeseriesExists(String path)` [...]
-| 10 | Metadata template | `public void createSchemaTemplate(Template template);` [...]
+| 10 | Schema template | `public void createSchemaTemplate(Template template);` [...]
| 11 | Insert tablet | `void insertTablet(Tablet tablet) void insertTablets(Map<String, Tablet> tablets)` [...]
| 12 | Insert record | `void insertRecord(String prefixPath, long time, List<String> measurements,List<TSDataType> types, List<Object> values) void insertRecords(List<String> deviceIds,List<Long> times,List<List<String>> measurementsList,List<List<TSDataType>> typesList,List<List<Object>> valuesList) void insertRecordsOfOneDevice(String deviceId, List<Long> times,List<List<Object>> valuesList)` [...]
| 13 | Write with type inference | `void insertRecord(String prefixPath, long time, List<String> measurements, List<String> values) void insertRecords(List<String> deviceIds, List<Long> times,List<List<String>> measurementsList, List<List<String>> valuesList) void insertStringRecordsOfOneDevice(String deviceId, List<Long> times,List<List<String>> measurementsList, List<List<String>> valuesList)` [...]
diff --git a/src/UserGuide/V1.2.x/stage/Operate-Metadata/Template.md b/src/UserGuide/V1.2.x/stage/Operate-Metadata/Template.md
index 25768b4..68757a2 100644
--- a/src/UserGuide/V1.2.x/stage/Operate-Metadata/Template.md
+++ b/src/UserGuide/V1.2.x/stage/Operate-Metadata/Template.md
@@ -27,7 +27,7 @@ Note: The `schema` keyword in the following statements can be omitted.
## Create Schema Template
-The SQL syntax for creating a metadata template is as follows:
+The SQL syntax for creating a schema template is as follows:
```sql
CREATE SCHEMA TEMPLATE <templateName> ALIGNED? '(' <measurementId> <attributeClauses> [',' <measurementId> <attributeClauses>]+ ')'
diff --git a/src/zh/UserGuide/Master/API/Programming-Cpp-Native-API.md b/src/zh/UserGuide/Master/API/Programming-Cpp-Native-API.md
index 5a24e46..7637434 100644
--- a/src/zh/UserGuide/Master/API/Programming-Cpp-Native-API.md
+++ b/src/zh/UserGuide/Master/API/Programming-Cpp-Native-API.md
@@ -24,7 +24,7 @@
## 依赖
- Java 8+
-- Maven 3.5+
+- Maven 3.9+
- Flex
- Bison 2.7+
- Boost 1.56+
@@ -364,7 +364,7 @@ void deleteData(const std::vector<std::string> &deviceId, int64_t time);
- 执行查询语句
```cpp
-void executeNonQueryStatement(const std::string &sql);
+unique_ptr<SessionDataSet> executeQueryStatement(const std::string &sql);
```
- 执行非查询语句
diff --git a/src/zh/UserGuide/V0.13.x/API/Programming-Cpp-Native-API.md b/src/zh/UserGuide/V0.13.x/API/Programming-Cpp-Native-API.md
index b65fb85..d373ab4 100644
--- a/src/zh/UserGuide/V0.13.x/API/Programming-Cpp-Native-API.md
+++ b/src/zh/UserGuide/V0.13.x/API/Programming-Cpp-Native-API.md
@@ -364,7 +364,7 @@ void deleteData(const std::vector<std::string> &deviceId, int64_t time);
- 执行查询语句
```cpp
-void executeNonQueryStatement(const std::string &sql);
+unique_ptr<SessionDataSet> executeQueryStatement(const std::string &sql);
```
- 执行非查询语句
diff --git a/src/zh/UserGuide/V1.1.x/API/Programming-Cpp-Native-API.md b/src/zh/UserGuide/V1.1.x/API/Programming-Cpp-Native-API.md
index 5eb4403..87f4c32 100644
--- a/src/zh/UserGuide/V1.1.x/API/Programming-Cpp-Native-API.md
+++ b/src/zh/UserGuide/V1.1.x/API/Programming-Cpp-Native-API.md
@@ -364,7 +364,7 @@ void deleteData(const std::vector<std::string> &deviceId, int64_t time);
- 执行查询语句
```cpp
-void executeNonQueryStatement(const std::string &sql);
+unique_ptr<SessionDataSet> executeQueryStatement(const std::string &sql);
```
- 执行非查询语句
diff --git a/src/zh/UserGuide/V1.2.x/API/Programming-Cpp-Native-API.md b/src/zh/UserGuide/V1.2.x/API/Programming-Cpp-Native-API.md
index 5a24e46..5c4037d 100644
--- a/src/zh/UserGuide/V1.2.x/API/Programming-Cpp-Native-API.md
+++ b/src/zh/UserGuide/V1.2.x/API/Programming-Cpp-Native-API.md
@@ -364,7 +364,7 @@ void deleteData(const std::vector<std::string> &deviceId, int64_t time);
- 执行查询语句
```cpp
-void executeNonQueryStatement(const std::string &sql);
+unique_ptr<SessionDataSet> executeQueryStatement(const std::string &sql);
```
- 执行非查询语句