Skip to main content

C# Native API

About 3 min

C# Native API

The Git repository for the C# Native API client is located hereopen in new window


Install from NuGet Package

We have prepared Nuget Package for C# users. Users can directly install the client through .NET CLI. The link of our NuGet Package is hereopen in new window. Run the following command in the command line to complete installation

dotnet add package Apache.IoTDB

Note that the Apache.IoTDB package only supports versions of the .net framework 4.6.1 greater than 4.6.1.


.NET SDK Version >= 5.0 
.NET Framework >= 4.6.1

How to Use the Client (Quick Start)

Users can quickly get started by referring to the use cases under the Apache-IoTDB-Client-CSharp-UserCaseopen in new window directory in the iotdb-client-csharp Git repositoryopen in new window. These use cases serve as a useful resource for getting familiar with the client's functionality and capabilities.

For those who wish to delve deeper into the client's usage and explore more advanced features, the samplesopen in new window directory in the same repository contains additional code samples.

Developer environment requirements for iotdb-client-csharp

.NET SDK Version >= 5.0
.NET Framework >= 4.6.1
ApacheThrift >= 0.14.1
NLog >= 4.7.9


  • Linux, Macos or other unix-like OS
  • Windows+bash(WSL, cygwin, Git Bash)

Command Line Tools

  • dotnet CLI
  • Thrift

Basic interface description

The Session interface is semantically identical to other language clients

// Parameters
string host = "localhost";
int port = 6667;
int pool_size = 2;

// Init Session
var session_pool = new SessionPool(host, port, pool_size);

// Open Session
await session_pool.Open(false);

// Create TimeSeries 
await session_pool.CreateTimeSeries("root.test_group.test_device.ts1", TSDataType.TEXT, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);
await session_pool.CreateTimeSeries("root.test_group.test_device.ts2", TSDataType.BOOLEAN, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);
await session_pool.CreateTimeSeries("root.test_group.test_device.ts3", TSDataType.INT32, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);

// Insert Record
var measures = new List<string>{"ts1", "ts2", "ts3"};
var values = new List<object> { "test_text", true, (int)123 };
var timestamp = 1;
var rowRecord = new RowRecord(timestamp, values, measures);
await session_pool.InsertRecordAsync("root.test_group.test_device", rowRecord);

// Insert Tablet
var timestamp_lst = new List<long>{ timestamp + 1 };
var value_lst = new List<object> {"iotdb", true, (int) 12};
var tablet = new Tablet("root.test_group.test_device", measures, value_lst, timestamp_ls);
await session_pool.InsertTabletAsync(tablet);

// Close Session
await session_pool.Close();

Row Record

  • Encapsulate and abstract the record data in IoTDB
  • e.g.
  • Construction:
var rowRecord = 
  new RowRecord(long timestamp, List<object> values, List<string> measurements);


  • A data structure similar to a table, containing several non-empty data blocks of a device's rows。
  • e.g.
  • Construction:
var tablet = 
  Tablet(string deviceId,  List<string> measurements, List<List<object>> values, List<long> timestamps);


Basic API

api nameparametersnotesuse example
Openboolopen sessionsession_pool.Open(false)
Closenullclose sessionsession_pool.Close()
IsOpennullcheck if session is opensession_pool.IsOpen()
OpenDebugModeLoggingConfiguration=nullopen debug modesession_pool.OpenDebugMode()
CloseDebugModenullclose debug modesession_pool.CloseDebugMode()
SetTimeZonestringset time zonesession_pool.SetTimeZone("+08:00")
GetTimeZonenullget time zonesession_pool.GetTimeZone()

Record API

api nameparametersnotesuse example
InsertRecordAsyncstring, RowRecordinsert single recordsession_pool.InsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", new RowRecord(1, values, measures));
InsertRecordsAsyncList<string>, List<RowRecord>insert recordssession_pool.InsertRecordsAsync(device_ids, rowRecords)
InsertRecordsOfOneDeviceAsyncstring, List<RowRecord>insert records of one devicesession_pool.InsertRecordsOfOneDeviceAsync(device_id, rowRecords)
InsertRecordsOfOneDeviceSortedAsyncstring, List<RowRecord>insert sorted records of one deviceInsertRecordsOfOneDeviceSortedAsync(deviceId, sortedRowRecords);
TestInsertRecordAsyncstring, RowRecordtest insert recordsession_pool.TestInsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", rowRecord)
TestInsertRecordsAsyncList<string>, List<RowRecord>test insert recordsession_pool.TestInsertRecordsAsync(device_ids, rowRecords)

Tablet API

api nameparametersnotesuse example
InsertTabletAsyncTabletinsert single tabletsession_pool.InsertTabletAsync(tablet)
InsertTabletsAsyncList<Tablet>insert tabletssession_pool.InsertTabletsAsync(tablets)
TestInsertTabletAsyncTablettest insert tabletsession_pool.TestInsertTabletAsync(tablet)
TestInsertTabletsAsyncList<Tablet>test insert tabletssession_pool.TestInsertTabletsAsync(tablets)


api nameparametersnotesuse example
ExecuteQueryStatementAsyncstringexecute sql query statementsession_pool.ExecuteQueryStatementAsync("select * from root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE where time<15");
ExecuteNonQueryStatementAsyncstringexecute sql nonquery statementsession_pool.ExecuteNonQueryStatementAsync( "create timeseries root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE.status with datatype=BOOLEAN,encoding=PLAIN")

Scheam API

api nameparametersnotesuse example
SetStorageGroupstringset storage groupsession_pool.SetStorageGroup("root.97209_TEST_CSHARP_CLIENT_GROUP_01")
CreateTimeSeriesstring, TSDataType, TSEncoding, Compressorcreate time seriessession_pool.CreateTimeSeries("root.97209_TEST_CSHARP_CLIENT_GROUP_01", data_type, encoding, compressor)
DeleteStorageGroupAsyncstringdelete single storage groupsession_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP_01")
DeleteStorageGroupsAsyncList<string>delete storage groupsession_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP")
CreateMultiTimeSeriesAsyncList<string>, List<TSDataType> , List<TSEncoding> , List<Compressor>create multi time seriessession_pool.CreateMultiTimeSeriesAsync(ts_path_lst, data_type_lst, encoding_lst, compressor_lst);
DeleteTimeSeriesAsyncList<string>delete time seriessession_pool.DeleteTimeSeriesAsync(ts_path_lst)
DeleteTimeSeriesAsyncstringdelete time seriessession_pool.DeleteTimeSeriesAsync("root.97209_TEST_CSHARP_CLIENT_GROUP_01")
DeleteDataAsyncList<string>, long, longdelete datasession_pool.DeleteDataAsync(ts_path_lst, 2, 3)

Other API

api nameparametersnotesuse example
CheckTimeSeriesExistsAsyncstringcheck if time series existssession_pool.CheckTimeSeriesExistsAsync(time series) in new window


In order to execute concurrent client requests, we provide a SessionPool for the native interface.
Since SessionPool itself is a superset of Session, as soon as SessionPool is instantiated with a pool_size parameter set to 1, it reverts to the original Session.

We use the ConcurrentQueue data structure to encapsulate a client queue to maintain multiple connections with the server.
When the Open() interface is called, a specified number of clients are created and stored in the queue.
Synchronous access to the queue is achieved through the System.Threading.Monitor class.

When a request is executed, it will try to find an idle client connection from the Connection pool.
If there is no idle connection, the program will wait until there is an idle connection available and use that.

When a connection is finished executing a request, it will automatically be returned to the pool and be available for processing other requests.

Copyright © 2024 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.