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 hereC# Native API - 图1open in new window. Run the following command in the command line to complete installation

  1. dotnet add package Apache.IoTDB

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

Prerequisites

  1. .NET SDK Version >= 5.0 
  2. .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

  1. .NET SDK Version >= 5.0
  2. .NET Framework >= 4.6.1
  3. ApacheThrift >= 0.14.1
  4. 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

  1. // Parameters
  2. string host = "localhost";
  3. int port = 6667;
  4. int pool_size = 2;
  6. // Init Session
  7. var session_pool = new SessionPool(host, port, pool_size);
  9. // Open Session
  10. await session_pool.Open(false);
  12. // Create TimeSeries 
  13. await session_pool.CreateTimeSeries("root.test_group.test_device.ts1", TSDataType.TEXT, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);
  14. await session_pool.CreateTimeSeries("root.test_group.test_device.ts2", TSDataType.BOOLEAN, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);
  15. await session_pool.CreateTimeSeries("root.test_group.test_device.ts3", TSDataType.INT32, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);
  17. // Insert Record
  18. var measures = new List<string>{"ts1", "ts2", "ts3"};
  19. var values = new List<object> { "test_text", true, (int)123 };
  20. var timestamp = 1;
  21. var rowRecord = new RowRecord(timestamp, values, measures);
  22. await session_pool.InsertRecordAsync("root.test_group.test_device", rowRecord);
  24. // Insert Tablet
  25. var timestamp_lst = new List<long>{ timestamp + 1 };
  26. var value_lst = new List<object> {new() {"iotdb", true, (int) 12}};
  27. var tablet = new Tablet("root.test_group.test_device", measures, value_lst, timestamp_ls);
  28. await session_pool.InsertTabletAsync(tablet);
  30. // Close Session
  31. await session_pool.Close();

Row Record

  • Encapsulate and abstract the record data in IoTDB
  • e.g.
timestampstatustemperature
1020
  • Construction：
  1. var rowRecord = 
  2.   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.
timestatustemperature
1020
2020
3321
  • Construction：
  1. var tablet = 
  2.   Tablet(string deviceId,  List<string> measurements, List<List<object>> values, List<long> timestamps);

API

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.GetTimeZone()
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_id, 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_id, 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)

SQL API

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.InsertTabletsAsync(tablets)
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 series
DeleteTimeSeriesAsyncstringdelete time series
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)

e.g.C# Native API - 图2open in new window

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