Skip to content

Commit

Permalink
docs: standardize latest api (#481)
Browse files Browse the repository at this point in the history 
* docs: standardize latest api

* chore: tweaks
  • Loading branch information
@Mister-Hope
Mister-Hope authored Dec 17, 2024
1 parent bf430f5 commit e5e642d
Show file tree
Hide file tree
Showing 14 changed files with 1,402 additions and 1,818 deletions.
116 changes: 53 additions & 63 deletions src/UserGuide/latest/API/Programming-CSharp-Native-API.md
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,19 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
-->

# C# Native API
Expand All @@ -35,33 +32,31 @@ Note that the `Apache.IoTDB` package only supports versions greater than `.net f

## Prerequisites

.NET SDK Version >= 5.0
.NET Framework >= 4.6.1
- .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.
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
```
- .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)
- Linux, Macos or other unix-like OS
- Windows+bash(WSL, cygwin, Git Bash)

### Command Line Tools

* dotnet CLI
* Thrift
- dotnet CLI
- Thrift

## Basic interface description

Expand All @@ -79,7 +74,7 @@ var session_pool = new SessionPool(host, port, pool_size);
// Open Session
await session_pool.Open(false);

// Create TimeSeries
// 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);
Expand Down Expand Up @@ -113,7 +108,7 @@ await session_pool.Close();
- Construction：

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

Expand All @@ -131,12 +126,10 @@ var rowRecord =
- Construction：

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



## **API**

### **Basic API**
Expand All @@ -153,52 +146,50 @@ var tablet =

### **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) |
| 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) |
| 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) |
| 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"); |
| 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") |
| 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) |
| 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.](https://github.com/apache/iotdb-client-csharp/tree/main/samples/Apache.IoTDB.Samples)

## SessionPool
Expand All @@ -210,4 +201,3 @@ We use the `ConcurrentQueue` data structure to encapsulate a client queue to mai
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

Loading

0 comments on commit e5e642d

Please sign in to comment.