This is an automated email from the ASF dual-hosted git repository.
haonan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iotdb.git
The following commit(s) were added to refs/heads/master by this push:
new c648e5a Refactor the user documents of `API` (#3032)
c648e5a is described below
commit c648e5a7399c614c05ea3af8f645b4e802fbae49
Author: Steve Yurong Su <[email protected]>
AuthorDate: Tue Apr 20 11:51:11 2021 +0800
Refactor the user documents of `API` (#3032)
---
...-Languages.md => Programming-Cpp-Native-API.md} | 111 +++++------
docs/UserGuide/API/Programming-Go-Native-API.md | 65 ++++++
docs/UserGuide/API/Programming-JDBC.md | 12 +-
...ative-API.md => Programming-Java-Native-API.md} | 108 +++++-----
.../UserGuide/API/Programming-Python-Native-API.md | 207 +++++++++++++++++++
docs/UserGuide/API/Programming-TsFile-API.md | 159 ++++++++-------
.../DML-Data-Manipulation-Language.md | 2 +-
...-Languages.md => Programming-Cpp-Native-API.md} | 122 +++---------
docs/zh/UserGuide/API/Programming-Go-Native-API.md | 65 ++++++
docs/zh/UserGuide/API/Programming-JDBC.md | 16 +-
...ative-API.md => Programming-Java-Native-API.md} | 89 +++++----
.../UserGuide/API/Programming-Python-Native-API.md | 220 +++++++++++++++++++++
docs/zh/UserGuide/API/Programming-TsFile-API.md | 156 ++++++++-------
site/src/main/.vuepress/config.js | 16 +-
14 files changed, 934 insertions(+), 414 deletions(-)
diff --git a/docs/UserGuide/API/Programming-Other-Languages.md
b/docs/UserGuide/API/Programming-Cpp-Native-API.md
similarity index 83%
rename from docs/UserGuide/API/Programming-Other-Languages.md
rename to docs/UserGuide/API/Programming-Cpp-Native-API.md
index 83c2b75..a732148 100644
--- a/docs/UserGuide/API/Programming-Other-Languages.md
+++ b/docs/UserGuide/API/Programming-Cpp-Native-API.md
@@ -18,47 +18,7 @@
under the License.
-->
-
-
-## Python Native Dependencies
-
-
-### Dependencies
-
-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:
-
-```
-http://thrift.apache.org/docs/install/
-```
-
-### Installation
-
-* Option 1: pip install
-
-You can find the Apache IoTDB Python Client API package on
https://pypi.org/project/apache-iotdb/.
-
-The download command is:
-
-```
-pip install apache-iotdb
-```
-
-* Option 2: basic usage of thrift
-
-Optionally, if you know the basic usage of thrift, you can download the thrift
source file in
-`thrift\src\main\thrift\rpc.thrift`, and simply run `thrift -gen py -out
./target/iotdb rpc.thrift`
-to generate the Python library.
-
-### Coding Example
-
-We provided an example of how to use the thrift library to connect to IoTDB in
`client-py/src
-/SessionExample.py`, please read it carefully before you write your own code.
-
-
-## C++ Native Interfaces
+## C++ Native API
### Dependencies
- Java 8+
@@ -68,48 +28,54 @@ We provided an example of how to use the thrift library to
connect to IoTDB in `
- Boost
- OpenSSL 1.0+
+
+
### Installation
The compilation of CPP client requires the module "compile-tools" to be built
first.
"compile-tools" is mainly responsible for building Thrift libraries locally.
+
+
#### Build Thrift on MacOS
- 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:
+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:
+
+
+```shell
invalid directive: '%code'
```
-
-For such case, please update `Bison`:
-
+
+For such case, please update `Bison`:
```
brew install bison
brew link bison --force
```
-
- Then, you need to tell the OS where the new bison is.
-
- For Bash users:
-```
+
+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:
-```
+
+For zsh users:
+``` shell
echo 'export PATH="/usr/local/opt/bison/bin:$PATH"' >> ~/.zshrc
```
- 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
```
@@ -125,21 +91,25 @@ If Openssl header files can not be found when building
Thrift, please add option
to specify the OpenSSL installation directory on your Mac.
+
+
#### Build Thrift on Linux
To install all dependencies, run:
Debian/Ubuntu:
-```
+```shell
sudo apt-get install gcc g++ bison flex libboost-all-dev
```
CentOS:
-```
+```shell
yum install gcc g++ bison flex boost-devel
```
+
+
#### Build Thrift on Windows
Make sure a complete Windows C++ building environment is prepared on your
machine.
@@ -156,7 +126,7 @@ After downloaded, please rename the executables to flex.exe
and bison.exe and ad
For Boost, please download from the official website:
https://www.boost.org/users/download/
Then build Boost by executing bootstrap.bat and b2.exe.
-```
+```powershell
bootstrap.bat
.\b2.exe
```
@@ -164,6 +134,8 @@ bootstrap.bat
To help CMake find your Boost libraries on windows, you should set
`-Dboost.include.dir=${your boost header folder} -Dboost.library.dir=${your
boost lib (stage) folder}`
to your mvn build command.
+
+
#### Cmake generator on Windows
There is a long list of supported Cmake generators on Windows environment.
@@ -198,8 +170,6 @@ There is a long list of supported Cmake generators on
Windows environment.
Watcom WMake = Generates Watcom WMake makefiles.
CodeBlocks - MinGW Makefiles = Generates CodeBlocks project files.
CodeBlocks - NMake Makefiles = Generates CodeBlocks project files.
- CodeBlocks - NMake Makefiles = Generates CodeBlocks project fi
-
```
the list is available via command: `cmake --help`
@@ -207,6 +177,8 @@ When building client-cpp project, use -Dcmake.generator=""
option to specify a C
E.g., `mvn package -Dcmake.generator="Visual Studio 15 2017 [arch]"`
+
+
#### Building C++ Client
@@ -214,18 +186,20 @@ To compile cpp client, add "-P compile-cpp" option to
maven build command.
The compiling requires the module "compile-tools" to be built first.
-#### Compile and Test:
+
+
+#### Compile and Test
`mvn package -P compile-cpp -pl example/client-cpp-example -am -DskipTest`
To compile on Windows, please install Boost first and add following Maven
settings:
-```
+```shell
-Dboost.include.dir=${your boost header folder} -Dboost.library.dir=${your
boost lib (stage) folder}`
```
e.g.,
-```
+```shell
mvn package -P compile-cpp -pl client-cpp,server,example/client-cpp-example
-am
-D"boost.include.dir"="D:\boost_1_75_0"
-D"boost.library.dir"="D:\boost_1_75_0\stage\lib" -DskipTests
```
@@ -235,7 +209,7 @@ If the compilation finishes successfully, the packaged zip
file will be placed u
On Mac machines, the hierarchy of the package should look like this:
-```
+```shell
.
+-- client
| +-- include
@@ -259,13 +233,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.
- Add "\<skipCache>true\</skipCache>" configuration to the
download-maven-plugin maven phase that complains this error.
+
diff --git a/docs/UserGuide/API/Programming-Go-Native-API.md
b/docs/UserGuide/API/Programming-Go-Native-API.md
new file mode 100644
index 0000000..7681850
--- /dev/null
+++ b/docs/UserGuide/API/Programming-Go-Native-API.md
@@ -0,0 +1,65 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+## Go Native API
+
+### Dependencies
+
+ * golang >= 1.13
+ * make >= 3.0
+ * curl >= 7.1.1
+ * thrift 0.13.x
+ * Linux、Macos or other unix-like systems
+ * Windows+bash (WSL、cygwin、Git Bash)
+
+
+
+
+### Installation
+
+ * go mod
+
+```sh
+export GO111MODULE=on
+export GOPROXY=https://goproxy.io
+
+mkdir session_example && cd session_example
+
+curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
+
+go mod init session_example
+go run session_example.go
+```
+
+* GOPATH
+
+```sh
+# get thrift 0.13.0
+go get github.com/apache/thrift
+cd $GOPATH/src/github.com/apache/thrift
+git checkout 0.13.0
+
+mkdir -p $GOPATH/src/iotdb-client-go-example/session_example
+cd $GOPATH/src/iotdb-client-go-example/session_example
+curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
+go run session_example.go
+```
+
diff --git a/docs/UserGuide/API/Programming-JDBC.md
b/docs/UserGuide/API/Programming-JDBC.md
index f8eebda..d4ac83c 100644
--- a/docs/UserGuide/API/Programming-JDBC.md
+++ b/docs/UserGuide/API/Programming-JDBC.md
@@ -19,8 +19,6 @@
-->
-# Application Program Interface (API)
-
## JDBC
### Dependencies
@@ -28,17 +26,21 @@
* JDK >= 1.8
* Maven >= 3.6
+
+
### Installation
In root directory:
-```
+```shell
mvn clean install -pl jdbc -am -Dmaven.test.skip=true
```
+
+
### Use IoTDB JDBC with Maven
-```
+```xml
<dependencies>
<dependency>
<groupId>org.apache.iotdb</groupId>
@@ -49,6 +51,7 @@ mvn clean install -pl 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.
@@ -201,3 +204,4 @@ public class JDBCExample {
}
}
```
+
diff --git a/docs/UserGuide/API/Programming-Native-API.md
b/docs/UserGuide/API/Programming-Java-Native-API.md
similarity index 94%
rename from docs/UserGuide/API/Programming-Native-API.md
rename to docs/UserGuide/API/Programming-Java-Native-API.md
index ab763d7..1586ff7 100644
--- a/docs/UserGuide/API/Programming-Native-API.md
+++ b/docs/UserGuide/API/Programming-Java-Native-API.md
@@ -26,14 +26,18 @@
* JDK >= 1.8
* Maven >= 3.6
+
+
### Installation
In root directory:
> mvn clean install -pl session -am -DskipTests
+
+
### Using IoTDB Java Native API with Maven
-```
+```xml
<dependencies>
<dependency>
<groupId>org.apache.iotdb</groupId>
@@ -44,13 +48,14 @@ In root directory:
```
+
### Native APIs
Here we show the commonly used interfaces and their parameters in the Native
API:
* Initialize a Session
-```
+```java
Session(String host, int rpcPort)
Session(String host, String rpcPort, String username, String password)
@@ -60,32 +65,32 @@ Session(String host, int rpcPort, String username, String
password)
* Open a Session
-```
+```java
Session.open()
```
* Close a Session
+```java
+Session.close()
```
-Session.close()
-```
-
+
* Set storage group
-```
+```java
void setStorageGroup(String storageGroupId)
```
* Delete one or several storage groups
-```
+```java
void deleteStorageGroup(String storageGroup)
void deleteStorageGroups(List<String> storageGroups)
```
* Create one or multiple timeseries
-```
+```java
void createTimeseries(String path, TSDataType dataType,
TSEncoding encoding, CompressionType compressor, Map<String, String>
props,
Map<String, String> tags, Map<String, String> attributes, String
measurementAlias)
@@ -98,53 +103,53 @@ void createMultiTimeseries(List<String> paths,
List<TSDataType> dataTypes,
* Delete one or several timeseries
-```
+```java
void deleteTimeseries(String path)
void deleteTimeseries(List<String> paths)
```
* Delete data before or equal to a timestamp of one or several timeseries
-```
+```java
void deleteData(String path, long time)
void deleteData(List<String> paths, long time)
```
* Insert a Record，which contains multiple measurement value of a device at a
timestamp. Without type info the server has to do type inference, which may
cost some time
-```
+```java
void insertRecord(String deviceId, long time, List<String> measurements,
List<String> values)
```
* Insert a Tablet，which is multiple rows of a device, each row has the same
measurements
-```
+```java
void insertTablet(Tablet tablet)
```
* Insert multiple Tablets
-```
+```java
void insertTablets(Map<String, Tablet> tablet)
```
-
+
* Insert multiple Records. Without type info the server has to do type
inference, which may cost some time
-```
+```java
void insertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList, List<List<String>>
valuesList)
```
-
-* Insert a Record，which contains multiple measurement value of a device at a
timestamp. With type info the server has no need to do type inference, which
leads a better performance
-```
+* Insert a Record, which contains multiple measurement value of a device at a
timestamp. With type info the server has no need to do type inference, which
leads a better performance
+
+```java
void insertRecord(String deviceId, long time, List<String> measurements,
List<TSDataType> types, List<Object> values)
```
* Insert multiple Records. With type info the server has no need to do type
inference, which leads a better performance
-```
+```java
void insertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList, List<List<TSDataType>> typesList,
List<List<Object>> valuesList)
@@ -152,40 +157,42 @@ void insertRecords(List<String> deviceIds, List<Long>
times,
* 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
-```
+```java
void insertRecordsOfOneDevice(String deviceId, List<Long> times,
List<List<String>> measurementsList, List<List<TSDataType>> typesList,
List<List<Object>> valuesList)
```
-
+
* Raw data query. Time interval include startTime and exclude endTime
-```
+```java
SessionDataSet executeRawDataQuery(List<String> paths, long startTime, long
endTime)
```
* Execute query statement
-```
+```java
SessionDataSet executeQueryStatement(String sql)
```
-
+
* Execute non query statement
-```
+```java
void executeNonQueryStatement(String sql)
```
+
+
### Native APIs for profiling network cost
* Test the network and client cost of insertRecords. This method NOT insert
data into database and server just return after accept the request, this method
should be used to test other time cost in client
-```
+```java
void testInsertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList, List<List<String>>
valuesList)
```
or
-```
+```java
void testInsertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList, List<List<TSDataType>> typesList,
List<List<Object>> valuesList)
@@ -195,36 +202,40 @@ void testInsertRecords(List<String> deviceIds, List<Long>
times,
This method NOT insert data into database and server just return after accept
the request,
this method should be used to test other time cost in client
-```
+```java
void testInsertRecordsOfOneDevice(String deviceId, List<Long> times,
List<List<String>> measurementsList, List<List<TSDataType>> typesList,
List<List<Object>> valuesList)
-```
+```
* Test the network and client cost of insertRecord. This method NOT insert
data into database and server just return after accept the request, this method
should be used to test other time cost in client
-```
+```java
void testInsertRecord(String deviceId, long time, List<String> measurements,
List<String> values)
```
or
-```
+```java
void testInsertRecord(String deviceId, long time, List<String> measurements,
List<TSDataType> types, List<Object> values)
```
* Test the network and client cost of insertTablet. This method NOT insert
data into database and server just return after accept the request, this method
should be used to test other time cost in client
-```
+```java
void testInsertTablet(Tablet tablet)
```
-
-### Coding example
+
+
+
+### 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.
+
+
### Session Pool for Native API
We provide a connection pool (`SessionPool) for Native API.
@@ -250,16 +261,18 @@ Examples:
```session/src/test/java/org/apache/iotdb/session/pool/SessionPoolTest
Or `example/session/src/main/java/org/apache/iotdb/SessionPoolExample.java`
+
+
### New Interfaces
-```
+```java
void open(boolean enableRPCCompression)
```
Open a session, with a parameter to specify whether to enable RPC compression.
Please pay attention that this RPC compression status of client must comply
with the status of IoTDB server
-```
+```java
void insertRecord(String deviceId, long time, List<String> measurements,
List<TSDataType> types, List<Object> values)
```
@@ -267,32 +280,32 @@ void insertRecord(String deviceId, long time,
List<String> measurements,
Insert one record, in a way that user has to provide the type information of
each measurement, which is different from the original insertRecord() interface.
The values should be provided in their primitive types. This interface is more
proficient than the one without type parameters.
-```
+```java
void insertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList,
List<List<TSDataType>> typesList, List<List<Object>>
valuesList)
```
Insert multiple records with type parameters. This interface is more
proficient than the one without type parameters.
-```
+```java
void insertTablet(Tablet tablet, boolean sorted)
```
An additional insertTablet() interface that providing a "sorted" parameter
indicating if the tablet is in order. A sorted tablet may accelerate the
insertion process.
-```
+```java
void insertTablets(Map<String, Tablet> tablets)
```
A new insertTablets() for inserting multiple tablets.
-```
+```java
void insertTablets(Map<String, Tablet> tablets, boolean sorted)
```
insertTablets() with an additional "sorted" parameter.
-```
+```java
void testInsertRecord(String deviceId, long time, List<String> measurements,
List<TSDataType> types,
List<Object> values)
void testInsertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList,
@@ -304,7 +317,7 @@ void testInsertTablets(Map<String, Tablet> tablets, boolean
sorted)
The above interfaces are newly added to test responsiveness of new insert
interfaces.
-```
+```java
void createTimeseries(String path, TSDataType dataType, TSEncoding encoding,
CompressionType compressor,
Map<String, String> props, Map<String, String> tags,
Map<String, String> attributes,
String measurementAlias)
@@ -312,7 +325,7 @@ void createTimeseries(String path, TSDataType dataType,
TSEncoding encoding, Com
Create a timeseries with path, datatype, encoding and compression.
Additionally, users can provide props, tags, attributes and measurementAlias。
-```
+```java
void createMultiTimeseries(List<String> paths, List<TSDataType> dataTypes,
List<TSEncoding> encodings,
List<CompressionType> compressors, List<Map<String,
String>> propsList,
List<Map<String, String>> tagsList,
List<Map<String, String>> attributesList,
@@ -321,15 +334,16 @@ void createMultiTimeseries(List<String> paths,
List<TSDataType> dataTypes, List<
Create multiple timeseries with a single method. Users can provide props,
tags, attributes and measurementAlias as well for detailed timeseries
information.
-```
+```java
boolean checkTimeseriesExists(String path)
```
Add a method to check whether the specific timeseries exists.
-```
+```java
public Session(String host, int rpcPort, String username, String password,
boolean isEnableCacheLeader)
```
-Open a session and specifies whether the Leader cache is enabled. Note that
this interface improves performance for distributed IoTDB, but adds less cost
to the client for stand-alone IoTDB.
\ No newline at end of file
+Open a session and specifies whether the Leader cache is enabled. Note that
this interface improves performance for distributed IoTDB, but adds less cost
to the client for stand-alone IoTDB.
+
diff --git a/docs/UserGuide/API/Programming-Python-Native-API.md
b/docs/UserGuide/API/Programming-Python-Native-API.md
new file mode 100644
index 0000000..7c9c6b6
--- /dev/null
+++ b/docs/UserGuide/API/Programming-Python-Native-API.md
@@ -0,0 +1,207 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+## 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 need to add `import iotdb` in the head of the file)
+
+Or:
+
+```python
+from iotdb.Session import Session
+
+ip = "127.0.0.1"
+port_ = "6667"
+username_ = 'root'
+password_ = 'root'
+session = Session(ip, port_, username_, password_)
+session.open(False)
+zone = session.get_time_zone()
+session.close()
+```
+
+
+
+### 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.
+
+To start (and stop) an IoTDB Database in a Docker container simply do:
+```python
+class MyTestCase(unittest.TestCase):
+
+ def test_something(self):
+ with IoTDBContainer() as c:
+ session = Session('localhost', c.get_exposed_port(6667), 'root',
'root')
+ session.open(False)
+ result = session.execute_query_statement("SHOW TIMESERIES")
+ print(result)
+ 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.10.0")`
to get version `0.10.0` running.
+
+
+
+### 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.
+
+Example:
+
+```python
+from iotdb.Session import Session
+
+ip = "127.0.0.1"
+port_ = "6667"
+username_ = 'root'
+password_ = 'root'
+session = Session(ip, port_, username_, password_)
+session.open(False)
+result = session.execute_query_statement("SELECT * FROM root.*")
+
+# Transform to Pandas Dataset
+df = result.todf()
+
+session.close()
+
+# Now you can work with the dataframe
+df = ...
+```
+
+
+
+### 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.
+
+
+
+#### 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 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.
+
+
+Or, another simple example:
+
+```python
+from iotdb.Session import Session
+
+ip = "127.0.0.1"
+port_ = "6667"
+username_ = 'root'
+password_ = 'root'
+session = Session(ip, port_, username_, password_)
+session.open(False)
+zone = session.get_time_zone()
+session.close()
+```
+
+
+
+#### Tests
+
+Please add your custom tests in `tests` folder.
+
+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, 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.
+Namely, these are
+
+* Remove all transient directories from last release (if exists)
+* (Re-)generate all generated sources via mvn
+* Run Linting (flake8)
+* Run Tests via pytest
+* Build
+* Release to pypi
+
diff --git a/docs/UserGuide/API/Programming-TsFile-API.md
b/docs/UserGuide/API/Programming-TsFile-API.md
index 90e134a..ee09cbb 100644
--- a/docs/UserGuide/API/Programming-TsFile-API.md
+++ b/docs/UserGuide/API/Programming-TsFile-API.md
@@ -23,13 +23,15 @@
TsFile is a file format of Time Series used in IoTDB. This session 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 tsfile/
mvn clean package -Dmaven.test.skip=true
@@ -43,20 +45,20 @@ Then, all the jars are in folder named `target/`. Import
`target/tsfile-0.12.0-j
* Get the source codes
- ```
+ ```shell
git clone https://github.com/apache/iotdb.git
```
* Compile the source codes and deploy
- ```
+ ```shell
cd tsfile/
mvn clean install -Dmaven.test.skip=true
```
* add dependencies into your project:
- ```
+ ```xml
<dependency>
<groupId>org.apache.iotdb</groupId>
<artifactId>tsfile</artifactId>
@@ -69,7 +71,7 @@ Then, all the jars are in folder named `target/`. Import
`target/tsfile-0.12.0-j
* First, find your maven `settings.xml` on path:
`${username}\.m2\settings.xml`
, add this `<profile>` to `<profiles>`:
- ```
+ ```xml
<profile>
<id>allow-snapshots</id>
<activation><activeByDefault>true</activeByDefault></activation>
@@ -90,7 +92,7 @@ Then, all the jars are in folder named `target/`. Import
`target/tsfile-0.12.0-j
```
* Then add dependencies into your project:
- ```
+ ```xml
<dependency>
<groupId>org.apache.iotdb</groupId>
<artifactId>tsfile</artifactId>
@@ -98,7 +100,10 @@ Then, all the jars are in folder named `target/`. Import
`target/tsfile-0.12.0-j
</dependency>
```
+
+
### TsFile Usage
+
This section demonstrates the detailed usages of TsFile.
Time-series Data
@@ -131,6 +136,7 @@ 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".
@@ -141,23 +147,23 @@ A TsFile is generated by the following three steps and
the complete code is give
* 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);
@@ -182,8 +188,8 @@ A TsFile is generated by the following three steps and the
complete code is give
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)
@@ -199,12 +205,12 @@ A TsFile is generated by the following three steps and
the complete code is give
You can always use the following interface in `TsFileWriter` class to add
additional measurements:
- ```
+ ```java
public void addMeasurement(MeasurementSchema measurementSchema) throws
WriteProcessException
```
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,
@@ -228,32 +234,37 @@ A TsFile is generated by the following three steps and
the complete code is give
it's not allowed to add one measurement name for multiple times with
different type or encoding.
Here is a bad example:
- // 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));
+ ```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.
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 method to write
- ```
+ ```java
public void write(TSRecord record) throws IOException,
WriteProcessException
- ```
-
+ ```
+
4. call `close` to finish this writing process.
- ```
+ ```java
public void close() throws IOException
```
@@ -261,7 +272,7 @@ We are also able to write data into a closed TsFile.
1. Use `ForceAppendTsFileWriter` to open a closed file.
- ```
+ ```java
public ForceAppendTsFileWriter(File file) throws IOException
```
@@ -269,16 +280,18 @@ We are also able to write data into a closed TsFile.
3. Then use `ForceAppendTsFileWriter` to construct a new `TsFileWriter`
-```
+```java
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.
-```
+```shell
mvn clean install -pl tsfile -am -DskipTests
```
@@ -294,6 +307,8 @@ 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
@@ -306,13 +321,13 @@ In read interfaces, The parameter `paths` indicates the
measurements to be selec
Path instance can be easily constructed through the class `Path`. For example:
-```
+```java
Path p = new Path("device_1.sensor_1");
```
We will pass an ArrayList of paths for final query call to support multiple
paths.
-```
+```java
List<Path> paths = new ArrayList<Path>();
paths.add(new Path("device_1.sensor_1"));
paths.add(new Path("device_1.sensor_3"));
@@ -341,17 +356,16 @@ We create one or more filter expressions and may use
binary filter operators to
```
Use the following relationships to get a `TimeFilter` object (value is
a long int variable).
- |Relationship|Description|
- |---|---|
- |TimeFilter.eq(value)|Choose the time equal to the value|
- |TimeFilter.lt(value)|Choose the time less than the value|
- |TimeFilter.gt(value)|Choose the time greater than the value|
- |TimeFilter.ltEq(value)|Choose the time less than or equal to the
value|
- |TimeFilter.gtEq(value)|Choose the time greater than or equal to the
value|
- |TimeFilter.notEq(value)|Choose the time not equal to the value|
- |TimeFilter.not(TimeFilter)|Choose the time not satisfy another
TimeFilter|
+ |Relationship|Description|
+ |---|---|
+ |TimeFilter.eq(value)|Choose the time equal to the value|
+ |TimeFilter.lt(value)|Choose the time less than the value|
+ |TimeFilter.gt(value)|Choose the time greater than the value|
+ |TimeFilter.ltEq(value)|Choose the time less than or equal to the
value|
+ |TimeFilter.gtEq(value)|Choose the time greater than or equal to the
value|
+ |TimeFilter.notEq(value)|Choose the time not equal to the value|
+ |TimeFilter.not(TimeFilter)|Choose the time not satisfy another
TimeFilter|
-
* ValueFilter: A filter for `value` in time-series data.
```
@@ -359,7 +373,7 @@ We create one or more filter expressions and may use binary
filter operators to
```
The usage of `ValueFilter` is the same as using `TimeFilter`, just to
make sure that the type of the value
equal to the measurement's(defined in the path).
-
+
* **Binary Filter Operators**
Binary filter operators can be used to link two single expressions.
@@ -372,59 +386,57 @@ Filter Expression Examples
* **TimeFilterExpression Examples**
- ```
+ ```java
IExpression timeFilterExpr = new GlobalTimeExpression(TimeFilter.eq(15));
// series time = 15
-
- ```
```
+```
+ ```java
IExpression timeFilterExpr = new
GlobalTimeExpression(TimeFilter.ltEq(15)); // series time <= 15
-
- ```
- ```
+```
+```java
IExpression timeFilterExpr = new GlobalTimeExpression(TimeFilter.lt(15));
// series time < 15
-
- ```
- ```
- IExpression timeFilterExpr = new
GlobalTimeExpression(TimeFilter.gtEq(15)); // series time >= 15
-
- ```
+```
+ ```java
+IExpression timeFilterExpr = new GlobalTimeExpression(TimeFilter.gtEq(15)); //
series time >= 15
```
+ ```java
IExpression timeFilterExpr = new
GlobalTimeExpression(TimeFilter.notEq(15)); // series time != 15
-
- ```
- ```
- IExpression timeFilterExpr = BinaryExpression.and(new
GlobalTimeExpression(TimeFilter.gtEq(15L)),
- new
GlobalTimeExpression(TimeFilter.lt(25L))); // 15 <= series time < 25
- ```
- ```
- IExpression timeFilterExpr = BinaryExpression.or(new
GlobalTimeExpression(TimeFilter.gtEq(15L)),
- new
GlobalTimeExpression(TimeFilter.lt(25L))); // series time >= 15 or series time
< 25
+```
+ ```java
+ IExpression timeFilterExpr = BinaryExpression.and(
+ new GlobalTimeExpression(TimeFilter.gtEq(15L)),
+ new GlobalTimeExpression(TimeFilter.lt(25L))); // 15 <= series time < 25
+```
+ ```java
+ IExpression timeFilterExpr = BinaryExpression.or(
+ new GlobalTimeExpression(TimeFilter.gtEq(15L)),
+ new GlobalTimeExpression(TimeFilter.lt(25L))); // series time >= 15 or
series time < 25
```
* Read Interface
First, we open the TsFile and get a `ReadOnlyTsFile` instance from a file path
string `path`.
-```
+```java
TsFileSequenceReader reader = new TsFileSequenceReader(path);
ReadOnlyTsFile readTsFile = new ReadOnlyTsFile(reader);
```
Next, we prepare the path array and query expression, then get final
`QueryExpression` object by this interface:
-```
+```java
QueryExpression queryExpression = QueryExpression.create(paths, statement);
```
The ReadOnlyTsFile class has two `query` method to perform a query.
* **Method 1**
- ```
+ ```java
public QueryDataSet query(QueryExpression queryExpression) throws
IOException
```
* **Method 2**
- ```
+ ```java
public QueryDataSet query(QueryExpression queryExpression, long
partitionStartOffset, long partitionEndOffset) throws IOException
```
@@ -453,7 +465,7 @@ Here's the useful interfaces for user.
* `List<TSDataType> getDataTypes();`
Get the data types. The class TSDataType is an enum class, the value will
be one of the following:
-
+
BOOLEAN,
INT32,
INT64,
@@ -467,18 +479,20 @@ Here's the useful interfaces for user.
The class `RowRecord` consists of a `long` timestamp and a `List<Field>`
for data in different sensors,
we can use two getter methods to get them.
- ```
+ ```java
long getTimestamp();
List<Field> getFields();
```
To get data from one Field, use these methods:
- ```
+ ```java
TSDataType getDataType();
Object getObjectValue();
```
+
+
#### Example for reading an existing TsFile
@@ -541,12 +555,13 @@ public class TsFileRead {
reader.close();
}
}
-
```
+
+
### Change TsFile Configuration
-```
+```java
TSFileConfig config = TSFileDescriptor.getInstance().getConfig();
config.setXXX();
```
diff --git
a/docs/UserGuide/IoTDB-SQL-Language/DML-Data-Manipulation-Language.md
b/docs/UserGuide/IoTDB-SQL-Language/DML-Data-Manipulation-Language.md
index 8128b42..e155237 100644
--- a/docs/UserGuide/IoTDB-SQL-Language/DML-Data-Manipulation-Language.md
+++ b/docs/UserGuide/IoTDB-SQL-Language/DML-Data-Manipulation-Language.md
@@ -466,7 +466,7 @@ This section mainly introduces the related examples of
down-frequency aggregatio
using the [GROUP BY clause](../Appendix/SQL-Reference.md),
which is used to partition the result set according to the user's given
partitioning conditions and aggregate the partitioned result set.
IoTDB supports partitioning result sets according to time interval and
customized sliding step which should not be smaller than the time interval and
defaults to equal the time interval if not set. And by default results are
sorted by time in ascending order.
-You can also use the [Java JDBC](../API/Programming-Native-API.md) standard
interface to execute related queries.
+You can also use the [Java JDBC](../API/Programming-JDBC.md) standard
interface to execute related queries.
The GROUP BY statement provides users with three types of specified parameters:
diff --git a/docs/zh/UserGuide/API/Programming-Other-Languages.md
b/docs/zh/UserGuide/API/Programming-Cpp-Native-API.md
similarity index 78%
rename from docs/zh/UserGuide/API/Programming-Other-Languages.md
rename to docs/zh/UserGuide/API/Programming-Cpp-Native-API.md
index af6ffca..f46ba5a 100644
--- a/docs/zh/UserGuide/API/Programming-Other-Languages.md
+++ b/docs/zh/UserGuide/API/Programming-Cpp-Native-API.md
@@ -19,46 +19,10 @@
-->
-
-## Python 原生接口
-
-### 依赖
-
-首选python3.7或更高版本。
-
-您必须安装Thrift（0.11.0或更高版本）才能将我们的Thrift文件编译为python代码。
-
-下面是官方安装教程：
-
-```
-http://thrift.apache.org/docs/install/
-```
-
-### 安装方法
-
- * 方案1: pip install
-
-您可以在https://pypi.org/project/apache-iotdb/上找到Apache IoTDB Python客户端API软件包。
-
-下载命令为：
-
-```
-pip install apache-iotdb
-```
-
- * 方案2：thrift的基本用法
-
-或者，如果您了解thrift的基本用法，则可以在以下位置查看thrift源文件：
-`thrift\src\main\thrift\rpc.thrift`，使用`thrift -gen py -out ./target/iotdb
rpc.thrift`生成Python库。
-
-### 示例代码
-
-我们在`client-py/src/SessionExample.py`中提供了一个示例，说明如何使用Thrift库连接到IoTDB，请先仔细阅读，然后再编写自己的代码。
-
-
## C++ 原生接口
### 依赖
+
- Java 8+
- Maven 3.5+
- Flex
@@ -66,38 +30,40 @@ pip install apache-iotdb
- Boost
- OpenSSL 1.0+
+
+
### 安装方法
编译C++客户端之前首先需要本地编译Thrift库，compile-tools模块负责编译Thrift，之后再编译client-cpp。
+
+
#### 在Mac上编译Thrift
- Bison
Mac 环境下预安装了Bison 2.3版本，但该版本过低不能够用来编译Thrift。使用Bison 2.3版本是会报以下错误：
- ```invalid directive: '%code'```
-
+ ```invalid directive: '%code'```
+
使用下面brew 命令更新bison版本
-```
+``` shell
brew install bison
brew link bison --force
```
添加环境变量：
-```
+``` shell
echo 'export PATH="/usr/local/opt/bison/bin:$PATH"' >> ~/.bash_profile
```
-
-
- Boost
确保安装较新的Boost版本：
-```
+```shell
brew install boost
brew link boost
```
@@ -120,13 +86,13 @@ Linux下需要确保g++已被安装。
Debian/Ubuntu:
-```
+```shell
sudo apt-get install gcc g++ bison flex libboost-all-dev
```
CentOS:
-```
+```shell
yum install gcc g++ bison flex boost-devel
```
@@ -138,8 +104,6 @@ yum install gcc g++ bison flex boost-devel
如使用MS Visual Studio，在安装时需要勾选 Visual Studio C/C++ IDE and compiler(supporting
CMake, Clang, MinGW)。
-
-
- Flex 和 Bison
Windows版的 Flex 和 Bison 可以从 SourceForge下载:
https://sourceforge.net/projects/winflexbison/
@@ -152,7 +116,7 @@ Boost官网下载新版本Boost: https://www.boost.org/users/download/
依次执行bootstrap.bat 和 b2.exe，本地编译boost
-```
+```shell
bootstrap.bat
.\b2.exe
```
@@ -161,6 +125,8 @@ bootstrap.bat
`-Dboost.include.dir=${your boost header folder} -Dboost.library.dir=${your
boost lib (stage) folder}`
+
+
#### CMake 生成器
CMake需要根据不同编译平台使用不同的生成器。CMake支持的生成器列表如下(`cmake --help`的结果)：
@@ -195,8 +161,6 @@ CMake需要根据不同编译平台使用不同的生成器。CMake支持的生
Watcom WMake = Generates Watcom WMake makefiles.
CodeBlocks - MinGW Makefiles = Generates CodeBlocks project files.
CodeBlocks - NMake Makefiles = Generates CodeBlocks project files.
- CodeBlocks - NMake Makefiles = Generates CodeBlocks project fi
-
```
编译client-cpp 时的mvn命令中添加 -Dcmake.generator="" 选项来指定使用的生成器名称。
@@ -206,9 +170,9 @@ CMake需要根据不同编译平台使用不同的生成器。CMake支持的生
#### 编译C++ 客户端
+Maven 命令中添加"-P client-cpp"
选项编译client-cpp模块。client-cpp需要依赖编译好的thrift，即compile-tools模块。
-Maven 命令中添加"-P client-cpp"
选项编译client-cpp模块。client-cpp需要依赖编译好的thrift，即compile-tools模块。
#### 编译及测试
@@ -218,13 +182,14 @@ Maven 命令中添加"-P client-cpp" 选项编译client-cpp模块。client-cpp
`mvn package -P compile-cpp -pl example/client-cpp-example -am -DskipTest`
注意在Windows下需提前安装好Boost，并添加以下Maven 编译选项:
-```
+
+```shell
-Dboost.include.dir=${your boost header folder} -Dboost.library.dir=${your
boost lib (stage) folder}`
```
例如：
-```
+```shell
mvn package -P compile-cpp -pl client-cpp,server,example/client-cpp-example
-am
-D"boost.include.dir"="D:\boost_1_75_0"
-D"boost.library.dir"="D:\boost_1_75_0\stage\lib" -DskipTests
```
@@ -235,7 +200,7 @@ mvn package -P compile-cpp -pl
client-cpp,server,example/client-cpp-example -am
解压后的目录结构如下图所示(Mac)：
-```
+```shell
.
+-- client
| +-- include
@@ -251,8 +216,6 @@ mvn package -P compile-cpp -pl
client-cpp,server,example/client-cpp-example -am
-
-
### Q&A
#### Mac相关问题
@@ -261,6 +224,8 @@ mvn package -P compile-cpp -pl
client-cpp,server,example/client-cpp-example -am
https://stackoverflow.com/questions/63592445/ld-unsupported-tapi-file-type-tapi-tbd-in-yaml-file/65518087#65518087
+
+
#### Windows相关问题
Maven编译Thrift时需要使用wget下载远端文件，可能出现以下报错：
@@ -275,46 +240,3 @@ Failed to delete cached file
C:\Users\Administrator\.m2\repository\.cache\downlo
- 在添加 pom文件对应的 download-maven-plugin 中添加 "\<skipCache>true\</skipCache>"
-
-## Go 原生接口
-
-### 依赖
-
- * golang >= 1.13
- * make >= 3.0
- * curl >= 7.1.1
- * thrift 0.13.x
- * Linux、Macos或其他类unix系统
- * Windows+bash(WSL、cygwin、Git Bash)
-
-
-### 安装方法
-
- * 通过go mod
-
-```sh
-export GO111MODULE=on
-export GOPROXY=https://goproxy.io
-
-mkdir session_example && cd session_example
-
-curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
-
-go mod init session_example
-go run session_example.go
-```
-
-* 通过GOPATH
-
-```sh
-# get thrift 0.13.0
-go get github.com/apache/thrift
-cd $GOPATH/src/github.com/apache/thrift
-git checkout 0.13.0
-
-mkdir -p $GOPATH/src/iotdb-client-go-example/session_example
-cd $GOPATH/src/iotdb-client-go-example/session_example
-curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
-go run session_example.go
-```
-
diff --git a/docs/zh/UserGuide/API/Programming-Go-Native-API.md
b/docs/zh/UserGuide/API/Programming-Go-Native-API.md
new file mode 100644
index 0000000..d8b7092
--- /dev/null
+++ b/docs/zh/UserGuide/API/Programming-Go-Native-API.md
@@ -0,0 +1,65 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+## Go 原生接口
+
+### 依赖
+
+ * golang >= 1.13
+ * make >= 3.0
+ * curl >= 7.1.1
+ * thrift 0.13.x
+ * Linux、Macos或其他类unix系统
+ * Windows+bash(WSL、cygwin、Git Bash)
+
+
+
+
+### 安装方法
+
+ * 通过go mod
+
+```sh
+export GO111MODULE=on
+export GOPROXY=https://goproxy.io
+
+mkdir session_example && cd session_example
+
+curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
+
+go mod init session_example
+go run session_example.go
+```
+
+* 通过GOPATH
+
+```sh
+# get thrift 0.13.0
+go get github.com/apache/thrift
+cd $GOPATH/src/github.com/apache/thrift
+git checkout 0.13.0
+
+mkdir -p $GOPATH/src/iotdb-client-go-example/session_example
+cd $GOPATH/src/iotdb-client-go-example/session_example
+curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
+go run session_example.go
+```
+
diff --git a/docs/zh/UserGuide/API/Programming-JDBC.md
b/docs/zh/UserGuide/API/Programming-JDBC.md
index c50f0e5..395259f 100644
--- a/docs/zh/UserGuide/API/Programming-JDBC.md
+++ b/docs/zh/UserGuide/API/Programming-JDBC.md
@@ -19,8 +19,6 @@
-->
-# 应用编程接口
-
## JDBC
### 依赖
@@ -28,16 +26,20 @@
* JDK >= 1.8
* Maven >= 3.6
+
+
### 安装方法
在根目录下执行下面的命令:
-```
+```shell
mvn clean install -pl jdbc -am -Dmaven.test.skip=true
```
-### 在MAVEN中使用 IoTDB JDBC
-```
+
+#### 在MAVEN中使用 IoTDB JDBC
+
+```xml
<dependencies>
<dependency>
<groupId>org.apache.iotdb</groupId>
@@ -47,7 +49,9 @@ mvn clean install -pl jdbc -am -Dmaven.test.skip=true
</dependencies>
```
-### 示例代码
+
+
+#### 示例代码
本章提供了如何建立数据库连接、执行 SQL 和显示查询结果的示例。
diff --git a/docs/zh/UserGuide/API/Programming-Native-API.md
b/docs/zh/UserGuide/API/Programming-Java-Native-API.md
similarity index 94%
rename from docs/zh/UserGuide/API/Programming-Native-API.md
rename to docs/zh/UserGuide/API/Programming-Java-Native-API.md
index 8f5198e..23512ca 100644
--- a/docs/zh/UserGuide/API/Programming-Native-API.md
+++ b/docs/zh/UserGuide/API/Programming-Java-Native-API.md
@@ -26,17 +26,21 @@
* JDK >= 1.8
* Maven >= 3.6
+
+
### 安装方法
在根目录下运行:
-```
+```shell
mvn clean install -pl session -am -Dmaven.test.skip=true
```
+
+
### 在MAVEN中使用原生接口
-```
+```xml
<dependencies>
<dependency>
<groupId>org.apache.iotdb</groupId>
@@ -46,46 +50,48 @@ mvn clean install -pl session -am -Dmaven.test.skip=true
</dependencies>
```
+
+
### 原生接口说明
下面将给出Session对应的接口的简要介绍和对应参数：
* 初始化Session
+```java
+Session(String host, int rpcPort)
+Session(String host, String rpcPort, String username, String password)
+Session(String host, int rpcPort, String username, String password)
```
-Session(String host, int rpcPort)
-Session(String host, String rpcPort, String username, String password)
-Session(String host, int rpcPort, String username, String password)
-```
-
+
* 开启Session
+```java
+Session.open()
```
-Session.open()
-```
-
+
* 关闭Session
-```
+```java
Session.close()
```
-
+
* 设置存储组
-```
+```java
void setStorageGroup(String storageGroupId)
```
* 删除单个或多个存储组
-```
+```java
void deleteStorageGroup(String storageGroup)
void deleteStorageGroups(List<String> storageGroups)
```
* 创建单个或多个时间序列
-```
+```java
void createTimeseries(String path, TSDataType dataType,
TSEncoding encoding, CompressionType compressor, Map<String, String>
props,
Map<String, String> tags, Map<String, String> attributes, String
measurementAlias)
@@ -98,61 +104,61 @@ void createMultiTimeseries(List<String> paths,
List<TSDataType> dataTypes,
* 删除一个或多个时间序列
-```
+```java
void deleteTimeseries(String path)
void deleteTimeseries(List<String> paths)
```
* 删除一个或多个时间序列在某个时间点前或这个时间点的数据
-```
+```java
void deleteData(String path, long time)
void deleteData(List<String> paths, long time)
```
* 插入一个 Record，一个 Record 是一个设备一个时间戳下多个测点的数据。服务器需要做类型推断，可能会有额外耗时
-```
+```java
void insertRecord(String deviceId, long time, List<String> measurements,
List<String> values)
```
* 插入一个 Tablet，Tablet 是一个设备若干行非空数据块，每一行的列都相同
-```
+```java
void insertTablet(Tablet tablet)
```
* 插入多个 Tablet
-```
+```java
void insertTablets(Map<String, Tablet> tablet)
```
-
+
* 插入多个 Record。服务器需要做类型推断，可能会有额外耗时
-```
+```java
void insertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList, List<List<String>>
valuesList)
```
-
+
* 插入一个 Record，一个 Record 是一个设备一个时间戳下多个测点的数据。提供数据类型后，服务器不需要做类型推断，可以提高性能
-```
+```java
void insertRecord(String deviceId, long time, List<String> measurements,
List<TSDataType> types, List<Object> values)
```
* 插入多个 Record。提供数据类型后，服务器不需要做类型推断，可以提高性能
-```
+```java
void insertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList, List<List<TSDataType>> typesList,
List<List<Object>> valuesList)
```
-
+
* 插入同属于一个device的多个 Record。
-```
+```java
void insertRecordsOfOneDevice(String deviceId, List<Long> times,
List<List<String>> measurementsList, List<List<TSDataType>> typesList,
List<List<Object>> valuesList)
@@ -160,32 +166,34 @@ void insertRecordsOfOneDevice(String deviceId, List<Long>
times,
* 原始数据查询。时间间隔包含开始时间，不包含结束时间
-```
+```java
SessionDataSet executeRawDataQuery(List<String> paths, long startTime, long
endTime)
```
* 执行查询语句
-```
+```java
SessionDataSet executeQueryStatement(String sql)
```
-
+
* 执行非查询语句
-```
+```java
void executeNonQueryStatement(String sql)
```
+
+
### 测试接口说明
* 测试 testInsertRecords，不实际写入数据，只将数据传输到 server 即返回。
-```
+```java
void testInsertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList, List<List<String>> valuesList)
```
或
-
-```
+
+```java
void testInsertRecords(List<String> deviceIds, List<Long> times,
List<List<String>> measurementsList, List<List<TSDataType>> typesList,
List<List<Object>> valuesList)
@@ -193,12 +201,12 @@ void testInsertRecords(List<String> deviceIds, List<Long>
times,
* 测试 insertRecord，不实际写入数据，只将数据传输到 server 即返回。
-```
+```java
void testInsertRecord(String deviceId, long time, List<String> measurements,
List<String> values)
```
或
-
-```
+
+```java
void testInsertRecord(String deviceId, long time, List<String> measurements,
List<TSDataType> types, List<Object> values)
```
@@ -206,10 +214,12 @@ void testInsertRecord(String deviceId, long time,
List<String> measurements,
* 测试 insertTablet，不实际写入数据，只将数据传输到 server 即返回。
-```
+```java
void testInsertTablet(Tablet tablet)
```
+
+
### 针对原生接口的连接池
我们提供了一个针对原生接口的连接池(`SessionPool`)，使用该接口时，你只需要指定连接池的大小，就可以在使用时从池中获取连接。
@@ -229,7 +239,8 @@ void testInsertTablet(Tablet tablet)
或 `example/session/src/main/java/org/apache/iotdb/SessionPoolExample.java`
-
+
+
### 示例代码
浏览上述接口的详细信息，请参阅代码
```session/src/main/java/org/apache/iotdb/session/Session.java```
diff --git a/docs/zh/UserGuide/API/Programming-Python-Native-API.md
b/docs/zh/UserGuide/API/Programming-Python-Native-API.md
new file mode 100644
index 0000000..b5bb058
--- /dev/null
+++ b/docs/zh/UserGuide/API/Programming-Python-Native-API.md
@@ -0,0 +1,220 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+## Python 原生接口
+
+### 依赖
+
+在使用Python原生接口包前，您需要安装 thrift (>=0.13) 依赖。
+
+
+
+### 如何使用 (示例)
+
+首先下载包：`pip3 install apache-iotdb`
+
+您可以从这里得到一个使用该包进行数据读写的例子：[Example](https://github.com/apache/iotdb/blob/master/client-py/SessionExample.py)
+
+（您需要在文件的头部添加`import iotdb`）
+
+或者：
+
+```python
+from iotdb.Session import Session
+
+ip = "127.0.0.1"
+port_ = "6667"
+username_ = 'root'
+password_ = 'root'
+session = Session(ip, port_, username_, password_)
+session.open(False)
+zone = session.get_time_zone()
+session.close()
+```
+
+
+
+### IoTDB Testcontainer
+
+Python客户端对测试的支持是基于`testcontainers`库
(https://testcontainers-python.readthedocs.io/en/latest/index.html)的，如果您想使用该特性，就需要将其安装到您的项目中。
+
+要在Docker容器中启动（和停止）一个IoTDB数据库，只需这样做:
+
+```python
+class MyTestCase(unittest.TestCase):
+
+ def test_something(self):
+ with IoTDBContainer() as c:
+ session = Session('localhost', c.get_exposed_port(6667), 'root',
'root')
+ session.open(False)
+ result = session.execute_query_statement("SHOW TIMESERIES")
+ print(result)
+ session.close()
+```
+
+默认情况下，它会拉取最新的IoTDB镜像
`apache/iotdb:latest`进行测试，如果您想指定待测IoTDB的版本，您只需要将版本信息像这样声明：`IoTDBContainer("apache/iotdb:0.10.0")`，此时，您就会得到一个`0.10.0`版本的IoTDB实例。
+
+
+
+### 对 Pandas 的支持
+
+我们支持将查询结果轻松地转换为[Pandas
Dataframe](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html)。
+
+SessionDataSet有一个方法`.todf()`，它的作用是消费SessionDataSet中的数据，并将数据转换为pandas dataframe。
+
+例子：
+
+```python
+from iotdb.Session import Session
+
+ip = "127.0.0.1"
+port_ = "6667"
+username_ = 'root'
+password_ = 'root'
+session = Session(ip, port_, username_, password_)
+session.open(False)
+result = session.execute_query_statement("SELECT * FROM root.*")
+
+# Transform to Pandas Dataset
+df = result.todf()
+
+session.close()
+
+# Now you can work with the dataframe
+df = ...
+```
+
+
+
+### 给开发人员
+
+#### 介绍
+
+这是一个使用thrift rpc接口连接到IoTDB的示例。在Windows和Linux上操作几乎是一样的，但要注意路径分隔符等不同之处。
+
+
+
+#### 依赖
+
+首选Python3.7或更高版本。
+
+必须安装thrift（0.11.0或更高版本）才能将thrift文件编译为Python代码。下面是官方的安装教程，最终，您应该得到一个thrift可执行文件。
+
+```
+http://thrift.apache.org/docs/install/
+```
+
+在开始之前，您还需要在Python环境中安装`requirements_dev.txt`中的其他依赖：
+```shell
+pip install -r requirements_dev.txt
+```
+
+
+
+#### 编译thrift库并调试
+
+在IoTDB源代码文件夹的根目录下，运行`mvn clean generate-sources -pl client-py -am`，
+
+这个指令将自动删除`iotdb/thrift`中的文件，并使用新生成的thrift文件重新填充该文件夹。
+
+这个文件夹在git中会被忽略，并且**永远不应该被推到git中！**
+
+**注意**不要将`iotdb/thrift`上传到git仓库中 ！
+
+
+
+
+#### Session 客户端 & 使用示例
+
+我们将thrift接口打包到`client-py/src/iotdb/session.py
`中（与Java版本类似），还提供了一个示例文件`client-py/src/SessionExample.py`来说明如何使用Session模块。请仔细阅读。
+
+另一个简单的例子：
+
+```python
+from iotdb.Session import Session
+
+ip = "127.0.0.1"
+port_ = "6667"
+username_ = 'root'
+password_ = 'root'
+session = Session(ip, port_, username_, password_)
+session.open(False)
+zone = session.get_time_zone()
+session.close()
+```
+
+
+
+#### 测试
+
+请在`tests`文件夹中添加自定义测试。
+
+要运行所有的测试，只需在根目录中运行`pytest . `即可。
+
+**注意**一些测试需要在您的系统上使用docker，因为测试的IoTDB实例是使用[testcontainers](https://testcontainers-python.readthedocs.io/en/latest/index.html)在docker容器中启动的。
+
+
+
+#### 其他工具
+
+[black](https://pypi.org/project/black/) 和
[flake8](https://pypi.org/project/flake8/) 分别用于自动格式化和 linting。
+它们可以通过 `black .` 或 `flake8 .` 分别运行。
+
+
+
+### 发版
+
+要进行发版，
+
+只需确保您生成了正确的thrift代码，
+
+运行了linting并进行了自动格式化，
+
+然后，确保所有测试都正常通过（通过`pytest . `），
+
+最后，您就可以将包发布到pypi了。
+
+
+
+#### 准备您的环境
+
+首先，通过`pip install -r requirements_dev.txt`安装所有必要的开发依赖。
+
+
+
+#### 发版
+
+有一个脚本`release.sh`可以用来执行发版的所有步骤。
+
+这些步骤包括：
+
+* 删除所有临时目录（如果存在）
+
+* （重新）通过mvn生成所有必须的源代码
+
+* 运行 linting （flke8）
+
+* 通过 pytest 运行测试
+
+* Build
+
+* 发布到 pypi
+
diff --git a/docs/zh/UserGuide/API/Programming-TsFile-API.md
b/docs/zh/UserGuide/API/Programming-TsFile-API.md
index 42c2b31..53a08bc 100644
--- a/docs/zh/UserGuide/API/Programming-TsFile-API.md
+++ b/docs/zh/UserGuide/API/Programming-TsFile-API.md
@@ -23,6 +23,8 @@
TsFile 是在 IoTDB 中使用的时间序列的文件格式。在这个章节中，我们将介绍这种文件格式的用法。
+
+
### 安装 TsFile library
@@ -30,7 +32,7 @@ TsFile 是在 IoTDB 中使用的时间序列的文件格式。在这个章节中
* 使用 jar 包: 编译源码生成 jar 包
-```
+```shell
git clone https://github.com/apache/iotdb.git
cd tsfile/
mvn clean package -Dmaven.test.skip=true
@@ -44,31 +46,31 @@ mvn clean package -Dmaven.test.skip=true
1. 下载源码
- ```
+ ```shell
git clone https://github.com/apache/iotdb.git
-```
- 2. 编译源码和部署到本地仓库
-
```
+ 2. 编译源码和部署到本地仓库
+
+ ```shell
cd tsfile/
mvn clean install -Dmaven.test.skip=true
-```
+ ```
3. 在您自己的工程中增加依赖:
- ```
+ ```xml
<dependency>
<groupId>org.apache.iotdb</groupId>
<artifactId>tsfile</artifactId>
<version>0.12.0</version>
</dependency>
```
-
+
或者，您可以直接使用官方的 Maven 仓库:
1. 首先，在`${username}\.m2\settings.xml`目录下的`settings.xml`文件中`<profiles>`
节中增加`<profile>`，内容如下:
- ```
+ ```xml
<profile>
<id>allow-snapshots</id>
<activation><activeByDefault>true</activeByDefault></activation>
@@ -86,10 +88,10 @@ mvn clean install -Dmaven.test.skip=true
</repository>
</repositories>
</profile>
-```
+ ```
2. 之后您可以在您的工程中增加如下依赖:
- ```
+ ```xml
<dependency>
<groupId>org.apache.iotdb</groupId>
<artifactId>tsfile</artifactId>
@@ -97,7 +99,10 @@ mvn clean install -Dmaven.test.skip=true
</dependency>
```
+
+
### TsFile 的使用
+
本章节演示TsFile的详细用法。
时序数据(Time-series Data)
@@ -128,6 +133,7 @@ device_1, 1490860659000, m1, 10, m2, 12.12
```
+
#### 写入 TsFile
TsFile可以通过以下三个步骤生成，完整的代码参见"写入 TsFile 示例"章节。
@@ -138,28 +144,28 @@ TsFile可以通过以下三个步骤生成，完整的代码参见"写入 TsFile
* 没有预定义 schema
- ```
+ ```java
public TsFileWriter(File file) throws IOException
```
* 预定义 schema
- ```
+ ```java
public TsFileWriter(File file, Schema schema) throws IOException
```
这个是用于使用 HDFS 文件系统的。`TsFileOutput`可以是`HDFSOutput`类的一个实例。
- ```
+ ```java
public TsFileWriter(TsFileOutput output, Schema schema) throws IOException
```
如果你想自己设置一些 TSFile 的配置，你可以使用`config`参数。比如:
- ```
+ ```java
TSFileConfig conf = new TSFileConfig();
conf.setTSFileStorageFs("HDFS");
TsFileWriter tsFileWriter = new TsFileWriter(file, schema, conf);
```
-
+
在上面的例子中，数据文件将存储在 HDFS
中，而不是本地文件系统中。如果你想在本地文件系统中存储数据文件，你可以使用`conf.setTSFileStorageFs("LOCAL")`，这也是默认的配置。
您还可以通过`config.setHdfsIp(...)`和`config.setHdfsPort(...)`来配置 HDFS 的 IP
和端口。默认的 IP是`localhost`，默认的`RPC`端口是`9000`.
@@ -178,7 +184,7 @@ TsFile可以通过以下三个步骤生成，完整的代码参见"写入 TsFile
下面是一系列接口:
- ```
+ ```java
// Create an empty Schema or from an existing map
public Schema()
public Schema(Map<String, MeasurementSchema> measurements)
@@ -194,13 +200,13 @@ TsFile可以通过以下三个步骤生成，完整的代码参见"写入 TsFile
你可以在`TsFileWriter`类中使用以下接口来添加额外的测量(measurement):
- ```
+ ```java
public void addMeasurement(MeasurementSchema measurementSchema) throws
WriteProcessException
```
`MeasurementSchema`类保存了一个测量(measurement)的信息，有几个构造函数:
- ```
+ ```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,
@@ -209,6 +215,7 @@ TsFile可以通过以下三个步骤生成，完整的代码参见"写入 TsFile
**参数:**
+
* measurementID: 测量的名称，通常是传感器的名称。
* type: 数据类型，现在支持六种类型: `BOOLEAN`, `INT32`, `INT64`, `FLOAT`, `DOUBLE`,
`TEXT`;
@@ -222,8 +229,8 @@ TsFile可以通过以下三个步骤生成，完整的代码参见"写入 TsFile
> **注意:** 虽然一个测量(measurement)的名字可以被用在多个deltaObjects中, 但是它的参数是不允许被修改的。比如:
不允许多次为同一个测量(measurement)名添加不同类型的编码。下面是一个错误示例:
-
- ```
+
+ ```java
// The measurement "sensor_1" is float type
addMeasurement(new MeasurementSchema("sensor_1", TSDataType.FLOAT,
TSEncoding.RLE));
// This call will throw a WriteProcessException exception
@@ -233,7 +240,7 @@ TsFile可以通过以下三个步骤生成，完整的代码参见"写入 TsFile
使用这个接口创建一个新的`TSRecord`(时间戳和设备对)。
- ```
+ ```java
public TSRecord(long timestamp, String deviceId)
```
@@ -241,13 +248,13 @@ TsFile可以通过以下三个步骤生成，完整的代码参见"写入 TsFile
用下面这种方法写
- ```
+ ```java
public void write(TSRecord record) throws IOException,
WriteProcessException
```
4. 调用`close`方法来完成写入过程。
- ```
+ ```java
public void close() throws IOException
```
@@ -256,23 +263,25 @@ TsFile可以通过以下三个步骤生成，完整的代码参见"写入 TsFile
1. 使用`ForceAppendTsFileWriter`打开已经关闭的文件。
- ```
+ ```java
public ForceAppendTsFileWriter(File file) throws IOException
```
2. 调用 `doTruncate` 去掉文件的Metadata部分
3. 使用 `ForceAppendTsFileWriter` 构造另一个`TsFileWriter`
- ```
+ ```java
public TsFileWriter(TsFileIOWriter fileWriter) throws IOException
```
请注意 此时需要重新添加测量值(measurement) 再进行上述写入操作。
+
+
#### 写入 TsFile 示例
您需要安装 TsFile 到本地的 Maven 仓库中。
-```
+```shell
mvn clean install -pl tsfile -am -DskipTests
```
@@ -303,6 +312,8 @@ mvn clean install -pl tsfile -am -DskipTests
```
中查看
+
+
#### 读取 TsFile 接口
@@ -315,13 +326,13 @@ mvn clean install -pl tsfile -am -DskipTests
在read接口中，参数`paths`表示要选择的测量值(measurement)。
Path实例可以很容易地通过类`Path`来构造。例如:
-```
+```java
Path p = new Path("device_1.sensor_1");
```
我们可以为查询传递一个 ArrayList 路径，以支持多个路径查询。
-```
+```java
List<Path> paths = new ArrayList<Path>();
paths.add(new Path("device_1.sensor_1"));
paths.add(new Path("device_1.sensor_3"));
@@ -345,29 +356,30 @@ paths.add(new Path("device_1.sensor_3"));
* TimeFilter: 使用时序数据中的`time`过滤。
- ```
+ ```java
IExpression timeFilterExpr = new GlobalTimeExpression(TimeFilter);
```
使用以下关系获得一个`TimeFilter`对象(值是一个 long 型变量)。
- |Relationship|Description|
- |----|----|
- |TimeFilter.eq(value)|选择时间等于值的数据|
- |TimeFilter.lt(value)|选择时间小于值的数据|
- |TimeFilter.gt(value)|选择时间大于值的数据|
- |TimeFilter.ltEq(value)|选择时间小于等于值的数据|
- |TimeFilter.gtEq(value)|选择时间大于等于值的数据|
- |TimeFilter.notEq(value)|选择时间不等于值的数据|
- |TimeFilter.not(TimeFilter)|选择时间不满足另一个时间过滤器的数据|
-
-
+|Relationship|Description|
+|----|----|
+|TimeFilter.eq(value)|选择时间等于值的数据|
+|TimeFilter.lt(value)|选择时间小于值的数据|
+|TimeFilter.gt(value)|选择时间大于值的数据|
+|TimeFilter.ltEq(value)|选择时间小于等于值的数据|
+|TimeFilter.gtEq(value)|选择时间大于等于值的数据|
+|TimeFilter.notEq(value)|选择时间不等于值的数据|
+|TimeFilter.not(TimeFilter)|选择时间不满足另一个时间过滤器的数据|
+
+
* ValueFilter: 使用时序数据中的`value`过滤。
-
- ```
- IExpression valueFilterExpr = new SingleSeriesExpression(Path,
ValueFilter);
- ```
-
+
+
+```java
+IExpression valueFilterExpr = new SingleSeriesExpression(Path, ValueFilter);
+```
+
`ValueFilter`的用法与`TimeFilter`相同，只是需要确保值的类型等于measurement(在路径中定义)的类型。
* **Binary Filter Operators**
@@ -382,52 +394,49 @@ Filter Expression 示例
* **TimeFilterExpression 示例**
-```
+```java
IExpression timeFilterExpr = new GlobalTimeExpression(TimeFilter.eq(15)); //
series time = 15
-
-```
```
+```java
IExpression timeFilterExpr = new GlobalTimeExpression(TimeFilter.ltEq(15)); //
series time <= 15
-
-```
```
+```java
IExpression timeFilterExpr = new GlobalTimeExpression(TimeFilter.lt(15)); //
series time < 15
-
-```
```
+```java
IExpression timeFilterExpr = new GlobalTimeExpression(TimeFilter.gtEq(15)); //
series time >= 15
-
-```
```
+```java
IExpression timeFilterExpr = new GlobalTimeExpression(TimeFilter.notEq(15));
// series time != 15
-
-```
-```
-IExpression timeFilterExpr = BinaryExpression.and(new
GlobalTimeExpression(TimeFilter.gtEq(15L)),
- new
GlobalTimeExpression(TimeFilter.lt(25L))); // 15 <= series time < 25
```
+```java
+IExpression timeFilterExpr = BinaryExpression.and(
+ new GlobalTimeExpression(TimeFilter.gtEq(15L)),
+ new GlobalTimeExpression(TimeFilter.lt(25L))); // 15 <= series time < 25
```
-IExpression timeFilterExpr = BinaryExpression.or(new
GlobalTimeExpression(TimeFilter.gtEq(15L)),
- new
GlobalTimeExpression(TimeFilter.lt(25L))); // series time >= 15 or series time
< 25
+```java
+IExpression timeFilterExpr = BinaryExpression.or(
+ new GlobalTimeExpression(TimeFilter.gtEq(15L)),
+ new GlobalTimeExpression(TimeFilter.lt(25L))); // series time >= 15 or
series time < 25
```
* 读取接口
首先，我们打开 TsFile 并从文件路径`path`中获取一个`ReadOnlyTsFile`实例。
-```
+```java
TsFileSequenceReader reader = new TsFileSequenceReader(path);
ReadOnlyTsFile readTsFile = new ReadOnlyTsFile(reader);
```
接下来，我们准备路径数组和查询表达式，然后通过这个接口得到最终的`QueryExpression`对象:
-```
+```java
QueryExpression queryExpression = QueryExpression.create(paths, statement);
```
ReadOnlyTsFile类有两个`query`方法来执行查询。
-```
+```java
public QueryDataSet query(QueryExpression queryExpression) throws IOException
public QueryDataSet query(QueryExpression queryExpression, long
partitionStartOffset, long partitionEndOffset) throws IOException
```
@@ -461,21 +470,23 @@ public QueryDataSet query(QueryExpression
queryExpression, long partitionStartOf
* `RowRecord next() throws IOException;`
获取下一条记录。
-
+
`RowRecord`类包含一个`long`类型的时间戳和一个`List<Field>`，用于不同传感器中的数据，我们可以使用两个getter方法来获取它们。
-
- ```
+
+ ```java
long getTimestamp();
List<Field> getFields();
```
要从一个字段获取数据，请使用以下方法:
-
- ```
+
+ ```java
TSDataType getDataType();
Object getObjectValue();
```
+
+
#### 读取现有 TsFile 示例
@@ -537,12 +548,13 @@ public class TsFileRead {
reader.close();
}
}
-
```
+
+
### 修改 TsFile 配置项
-```
+```java
TSFileConfig config = TSFileDescriptor.getInstance().getConfig();
config.setXXX();
```
diff --git a/site/src/main/.vuepress/config.js
b/site/src/main/.vuepress/config.js
index d35d8f4..fa1843c 100644
--- a/site/src/main/.vuepress/config.js
+++ b/site/src/main/.vuepress/config.js
@@ -688,8 +688,10 @@ var config = {
title: 'API',
children: [
['API/Programming-JDBC','JDBC'],
-
['API/Programming-Native-API','Native API'],
-
['API/Programming-Other-Languages','Other Languages'],
+
['API/Programming-Java-Native-API','Java Native API'],
+
['API/Programming-Python-Native-API','Python Native API'],
+
['API/Programming-Cpp-Native-API','C++ Native API'],
+
['API/Programming-Go-Native-API','Go Native API'],
['API/Programming-TsFile-API','TsFile API']
]
},
@@ -1365,7 +1367,7 @@ var config = {
title: '系统工具',
children: [
['System-Tools/Load-External-Tsfile','加载 TsFile'],
-
['System-Tools/Performance-Tracing-Tool','查询性API/Programming-Native-API能追踪'],
+
['System-Tools/Performance-Tracing-Tool','查询性能追踪'],
['System-Tools/CSV-Tool','导入导出 CSV'],
['System-Tools/Monitor-and-Log-Tools','监控工具和系统日志'],
['System-Tools/JMX-Tool','JMX 工具'],
@@ -1473,8 +1475,10 @@ var config = {
title: '应用编程接口',
children: [
['API/Programming-JDBC','JDBC'],
-
['API/Programming-Native-API','Java 原生接口'],
-
['API/Programming-Other-Languages','其他语言原生接口'],
+
['API/Programming-Java-Native-API','Java 原生接口'],
+
['API/Programming-Python-Native-API','Python 原生接口'],
+
['API/Programming-Cpp-Native-API','C++ 原生接口'],
+
['API/Programming-Go-Native-API','Go 原生接口'],
['API/Programming-TsFile-API','TsFile API']
]
},
@@ -1498,7 +1502,7 @@ var config = {
title: '系统工具',
children: [
['System-Tools/Load-External-Tsfile','加载 TsFile'],
-
['System-Tools/Performance-Tracing-Tool','查询性API/Programming-Native-API能追踪'],
+
['System-Tools/Performance-Tracing-Tool','查询性能追踪'],
['System-Tools/CSV-Tool','导入导出 CSV'],
['System-Tools/Monitor-and-Log-Tools','监控工具和系统日志'],
['System-Tools/JMX-Tool','JMX 工具'],
