# 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

    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:

      brew install bison
      brew link bison --force
      
      1
      2

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

      For Bash users:

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

      For zsh users:

      echo 'export PATH="/usr/local/opt/bison/bin:$PATH"' >> ~/.zshrc
      
      1
    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:

      brew install boost
      brew link boost
      
      1
      2
    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:

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

    Some packages can be installed using Yum:

    sudo yum install bison flex openssl-devel
    
    1

    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 (opens new window) .
    2. Download and install Flex & Bison

    3. Install Boost

    4. Install OpenSSL

# Compile

You can download the source code from:

git clone https://github.com/apache/iotdb.git
1

The default dev branch is the master branch, If you want to use a released version (eg. rel/0.13):

git checkout rel/0.13
1

Under the root path of iotdb:

  • Mac & Linux

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

    mvn package -P compile-cpp -pl client-cpp,server,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
    
    1
    • 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.1.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
void open(); 
1
  • Open a session, with a parameter to specify whether to enable RPC compression
void open(bool enableRPCCompression); 
1

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

  • Close a Session
void close(); 
1

# Data Definition Interface (DDL)

# Database Management

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

# Timeseries Management

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

# Schema Template

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

// Add one aligned measurement to a template
void addAlignedMeasurementsInTemplate(const std::string &template_name,
                                      const std::string &measurement,
                                      TSDataType::TSDataType dataType,
                                      TSEncoding::TSEncoding encoding,
                                      CompressionType::CompressionType compressor);

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

// Add one unaligned measurement to a template
void addUnalignedMeasurementsInTemplate(const std::string &template_name,
                                        const std::string &measurement,
                                        TSDataType::TSDataType dataType,
                                        TSEncoding::TSEncoding encoding,
                                        CompressionType::CompressionType compressor);

// Delete a node in template and its children
void deleteNodeInTemplate(const std::string &template_name, const std::string &path);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
  • You can query measurement templates with these APIS:
// Return the amount of measurements inside a template
int countMeasurementsInTemplate(const std::string &template_name);

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

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

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

// Return all measurements paths under the designated patter inside template
std::vector<std::string> showMeasurementsInTemplate(const std::string &template_name, const std::string &pattern);
1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

# Insert with type inference

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

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


void insertRecords(const std::vector<std::string> &deviceIds,
                   const std::vector<int64_t> &times,
                   const std::vector<std::vector<std::string>> &measurementsList,
                   const std::vector<std::vector<std::string>> &valuesList);


void insertRecordsOfOneDevice(const std::string &deviceId,
                              std::vector<int64_t> &times,
                              std::vector<std::vector<std::string>> &measurementsList,
                              const std::vector<std::vector<std::string>> &valuesList);
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 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
void deleteData(const std::string &path, int64_t time);
void deleteData(const std::vector<std::string> &deviceId, int64_t time);
1
2

# IoTDB-SQL Interface

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

# 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#65518087

# on Windows

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

Failed to delete cached file C:\Users\Administrator\.m2\repository\.cache\download-maven-plugin\index.ser
1

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.

Found Error, Edit this page on GitHub (opens new window)

Copyright © 2022 The Apache Software Foundation.
Apache and the Apache feather logo are trademarks of The Apache Software Foundation

Have a question? Connect with us on QQ, WeChat, or Slack. Join the community now.

We use Google Analytics to collect anonymous, aggregated usage information.