C# Native API

Installation

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 here. 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 greater than .net framework 4.6.1.

Prerequisites

.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-UserCase directory. 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 samples directory 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

OS

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

timestamp	status	temperature
1	0	20

• Construction：

var rowRecord = 
  new RowRecord(long timestamps, List<object> values, List<string> measurements);

Tablet

• A data structure similar to a table, containing several non empty data blocks of a device's rows。
• e.g.

time	status	temperature
1	0	20
2	0	20
3	3	21

• Construction：

var tablet = 
  Tablet(string deviceId,  List<string> measurements, List<List<object>> values, List<long> timestamps);

API

Basic API

api name	parameters	notes	use example
Open	bool	open session	session_pool.Open(false)
Close	null	close session	session_pool.Close()
IsOpen	null	check if session is open	session_pool.IsOpen()
OpenDebugMode	LoggingConfiguration=null	open debug mode	session_pool.OpenDebugMode()
CloseDebugMode	null	close debug mode	session_pool.CloseDebugMode()
SetTimeZone	string	set time zone	session_pool.GetTimeZone()
GetTimeZone	null	get time zone	session_pool.GetTimeZone()

Record API

api name	parameters	notes	use example
InsertRecordAsync	string, RowRecord	insert single record	session_pool.InsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", new RowRecord(1, values, measures));
InsertRecordsAsync	List<string>, List<RowRecord>	insert records	session_pool.InsertRecordsAsync(device_id, rowRecords)
InsertRecordsOfOneDeviceAsync	string, List<RowRecord>	insert records of one device	session_pool.InsertRecordsOfOneDeviceAsync(device_id, rowRecords)
InsertRecordsOfOneDeviceSortedAsync	string, List<RowRecord>	insert sorted records of one device	InsertRecordsOfOneDeviceSortedAsync(deviceId, sortedRowRecords);
TestInsertRecordAsync	string, RowRecord	test insert record	session_pool.TestInsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", rowRecord)
TestInsertRecordsAsync	List<string>, List<RowRecord>	test insert record	session_pool.TestInsertRecordsAsync(device_id, rowRecords)

Tablet API

api name	parameters	notes	use example
InsertTabletAsync	Tablet	insert single tablet	session_pool.InsertTabletAsync(tablet)
InsertTabletsAsync	List<Tablet>	insert tablets	session_pool.InsertTabletsAsync(tablets)
TestInsertTabletAsync	Tablet	test insert tablet	session_pool.TestInsertTabletAsync(tablet)
TestInsertTabletsAsync	List<Tablet>	test insert tablets	session_pool.TestInsertTabletsAsync(tablets)

SQL API

api name	parameters	notes	use example
ExecuteQueryStatementAsync	string	execute sql query statement	session_pool.ExecuteQueryStatementAsync("select * from root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE where time<15");
ExecuteNonQueryStatementAsync	string	execute sql nonquery statement	session_pool.ExecuteNonQueryStatementAsync( "create timeseries root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE.status with datatype=BOOLEAN,encoding=PLAIN")

Scheam API

api name	parameters	notes	use example
SetStorageGroup	string	set storage group	session_pool.SetStorageGroup("root.97209_TEST_CSHARP_CLIENT_GROUP_01")
CreateTimeSeries	string, TSDataType, TSEncoding, Compressor	create time series	session_pool.InsertTabletsAsync(tablets)
DeleteStorageGroupAsync	string	delete single storage group	session_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP_01")
DeleteStorageGroupsAsync	List<string>	delete storage group	session_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP")
CreateMultiTimeSeriesAsync	List<string>, List<TSDataType> , List<TSEncoding> , List<Compressor>	create multi time series	session_pool.CreateMultiTimeSeriesAsync(ts_path_lst, data_type_lst, encoding_lst, compressor_lst);
DeleteTimeSeriesAsync	List<string>	delete time series
DeleteTimeSeriesAsync	string	delete time series
DeleteDataAsync	List<string>, long, long	delete data	session_pool.DeleteDataAsync(ts_path_lst, 2, 3)

Other API

api name	parameters	notes	use example
CheckTimeSeriesExistsAsync	string	check if time series exists	session_pool.CheckTimeSeriesExistsAsync(time series)

e.g.

SessionPool

To implement concurrent client requests, we provide a SessionPool for the native interface. Since SessionPool itself is a superset of Session, when SessionPool is a When the pool_size parameter is 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 in the queue, and synchronous access to the queue is achieved through the System.Threading.Monitor class.

When a request occurs, it will try to find an idle client connection from the Connection pool. If there is no idle connection, the program will need to wait until there is an idle connection

When a connection is used up, it will automatically return to the pool and wait for the next time it is used up