C Native API

1. Overview

The C Native API (SessionC) is a C language wrapper for the C++ Session SDK. It is used in the same way as the C++ driver. You only need to include the additional header file SessionC.h. Compilation, linking, and runtime deployment share the same iotdb_session shared library as the C++ driver.

Thrift and Boost are already packaged into iotdb_session. Applications do not need to install Thrift or Boost headers/libraries separately.

Note: This feature is supported since V2.0.10.

2. Installation

2.1 Option 1: Use the precompiled SDK package (recommended)

CI publishes zip packages by platform/toolchain. The file name is in the form iotdb-session-cpp-<version>-<classifier>.zip. After extraction, the directory structure is as follows:

iotdb-session-cpp-<version>-<classifier>/
├── include/
│   ├── SessionC.h          # C Native API header file
│   ├── Session.h           # C++ API header file
│   └── ...
├── lib/
│   ├── libiotdb_session.so       # Linux
│   ├── libiotdb_session.dylib      # macOS
│   └── iotdb_session.dll + .lib    # Windows
├── cmake/iotdb-session-config.cmake
├── pkgconfig/iotdb-session.pc
└── examples/                       # Includes tree_example.c

Select the classifier according to the target environment:

Target environment	classifier suffix
Linux x86_64, glibc >= 2.28	`linux-x86_64-glibc2.28`
Linux aarch64, glibc >= 2.28	`linux-aarch64-glibc2.28`
macOS x86_64	`macos-x86_64`
macOS arm64	`macos-aarch64`
Windows + Visual Studio 2017	`windows-x86_64-msvc14.1`
Windows + Visual Studio 2019	`windows-x86_64-msvc14.2`
Windows + Visual Studio 2022	`windows-x86_64-msvc14.3`
Windows + Visual Studio 2026	`windows-x86_64-msvc14.4`

Note: Do not use a higher-version client to connect to a lower-version server.

2.1.1 C program compilation example

Linux / macOS:

gcc -std=c11 tree_example.c \
  -I"$IOTDB_SESSION_HOME/include" \
  -L"$IOTDB_SESSION_HOME/lib" \
  -liotdb_session -pthread \
  -Wl,-rpath,"$IOTDB_SESSION_HOME/lib" \
  -o tree_example

Windows + MSVC:

Compile in the x64 Native Tools Command Prompt (or run vcvars64.bat first to initialize the environment):

set IOTDB_SESSION_HOME=C:\path\to\iotdb-session-cpp-<version>-<classifier>
cd /d %IOTDB_SESSION_HOME%\examples
cl /TC /std:c11 tree_example.c /I "%IOTDB_SESSION_HOME%\include" ^
  /link /LIBPATH:"%IOTDB_SESSION_HOME%\lib" iotdb_session.lib
copy /Y "%IOTDB_SESSION_HOME%\lib\iotdb_session.dll" .

At runtime, place libiotdb_session.so / .dylib / .dll in the same directory as the executable, or configure the corresponding dynamic library search path for your platform.

2.1.2 Compile examples in the SDK package

Run the following commands in the root directory of the extracted SDK package. The examples/ directory must be at the same level as include/ and lib/.

cd iotdb-session-cpp-<version>-<classifier>
cmake -S examples -B examples-build -DCMAKE_BUILD_TYPE=Release
cmake --build examples-build

Windows + Visual Studio:

cd iotdb-session-cpp-<version>-<classifier>
cmake -S examples -B examples-build -G "Visual Studio 17 2022" -A x64
cmake --build examples-build --config Release

If the library is installed in another path, such as the source CMake installation directory iotdb-client/client-cpp/target/install, explicitly specify IOTDB_SDK_ROOT. This directory must contain include/ and lib/.

cmake -S iotdb-client/client-cpp/examples -B examples-build -DCMAKE_BUILD_TYPE=Release \
  -DIOTDB_SDK_ROOT=iotdb-client/client-cpp/target/install
cmake --build examples-build

Windows example:

