C++ Native API

Dependencies

  • Java 8+
  • Maven 3.5+
  • Flex
  • Bison 2.7+
  • Boost 1.56+
  • OpenSSL 1.0+
  • GCC 5.5.0+

Installation From Source Code

Install CPP Dependencies

  • MAC

  • 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. brew install bison 2. brew link bison --force

    Then, you need to tell the OS where the new bison is.

    For Bash users:

    1. echo 'export PATH="/usr/local/opt/bison/bin:$PATH"' >> ~/.bash_profile

    For zsh users:

    1. 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:

    1. brew install boost 2. 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="". - Ubuntu 20

To install all dependencies, run:

1. sudo apt-get install gcc-9 g++-9 libstdc++-9-dev bison flex libboost-all-dev libssl-dev zlib1g-dev - CentOS 7.x

Some packages can be installed using Yum:

1. sudo yum install bison flex openssl-devel

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 CMakeC++ Native API - 图1open in new window .

    • Download and install Flex & Bison

    • Download Win_Flex_BisonC++ Native API - 图2open in new window .

    • After downloaded, please rename the executables to flex.exe and bison.exe and add them to “PATH” environment variables.

    • Install Boost

    • Download BoostC++ Native API - 图3open in new window .

    • Then build Boost by executing bootstrap.bat and b2.exe.

    • Install OpenSSL

    • Download and install OpenSSLC++ Native API - 图4open in new window .

Compile

You can download the source code from:

1. 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):

1. git checkout rel/0.13

Under the root path of iotdb:

  • Mac & Linux

1. mvn package -P compile-cpp -pl example/client-cpp-example -am -DskipTest - Windows

1. 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. ``

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

Native APIs

Here we show the commonly used interfaces and their parameters in the Native API:

Initialization

  • Open a Session
1. void open();
  • Open a session, with a parameter to specify whether to enable RPC compression
1. void open(bool enableRPCCompression);

Notice: this RPC compression status of client must comply with that of IoTDB server

  • Close a Session
1. void close();

Data Definition Interface (DDL)

Database Management

  • CREATE DATABASE
1. void setStorageGroup(const std::string &storageGroupId);
  • Delete one or several databases
1. void deleteStorageGroup(const std::string &storageGroup);
2. void deleteStorageGroups(const std::vector<std::string> &storageGroups);

Timeseries Management

  • Create one or multiple timeseries
1. void createTimeseries(const std::string &path, TSDataType::TSDataType dataType, TSEncoding::TSEncoding encoding,
2. CompressionType::CompressionType compressor);

4. void createMultiTimeseries(const std::vector<std::string> &paths,
5. const std::vector<TSDataType::TSDataType> &dataTypes,
6. const std::vector<TSEncoding::TSEncoding> &encodings,
7. const std::vector<CompressionType::CompressionType> &compressors,
8. std::vector<std::map<std::string, std::string>> *propsList,
9. std::vector<std::map<std::string, std::string>> *tagsList,
10. std::vector<std::map<std::string, std::string>> *attributesList,
11. std::vector<std::string> *measurementAliasList);
  • Create aligned timeseries
1. void createAlignedTimeseries(const std::string &deviceId,
2. const std::vector<std::string> &measurements,
3. const std::vector<TSDataType::TSDataType> &dataTypes,
4. const std::vector<TSEncoding::TSEncoding> &encodings,
5. const std::vector<CompressionType::CompressionType> &compressors);
  • Delete one or several timeseries
1. void deleteTimeseries(const std::string &path);
2. void deleteTimeseries(const std::vector<std::string> &paths);
  • Check whether the specific timeseries exists.
1. bool checkTimeseriesExists(const std::string &path);

Schema Template

  • Create a schema template
1. void createSchemaTemplate(const Template &templ);
  • Set the schema template named templateName at path prefixPath.
1. void setSchemaTemplate(const std::string &template_name, const std::string &prefix_path);
  • Unset the schema template
1. void unsetSchemaTemplate(const std::string &prefix_path, const std::string &template_name);
  • After measurement template created, you can edit the template with belowed APIs.
1. // Add aligned measurements to a template
2. void addAlignedMeasurementsInTemplate(const std::string &template_name,
3. const std::vector<std::string> &measurements,
4. const std::vector<TSDataType::TSDataType> &dataTypes,
5. const std::vector<TSEncoding::TSEncoding> &encodings,
6. const std::vector<CompressionType::CompressionType> &compressors);

8. // Add one aligned measurement to a template
9. void addAlignedMeasurementsInTemplate(const std::string &template_name,
10. const std::string &measurement,
11. TSDataType::TSDataType dataType,
12. TSEncoding::TSEncoding encoding,
13. CompressionType::CompressionType compressor);

