Skip to content

Programming-CSharp-Native-API.md

Latest commit

 

History

History
170 lines (128 loc) · 10.4 KB

Programming-CSharp-Native-API.md

File metadata and controls

170 lines (128 loc) · 10.4 KB

C# Native API

1. Environment Requirements

  • .NET SDK >= 5.0 or .NET Framework 4.x
  • Thrift >= 0.14.1
  • NLog >= 4.7.9

2. Dependency Installation

You can use NuGet Package Manager, .NET CLI, or other tools to install the required packages.

Using .NET CLI:

If you are using .NET 5.0 or later, run the following command to install the latest NuGet package

dotnet add package Apache.IoTDB

For .NET Framework 4.x, we provide a separate NuGet package. Run

dotnet add package Apache.IoTDB.framework

To install an older version, specify the version explicitly

# Install v0.12.1.2
dotnet add package Apache.IoTDB --version 0.12.1.2

3. Quick Start

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

// Initialize session pool  
var session_pool = new SessionPool(host, port, pool_size);  

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

// Create time series  
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 a 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 a 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_lst);  
await session_pool.InsertTabletAsync(tablet);  

// Close session  
await session_pool.Close();

4. Full API Reference

SessionPoolis a thread-safe connection pool that supports concurrent client requests. When pool_size=1, it behaves like a single session.

4.1 Basic API

Method Parameters Description Example
Open bool Open session session_pool.Open(false)
Close null Close session session_pool.Close()
IsOpen null Check session status session_pool.IsOpen()
OpenDebugMode LoggingConfiguration=null Enable debug mode session_pool.OpenDebugMode()
CloseDebugMode null Disable debug mode session_pool.CloseDebugMode()
SetTimeZone string Set timezone session_pool.GetTimeZone()
GetTimeZone null Get timezone session_pool.GetTimeZone()

4.2 Metadata API

Method Parameters Description Example
SetStorageGroup string Create a storage group session_pool.SetStorageGroup("root.97209_TEST_CSHARP_CLIENT_GROUP_01")
CreateTimeSeries string, TSDataType, TSEncoding, Compressor Create a time series session_pool.InsertTabletsAsync(tablets)
CreateMultiTimeSeriesAsync List, List , List , List Create multiple time series session_pool.CreateMultiTimeSeriesAsync(ts_path_lst, data_type_lst, encoding_lst, compressor_lst);
CheckTimeSeriesExistsAsync string Check if a time series exists session_pool.CheckTimeSeriesExistsAsync(time series)

4.3 Write API

IoTDB C# client supports RowRecord (single-row) and Tablet (batch) writing

  • RowRecord: For single-row insertion.
var rowRecord = 
  new RowRecord(long timestamps, List<object> values, List<string> measurements);
  • Tablet: For batch insertion (device + multiple rows).
var tablet = 
  new Tablet(string deviceId,  List<string> measurements, List<List<object>> values, List<long> timestamps);

4.3.1 Record

Method Parameters Description Example
InsertRecordAsync string, RowRecord Insert a single record session_pool.InsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", new RowRecord(1, values, measures));
InsertRecordsAsync List, List Insert multiple records session_pool.InsertRecordsAsync(device_id, rowRecords)
InsertRecordsOfOneDeviceAsync string, List Insert records for one device session_pool.InsertRecordsOfOneDeviceAsync(device_id, rowRecords)
InsertRecordsOfOneDeviceSortedAsync string, List Insert sorted records for one device session_pool.InsertRecordsOfOneDeviceSortedAsync(deviceId, sortedRowRecords);
TestInsertRecordAsync string, RowRecord Test record insertion session_pool.TestInsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", rowRecord)
TestInsertRecordsAsync List, List Test record insertion session_pool.TestInsertRecordsAsync(device_id, rowRecords)

4.3.2 Tablet

Method Parameters Description Example
InsertTabletAsync Tablet Insert a single tablet session_pool.InsertTabletAsync(tablet)
InsertTabletsAsync List Insert multiple tablets session_pool.InsertTabletsAsync(tablets)
TestInsertTabletAsync Tablet Test tablet insertion session_pool.TestInsertTabletAsync(tablet)
TestInsertTabletsAsync List Test tablet insertion session_pool.TestInsertTabletsAsync(tablets)

4.4 Query API

Method Parameters Description Example
ExecuteQueryStatementAsync string Execute a query session_pool.ExecuteQueryStatementAsync("select * from root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE where time<15");
ExecuteNonQueryStatementAsync string Execute a non-query statement session_pool.ExecuteNonQueryStatementAsync( "create timeseries root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE.status with datatype=BOOLEAN,encoding=PLAIN")

4.5 Delete API

Method Parameters Description Example
DeleteStorageGroupAsync string Delete a storage group session_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP_01")
DeleteStorageGroupsAsync List Delete storage groups session_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP")
DeleteTimeSeriesAsync List Delete time series session_pool.DeleteTimeSeriesAsync(ts_path_lst)
DeleteTimeSeriesAsync string Delete time series session_pool.DeleteTimeSeriesAsync(ts_path)
DeleteDataAsync List, long, long Delete data session_pool.DeleteDataAsync(ts_path_lst, 2, 3)

5. Sample Code

For complete examples, refer to: Apache.IoTDB.Samples