cmake -S iotdb-client\client-cpp\examples -B examples-build -G "Visual Studio 17 2022" -A x64 ^
  -DIOTDB_SDK_ROOT=D:\iotdb\iotdb-client\client-cpp\target\install
cmake --build examples-build --config Release --target tree_example

2.2 Option 2: Build from source

2.2.1 Install build dependencies (required only for source builds)

macOS

brew install bison boost openssl

Ubuntu 16.04+ or other Debian distributions

sudo apt-get update
sudo apt-get install gcc g++ bison flex libboost-all-dev libssl-dev cmake

CentOS 7.7+/Fedora/Rocky Linux or other Red Hat distributions

sudo yum update
sudo yum install gcc gcc-c++ boost-devel bison flex openssl-devel cmake

Windows

Install MS Visual Studio (2019+ recommended), and select the C/C++ IDE and compiler components with CMake support.
Install CMake.
Install Win_Flex_Bison, rename the executables to flex.exe and bison.exe, and add them to PATH.
Install Boost (optional, CMake can also fetch it automatically) and OpenSSL.

The CMake build compiles Thrift 0.23 from source. SSL is enabled by default. If system OpenSSL cannot be found, the build falls back to building OpenSSL from source.

2.2.2 Build

Clone the source code from git:

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

To use a specific release version, switch to the corresponding branch, such as 2.0.6:

git checkout rc/2.0.6

Run the Maven build in the IoTDB root directory (recommended):

# Linux / macOS: build and package the SDK
./mvnw -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests package

# Windows (Visual Studio 2022 example)
.\mvnw.cmd -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests package

If Boost is not added to PATH on Windows, append a parameter such as:

-Dboost.include.dir="C:\boost_1_88_0"

You can also use CMake directly:

cmake -S iotdb-client/client-cpp -B build
cmake --build build --target install

Linux release packages are built in the manylinux_2_28 container. The target machine requires glibc 2.28 or later. The current build no longer uses old parameters such as -Diotdb-tools-thrift.version=0.14.1.1-gcc4-SNAPSHOT.

Full verification with integration tests:

./mvnw clean verify -P with-cpp -pl iotdb-client/client-cpp -am

2.3 Build artifacts

After a successful build, C API related files are located as follows:

C API header file (source): iotdb-client/client-cpp/src/include/SessionC.h
C API header file (installation/SDK package): include/SessionC.h
Library files:
- Source build: iotdb-client/client-cpp/target/install/lib/
- Maven package: iotdb-client/client-cpp/target/iotdb-session-cpp-<version>-<classifier>.zip
- Linux: lib/libiotdb_session.so
- Windows: lib/iotdb_session.dll / lib/iotdb_session.lib
Example source code:
- Tree model: iotdb-client/client-cpp/examples/tree_example.c
- Table model: iotdb-client/client-cpp/examples/table_example.c
Integration tests:
- Tree model: iotdb-client/client-cpp/test/cpp/sessionCIT.cpp
- Table model: iotdb-client/client-cpp/test/cpp/sessionCRelationalIT.cpp

3. Basic API description

Description: The C driver is used in the same way as the C++ driver. You only need to include the additional header file SessionC.h. Compilation, runtime behavior, and system dependencies are shared with the C++ driver.

3.1 Common conventions

3.1.1 Status codes and error messages

TsStatus: TS_OK (0) indicates success. Any non-zero value indicates failure.
Predefined error codes:
- TS_ERR_CONNECTION (-1)
- TS_ERR_EXECUTION (-2)
- TS_ERR_INVALID_PARAM (-3)
- TS_ERR_NULL_PTR (-4)
- TS_ERR_UNKNOWN (-99)
The implementation may also return other negative values, which must be interpreted together with ts_get_last_error().
The Session C++ API reports many errors through exceptions and does not return a unified status code. The C API uniformly returns the integer type TsStatus, and fine-grained error information can be obtained through ts_get_last_error().

const char* ts_get_last_error(void);

