Skip to content

Commit 404c831

Browse files
W1y1rW1y1r
authored
Add dev-1.3 folder (#592)
1 parent 1820ccc commit 404c831

232 files changed

Lines changed: 111530 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/UserGuide/dev-1.3/API/Programming-CSharp-Native-API.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
<!--
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
-->
18+
19+
# C# Native API
20+
21+
## Installation
22+
23+
### Install from NuGet Package
24+
25+
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](https://www.nuget.org/packages/Apache.IoTDB/). Run the following command in the command line to complete installation
26+
27+
```sh
28+
dotnet add package Apache.IoTDB
29+
```
30+
31+
Note that the `Apache.IoTDB` package only supports versions greater than `.net framework 4.6.1`.
32+
33+
## Prerequisites
34+
35+
- .NET SDK Version >= 5.0
36+
- .NET Framework >= 4.6.1
37+
38+
## How to Use the Client (Quick Start)
39+
40+
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.
41+
42+
For those who wish to delve deeper into the client's usage and explore more advanced features, the samples directory contains additional code samples.
43+
44+
## Developer environment requirements for iotdb-client-csharp
45+
46+
- .NET SDK Version >= 5.0
47+
- .NET Framework >= 4.6.1
48+
- ApacheThrift >= 0.14.1
49+
- NLog >= 4.7.9
50+
51+
### OS
52+
53+
- Linux, Macos or other unix-like OS
54+
- Windows+bash(WSL, cygwin, Git Bash)
55+
56+
### Command Line Tools
57+
58+
- dotnet CLI
59+
- Thrift
60+
61+
## Basic interface description
62+
63+
The Session interface is semantically identical to other language clients
64+
65+
```csharp
66+
// Parameters
67+
string host = "localhost";
68+
int port = 6667;
69+
int pool_size = 2;
70+
71+
// Init Session
72+
var session_pool = new SessionPool(host, port, pool_size);
73+
74+
// Open Session
75+
await session_pool.Open(false);
76+
77+
// Create TimeSeries
78+
await session_pool.CreateTimeSeries("root.test_group.test_device.ts1", TSDataType.TEXT, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);
79+
await session_pool.CreateTimeSeries("root.test_group.test_device.ts2", TSDataType.BOOLEAN, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);
80+
await session_pool.CreateTimeSeries("root.test_group.test_device.ts3", TSDataType.INT32, TSEncoding.PLAIN, Compressor.UNCOMPRESSED);
81+
82+
// Insert Record
83+
var measures = new List<string>{"ts1", "ts2", "ts3"};
84+
var values = new List<object> { "test_text", true, (int)123 };
85+
var timestamp = 1;
86+
var rowRecord = new RowRecord(timestamp, values, measures);
87+
await session_pool.InsertRecordAsync("root.test_group.test_device", rowRecord);
88+
89+
// Insert Tablet
90+
var timestamp_lst = new List<long>{ timestamp + 1 };
91+
var value_lst = new List<object> {"iotdb", true, (int) 12};
92+
var tablet = new Tablet("root.test_group.test_device", measures, value_lst, timestamp_ls);
93+
await session_pool.InsertTabletAsync(tablet);
94+
95+
// Close Session
96+
await session_pool.Close();
97+
```
98+
99+
## **Row Record**
100+
101+
- Encapsulate and abstract the `record` data in **IoTDB**
102+
- e.g.
103+
104+
| timestamp | status | temperature |
105+
| --------- | ------ | ----------- |
106+
| 1 | 0 | 20 |
107+
108+
- Construction：
109+
110+
```csharp
111+
var rowRecord =
112+
new RowRecord(long timestamps, List<object> values, List<string> measurements);
113+
```
114+
115+
### **Tablet**
116+
117+
- A data structure similar to a table, containing several non empty data blocks of a device's rows。
118+
- e.g.
119+
120+
| time | status | temperature |
121+
| ---- | ------ | ----------- |
122+
| 1 | 0 | 20 |
123+
| 2 | 0 | 20 |
124+
| 3 | 3 | 21 |
125+
126+
- Construction：
127+
128+
```csharp
129+
var tablet =
130+
Tablet(string deviceId, List<string> measurements, List<List<object>> values, List<long> timestamps);
131+
```
132+
133+
## **API**
134+
135+
### **Basic API**
136+
137+
| api name | parameters | notes | use example |
138+
| -------------- | ------------------------- | ------------------------ | ----------------------------- |
139+
| Open | bool | open session | session_pool.Open(false) |
140+
| Close | null | close session | session_pool.Close() |
141+
| IsOpen | null | check if session is open | session_pool.IsOpen() |
142+
| OpenDebugMode | LoggingConfiguration=null | open debug mode | session_pool.OpenDebugMode() |
143+
| CloseDebugMode | null | close debug mode | session_pool.CloseDebugMode() |
144+
| SetTimeZone | string | set time zone | session_pool.GetTimeZone() |
145+
| GetTimeZone | null | get time zone | session_pool.GetTimeZone() |
146+
147+
### **Record API**
148+
149+
| api name | parameters | notes | use example |
150+
| ----------------------------------- | --------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
151+
| InsertRecordAsync | string, RowRecord | insert single record | session_pool.InsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", new RowRecord(1, values, measures)); |
152+
| InsertRecordsAsync | List\<string\>, List\<RowRecord\> | insert records | session_pool.InsertRecordsAsync(device_id, rowRecords) |
153+
| InsertRecordsOfOneDeviceAsync | string, List\<RowRecord\> | insert records of one device | session_pool.InsertRecordsOfOneDeviceAsync(device_id, rowRecords) |
154+
| InsertRecordsOfOneDeviceSortedAsync | string, List\<RowRecord\> | insert sorted records of one device | InsertRecordsOfOneDeviceSortedAsync(deviceId, sortedRowRecords); |
155+
| TestInsertRecordAsync | string, RowRecord | test insert record | session_pool.TestInsertRecordAsync("root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE", rowRecord) |
156+
| TestInsertRecordsAsync | List\<string\>, List\<RowRecord\> | test insert record | session_pool.TestInsertRecordsAsync(device_id, rowRecords) |
157+
158+
### **Tablet API**
159+
160+
| api name | parameters | notes | use example |
161+
| ---------------------- | -------------- | -------------------- | -------------------------------------------- |
162+
| InsertTabletAsync | Tablet | insert single tablet | session_pool.InsertTabletAsync(tablet) |
163+
| InsertTabletsAsync | List\<Tablet\> | insert tablets | session_pool.InsertTabletsAsync(tablets) |
164+
| TestInsertTabletAsync | Tablet | test insert tablet | session_pool.TestInsertTabletAsync(tablet) |
165+
| TestInsertTabletsAsync | List\<Tablet\> | test insert tablets | session_pool.TestInsertTabletsAsync(tablets) |
166+
167+
### **SQL API**
168+
169+
| api name | parameters | notes | use example |
170+
| ----------------------------- | ---------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
171+
| ExecuteQueryStatementAsync | string | execute sql query statement | session_pool.ExecuteQueryStatementAsync("select \* from root.97209_TEST_CSHARP_CLIENT_GROUP.TEST_CSHARP_CLIENT_DEVICE where time<15"); |
172+
| 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") |
173+
174+
### **Scheam API**
175+
176+
| api name | parameters | notes | use example |
177+
| -------------------------- | ---------------------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
178+
| SetStorageGroup | string | set storage group | session_pool.SetStorageGroup("root.97209_TEST_CSHARP_CLIENT_GROUP_01") |
179+
| CreateTimeSeries | string, TSDataType, TSEncoding, Compressor | create time series | session_pool.InsertTabletsAsync(tablets) |
180+
| DeleteStorageGroupAsync | string | delete single storage group | session_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP_01") |
181+
| DeleteStorageGroupsAsync | List\<string\> | delete storage group | session_pool.DeleteStorageGroupAsync("root.97209_TEST_CSHARP_CLIENT_GROUP") |
182+
| 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); |
183+
| DeleteTimeSeriesAsync | List\<string\> | delete time series | |
184+
| DeleteTimeSeriesAsync | string | delete time series | |
185+
| DeleteDataAsync | List\<string\>, long, long | delete data | session_pool.DeleteDataAsync(ts_path_lst, 2, 3) |
186+
187+
### **Other API**
188+
189+
| api name | parameters | notes | use example |
190+
| -------------------------- | ---------- | --------------------------- | ---------------------------------------------------- |
191+
| CheckTimeSeriesExistsAsync | string | check if time series exists | session_pool.CheckTimeSeriesExistsAsync(time series) |
192+
193+
[e.g.](https://github.com/apache/iotdb-client-csharp/tree/main/samples/Apache.IoTDB.Samples)
194+
195+
## SessionPool
196+
197+
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`
198+
199+
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.
200+
201+
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
202+
203+
When a connection is used up, it will automatically return to the pool and wait for the next time it is used up

0 commit comments

Comments
 (0)