Introduction to Apache IoTDB C# Client

[Xiulong Yuan <yu...@gmail.com>]

Hi guys, I am Yuan Xiulong from China. I'm currently pursuing my master's
degree in School of Software, Tsinghua University. In April last year, my
mentor, Professor Liu Lin, suggested that I, Lu Zhan and Zeng Zheng should
develop a C# client for Apache IoTDB so that C# users can easily use Apache
IoTDB. After weeks of research and development, we open-sourced the client
and released it on NuGet
<https://github.com/eedalong/Apache-IoTDB-Client-CSharp> in May of last
year[1]. Since its release, our C# client has received thousands of
downloads and also received a lot of feedback and improvement suggestions
from our community: such as providing a more user-friendly interface,
providing parallel request sending and processing
<https://github.com/eedalong/Apache-IoTDB-Client-CSharp/releases/tag/0.12.1.0>,
and supporting session abnormal reconnecting
<https://github.com/eedalong/Apache-IoTDB-Client-CSharp/blob/main/docs/C%23%E5%8E%9F%E7%94%9F%E6%8E%A5%E5%8F%A3.md#%E5%BC%82%E5%B8%B8%E9%87%8D%E8%BF%9E>[2]
(support from Lu Zhan), etc. At the same time, our C# client is also timely
updated to support the latest features of Apache IoTDB, such as aligned
time series insertion, SchemaTemplate manipulation interface support, and
Tablet structure that supports inserting null values
<https://github.com/eedalong/Apache-IoTDB-Client-CSharp/releases/tag/0.13.0.1>[3]
(support from Lu Zhan), etc. We even had a developer from Lithuania
involved in refactoring the code structure for us. In this blog, we will
give a basic introduction to the key features of our C# client, the
installation guide and examples.
Installation
For easier installation, we have prepared NuGet packages for C# users. You
can directly install the client through .NET CLI. The NuGet package is
linked as follows <https://www.nuget.org/packages/Apache.IoTDB/> [4]. Run
the following command on your command line to complete the installation of
the latest version of the client. At the same time, in order to support
better cross-platform, our client is developed and constructed based on
.NET SDK (supported by Zeng Zheng).

dotnet add package Apache.IoTDB

Features
SessionPool
Similar to the Java client of Apache IoTDB, we also provide an
implementation of SessionPool that supports parallel request sending and
processing. In scenarios where network requests take a long time or are
unstable, SessionPool can provide better performance than a single client.
Regarding SessionPool, we provide detailed implementation details and
performance tests in the document. For details, see the document link
<https://github.com/eedalong/Apache-IoTDB-Client-CSharp/blob/main/docs/session_pool_zh.md>
[5] (support from Ma Wenxuan).
ByteBuffer
Data communication between the client and the server requires a lot of
serialization and deserialization operations according to the Apache IoTDB
serialization protocol. Simply using native C# serialization method will
bring severe memory allocation and free overhead. We provide ByteBuffer
which can estimateof the memory size of large tablets and use a smart
algorithm to expand the memory size to improve the performance of
serialization and deserialization during serializing large tablet.
Serialization and deserialization using the implemented ByteBuffer can
improve the performance by 30 times compared with C# native serialization.
See document
<https://github.com/eedalong/Apache-IoTDB-Client-CSharp/blob/main/docs/bytebuffer_zh.md>
[6] for details.
Example
In this section, we provide code examples for the use of the C# client. All
interfaces exposed by the C# client are asynchronous interfaces. You start
with establishing a sessionpool by specifying the IP, port and size of the
pool. The size of the SessionPool represents the number of local
connections established with the server.

var session_pool = new SessionPool(host, port, pool_size);
await session_pool.Open(false);

After setting up the SessionPool, we can use it to create a timeseries:

status = await session_pool.CreateTimeSeries(

"root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE.TEST_CSHARP_CLIENT_TS1",
TSDataType.TEXT,
                TSEncoding.PLAIN, Compressor.UNCOMPRESSED);

We can use SessionPool for row-by-row Record insertion. Since SessionPool
can support parallel sending, when sending a large number of Records,
SessionPool will provide better performance than a single client
connection.

var tasks = new List<Task<int>>();
for (var timestamp = 1; timestamp <= fetch_size * processed_size; timestamp++)
{
    var rowRecord = new RowRecord(timestamp, values, measures);
    var task = session_pool.InsertRecordAsync(
        "root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE",
rowRecord);
    tasks.Add(task);
}
Task.WaitAll(tasks.ToArray());

We can also use SessionPool to execute SQL statements and display the
results.

var res = await session_pool.ExecuteQueryStatementAsync(
                "select * from " + string.Format("{0}.{1}",
test_group_name, test_devices[1]) + " where time<15");
res.ShowTableNames();
while (res.HasNext()) Console.WriteLine(res.Next());

Above, we briefly introduce several interface calls used by C# clients. We
provide API document
<https://github.com/eedalong/Apache-IoTDB-Client-CSharp/blob/main/docs/API.md>[7]
and test codes
<https://github.com/eedalong/Apache-IoTDB-Client-CSharp/tree/main/samples/Apache.IoTDB.Samples>
[8] in our repository. Users can read these documents and codes to
understand the use of interfaces supported by C# client (supported by Lu
Zhan, Zeng Zheng and Ma Wenxuan).
Summary
Above, we have made an overall introduction to the C# client of Apache
IoTDB. Apache IoTDB users of C# technology stack are very welcome to use
our client and put forward improvement suggestions to us!
References
[1] https://github.com/eedalong/Apache-IoTDB-Client-CSharp
[2]
https://github.com/eedalong/Apache-IoTDB-Client-CSharp/blob/main/docs/C%23%E5%8E%9F%E7%94%9F%E6%8E%A5%E5%8F%A3.md#%E5%BC%82%E5%B8%B8%E9%87%8D%E8%BF%9E
[3]
https://github.com/eedalong/Apache-IoTDB-Client-CSharp/releases/tag/0.13.0.1
[4] https://www.nuget.org/packages/Apache.IoTDB/
[5]
https://github.com/eedalong/Apache-IoTDB-Client-CSharp/blob/main/docs/session_pool_zh.md
[6]
https://github.com/eedalong/Apache-IoTDB-Client-CSharp/blob/main/docs/API.md
[7]
https://github.com/eedalong/Apache-IoTDB-Client-CSharp/blob/main/docs/API.md
[8]
https://github.com/eedalong/Apache-IoTDB-Client-CSharp/tree/main/samples/Apache.IoTDB.Samples