Returns the error message of the last failed C API call in the current thread. The returned pointer is valid until the next C API call in the same thread.

3.1.2 Memory and handle rules

All char* buf + int bufLen output parameters must be allocated by the caller.
CSession*, CTablet*, CSessionDataSet*, and CRowRecord* are opaque pointers. After successful creation, the caller must release them according to the conventions of each API.

3.2 Enumerations and constants

TSDataType_C (data type)

Enumeration value	Meaning
`TS_TYPE_BOOLEAN`	Boolean
`TS_TYPE_INT32`	32-bit integer
`TS_TYPE_INT64`	64-bit integer
`TS_TYPE_FLOAT`	Single-precision floating point
`TS_TYPE_DOUBLE`	Double-precision floating point
`TS_TYPE_TEXT`	Text
`TS_TYPE_TIMESTAMP`	Timestamp
`TS_TYPE_DATE`	Date
`TS_TYPE_BLOB`	Binary large object
`TS_TYPE_STRING`	String
`TS_TYPE_INVALID`	Invalid parameter/error path (not a server-side type)

TSEncoding_C (encoding)

TS_ENCODING_PLAIN, TS_ENCODING_DICTIONARY, TS_ENCODING_RLE, TS_ENCODING_DIFF, TS_ENCODING_TS_2DIFF, TS_ENCODING_BITMAP, TS_ENCODING_GORILLA_V1, TS_ENCODING_REGULAR, TS_ENCODING_GORILLA, TS_ENCODING_ZIGZAG, TS_ENCODING_FREQ

TSCompressionType_C (compression)

TS_COMPRESSION_UNCOMPRESSED, TS_COMPRESSION_SNAPPY, TS_COMPRESSION_GZIP, TS_COMPRESSION_LZO, TS_COMPRESSION_SDT, TS_COMPRESSION_PAA, TS_COMPRESSION_PLA, TS_COMPRESSION_LZ4, TS_COMPRESSION_ZSTD, TS_COMPRESSION_LZMA2

3.3 Handles, status codes, and constants

Name	C definition	Meaning	Lifecycle responsibility
`CSession*`	`typedef struct CSession_ CSession;`	Tree model session	After `ts_session_new` / `ts_session_new_with_zone` / `ts_session_new_multi_node` succeeds, the caller calls `ts_session_close` if it has been opened, and then `ts_session_destroy`
`CTablet*`	`typedef struct CTablet_ CTablet;` (opaque)	Tablet batch writing, shared by tree and table models	After `ts_tablet_new` / `ts_tablet_new_with_category` succeeds, the caller calls `ts_tablet_destroy`
`CSessionDataSet*`	`typedef struct CSessionDataSet_ CSessionDataSet;` (opaque)	Query result set, shared by tree and table models	After a query API successfully returns `*dataSet`, the caller calls `ts_dataset_destroy`
`CRowRecord*`	`typedef struct CRowRecord_ CRowRecord;` (opaque)	Current row	When `ts_dataset_next` returns a non-null value, the caller calls `ts_row_record_destroy`
`TsStatus`	`typedef int64_t TsStatus;`	API execution result code	`TS_OK` is 0. Any non-zero value indicates failure
`ts_get_last_error`	`const char* ts_get_last_error(void);`	Error message of the last failed C API call in the current thread	The returned pointer is valid until the next C API call in the same thread

3.4 Common Tablet APIs

3.4.1 Creation and destruction

API signature	Function	Input parameters	Return value	Success condition	Failure condition	Resource responsibility
`CTablet* ts_tablet_new(const char* deviceId, int columnCount, const char* const* columnNames, const TSDataType_C* dataTypes, int maxRowNumber);`	Create a Tablet handle	deviceId: device or table name; columnNames / dataTypes: arrays of column names and types; maxRowNumber: maximum number of rows	`CTablet*`	Returns a non-null handle	Returns a null handle	Caller calls `ts_tablet_destroy`
`void ts_tablet_destroy(CTablet* tablet);`	Destroy a Tablet handle	tablet: handle to release	None	The handle must not be used after the call	-	Releases tablet