15. // Add unaligned measurements to a template
16. void addUnalignedMeasurementsInTemplate(const std::string &template_name,
17. const std::vector<std::string> &measurements,
18. const std::vector<TSDataType::TSDataType> &dataTypes,
19. const std::vector<TSEncoding::TSEncoding> &encodings,
20. const std::vector<CompressionType::CompressionType> &compressors);

22. // Add one unaligned measurement to a template
23. void addUnalignedMeasurementsInTemplate(const std::string &template_name,
24. const std::string &measurement,
25. TSDataType::TSDataType dataType,
26. TSEncoding::TSEncoding encoding,
27. CompressionType::CompressionType compressor);

29. // Delete a node in template and its children
30. void deleteNodeInTemplate(const std::string &template_name, const std::string &path);
  • You can query measurement templates with these APIS:
1. // Return the amount of measurements inside a template
2. int countMeasurementsInTemplate(const std::string &template_name);

4. // Return true if path points to a measurement, otherwise returne false
5. bool isMeasurementInTemplate(const std::string &template_name, const std::string &path);

7. // Return true if path exists in template, otherwise return false
8. bool isPathExistInTemplate(const std::string &template_name, const std::string &path);

10. // Return all measurements paths inside template
11. std::vector<std::string> showMeasurementsInTemplate(const std::string &template_name);

13. // Return all measurements paths under the designated patter inside template
14. std::vector<std::string> showMeasurementsInTemplate(const std::string &template_name, const std::string &pattern);

Data Manipulation Interface (DML)

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
1. void insertTablet(Tablet &tablet);
  • Insert multiple Tablets
1. void insertTablets(std::unordered_map<std::string, Tablet *> &tablets);
  • Insert a Record, which contains multiple measurement value of a device at a timestamp
1. void insertRecord(const std::string &deviceId, int64_t time, const std::vector<std::string> &measurements,
2. const std::vector<TSDataType::TSDataType> &types, const std::vector<char *> &values);
  • Insert multiple Records
1. void insertRecords(const std::vector<std::string> &deviceIds,
2. const std::vector<int64_t> &times,
3. const std::vector<std::vector<std::string>> &measurementsList,
4. const std::vector<std::vector<TSDataType::TSDataType>> &typesList,
5. 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
1. void insertRecordsOfOneDevice(const std::string &deviceId,
2. std::vector<int64_t> &times,
3. std::vector<std::vector<std::string>> &measurementsList,
4. std::vector<std::vector<TSDataType::TSDataType>> &typesList,
5. std::vector<std::vector<char *>> &valuesList);

Insert with type inference

Without type information, server has to do type inference, which may cost some time.

1. void insertRecord(const std::string &deviceId, int64_t time, const std::vector<std::string> &measurements,
2. const std::vector<std::string> &values);

5. void insertRecords(const std::vector<std::string> &deviceIds,
6. const std::vector<int64_t> &times,
7. const std::vector<std::vector<std::string>> &measurementsList,
8. const std::vector<std::vector<std::string>> &valuesList);

11. void insertRecordsOfOneDevice(const std::string &deviceId,
12. std::vector<int64_t> &times,
13. std::vector<std::vector<std::string>> &measurementsList,
14. const std::vector<std::vector<std::string>> &valuesList);

Insert data into Aligned Timeseries

The Insert of aligned timeseries uses interfaces like insertAlignedXXX, and others are similar to the above interfaces:

  • insertAlignedRecord
  • insertAlignedRecords
  • insertAlignedRecordsOfOneDevice
  • insertAlignedTablet
  • insertAlignedTablets

Delete

  • Delete data before or equal to a timestamp of one or several timeseries
1. void deleteData(const std::string &path, int64_t time);
2. void deleteData(const std::vector<std::string> &deviceId, int64_t time);

IoTDB-SQL Interface

  • Execute query statement
1. void executeNonQueryStatement(const std::string &sql);
  • Execute non query statement
1. void executeNonQueryStatement(const std::string &sql);

Examples

The sample code of using these interfaces is in:

  • example/client-cpp-example/src/SessionExample.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

FAQ

on Mac

If errors occur when compiling thrift source code, try to downgrade your xcode-commandline from 12 to 11.5

see https://stackoverflow.com/questions/63592445/ld-unsupported-tapi-file-type-tapi-tbd-in-yaml-file/65518087#65518087C++ Native API - 图5open in new window

on Windows

When Building Thrift and downloading packages via “wget”, a possible annoying issue may occur with error message looks like:

1. 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.