3.4.2 Data filling and state control

API signature	Function	Return value	Success condition	Remarks
`int ts_tablet_get_row_count(CTablet* tablet);`	Query the current valid row count of the Tablet	int	Row count >= 0	Read-only query
`TsStatus ts_tablet_set_row_count(CTablet* tablet, int rowCount);`	Set the valid row count of the Tablet	TsStatus	`TS_OK`	The valid row count must be set before writing
`TsStatus ts_tablet_add_timestamp(CTablet* tablet, int rowIndex, int64_t timestamp);`	Write a timestamp for the specified row	TsStatus	`TS_OK`
`TsStatus ts_tablet_add_value_bool(CTablet* tablet, int colIndex, int rowIndex, bool value);`	Write a Boolean value	TsStatus	`TS_OK`
`TsStatus ts_tablet_add_value_int32(CTablet* tablet, int colIndex, int rowIndex, int32_t value);`	Write an int32 value	TsStatus	`TS_OK`
`TsStatus ts_tablet_add_value_int64(CTablet* tablet, int colIndex, int rowIndex, int64_t value);`	Write an int64 value	TsStatus	`TS_OK`
`TsStatus ts_tablet_add_value_float(CTablet* tablet, int colIndex, int rowIndex, float value);`	Write a float value	TsStatus	`TS_OK`
`TsStatus ts_tablet_add_value_double(CTablet* tablet, int colIndex, int rowIndex, double value);`	Write a double value	TsStatus	`TS_OK`
`TsStatus ts_tablet_add_value_string(CTablet* tablet, int colIndex, int rowIndex, const char* value);`	Write a string	TsStatus	`TS_OK`	String memory is managed by the caller
`void ts_tablet_reset(CTablet* tablet);`	Reset the internal state of the Tablet for reuse	void	-	Does not release the object. Only clears the state

Description: The current SessionC implementation does not provide ts_tablet_add_value_object. Use the C++ Session API to write OBJECT values.

3.5 Common DataSet APIs

3.5.1 Iteration control and metadata

API signature	Function	Return value	Remarks
`void ts_dataset_set_fetch_size(CSessionDataSet* dataSet, int fetchSize);`	Set the fetch batch size of the result set	None
`bool ts_dataset_has_next(CSessionDataSet* dataSet);`	Determine whether there may be another row	bool	On failure, check `ts_get_last_error()`
`CRowRecord* ts_dataset_next(CSessionDataSet* dataSet);`	Get the next row record handle	Row handle pointer	Non-NULL indicates a valid row. NULL indicates end or failure
`int ts_dataset_get_column_count(CSessionDataSet* dataSet);`	Get the number of columns in the result set	int
`const char* ts_dataset_get_column_name(CSessionDataSet* dataSet, int index);`	Get a column name by index	String pointer	No buf/bufLen output
`const char* ts_dataset_get_column_type(CSessionDataSet* dataSet, int index);`	Get a column type name by index	Type name string pointer	No buf/bufLen output
`void ts_dataset_destroy(CSessionDataSet* dataSet);`	Release a query result set handle	None	After each non-null `CRowRecord*` returned by `ts_dataset_next`, call `ts_row_record_destroy` in time

3.5.2 Value access

API signature	Function	Return value	Remarks
`void ts_row_record_destroy(CRowRecord* record);`	Release a row record handle	None
`int64_t ts_row_record_get_timestamp(CRowRecord* record);`	Read the timestamp of the current row	int64_t	The timestamp is not read from DataSet
`int ts_row_record_get_field_count(CRowRecord* record);`	Read the number of fields in the current row	int
`bool ts_row_record_is_null(CRowRecord* record, int index);`	Determine whether the specified column is null	bool
`bool ts_row_record_get_bool(CRowRecord* record, int index);`	Read a Boolean value by column index	bool
`int32_t ts_row_record_get_int32(CRowRecord* record, int index);`	Read an int32 value by column index	int32_t
`int64_t ts_row_record_get_int64(CRowRecord* record, int index);`	Read an int64 value by column index	int64_t
`float ts_row_record_get_float(CRowRecord* record, int index);`	Read a float value by column index	float
`double ts_row_record_get_double(CRowRecord* record, int index);`	Read a double value by column index	double
`const char* ts_row_record_get_string(CRowRecord* record, int index);`	Read the byte view of a text/binary column	const char.	May contain `.`. Not a buf . bufLen pattern
`int32_t ts_row_record_get_date_int32(CRowRecord* record, int index);`	Read a DATE column and return an integer in YYYYMMDD format	int32_t	Returns 0 if the field is null, out of bounds, or not DATE
`size_t ts_row_record_get_string_byte_length(CRowRecord* record, int index);`	Read the byte length of a string/binary field	size_t	TEXT/BLOB/STRING, etc. Do not use strlen
`TSDataType_C ts_row_record_get_data_type(CRowRecord* record, int index);`	Read the data type enumeration by column index	Enumeration	Returns `TS_TYPE_INVALID` for invalid parameters or out-of-bounds indexes

3.6 Tree model CSession API matrix

3.6.1 Lifecycle and session properties

API signature	Function	Return value	Success condition	Resource responsibility
`CSession* ts_session_new(const char* host, int rpcPort, const char* username, const char* password);`	Create a tree model session (single host)	`CSession*`	Returns a non-null handle	If opened, call `ts_session_close` first, and then `ts_session_destroy`
`CSession* ts_session_new_with_zone(const char* host, int rpcPort, const char* username, const char* password, const char* zoneId, int fetchSize);`	Create a session and specify the time zone and fetch size	`CSession*`	Returns a non-null handle	Same as above
`CSession* ts_session_new_multi_node(const char* const* nodeUrls, int urlCount, const char* username, const char* password);`	Create a tree model session (multi-node URL)	`CSession*`	Returns a non-null handle	Same as above
`void ts_session_destroy(CSession* session);`	Destroy a tree model session handle	None	-	Releases session
`TsStatus ts_session_open(CSession* session);`	Open a tree model RPC connection	TsStatus	`TS_OK`	On failure, read `ts_get_last_error()`
`TsStatus ts_session_open_with_compression(CSession* session, bool enableRPCCompression);`	Open a connection and set whether to enable RPC compression	TsStatus	`TS_OK`	Same as above
`TsStatus ts_session_close(CSession* session);`	Close a tree model connection	TsStatus	`TS_OK`	`ts_session_destroy` is still required
`TsStatus ts_session_set_timezone(CSession* session, const char* zoneId);`	Set the session time zone	TsStatus	`TS_OK`
`TsStatus ts_session_get_timezone(CSession* session, char* buf, int bufLen);`	Get the current session time zone string into a buffer	TsStatus	`TS_OK` and buf is valid	The caller allocates the buffer

3.6.2 Schema management

API signature	Function	Return value	Remarks
`TsStatus ts_session_create_database(CSession* session, const char* database);`	Create a database	TsStatus
`TsStatus ts_session_delete_database(CSession* session, const char* database);`	Delete a database	TsStatus
`TsStatus ts_session_delete_databases(CSession* session, const char* const* databases, int count);`	Delete databases in batches	TsStatus
`TsStatus ts_session_create_timeseries(CSession* session, const char* path, TSDataType_C dataType, TSEncoding_C encoding, TSCompressionType_C compressor);`	Create a single timeseries	TsStatus
`TsStatus ts_session_create_timeseries_ex(CSession* session, const char* path, TSDataType_C dataType, TSEncoding_C encoding, TSCompressionType_C compressor, int propsCount, const char* const* propKeys, const char* const* propValues, int tagsCount, const char* const* tagKeys, const char* const* tagValues, int attrsCount, const char* const* attrKeys, const char* const* attrValues, const char* measurementAlias);`	Create a timeseries with extensions such as properties, tags, attributes, and alias	TsStatus	`propsCount`/`tagsCount`/`attrsCount` must match their corresponding key/value arrays. `measurementAlias` can be NULL
`TsStatus ts_session_create_multi_timeseries(CSession* session, int count, const char* const* paths, const TSDataType_C* dataTypes, const TSEncoding_C* encodings, const TSCompressionType_C* compressors);`	Create timeseries in batches	TsStatus
`TsStatus ts_session_create_aligned_timeseries(CSession* session, const char* deviceId, int count, const char* const* measurements, const TSDataType_C* dataTypes, const TSEncoding_C* encodings, const TSCompressionType_C* compressors);`	Create aligned timeseries under the specified device	TsStatus
`TsStatus ts_session_check_timeseries_exists(CSession* session, const char* path, bool* exists);`	Check whether the timeseries for the path exists	TsStatus	Existence is output through `bool*`
`TsStatus ts_session_delete_timeseries(CSession* session, const char* path);`	Delete a single timeseries	TsStatus
`TsStatus ts_session_delete_timeseries_batch(CSession* session, const char* const* paths, int count);`	Delete timeseries in batches	TsStatus

3.6.3 Writing

API signature	Function	Return value	Remarks
`TsStatus ts_session_insert_record_str(CSession* session, const char* deviceId, int64_t time, int count, const char* const* measurements, const char* const* values);`	Insert one record for one device (string values)	TsStatus	No new handle
`TsStatus ts_session_insert_record(CSession* session, const char* deviceId, int64_t time, int count, const char* const* measurements, const TSDataType_C* types, const void* const* values);`	Insert one record for one device (strongly typed values)	TsStatus	`values[i]` points to the value of the type corresponding to `types[i]`
`TsStatus ts_session_insert_aligned_record_str(CSession* session, const char* deviceId, int64_t time, int count, const char* const* measurements, const char* const* values);`	Insert one record for an aligned device (string values)	TsStatus
`TsStatus ts_session_insert_aligned_record(CSession* session, const char* deviceId, int64_t time, int count, const char* const* measurements, const TSDataType_C* types, const void* const* values);`	Insert one record for an aligned device (strongly typed values)	TsStatus
`TsStatus ts_session_insert_records_str(CSession* session, int deviceCount, const char* const* deviceIds, const int64_t* times, const int* measurementCounts, const char* const* const* measurementsList, const char* const* const* valuesList);`	Batch insert for multiple devices (string values)	TsStatus	The lengths of `measurementsList[i]` / `valuesList[i]` are determined by `measurementCounts[i]`
`TsStatus ts_session_insert_aligned_records_str(CSession* session, int deviceCount, const char* const* deviceIds, const int64_t* times, const int* measurementCounts, const char* const* const* measurementsList, const char* const* const* valuesList);`	Batch insert for multiple aligned devices (string values)	TsStatus	Same as above
`TsStatus ts_session_insert_records(CSession* session, int deviceCount, const char* const* deviceIds, const int64_t* times, const int* measurementCounts, const char* const* const* measurementsList, const TSDataType_C* const* typesList, const void* const* const* valuesList);`	Batch insert for multiple devices (strongly typed values)	TsStatus
`TsStatus ts_session_insert_aligned_records(CSession* session, int deviceCount, const char* const* deviceIds, const int64_t* times, const int* measurementCounts, const char* const* const* measurementsList, const TSDataType_C* const* typesList, const void* const* const* valuesList);`	Batch insert for multiple aligned devices (strongly typed values)	TsStatus
`TsStatus ts_session_insert_records_of_one_device(CSession* session, const char* deviceId, int rowCount, const int64_t* times, const int* measurementCounts, const char* const* const* measurementsList, const TSDataType_C* const* typesList, const void* const* const* valuesList, bool sorted);`	Batch insert multiple rows for one device	TsStatus	`sorted` indicates whether timestamps are already sorted
`TsStatus ts_session_insert_aligned_records_of_one_device(CSession* session, const char* deviceId, int rowCount, const int64_t* times, const int* measurementCounts, const char* const* const* measurementsList, const TSDataType_C* const* typesList, const void* const* const* valuesList, bool sorted);`	Batch insert multiple aligned rows for one device	TsStatus	Same as above
`TsStatus ts_session_insert_tablet(CSession* session, CTablet* tablet, bool sorted);`	Batch write by Tablet in the tree model	TsStatus	Ownership of tablet is not transferred
`TsStatus ts_session_insert_aligned_tablet(CSession* session, CTablet* tablet, bool sorted);`	Batch write by Tablet in the aligned model	TsStatus	Ownership of tablet is not transferred
`TsStatus ts_session_insert_tablets(CSession* session, int tabletCount, const char* const* deviceIds, CTablet** tablets, bool sorted);`	Batch write multiple Tablets	TsStatus	Ownership of tablets is not transferred
`TsStatus ts_session_insert_aligned_tablets(CSession* session, int tabletCount, const char* const* deviceIds, CTablet** tablets, bool sorted);`	Batch write multiple aligned Tablets	TsStatus	Same as above

3.6.4 Querying

API signature	Function	Return value	Resource responsibility
`TsStatus ts_session_execute_query(CSession* session, const char* sql, CSessionDataSet** dataSet);`	Execute query SQL and return a result set	TsStatus	Caller calls `ts_dataset_destroy` for `*dataSet`
`TsStatus ts_session_execute_query_with_timeout(CSession* session, const char* sql, int64_t timeoutInMs, CSessionDataSet** dataSet);`	Execute a query with timeout	TsStatus	Same as above
`TsStatus ts_session_execute_non_query(CSession* session, const char* sql);`	Execute non-query SQL	TsStatus	No new handle
`TsStatus ts_session_execute_raw_data_query(CSession* session, int pathCount, const char* const* paths, int64_t startTime, int64_t endTime, CSessionDataSet** dataSet);`	Query raw data by paths and time range	TsStatus	Caller destroys `*dataSet`
`TsStatus ts_session_execute_last_data_query(CSession* session, int pathCount, const char* const* paths, CSessionDataSet** dataSet);`	Query last point data for specified paths	TsStatus	Caller destroys `*dataSet`
`TsStatus ts_session_execute_last_data_query_with_time(CSession* session, int pathCount, const char* const* paths, int64_t lastTime, CSessionDataSet** dataSet);`	Query last point data with lastTime	TsStatus	Caller destroys `*dataSet`

3.6.5 Data deletion

API signature	Function	Return value
`TsStatus ts_session_delete_data(CSession* session, const char* path, int64_t endTime);`	Delete data by path	TsStatus
`TsStatus ts_session_delete_data_batch(CSession* session, int pathCount, const char* const* paths, int64_t endTime);`	Delete data by multiple paths in batches	TsStatus
`TsStatus ts_session_delete_data_range(CSession* session, int pathCount, const char* const* paths, int64_t startTime, int64_t endTime);`	Delete data by time range	TsStatus

4. Sample code

#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include "SessionC.h"

#define HOST "127.0.0.1"
#define PORT 6667
#define USER "root"
#define PASS "root"

#define TS_PATH "root.cdemo.d0.s0"
#define DEVICE "root.cdemo.d0"

static void fail(const char* ctx, CSession* s) {
  fprintf(stderr, "[tree_example] %s failed: %s.", ctx, ts_get_last_error());
  if (s) {
    ts_session_close(s);
    ts_session_destroy(s);
  }
  exit(1);
}

int main(void) {
  const char* path = TS_PATH;
  CSession* session = ts_session_new(HOST, PORT, USER, PASS);
  if (!session) {
    fprintf(stderr, "[tree_example] ts_session_new returned NULL: %s.", ts_get_last_error());
    return 1;
  }
  if (ts_session_open(session) != TS_OK) {
    fail("ts_session_open", session);
  }

  bool exists = false;
  if (ts_session_check_timeseries_exists(session, path, &exists) != TS_OK) {
    fail("ts_session_check_timeseries_exists", session);
  }
  if (exists) {
    if (ts_session_delete_timeseries(session, path) != TS_OK) {
      fail("ts_session_delete_timeseries (cleanup old)", session);
    }
  }
  if (ts_session_create_timeseries(session, path, TS_TYPE_INT64, TS_ENCODING_RLE,
                                   TS_COMPRESSION_SNAPPY) != TS_OK) {
    fail("ts_session_create_timeseries", session);
  }

  const char* measurements[] = {"s0"};
  const char* values[] = {"100"};
  if (ts_session_insert_record_str(session, DEVICE, 1LL, 1, measurements, values) != TS_OK) {
    fail("ts_session_insert_record_str", session);
  }

  CSessionDataSet* dataSet = NULL;
  if (ts_session_execute_query(session, "select s0 from root.cdemo.d0", &dataSet) != TS_OK) {
    fail("ts_session_execute_query", session);
  }
  if (!dataSet) {
    fprintf(stderr, "[tree_example] dataSet is NULL.");
    ts_session_close(session);
    ts_session_destroy(session);
    return 1;
  }
  ts_dataset_set_fetch_size(dataSet, 1024);

  int rows = 0;
  while (ts_dataset_has_next(dataSet)) {
    CRowRecord* record = ts_dataset_next(dataSet);
    if (!record) {
      break;
    }
    int64_t v = ts_row_record_get_int64(record, 0);
    printf("[tree_example] row %d: s0 = %lld.", rows, (long long)v);
    ts_row_record_destroy(record);
    rows++;
  }
  ts_dataset_destroy(dataSet);

  printf("[tree_example] done, read %d row(s)..", rows);

  if (ts_session_delete_timeseries(session, path) != TS_OK) {
    fail("ts_session_delete_timeseries", session);
  }

  ts_session_close(session);
  ts_session_destroy(session);
  return 0;
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

C Native API

1. Overview

2. Installation

2.1 Option 1: Use the precompiled SDK package (recommended)

2.1.1 C program compilation example

2.1.2 Compile examples in the SDK package

2.2 Option 2: Build from source

2.2.1 Install build dependencies (required only for source builds)

2.2.2 Build

2.3 Build artifacts

3. Basic API description

3.1 Common conventions

3.1.1 Status codes and error messages

3.1.2 Memory and handle rules

3.2 Enumerations and constants

3.3 Handles, status codes, and constants

3.4 Common Tablet APIs

3.4.1 Creation and destruction

3.4.2 Data filling and state control

3.5 Common DataSet APIs

3.5.1 Iteration control and metadata

3.5.2 Value access

3.6 Tree model CSession API matrix

3.6.1 Lifecycle and session properties

3.6.2 Schema management

3.6.3 Writing

3.6.4 Querying

3.6.5 Data deletion

4. Sample code

FilesExpand file tree

Programming-C-Native-API_apache.md

Latest commit

History

Programming-C-Native-API_apache.md

File metadata and controls

C Native API

1. Overview

2. Installation

2.1 Option 1: Use the precompiled SDK package (recommended)

2.1.1 C program compilation example

2.1.2 Compile examples in the SDK package

2.2 Option 2: Build from source

2.2.1 Install build dependencies (required only for source builds)

2.2.2 Build

2.3 Build artifacts

3. Basic API description

3.1 Common conventions

3.1.1 Status codes and error messages

3.1.2 Memory and handle rules

3.2 Enumerations and constants

3.3 Handles, status codes, and constants

3.4 Common Tablet APIs

3.4.1 Creation and destruction

3.4.2 Data filling and state control

3.5 Common DataSet APIs

3.5.1 Iteration control and metadata

3.5.2 Value access

3.6 Tree model CSession API matrix

3.6.1 Lifecycle and session properties

3.6.2 Schema management

3.6.3 Writing

3.6.4 Querying

3.6.5 Data deletion

4. Sample code