This is an automated email from the ASF dual-hosted git repository.
critas pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 45ed6e9e update go api of tree model (#965)
45ed6e9e is described below
commit 45ed6e9ef4b983f0ff2adacdb2fd1e3d6c148ec0
Author: leto-b <[email protected]>
AuthorDate: Fri Jan 16 10:46:56 2026 +0800
update go api of tree model (#965)
---
.../Master/Tree/API/Programming-Go-Native-API.md | 406 +++++++++++++++++++--
.../latest/API/Programming-Go-Native-API.md | 406 +++++++++++++++++++--
.../Master/Tree/API/Programming-Go-Native-API.md | 357 +++++++++++++++++-
.../latest/API/Programming-Go-Native-API.md | 357 +++++++++++++++++-
4 files changed, 1446 insertions(+), 80 deletions(-)
diff --git a/src/UserGuide/Master/Tree/API/Programming-Go-Native-API.md
b/src/UserGuide/Master/Tree/API/Programming-Go-Native-API.md
index baad278b..a4afa6c4 100644
--- a/src/UserGuide/Master/Tree/API/Programming-Go-Native-API.md
+++ b/src/UserGuide/Master/Tree/API/Programming-Go-Native-API.md
@@ -21,44 +21,396 @@
# Go Native API
-The Git repository for the Go Native API client is located
[here](https://github.com/apache/iotdb-client-go/)
+The Go Native API supports interaction with the database through both
`Session` and `SessionPool` methods. Since `Session` is not thread-safe, using
`SessionPool` is strongly recommended for programming. In multi-threaded
concurrent scenarios, `SessionPool` can reasonably manage and allocate
connection resources to enhance system performance and resource utilization
efficiency.
-## 1. Dependencies
+This article focuses on the usage of `SessionPool`, covering the complete
process from environment preparation and core operation steps to the full set
of interfaces.
- * golang >= 1.13
- * make >= 3.0
- * curl >= 7.1.1
- * thrift 0.15.0
- * Linux、Macos or other unix-like systems
- * Windows+bash (WSL、cygwin、Git Bash)
+## 1. Environment Preparation
-## 2. Installation
+### 1.1 Prerequisites
- * go mod
+- golang >= 1.13
+- make >= 3.0
+- curl >= 7.1.1
+- thrift: 0.15.0
+- Linux, MacOS, or other Unix-like systems
+- Windows + bash (Git is needed to download the IoTDB Go client; any one of
WSL, cygwin, or Git Bash is acceptable)
-```sh
-export GO111MODULE=on
-export GOPROXY=https://goproxy.io
+### 1.2 Installation Methods
-mkdir session_example && cd session_example
+- **Using go mod**
-curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
+ ```bash
+ # Switch to the HOME path of GOPATH and enable the Go Modules feature
+ export GO111MODULE=on
+
+ # Configure the GOPROXY environment variable
+ export GOPROXY=https://goproxy.io
+
+ # Create a named folder or directory and switch to it
+ mkdir session_example && cd session_example
+
+ # Save the file, which will automatically redirect to the new address
+ curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
+
+ # Initialize the go module environment
+ go mod init session_example
+
+ # Download dependency packages
+ go mod tidy
+
+ # Compile and run the program
+ go run session_example.go
+ ```
+- **Using GOPATH**
-go mod init session_example
-go run session_example.go
+ ```bash
+ # Get thrift 0.13.0
+ go get github.com/apache/[email protected]
+
+ # Recursively create the directory
+ mkdir -p $GOPATH/src/iotdb-client-go-example/session_example
+
+ # Switch to the current directory
+ cd $GOPATH/src/iotdb-client-go-example/session_example
+
+ # Save the file, which will automatically redirect to the new address
+ curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
+
+ # Initialize the go module environment
+ go mod init
+
+ # Download dependency packages
+ go mod tidy
+
+ # Compile and run the program
+ go run session_example.go
+ ```
+
+## 2. Core Steps
+
+The three core steps for using the Go native interface to operate IoTDB are as
follows:
+
+1. **Create a connection pool instance**: Initialize a `SessionPool` object,
configuring connection parameters and pool size.
+2. **Execute database operations**: `GetSession()` from the pool, perform
operations like data writing or querying, and **must** `PutBack(session)` upon
completion.
+3. **Close connection pool resources**: Call `sessionPool.Close()` at the end
of the program to release all connections.
+
+The following sections illustrate the core development workflow and do not
demonstrate all parameters and interfaces. For the complete functionality and
parameters, please refer to: **[Full Interface
Description](../API/Programming-Go-Native-API.md#_3-full-interface-list)** or
check: **[SessionPool Example Source
Code](https://github.com/apache/iotdb-client-go/blob/main/example/session_pool/session_pool_example.go)**
+
+### 2.1 Create Connection Pool Instance
+
+- **Single Instance**
+
+ ```go
+ config := &client.PoolConfig{
+ Host: host,
+ Port: port,
+ UserName: user,
+ Password: password,
+ }
+ sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+ defer sessionPool.Close()
+ ```
+- **Distributed or Active-Active**
+
+ ```go
+ config := &client.PoolConfig{
+ UserName: user,
+ Password: password,
+ NodeUrls: strings.Split("127.0.0.1:6667,127.0.0.1:6668", ","),
+ }
+ sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+ defer sessionPool.Close()
+ ```
+
+### 2.2 Database Operations
+
+#### 2.2.1 Data Insertion
+
+```go
+session, err := sessionPool.GetSession()
+defer sessionPool.PutBack(session)
+status, err := session.InsertTablet(tablet, false)
+tablet.Reset()
+checkError(status, err)
```
-* GOPATH
+#### 2.2.2 Data Query
+
+```go
+var timeout int64 = 1000
+session, err := sessionPool.GetSession()
+defer sessionPool.PutBack(session)
+if err != nil {
+ log.Print(err)
+ return
+}
+sessionDataSet, err := session.ExecuteQueryStatement(sql, &timeout)
+if err == nil {
+ defer sessionDataSet.Close()
+ printDataSet(sessionDataSet)
+} else {
+ log.Println(err)
+}
+```
+
+### 2.3 Usage Example
+
+```go
+import (
+ "flag"
+ "fmt"
+ "log"
+ "math/rand"
+ "strings"
+ "time"
+
+ "github.com/apache/iotdb-client-go/v2/client"
+ "github.com/apache/iotdb-client-go/v2/common"
+)
+
+var (
+ host string
+ port string
+ user string
+ password string
+)
+var sessionPool client.SessionPool
+
+func main() {
+ flag.StringVar(&host, "host", "127.0.0.1", "--host=192.168.1.100")
+ flag.StringVar(&port, "port", "6667", "--port=6667")
+ flag.StringVar(&user, "user", "root", "--user=root")
+ flag.StringVar(&password, "password", "root", "--password=root")
+ flag.Parse()
+
+ // 1. Create connection pool
+ config := &client.PoolConfig{
+ Host: host,
+ Port: port,
+ UserName: user,
+ Password: password,
+ }
+ sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+
+ defer sessionPool.Close()
+
+ // 2. Create storage group
+ setStorageGroup("root.sg1")
+
+ // 3. Create time series
+ createTimeseries("root.sg1.dev1.temperature")
+
+ // 4. Data insertion
+ insertTablet()
+
+ // 5. Data query
+ executeQueryStatement("select temperature from root.sg1.dev1")
+
+ // 6. Deletion
+ deleteTimeseries("root.sg1.dev1.temperature")
+ deleteStorageGroup("root.sg1")
-```sh
-# get thrift 0.15.0
-go get github.com/apache/thrift
-cd $GOPATH/src/github.com/apache/thrift
-git checkout 0.15.0
+}
-mkdir -p $GOPATH/src/iotdb-client-go-example/session_example
-cd $GOPATH/src/iotdb-client-go-example/session_example
-curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
-go run session_example.go
+// Set storage group
+func setStorageGroup(sg string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ session.SetStorageGroup(sg)
+ }
+}
+
+// Delete storage group
+func deleteStorageGroup(sg string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.DeleteStorageGroup(sg))
+ }
+}
+
+// Create time series
+func createTimeseries(path string) {
+ var (
+ dataType = client.FLOAT
+ encoding = client.PLAIN
+ compressor = client.SNAPPY
+ )
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.CreateTimeseries(path, dataType, encoding,
compressor, nil, nil))
+ }
+}
+
+// Delete time series
+func deleteTimeseries(paths ...string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.DeleteTimeseries(paths))
+ }
+}
+
+// Insert Tablet data
+func insertTablet() {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ if tablet, err := createTablet(12); err == nil {
+ status, err := session.InsertTablet(tablet, false)
+ tablet.Reset()
+ checkError(status, err)
+ } else {
+ log.Fatal(err)
+ }
+ }
+}
+
+// Create Tablet
+func createTablet(rowCount int) (*client.Tablet, error) {
+ tablet, err := client.NewTablet("root.sg1.dev1",
[]*client.MeasurementSchema{
+ {
+ Measurement: "temperature",
+ DataType: client.FLOAT,
+ },
+ }, rowCount)
+
+ if err != nil {
+ return nil, err
+ }
+ ts := time.Now().UTC().UnixNano() / 1000000
+ for row := 0; row < int(rowCount); row++ {
+ ts++
+ tablet.SetTimestamp(ts, row)
+ tablet.SetValueAt(rand.Float32(), 0, row)
+ tablet.RowSize++
+ }
+ return tablet, nil
+}
+
+// Execute query statement
+func executeQueryStatement(sql string) {
+ var timeout int64 = 1000
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err != nil {
+ log.Print(err)
+ return
+ }
+ sessionDataSet, err := session.ExecuteQueryStatement(sql, &timeout)
+ if err == nil {
+ defer sessionDataSet.Close()
+ printDataSet(sessionDataSet)
+ } else {
+ log.Println(err)
+ }
+}
+
+// Print query results
+func printDataSet(sds *client.SessionDataSet) {
+ columnNames := sds.GetColumnNames()
+ for _, value := range columnNames {
+ fmt.Printf("%s\t", value)
+ }
+ fmt.Println()
+
+ for next, err := sds.Next(); err == nil && next; next, err = sds.Next() {
+ for _, columnName := range columnNames {
+ isNull, _ := sds.IsNull(columnName)
+
+ if isNull {
+ fmt.Printf("%v\t\t", "null")
+ } else {
+ v, _ := sds.GetString(columnName)
+ fmt.Printf("%v\t\t", v)
+ }
+ }
+ fmt.Println()
+ }
+}
+
+// Check error
+func checkError(status *common.TSStatus, err error) {
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ if status != nil {
+ if err = client.VerifySuccess(status); err != nil {
+ log.Println(err)
+ }
+ }
+}
```
+## 3. Full Interface List
+
+### 3.1 SessionPool Management Interfaces
+
+| Interface Name
| Function Description
| Parameter Description
|
+|:-------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `NewSessionPool(config *PoolConfig, maxSize, connTimeoutMs, waitTimeoutMs
int, enableComp bool) SessionPool` | Creates and returns a Session connection
pool instance.
| `config`: Pool configuration<br> `maxSize`: Maximum connections (≤0 uses
CPU count * 5)<br>`connTimeoutMs`: TCP connection timeout
(ms)<br>`waitTimeoutMs`: Session acquisition wait timeout (ms)<br>`enableComp`:
Whether to enable compression |
+| `GetSession() (Session, error)`
| Gets an available Session from the pool.
Blocks if the pool is full, returns error on timeout. Must be paired with
`PutBack`. | None
|
+| `PutBack(session Session)`
| Returns a used Session back to the connection
pool.
| `session`: The instance obtained from `GetSession`
|
+| `Close()`
| Closes the connection pool, releasing all
active connections. Must be called before program exit.
| None
|
+
+### 3.2 Data Insertion Interfaces
+
+*The following interfaces are called via the obtained Session.*
+
+| Interface Name
| Function Description |
Parameter Description
|
+|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `InsertRecord(deviceId string, measurements []string, dataTypes
[]TSDataType, values []interface{}, timestamp int64) (r common.TSStatus, err
error)` | Inserts a single record.
| `deviceId`: Device ID <br>`measurements`: Measurement
list<br>`dataTypes`: Data type list<br>`values`: Value list<br>`timestamp`:
Timestamp |
+| `InsertAlignedRecord(deviceId string, measurements []string, dataTypes
[]TSDataType, values []interface{}, timestamp int64) (r common.TSStatus, err
error)` | Inserts a single aligned record.
| `deviceId`: Device ID<br>`measurements`: Measurement list<br>`dataTypes`:
Data type list<br>`values`: Value list<br>`timestamp`: Timestamp
|
+| `InsertStringRecord(deviceId string, measurements []string, values []string,
timestamp int64) (r common.TSStatus, err error)`
| Inserts a single record in string format. |
`deviceId`: Device ID<br>`measurements`: Measurement list<br>`values`:
String-type value list<br>`timestamp`: Timestamp
|
+| `InsertRecords(deviceIds []string, measurements [][]string, dataTypes
[][]TSDataType, values [][]interface{}, timestamps []int64) (r common.TSStatus,
err error)` | Inserts multiple records for multiple devices.
| `deviceIds`: Device ID list<br>`measurements`: 2D measurement
list<br>`dataTypes`: 2D data type list<br>`values`: 2D value
list<br>`timestamps`: Timestamp list |
+| `InsertAlignedRecords(deviceIds []string, measurements [][]string, dataTypes
[][]TSDataType, values [][]interface{}, timestamps []int64) (r common.TSStatus,
err error)` | Inserts multiple records for multiple aligned devices. |
`deviceIds`: Device ID list<br>`measurements`: 2D measurement
list<br>`dataTypes`: 2D data type list<br>`values`: 2D value
list<br>`timestamps`: Timestamp list |
+| `InsertTablet(tablet Tablet, sorted bool) (r common.TSStatus, err error)`
| Inserts multiple rows of data for a single device. |
`tablet`: The Tablet data to insert<br>`sorted`: Whether the data is sorted
|
+| `InsertAlignedTablet(tablet Tablet, sorted bool) (r common.TSStatus, err
error)`
| Inserts multiple rows of data for a single aligned device. |
`tablet`: The Tablet data to insert<br>`sorted`: Whether the data is sorted
|
+| `InsertTablets(tablets []Tablet, sorted bool) (r common.TSStatus, err
error)`
| Batch inserts multiple Tablet data.
| `tablets`: Multiple Tablet data to insert<br>`sorted`: Whether the data is
sorted
|
+| `InsertAlignedTablets(tablets []Tablet, sorted bool) (r common.TSStatus, err
error)`
| Batch inserts multiple aligned devices' data. |
`tablets`: Multiple Tablet data to insert<br>`sorted`: Whether the data is
sorted
|
+
+### 3.3 SQL and Query Interfaces
+
+*The following interfaces are called via the obtained Session.*
+
+| Interface Name
|
Function Description
| Parameter Description
|
+|:---------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `ExecuteStatement(sql string)(SessionDataSet, error)`
|
Executes SQL (primarily for queries), returns a SessionDataSet.
| `sql`: The SQL query statement to execute
|
+| `ExecuteQueryStatement(sql string, timeoutMs *int64) (SessionDataSet,
error)`
| Executes a query SQL with optional timeout, returns a SessionDataSet.
| `sql`: The SQL query statement to execute <br> `timeoutMs`: Query timeout
time (milliseconds)
|
+| `ExecuteNonQueryStatement(sql string) (r common.TSStatus, err error)`
|
Executes SQL that does not return a result set (e.g., INSERT, CREATE, DELETE).
| `sql`: The SQL statement to execute
|
+| `ExecuteRawDataQuery(paths []string, startTime int64, endTime int64)
(*SessionDataSet, error)`
| Queries raw data for specified time series within a time range.
| `paths`: Query path list <br>`startTime`: Start timestamp<br>`endTime`:
End timestamp
|
+| `ExecuteAggregationQuery(paths []string, aggregations
[]common.TAggregationType, startTime, endTime, interval, timeoutMs int64)
(SessionDataSet, error)` | Executes an aggregation query (COUNT, AVG, etc.).
| `paths`: Query path list<br>`aggregations`:
Aggregation type list<br>`startTime, endTime, interval`: Start time, end time,
and interval<br>`timeoutMs`: Query timeout time |
+| `ExecuteBatchStatement(sqls []string) (r common.TSStatus, err error)`
|
Executes multiple SQL statements in batch.
| `sqls`: The SQL statements to execute
|
+
+### 3.4 Metadata Operation Interfaces
+
+*The following interfaces are called via the obtained Session.*
+
+| Interface Name
| Function Description
| Parameter
Description
[...]
+|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| `SetStorageGroup(storageGroupId string) (r common.TSStatus, err error)`
| Creates a database (storage
group). | `storageGroupId`:
Database (storage group) name
[...]
+| `DeleteStorageGroup(storageGroupId string) (r common.TSStatus, err error)`
| Deletes a database (storage
group). | `storageGroupId`:
The database (storage group) name to delete
[...]
+| `DeleteStorageGroups(storageGroupIds ...string) (r common.TSStatus, err
error)`
| Deletes multiple
databases (storage groups). |
`storageGroupIds`: The list of database (storage group) names to delete
[...]
+| `CreateTimeseries(path string, dataType TSDataType, encoding TSEncoding,
compressor TSCompressionType, attributes map[string]string, tags
map[string]string) (r common.TSStatus, err error)` | Creates
a non-aligned time series. |
`path`: Time series path<br>`dataType`: Data type<br>`encoding`: Encoding
method<br>`compressor`: Compression algorithm<br>`attributes`: (Optional)
Series attributes<br>`tags`: (Optional) Series [...]
+| `CreateAlignedTimeseries(prefixPath string, measurements []string, dataTypes
[]TSDataType, encodings []TSEncoding, compressors []TSCompressionType,
measurementAlias []string) (r common.TSStatus, err error)` | Creates a group of
aligned time series. |
`prefixPath`: Time series path prefix <br>`measurements`: Measurement name
list<br>`dataTypes, encodings, compressors`: Data type, encoding, and
compressor list for each measurement<br>`measurem [...]
+| `DeleteTimeseries(paths []string) (r common.TSStatus, err error)`
| Deletes multiple time
series (including their data). | `paths`: The
list of time series paths to delete
[...]
+| `DeleteData(paths []string, startTime int64, endTime int64) (r
common.TSStatus, err error)`
| Deletes data
within a time period for specified time series (metadata is preserved). |
`paths`: The list of time series paths<br>`startTime`: Start
timestamp<br>`endTime`: End timestamp
[...]
+| `SetTimeZone(timeZone string) (r common.TSStatus, err error)`
| Sets the time zone for the
current session. | `timeZone`: Time
zone string, e.g., "UTC", "Asia/Shanghai", "GMT+8"
[...]
+| `GetTimeZone() (string, error)`
| Gets the time zone of the
current session. | None
[...]
+
+### 3.5 Key Configuration Structure (PoolConfig)
+
+| Field | Type | Required | Description
|
+|:------------|:-----------|:------------------------------|:-------------------------------------------------------------------------|
+| `Host` | `string` | Choose one with `NodeUrls` | Single-node host
address. |
+| `Port` | `string` | Choose one with `NodeUrls` | Single-node port.
|
+| `NodeUrls` | `[]string` | Choose one with `Host`/`Port` | Cluster node
address list, format: `"host:port"`. |
+| `UserName` | `string` | Yes | Username.
|
+| `Password` | `string` | Yes | Password.
|
+| `FetchSize` | `int32` | No | Query result set
fetch size, default 1024. |
+| `TimeZone` | `string` | No | Session time
zone, e.g., "Asia/Shanghai". Default uses server time zone. |
+| `Database` | `string` | No | For table model;
used to set the session's default database. |
diff --git a/src/UserGuide/latest/API/Programming-Go-Native-API.md
b/src/UserGuide/latest/API/Programming-Go-Native-API.md
index baad278b..a4afa6c4 100644
--- a/src/UserGuide/latest/API/Programming-Go-Native-API.md
+++ b/src/UserGuide/latest/API/Programming-Go-Native-API.md
@@ -21,44 +21,396 @@
# Go Native API
-The Git repository for the Go Native API client is located
[here](https://github.com/apache/iotdb-client-go/)
+The Go Native API supports interaction with the database through both
`Session` and `SessionPool` methods. Since `Session` is not thread-safe, using
`SessionPool` is strongly recommended for programming. In multi-threaded
concurrent scenarios, `SessionPool` can reasonably manage and allocate
connection resources to enhance system performance and resource utilization
efficiency.
-## 1. Dependencies
+This article focuses on the usage of `SessionPool`, covering the complete
process from environment preparation and core operation steps to the full set
of interfaces.
- * golang >= 1.13
- * make >= 3.0
- * curl >= 7.1.1
- * thrift 0.15.0
- * Linux、Macos or other unix-like systems
- * Windows+bash (WSL、cygwin、Git Bash)
+## 1. Environment Preparation
-## 2. Installation
+### 1.1 Prerequisites
- * go mod
+- golang >= 1.13
+- make >= 3.0
+- curl >= 7.1.1
+- thrift: 0.15.0
+- Linux, MacOS, or other Unix-like systems
+- Windows + bash (Git is needed to download the IoTDB Go client; any one of
WSL, cygwin, or Git Bash is acceptable)
-```sh
-export GO111MODULE=on
-export GOPROXY=https://goproxy.io
+### 1.2 Installation Methods
-mkdir session_example && cd session_example
+- **Using go mod**
-curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
+ ```bash
+ # Switch to the HOME path of GOPATH and enable the Go Modules feature
+ export GO111MODULE=on
+
+ # Configure the GOPROXY environment variable
+ export GOPROXY=https://goproxy.io
+
+ # Create a named folder or directory and switch to it
+ mkdir session_example && cd session_example
+
+ # Save the file, which will automatically redirect to the new address
+ curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
+
+ # Initialize the go module environment
+ go mod init session_example
+
+ # Download dependency packages
+ go mod tidy
+
+ # Compile and run the program
+ go run session_example.go
+ ```
+- **Using GOPATH**
-go mod init session_example
-go run session_example.go
+ ```bash
+ # Get thrift 0.13.0
+ go get github.com/apache/[email protected]
+
+ # Recursively create the directory
+ mkdir -p $GOPATH/src/iotdb-client-go-example/session_example
+
+ # Switch to the current directory
+ cd $GOPATH/src/iotdb-client-go-example/session_example
+
+ # Save the file, which will automatically redirect to the new address
+ curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
+
+ # Initialize the go module environment
+ go mod init
+
+ # Download dependency packages
+ go mod tidy
+
+ # Compile and run the program
+ go run session_example.go
+ ```
+
+## 2. Core Steps
+
+The three core steps for using the Go native interface to operate IoTDB are as
follows:
+
+1. **Create a connection pool instance**: Initialize a `SessionPool` object,
configuring connection parameters and pool size.
+2. **Execute database operations**: `GetSession()` from the pool, perform
operations like data writing or querying, and **must** `PutBack(session)` upon
completion.
+3. **Close connection pool resources**: Call `sessionPool.Close()` at the end
of the program to release all connections.
+
+The following sections illustrate the core development workflow and do not
demonstrate all parameters and interfaces. For the complete functionality and
parameters, please refer to: **[Full Interface
Description](../API/Programming-Go-Native-API.md#_3-full-interface-list)** or
check: **[SessionPool Example Source
Code](https://github.com/apache/iotdb-client-go/blob/main/example/session_pool/session_pool_example.go)**
+
+### 2.1 Create Connection Pool Instance
+
+- **Single Instance**
+
+ ```go
+ config := &client.PoolConfig{
+ Host: host,
+ Port: port,
+ UserName: user,
+ Password: password,
+ }
+ sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+ defer sessionPool.Close()
+ ```
+- **Distributed or Active-Active**
+
+ ```go
+ config := &client.PoolConfig{
+ UserName: user,
+ Password: password,
+ NodeUrls: strings.Split("127.0.0.1:6667,127.0.0.1:6668", ","),
+ }
+ sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+ defer sessionPool.Close()
+ ```
+
+### 2.2 Database Operations
+
+#### 2.2.1 Data Insertion
+
+```go
+session, err := sessionPool.GetSession()
+defer sessionPool.PutBack(session)
+status, err := session.InsertTablet(tablet, false)
+tablet.Reset()
+checkError(status, err)
```
-* GOPATH
+#### 2.2.2 Data Query
+
+```go
+var timeout int64 = 1000
+session, err := sessionPool.GetSession()
+defer sessionPool.PutBack(session)
+if err != nil {
+ log.Print(err)
+ return
+}
+sessionDataSet, err := session.ExecuteQueryStatement(sql, &timeout)
+if err == nil {
+ defer sessionDataSet.Close()
+ printDataSet(sessionDataSet)
+} else {
+ log.Println(err)
+}
+```
+
+### 2.3 Usage Example
+
+```go
+import (
+ "flag"
+ "fmt"
+ "log"
+ "math/rand"
+ "strings"
+ "time"
+
+ "github.com/apache/iotdb-client-go/v2/client"
+ "github.com/apache/iotdb-client-go/v2/common"
+)
+
+var (
+ host string
+ port string
+ user string
+ password string
+)
+var sessionPool client.SessionPool
+
+func main() {
+ flag.StringVar(&host, "host", "127.0.0.1", "--host=192.168.1.100")
+ flag.StringVar(&port, "port", "6667", "--port=6667")
+ flag.StringVar(&user, "user", "root", "--user=root")
+ flag.StringVar(&password, "password", "root", "--password=root")
+ flag.Parse()
+
+ // 1. Create connection pool
+ config := &client.PoolConfig{
+ Host: host,
+ Port: port,
+ UserName: user,
+ Password: password,
+ }
+ sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+
+ defer sessionPool.Close()
+
+ // 2. Create storage group
+ setStorageGroup("root.sg1")
+
+ // 3. Create time series
+ createTimeseries("root.sg1.dev1.temperature")
+
+ // 4. Data insertion
+ insertTablet()
+
+ // 5. Data query
+ executeQueryStatement("select temperature from root.sg1.dev1")
+
+ // 6. Deletion
+ deleteTimeseries("root.sg1.dev1.temperature")
+ deleteStorageGroup("root.sg1")
-```sh
-# get thrift 0.15.0
-go get github.com/apache/thrift
-cd $GOPATH/src/github.com/apache/thrift
-git checkout 0.15.0
+}
-mkdir -p $GOPATH/src/iotdb-client-go-example/session_example
-cd $GOPATH/src/iotdb-client-go-example/session_example
-curl -o session_example.go -L
https://github.com/apache/iotdb-client-go/raw/main/example/session_example.go
-go run session_example.go
+// Set storage group
+func setStorageGroup(sg string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ session.SetStorageGroup(sg)
+ }
+}
+
+// Delete storage group
+func deleteStorageGroup(sg string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.DeleteStorageGroup(sg))
+ }
+}
+
+// Create time series
+func createTimeseries(path string) {
+ var (
+ dataType = client.FLOAT
+ encoding = client.PLAIN
+ compressor = client.SNAPPY
+ )
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.CreateTimeseries(path, dataType, encoding,
compressor, nil, nil))
+ }
+}
+
+// Delete time series
+func deleteTimeseries(paths ...string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.DeleteTimeseries(paths))
+ }
+}
+
+// Insert Tablet data
+func insertTablet() {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ if tablet, err := createTablet(12); err == nil {
+ status, err := session.InsertTablet(tablet, false)
+ tablet.Reset()
+ checkError(status, err)
+ } else {
+ log.Fatal(err)
+ }
+ }
+}
+
+// Create Tablet
+func createTablet(rowCount int) (*client.Tablet, error) {
+ tablet, err := client.NewTablet("root.sg1.dev1",
[]*client.MeasurementSchema{
+ {
+ Measurement: "temperature",
+ DataType: client.FLOAT,
+ },
+ }, rowCount)
+
+ if err != nil {
+ return nil, err
+ }
+ ts := time.Now().UTC().UnixNano() / 1000000
+ for row := 0; row < int(rowCount); row++ {
+ ts++
+ tablet.SetTimestamp(ts, row)
+ tablet.SetValueAt(rand.Float32(), 0, row)
+ tablet.RowSize++
+ }
+ return tablet, nil
+}
+
+// Execute query statement
+func executeQueryStatement(sql string) {
+ var timeout int64 = 1000
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err != nil {
+ log.Print(err)
+ return
+ }
+ sessionDataSet, err := session.ExecuteQueryStatement(sql, &timeout)
+ if err == nil {
+ defer sessionDataSet.Close()
+ printDataSet(sessionDataSet)
+ } else {
+ log.Println(err)
+ }
+}
+
+// Print query results
+func printDataSet(sds *client.SessionDataSet) {
+ columnNames := sds.GetColumnNames()
+ for _, value := range columnNames {
+ fmt.Printf("%s\t", value)
+ }
+ fmt.Println()
+
+ for next, err := sds.Next(); err == nil && next; next, err = sds.Next() {
+ for _, columnName := range columnNames {
+ isNull, _ := sds.IsNull(columnName)
+
+ if isNull {
+ fmt.Printf("%v\t\t", "null")
+ } else {
+ v, _ := sds.GetString(columnName)
+ fmt.Printf("%v\t\t", v)
+ }
+ }
+ fmt.Println()
+ }
+}
+
+// Check error
+func checkError(status *common.TSStatus, err error) {
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ if status != nil {
+ if err = client.VerifySuccess(status); err != nil {
+ log.Println(err)
+ }
+ }
+}
```
+## 3. Full Interface List
+
+### 3.1 SessionPool Management Interfaces
+
+| Interface Name
| Function Description
| Parameter Description
|
+|:-------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `NewSessionPool(config *PoolConfig, maxSize, connTimeoutMs, waitTimeoutMs
int, enableComp bool) SessionPool` | Creates and returns a Session connection
pool instance.
| `config`: Pool configuration<br> `maxSize`: Maximum connections (≤0 uses
CPU count * 5)<br>`connTimeoutMs`: TCP connection timeout
(ms)<br>`waitTimeoutMs`: Session acquisition wait timeout (ms)<br>`enableComp`:
Whether to enable compression |
+| `GetSession() (Session, error)`
| Gets an available Session from the pool.
Blocks if the pool is full, returns error on timeout. Must be paired with
`PutBack`. | None
|
+| `PutBack(session Session)`
| Returns a used Session back to the connection
pool.
| `session`: The instance obtained from `GetSession`
|
+| `Close()`
| Closes the connection pool, releasing all
active connections. Must be called before program exit.
| None
|
+
+### 3.2 Data Insertion Interfaces
+
+*The following interfaces are called via the obtained Session.*
+
+| Interface Name
| Function Description |
Parameter Description
|
+|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `InsertRecord(deviceId string, measurements []string, dataTypes
[]TSDataType, values []interface{}, timestamp int64) (r common.TSStatus, err
error)` | Inserts a single record.
| `deviceId`: Device ID <br>`measurements`: Measurement
list<br>`dataTypes`: Data type list<br>`values`: Value list<br>`timestamp`:
Timestamp |
+| `InsertAlignedRecord(deviceId string, measurements []string, dataTypes
[]TSDataType, values []interface{}, timestamp int64) (r common.TSStatus, err
error)` | Inserts a single aligned record.
| `deviceId`: Device ID<br>`measurements`: Measurement list<br>`dataTypes`:
Data type list<br>`values`: Value list<br>`timestamp`: Timestamp
|
+| `InsertStringRecord(deviceId string, measurements []string, values []string,
timestamp int64) (r common.TSStatus, err error)`
| Inserts a single record in string format. |
`deviceId`: Device ID<br>`measurements`: Measurement list<br>`values`:
String-type value list<br>`timestamp`: Timestamp
|
+| `InsertRecords(deviceIds []string, measurements [][]string, dataTypes
[][]TSDataType, values [][]interface{}, timestamps []int64) (r common.TSStatus,
err error)` | Inserts multiple records for multiple devices.
| `deviceIds`: Device ID list<br>`measurements`: 2D measurement
list<br>`dataTypes`: 2D data type list<br>`values`: 2D value
list<br>`timestamps`: Timestamp list |
+| `InsertAlignedRecords(deviceIds []string, measurements [][]string, dataTypes
[][]TSDataType, values [][]interface{}, timestamps []int64) (r common.TSStatus,
err error)` | Inserts multiple records for multiple aligned devices. |
`deviceIds`: Device ID list<br>`measurements`: 2D measurement
list<br>`dataTypes`: 2D data type list<br>`values`: 2D value
list<br>`timestamps`: Timestamp list |
+| `InsertTablet(tablet Tablet, sorted bool) (r common.TSStatus, err error)`
| Inserts multiple rows of data for a single device. |
`tablet`: The Tablet data to insert<br>`sorted`: Whether the data is sorted
|
+| `InsertAlignedTablet(tablet Tablet, sorted bool) (r common.TSStatus, err
error)`
| Inserts multiple rows of data for a single aligned device. |
`tablet`: The Tablet data to insert<br>`sorted`: Whether the data is sorted
|
+| `InsertTablets(tablets []Tablet, sorted bool) (r common.TSStatus, err
error)`
| Batch inserts multiple Tablet data.
| `tablets`: Multiple Tablet data to insert<br>`sorted`: Whether the data is
sorted
|
+| `InsertAlignedTablets(tablets []Tablet, sorted bool) (r common.TSStatus, err
error)`
| Batch inserts multiple aligned devices' data. |
`tablets`: Multiple Tablet data to insert<br>`sorted`: Whether the data is
sorted
|
+
+### 3.3 SQL and Query Interfaces
+
+*The following interfaces are called via the obtained Session.*
+
+| Interface Name
|
Function Description
| Parameter Description
|
+|:---------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `ExecuteStatement(sql string)(SessionDataSet, error)`
|
Executes SQL (primarily for queries), returns a SessionDataSet.
| `sql`: The SQL query statement to execute
|
+| `ExecuteQueryStatement(sql string, timeoutMs *int64) (SessionDataSet,
error)`
| Executes a query SQL with optional timeout, returns a SessionDataSet.
| `sql`: The SQL query statement to execute <br> `timeoutMs`: Query timeout
time (milliseconds)
|
+| `ExecuteNonQueryStatement(sql string) (r common.TSStatus, err error)`
|
Executes SQL that does not return a result set (e.g., INSERT, CREATE, DELETE).
| `sql`: The SQL statement to execute
|
+| `ExecuteRawDataQuery(paths []string, startTime int64, endTime int64)
(*SessionDataSet, error)`
| Queries raw data for specified time series within a time range.
| `paths`: Query path list <br>`startTime`: Start timestamp<br>`endTime`:
End timestamp
|
+| `ExecuteAggregationQuery(paths []string, aggregations
[]common.TAggregationType, startTime, endTime, interval, timeoutMs int64)
(SessionDataSet, error)` | Executes an aggregation query (COUNT, AVG, etc.).
| `paths`: Query path list<br>`aggregations`:
Aggregation type list<br>`startTime, endTime, interval`: Start time, end time,
and interval<br>`timeoutMs`: Query timeout time |
+| `ExecuteBatchStatement(sqls []string) (r common.TSStatus, err error)`
|
Executes multiple SQL statements in batch.
| `sqls`: The SQL statements to execute
|
+
+### 3.4 Metadata Operation Interfaces
+
+*The following interfaces are called via the obtained Session.*
+
+| Interface Name
| Function Description
| Parameter
Description
[...]
+|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| `SetStorageGroup(storageGroupId string) (r common.TSStatus, err error)`
| Creates a database (storage
group). | `storageGroupId`:
Database (storage group) name
[...]
+| `DeleteStorageGroup(storageGroupId string) (r common.TSStatus, err error)`
| Deletes a database (storage
group). | `storageGroupId`:
The database (storage group) name to delete
[...]
+| `DeleteStorageGroups(storageGroupIds ...string) (r common.TSStatus, err
error)`
| Deletes multiple
databases (storage groups). |
`storageGroupIds`: The list of database (storage group) names to delete
[...]
+| `CreateTimeseries(path string, dataType TSDataType, encoding TSEncoding,
compressor TSCompressionType, attributes map[string]string, tags
map[string]string) (r common.TSStatus, err error)` | Creates
a non-aligned time series. |
`path`: Time series path<br>`dataType`: Data type<br>`encoding`: Encoding
method<br>`compressor`: Compression algorithm<br>`attributes`: (Optional)
Series attributes<br>`tags`: (Optional) Series [...]
+| `CreateAlignedTimeseries(prefixPath string, measurements []string, dataTypes
[]TSDataType, encodings []TSEncoding, compressors []TSCompressionType,
measurementAlias []string) (r common.TSStatus, err error)` | Creates a group of
aligned time series. |
`prefixPath`: Time series path prefix <br>`measurements`: Measurement name
list<br>`dataTypes, encodings, compressors`: Data type, encoding, and
compressor list for each measurement<br>`measurem [...]
+| `DeleteTimeseries(paths []string) (r common.TSStatus, err error)`
| Deletes multiple time
series (including their data). | `paths`: The
list of time series paths to delete
[...]
+| `DeleteData(paths []string, startTime int64, endTime int64) (r
common.TSStatus, err error)`
| Deletes data
within a time period for specified time series (metadata is preserved). |
`paths`: The list of time series paths<br>`startTime`: Start
timestamp<br>`endTime`: End timestamp
[...]
+| `SetTimeZone(timeZone string) (r common.TSStatus, err error)`
| Sets the time zone for the
current session. | `timeZone`: Time
zone string, e.g., "UTC", "Asia/Shanghai", "GMT+8"
[...]
+| `GetTimeZone() (string, error)`
| Gets the time zone of the
current session. | None
[...]
+
+### 3.5 Key Configuration Structure (PoolConfig)
+
+| Field | Type | Required | Description
|
+|:------------|:-----------|:------------------------------|:-------------------------------------------------------------------------|
+| `Host` | `string` | Choose one with `NodeUrls` | Single-node host
address. |
+| `Port` | `string` | Choose one with `NodeUrls` | Single-node port.
|
+| `NodeUrls` | `[]string` | Choose one with `Host`/`Port` | Cluster node
address list, format: `"host:port"`. |
+| `UserName` | `string` | Yes | Username.
|
+| `Password` | `string` | Yes | Password.
|
+| `FetchSize` | `int32` | No | Query result set
fetch size, default 1024. |
+| `TimeZone` | `string` | No | Session time
zone, e.g., "Asia/Shanghai". Default uses server time zone. |
+| `Database` | `string` | No | For table model;
used to set the session's default database. |
diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-Go-Native-API.md
b/src/zh/UserGuide/Master/Tree/API/Programming-Go-Native-API.md
index 99f8d748..fe9e49b9 100644
--- a/src/zh/UserGuide/Master/Tree/API/Programming-Go-Native-API.md
+++ b/src/zh/UserGuide/Master/Tree/API/Programming-Go-Native-API.md
@@ -21,20 +21,25 @@
# Go 原生接口
-## 1. 依赖
+Go 原生 API 支持通过 `Session `和 `SessionPool `两种方式与数据库进行交互。由于 `Session
`非线程安全，因此强烈推荐使用 `SessionPool `编程。在多线程并发的情形下，`SessionPool
`能够合理地管理和分配连接资源，以提升系统性能与资源利用效率。
- * golang >= 1.13
- * make >= 3.0
- * curl >= 7.1.1
- * thrift 0.15.0
- * Linux、Macos 或其他类 unix 系统
- * Windows+bash (下载 IoTDB Go client 需要 git ，通过 WSL、cygwin、Git Bash 任意一种方式均可)
+本文将围绕 `SessionPool` 的使用进行说明，涵盖从环境准备、核心操作步骤到全量接口的完整内容。
-## 2. 安装方法
+## 1. 环境准备
+### 1.1 前置依赖
- * 通过 go mod
+* golang >= 1.13
+* make >= 3.0
+* curl >= 7.1.1
+* thrift: 0.15.0
+* Linux、Macos 或其他类 unix 系统
+* Windows+bash (下载 IoTDB Go client 需要 git ，通过 WSL、cygwin、Git Bash 任意一种方式均可)
-```sh
+### 1.2 安装方法
+
+* 使用 go mod
+
+```Bash
# 切换到 GOPATH 的 HOME 路径，启用 Go Modules 功能
export GO111MODULE=on
@@ -57,9 +62,9 @@ go mod tidy
go run session_example.go
```
-* 通过 GOPATH
+* 使用 GOPATH
-```sh
+```Bash
# get thrift 0.13.0
go get github.com/apache/[email protected]
@@ -81,4 +86,330 @@ go mod tidy
# 编译并运行程序
go run session_example.go
```
-**注意：GO原生客户端Session不是线程安全的，强烈不建议在多线程场景下应用。如有多线程应用场景，请使用Session Pool.**
+
+## 2. 核心步骤
+
+使用 Go 原生接口操作 IoTDB 的三个核心步骤如下：
+
+1. 创建连接池实例：初始化一个`SessionPool`对象，配置连接参数和池大小。
+2. 执行数据库操作：从连接池中`GetSession()`，执行数据写入或查询等操作，完成后必须`PutBack(session)`。
+3. 关闭连接池资源：程序结束时调用`sessionPool.Close()`，释放所有连接。
+
+下面的章节用于说明开发的核心流程，并未演示所有的参数和接口，如需了解全部功能及参数请参见:
[全量接口说明](../API/Programming-Go-Native-API.md#_3-全量接口) 或 查阅: [SessionPool
示例源码](https://github.com/apache/iotdb-client-go/blob/main/example/session_pool/session_pool_example.go)
+
+### 2.1 创建连接池实例
+
+* 单实例
+
+```Go
+config := &client.PoolConfig{
+ Host: host,
+ Port: port,
+ UserName: user,
+ Password: password,
+}
+sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+defer sessionPool.Close()
+```
+
+* 分布式或双活
+
+```Go
+config := &client.PoolConfig{
+ UserName: user,
+ Password: password,
+ NodeUrls: strings.Split("127.0.0.1:6667,127.0.0.1:6668", ","),
+ }
+sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+defer sessionPool.Close()
+```
+
+### 2.2 数据库操作
+#### 2.2.1 数据写入
+
+```Go
+session, err := sessionPool.GetSession()
+defer sessionPool.PutBack(session)
+status, err := session.InsertTablet(tablet, false)
+tablet.Reset()
+checkError(status, err)
+```
+
+#### 2.2.2 数据查询
+
+```Go
+var timeout int64 = 1000
+session, err := sessionPool.GetSession()
+defer sessionPool.PutBack(session)
+if err != nil {
+ log.Print(err)
+ return
+}
+sessionDataSet, err := session.ExecuteQueryStatement(sql, &timeout)
+if err == nil {
+ defer sessionDataSet.Close()
+ printDataSet(sessionDataSet)
+} else {
+ log.Println(err)
+}
+```
+
+### 2.3 使用示例
+
+```Go
+import (
+ "flag"
+ "fmt"
+ "log"
+ "math/rand"
+ "strings"
+ "time"
+
+ "github.com/apache/iotdb-client-go/v2/client"
+ "github.com/apache/iotdb-client-go/v2/common"
+)
+
+var (
+ host string
+ port string
+ user string
+ password string
+)
+var sessionPool client.SessionPool
+
+func main() {
+ flag.StringVar(&host, "host", "127.0.0.1", "--host=192.168.1.100")
+ flag.StringVar(&port, "port", "6667", "--port=6667")
+ flag.StringVar(&user, "user", "root", "--user=root")
+ flag.StringVar(&password, "password", "root", "--password=root")
+ flag.Parse()
+
+ //1.创建连接池
+ config := &client.PoolConfig{
+ Host: host,
+ Port: port,
+ UserName: user,
+ Password: password,
+ }
+ sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+
+ defer sessionPool.Close()
+
+ //2.创建存储组
+ setStorageGroup("root.sg1")
+
+ //3. 创建时间序列
+ createTimeseries("root.sg1.dev1.temperature")
+
+ //4.数据写入
+ insertTablet()
+
+ //5. 数据查询
+ executeQueryStatement("select temperature from root.sg1.dev1")
+
+ //6. 删除
+ deleteTimeseries("root.sg1.dev1.temperature")
+ deleteStorageGroup("root.sg1")
+
+}
+
+// 设置存储组
+func setStorageGroup(sg string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ session.SetStorageGroup(sg)
+ }
+}
+
+// 删除存储组
+func deleteStorageGroup(sg string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.DeleteStorageGroup(sg))
+ }
+}
+
+// 创建时间序列
+func createTimeseries(path string) {
+ var (
+ dataType = client.FLOAT
+ encoding = client.PLAIN
+ compressor = client.SNAPPY
+ )
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.CreateTimeseries(path, dataType, encoding,
compressor, nil, nil))
+ }
+}
+
+// 删除时间序列
+func deleteTimeseries(paths ...string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.DeleteTimeseries(paths))
+ }
+}
+
+// 插入Tablet数据
+func insertTablet() {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ if tablet, err := createTablet(12); err == nil {
+ status, err := session.InsertTablet(tablet, false)
+ tablet.Reset()
+ checkError(status, err)
+ } else {
+ log.Fatal(err)
+ }
+ }
+}
+
+//创建Tablet
+func createTablet(rowCount int) (*client.Tablet, error) {
+ tablet, err := client.NewTablet("root.sg1.dev1",
[]*client.MeasurementSchema{
+ {
+ Measurement: "temperature",
+ DataType: client.FLOAT,
+ },
+ }, rowCount)
+
+ if err != nil {
+ return nil, err
+ }
+ ts := time.Now().UTC().UnixNano() / 1000000
+ for row := 0; row < int(rowCount); row++ {
+ ts++
+ tablet.SetTimestamp(ts, row)
+ tablet.SetValueAt(rand.Float32(), 0, row)
+ tablet.RowSize++
+ }
+ return tablet, nil
+}
+
+// 执行查询语句
+func executeQueryStatement(sql string) {
+ var timeout int64 = 1000
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err != nil {
+ log.Print(err)
+ return
+ }
+ sessionDataSet, err := session.ExecuteQueryStatement(sql, &timeout)
+ if err == nil {
+ defer sessionDataSet.Close()
+ printDataSet(sessionDataSet)
+ } else {
+ log.Println(err)
+ }
+}
+
+// 打印查询结果
+func printDataSet(sds *client.SessionDataSet) {
+ columnNames := sds.GetColumnNames()
+ for _, value := range columnNames {
+ fmt.Printf("%s\t", value)
+ }
+ fmt.Println()
+
+ for next, err := sds.Next(); err == nil && next; next, err = sds.Next() {
+ for _, columnName := range columnNames {
+ isNull, _ := sds.IsNull(columnName)
+
+ if isNull {
+ fmt.Printf("%v\t\t", "null")
+ } else {
+ v, _ := sds.GetString(columnName)
+ fmt.Printf("%v\t\t", v)
+ }
+ }
+ fmt.Println()
+ }
+}
+
+// 检查错误
+func checkError(status *common.TSStatus, err error) {
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ if status != nil {
+ if err = client.VerifySuccess(status); err != nil {
+ log.Println(err)
+ }
+ }
+}
+```
+
+## 3. 全量接口
+### 3.1 SessionPool 管理接口
+
+| 接口名称
| 功能描述
| 参数说明
|
+|--------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
+| `NewSessionPool(config *PoolConfig, maxSize, connTimeoutMs, waitTimeoutMs
int, enableComp bool) SessionPool` | 创建并返回一个Session连接池实例。
| `config`: 连接池配置 <br>`maxSize`: 最大连接数(≤0时取CPU数\*5)
<br>`connTimeoutMs`: TCP连接超时(ms) <br>`waitTimeoutMs`: 获取Session等待超时(ms)
<br>`enableComp`: 是否启用压缩 |
+| `GetSession() (Session, error)`
|
从池中获取一个可用Session。若池满则阻塞等待，超时返回错误。**必须与PutBack配对使用**。 | 无
|
+| `PutBack(session Session)`
| 将使用完毕的Session归还到连接池中。
| `session`: 从GetSession获取的实例
|
+| `Close()`
| 关闭连接池，释放所有活跃连接。程序退出前必须调用。
| 无
|
+
+### 3.2 数据写入接口
+
+以下接口需通过获取的 Session 进行调用
+
+| 接口名称
| 功能描述 | 参数说明
|
+|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
------------------------------ |
----------------------------------------------------------------------------------------------------------------------------------------------------------------
|
+| `InsertRecord(deviceId string, measurements []string, dataTypes
[]TSDataType, values []interface{}, timestamp int64) (r common.TSStatus, err
error)` | 插入单条记录。| `deviceId`: 设备ID <br>`measurements`:
测点列表 <br>`dataTypes`: 数据类型列表<br>`values`: 值列表<br>`timestamp`: 时间戳 |
+| `InsertAlignedRecord(deviceId string, measurements []string, dataTypes
[]TSDataType, values []interface{}, timestamp int64) (r common.TSStatus, err
error)` | 插入单条对齐记录。 | `deviceId`:
设备ID<br>`measurements`: 测点列表<br>`dataTypes`: 数据类型列表<br>`values`:
值列表<br>`timestamp`: 时间戳 |
+| `InsertStringRecord(deviceId string, measurements []string, values []string,
timestamp int64) (r common.TSStatus, err error)`
| 插入字符串格式的单条记录。 | `deviceId`: 设备ID<br>`measurements`:
测点列表<br>`values`: 字符串类型的值列表<br>`timestamp`: 时间戳 |
+| `InsertRecords(deviceIds []string, measurements [][]string, dataTypes
[][]TSDataType, values [][]interface{}, timestamps []int64) (r common.TSStatus,
err error)` | 插入多条记录。| `deviceIds`:
设备ID列表<br>`measurements`:二维测点列表<br>`dataTypes`: 二维数据类型列表<br>`values`:
二维值列表<br>`timestamps`: 时间戳列表 |
+| `InsertAlignedRecords(deviceIds []string, measurements [][]string, dataTypes
[][]TSDataType, values [][]interface{}, timestamps []int64) (r common.TSStatus,
err error)` | 插入多个对齐设备的多条记录。 | `deviceIds`:
设备ID列表<br>`measurements`:二维测点列表<br>`dataTypes`: 二维数据类型列表<br>`values`:
二维值列表<br>`timestamps`: 时间戳列表 |
+| `InsertTablet(tablet Tablet, sorted bool) (r common.TSStatus, err error)`
| 插入单个设备的多条数据。 | `tablet`: 要插入的`Tablet`数据<br>`sorted`: 数据是否已排序
|
+| `InsertAlignedTablet(tablet Tablet, sorted bool) (r common.TSStatus, err
error)`
| 插入单个对齐设备的多条数据。 | `tablet`: 要插入的`Tablet`数据<br>`sorted`:
数据是否已排序
|
+| `InsertTablets``(tablets []Tablet, sorted bool) (r common.TSStatus, err
error)`
| 批量插入多个 Tablet 数据。 | `tablets`: 要插入的多个`Tablet
`数据<br>`sorted`: 数据是否已排序
|
+| `InsertAlignedTablets(tablets []Tablet, sorted bool) (r common.TSStatus, err
error)`
| 批量插入多个对齐设备的数据。 | `tablets`: 要插入的多个`Tablet `数据<br>`sorted`:
数据是否已排序
|
+
+### 3.3 SQL与查询接口
+
+以下接口需通过获取的 Session 进行调用
+
+| 接口名称
|
功能描述 | 参数说明
|
+|----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|----------------------------------------------------------------------------------------------------------------------|
+| `ExecuteStatement(sql string)`*`(`*`SessionDataSet, error)`
|
执行SQL（主要查询），返回`SessionDataSet`。 | `sql`：要执行的SQL查询语句
|
+| `ExecuteQueryStatement(sql string, timeoutMs int64) (SessionDataSet, error)`
|
执行查询SQL，可指定超时，返回`SessionDataSet`。 | `sql`：要执行的SQL查询语句<br>`timeoutMs`:
查询超时时间（毫秒）
|
+| `ExecuteNonQueryStatementExecuteNonQueryStatement(sql string) (r
common.TSStatus, err error)`
| 执行不返回结果集的SQL（如INSERT, CREATE, DELETE）。 | `sql`：要执行的SQL语句
|
+| `ExecuteRawDataQuery(paths []string, startTime int64, endTime int64)
(*SessionDataSet, error)`
| 查询指定时间序列在时间范围内的原始数据。 | `paths`: 查询路径列表<br>`startTime`:
起始时间戳<br>`endTime`: 结束时间戳
|
+| `ExecuteAggregationQuery(paths []string, aggregations
[]common.TAggregationType, startTime, endTime, interval, timeoutMs int64)
(SessionDataSet, error)` | 执行聚合查询（COUNT, AVG等）。 | `paths`:
查询路径列表<br>`aggregations`: 聚合类型列表<br>`startTime, endTime, interval`:
起始时间、结束时间和间隔时间<br>`timeoutMs`: 查询超时时间 |
+| `ExecuteBatchStatement(sqls []string) (r common.TSStatus, err error)`
|
批量执行多条SQL语句。 | `sqls`：要执行的SQL语句
|
+
+### 3.4 元数据操作接口
+
+以下接口需通过获取的 Session 进行调用
+
+| 接口名称
| 功能描述 |
参数说明
|
+|
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
+| `SetStorageGroup(storageGroupId string) (r common.TSStatus, err error)`
| 创建数据库（存储组）。 |
`storageGroupId`：数据库（存储组）名称
|
+| `DeleteStorageGroup(storageGroupId string) (r common.TSStatus, err error)`
| 删除一个数据库（存储组）。 |
`storageGroupId`：要删除的数据库（存储组）名称
|
+| `DeleteStorageGroups(storageGroupIds ...string) (r common.TSStatus, err
error)`
| 删除多个数据库（存储组）。
| `storageGroupIds`：要删除的数据库（存储组）名称列表
|
+| `CreateTimeseries(path string, dataType TSDataType, encoding TSEncoding,
compressor TSCompressionType, attributes map[string]string, tags
map[string]string) (r common.TSStatus, err error)` |
创建非对齐时间序列。 | `path`: 时间序列路径<br>`dataType`: 数据类型<br>`encoding`:
编码方式<br>`compressor`: 压缩算法<br>`attributes`: （可选）序列属性<br>`tags`: （可选）序列标签
|
+| `CreateAlignedTimeseries(prefixPath string, measurements []string, dataTypes
[]TSDataType, encodings []TSEncoding, compressors []TSCompressionType,
measurementAlias []string) (r common.TSStatus, err error)` | 创建一组对齐时间序列。
| `prefixPath`: 时间序列路径前缀<br>`measurements`: 测点名称列表<br>`dataTypes,
encodings, compressors`: 每个测点对应的数据类型、编码和压缩算法列表<br>`measurementAlias`:
（可选）每个测点的别名列表 |
+| `DeleteTimeseries(paths []string) (r common.TSStatus, err error)`
| 删除多条时间序列（含数据）。 |
`paths`：要删除的时间序列路径列表
|
+| `DeleteData(paths []string, startTime int64, endTime int64) (r
common.TSStatus, err error)`
|
删除指定时间序列在时间段内的数据（保留元数据）。 | `paths`: 要删除的时间序列路径列表<br>`startTime`:
起始时间戳<br>`endTime`: 结束时间戳。
|
+| `SetTimeZone(timeZone string) (r common.TSStatus, err error)`
| 设置当前会话时区。 |
`timeZone`: 时区字符串，例如 ”UTC”, ”Asia/Shanghai”, ”GMT+8”
|
+| `GetTimeZone() (string, error)`
| 获取当前会话时区。 |
无
|
+
+### 3.5 关键配置结构 (PoolConfig)
+
+| 字段 | 类型 | 必填 | 描述
|
+| ----------------- | ---------------- | ------------------- |
----------------------------------------------------------- |
+| `Host` | `string` | 与NodeUrls二选一 | 单节点主机地址。
|
+| `Port` | `string` | 与NodeUrls二选一 | 单节点端口。
|
+| `NodeUrls` | `[]string` | 与Host/Port二选一 | 集群节点地址列表，格式为`”host:port”`。
|
+| `UserName` | `string` | 是 | 用户名。
|
+| `Password` | `string` | 是 | 密码。
|
+| `FetchSize` | `int32` | 否 | 查询结果集获取大小，默认1024。
|
+| `TimeZone` | `string` | 否 |
会话时区，如`”Asia/Shanghai”`，默认使用服务端时区。 |
+| `Database` | `string` | 否 | 表模型适用，用于设置会话默认数据库。
|
diff --git a/src/zh/UserGuide/latest/API/Programming-Go-Native-API.md
b/src/zh/UserGuide/latest/API/Programming-Go-Native-API.md
index 99f8d748..fe9e49b9 100644
--- a/src/zh/UserGuide/latest/API/Programming-Go-Native-API.md
+++ b/src/zh/UserGuide/latest/API/Programming-Go-Native-API.md
@@ -21,20 +21,25 @@
# Go 原生接口
-## 1. 依赖
+Go 原生 API 支持通过 `Session `和 `SessionPool `两种方式与数据库进行交互。由于 `Session
`非线程安全，因此强烈推荐使用 `SessionPool `编程。在多线程并发的情形下，`SessionPool
`能够合理地管理和分配连接资源，以提升系统性能与资源利用效率。
- * golang >= 1.13
- * make >= 3.0
- * curl >= 7.1.1
- * thrift 0.15.0
- * Linux、Macos 或其他类 unix 系统
- * Windows+bash (下载 IoTDB Go client 需要 git ，通过 WSL、cygwin、Git Bash 任意一种方式均可)
+本文将围绕 `SessionPool` 的使用进行说明，涵盖从环境准备、核心操作步骤到全量接口的完整内容。
-## 2. 安装方法
+## 1. 环境准备
+### 1.1 前置依赖
- * 通过 go mod
+* golang >= 1.13
+* make >= 3.0
+* curl >= 7.1.1
+* thrift: 0.15.0
+* Linux、Macos 或其他类 unix 系统
+* Windows+bash (下载 IoTDB Go client 需要 git ，通过 WSL、cygwin、Git Bash 任意一种方式均可)
-```sh
+### 1.2 安装方法
+
+* 使用 go mod
+
+```Bash
# 切换到 GOPATH 的 HOME 路径，启用 Go Modules 功能
export GO111MODULE=on
@@ -57,9 +62,9 @@ go mod tidy
go run session_example.go
```
-* 通过 GOPATH
+* 使用 GOPATH
-```sh
+```Bash
# get thrift 0.13.0
go get github.com/apache/[email protected]
@@ -81,4 +86,330 @@ go mod tidy
# 编译并运行程序
go run session_example.go
```
-**注意：GO原生客户端Session不是线程安全的，强烈不建议在多线程场景下应用。如有多线程应用场景，请使用Session Pool.**
+
+## 2. 核心步骤
+
+使用 Go 原生接口操作 IoTDB 的三个核心步骤如下：
+
+1. 创建连接池实例：初始化一个`SessionPool`对象，配置连接参数和池大小。
+2. 执行数据库操作：从连接池中`GetSession()`，执行数据写入或查询等操作，完成后必须`PutBack(session)`。
+3. 关闭连接池资源：程序结束时调用`sessionPool.Close()`，释放所有连接。
+
+下面的章节用于说明开发的核心流程，并未演示所有的参数和接口，如需了解全部功能及参数请参见:
[全量接口说明](../API/Programming-Go-Native-API.md#_3-全量接口) 或 查阅: [SessionPool
示例源码](https://github.com/apache/iotdb-client-go/blob/main/example/session_pool/session_pool_example.go)
+
+### 2.1 创建连接池实例
+
+* 单实例
+
+```Go
+config := &client.PoolConfig{
+ Host: host,
+ Port: port,
+ UserName: user,
+ Password: password,
+}
+sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+defer sessionPool.Close()
+```
+
+* 分布式或双活
+
+```Go
+config := &client.PoolConfig{
+ UserName: user,
+ Password: password,
+ NodeUrls: strings.Split("127.0.0.1:6667,127.0.0.1:6668", ","),
+ }
+sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+defer sessionPool.Close()
+```
+
+### 2.2 数据库操作
+#### 2.2.1 数据写入
+
+```Go
+session, err := sessionPool.GetSession()
+defer sessionPool.PutBack(session)
+status, err := session.InsertTablet(tablet, false)
+tablet.Reset()
+checkError(status, err)
+```
+
+#### 2.2.2 数据查询
+
+```Go
+var timeout int64 = 1000
+session, err := sessionPool.GetSession()
+defer sessionPool.PutBack(session)
+if err != nil {
+ log.Print(err)
+ return
+}
+sessionDataSet, err := session.ExecuteQueryStatement(sql, &timeout)
+if err == nil {
+ defer sessionDataSet.Close()
+ printDataSet(sessionDataSet)
+} else {
+ log.Println(err)
+}
+```
+
+### 2.3 使用示例
+
+```Go
+import (
+ "flag"
+ "fmt"
+ "log"
+ "math/rand"
+ "strings"
+ "time"
+
+ "github.com/apache/iotdb-client-go/v2/client"
+ "github.com/apache/iotdb-client-go/v2/common"
+)
+
+var (
+ host string
+ port string
+ user string
+ password string
+)
+var sessionPool client.SessionPool
+
+func main() {
+ flag.StringVar(&host, "host", "127.0.0.1", "--host=192.168.1.100")
+ flag.StringVar(&port, "port", "6667", "--port=6667")
+ flag.StringVar(&user, "user", "root", "--user=root")
+ flag.StringVar(&password, "password", "root", "--password=root")
+ flag.Parse()
+
+ //1.创建连接池
+ config := &client.PoolConfig{
+ Host: host,
+ Port: port,
+ UserName: user,
+ Password: password,
+ }
+ sessionPool = client.NewSessionPool(config, 3, 60000, 60000, false)
+
+ defer sessionPool.Close()
+
+ //2.创建存储组
+ setStorageGroup("root.sg1")
+
+ //3. 创建时间序列
+ createTimeseries("root.sg1.dev1.temperature")
+
+ //4.数据写入
+ insertTablet()
+
+ //5. 数据查询
+ executeQueryStatement("select temperature from root.sg1.dev1")
+
+ //6. 删除
+ deleteTimeseries("root.sg1.dev1.temperature")
+ deleteStorageGroup("root.sg1")
+
+}
+
+// 设置存储组
+func setStorageGroup(sg string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ session.SetStorageGroup(sg)
+ }
+}
+
+// 删除存储组
+func deleteStorageGroup(sg string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.DeleteStorageGroup(sg))
+ }
+}
+
+// 创建时间序列
+func createTimeseries(path string) {
+ var (
+ dataType = client.FLOAT
+ encoding = client.PLAIN
+ compressor = client.SNAPPY
+ )
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.CreateTimeseries(path, dataType, encoding,
compressor, nil, nil))
+ }
+}
+
+// 删除时间序列
+func deleteTimeseries(paths ...string) {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ checkError(session.DeleteTimeseries(paths))
+ }
+}
+
+// 插入Tablet数据
+func insertTablet() {
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err == nil {
+ if tablet, err := createTablet(12); err == nil {
+ status, err := session.InsertTablet(tablet, false)
+ tablet.Reset()
+ checkError(status, err)
+ } else {
+ log.Fatal(err)
+ }
+ }
+}
+
+//创建Tablet
+func createTablet(rowCount int) (*client.Tablet, error) {
+ tablet, err := client.NewTablet("root.sg1.dev1",
[]*client.MeasurementSchema{
+ {
+ Measurement: "temperature",
+ DataType: client.FLOAT,
+ },
+ }, rowCount)
+
+ if err != nil {
+ return nil, err
+ }
+ ts := time.Now().UTC().UnixNano() / 1000000
+ for row := 0; row < int(rowCount); row++ {
+ ts++
+ tablet.SetTimestamp(ts, row)
+ tablet.SetValueAt(rand.Float32(), 0, row)
+ tablet.RowSize++
+ }
+ return tablet, nil
+}
+
+// 执行查询语句
+func executeQueryStatement(sql string) {
+ var timeout int64 = 1000
+ session, err := sessionPool.GetSession()
+ defer sessionPool.PutBack(session)
+ if err != nil {
+ log.Print(err)
+ return
+ }
+ sessionDataSet, err := session.ExecuteQueryStatement(sql, &timeout)
+ if err == nil {
+ defer sessionDataSet.Close()
+ printDataSet(sessionDataSet)
+ } else {
+ log.Println(err)
+ }
+}
+
+// 打印查询结果
+func printDataSet(sds *client.SessionDataSet) {
+ columnNames := sds.GetColumnNames()
+ for _, value := range columnNames {
+ fmt.Printf("%s\t", value)
+ }
+ fmt.Println()
+
+ for next, err := sds.Next(); err == nil && next; next, err = sds.Next() {
+ for _, columnName := range columnNames {
+ isNull, _ := sds.IsNull(columnName)
+
+ if isNull {
+ fmt.Printf("%v\t\t", "null")
+ } else {
+ v, _ := sds.GetString(columnName)
+ fmt.Printf("%v\t\t", v)
+ }
+ }
+ fmt.Println()
+ }
+}
+
+// 检查错误
+func checkError(status *common.TSStatus, err error) {
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ if status != nil {
+ if err = client.VerifySuccess(status); err != nil {
+ log.Println(err)
+ }
+ }
+}
+```
+
+## 3. 全量接口
+### 3.1 SessionPool 管理接口
+
+| 接口名称
| 功能描述
| 参数说明
|
+|--------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
+| `NewSessionPool(config *PoolConfig, maxSize, connTimeoutMs, waitTimeoutMs
int, enableComp bool) SessionPool` | 创建并返回一个Session连接池实例。
| `config`: 连接池配置 <br>`maxSize`: 最大连接数(≤0时取CPU数\*5)
<br>`connTimeoutMs`: TCP连接超时(ms) <br>`waitTimeoutMs`: 获取Session等待超时(ms)
<br>`enableComp`: 是否启用压缩 |
+| `GetSession() (Session, error)`
|
从池中获取一个可用Session。若池满则阻塞等待，超时返回错误。**必须与PutBack配对使用**。 | 无
|
+| `PutBack(session Session)`
| 将使用完毕的Session归还到连接池中。
| `session`: 从GetSession获取的实例
|
+| `Close()`
| 关闭连接池，释放所有活跃连接。程序退出前必须调用。
| 无
|
+
+### 3.2 数据写入接口
+
+以下接口需通过获取的 Session 进行调用
+
+| 接口名称
| 功能描述 | 参数说明
|
+|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
------------------------------ |
----------------------------------------------------------------------------------------------------------------------------------------------------------------
|
+| `InsertRecord(deviceId string, measurements []string, dataTypes
[]TSDataType, values []interface{}, timestamp int64) (r common.TSStatus, err
error)` | 插入单条记录。| `deviceId`: 设备ID <br>`measurements`:
测点列表 <br>`dataTypes`: 数据类型列表<br>`values`: 值列表<br>`timestamp`: 时间戳 |
+| `InsertAlignedRecord(deviceId string, measurements []string, dataTypes
[]TSDataType, values []interface{}, timestamp int64) (r common.TSStatus, err
error)` | 插入单条对齐记录。 | `deviceId`:
设备ID<br>`measurements`: 测点列表<br>`dataTypes`: 数据类型列表<br>`values`:
值列表<br>`timestamp`: 时间戳 |
+| `InsertStringRecord(deviceId string, measurements []string, values []string,
timestamp int64) (r common.TSStatus, err error)`
| 插入字符串格式的单条记录。 | `deviceId`: 设备ID<br>`measurements`:
测点列表<br>`values`: 字符串类型的值列表<br>`timestamp`: 时间戳 |
+| `InsertRecords(deviceIds []string, measurements [][]string, dataTypes
[][]TSDataType, values [][]interface{}, timestamps []int64) (r common.TSStatus,
err error)` | 插入多条记录。| `deviceIds`:
设备ID列表<br>`measurements`:二维测点列表<br>`dataTypes`: 二维数据类型列表<br>`values`:
二维值列表<br>`timestamps`: 时间戳列表 |
+| `InsertAlignedRecords(deviceIds []string, measurements [][]string, dataTypes
[][]TSDataType, values [][]interface{}, timestamps []int64) (r common.TSStatus,
err error)` | 插入多个对齐设备的多条记录。 | `deviceIds`:
设备ID列表<br>`measurements`:二维测点列表<br>`dataTypes`: 二维数据类型列表<br>`values`:
二维值列表<br>`timestamps`: 时间戳列表 |
+| `InsertTablet(tablet Tablet, sorted bool) (r common.TSStatus, err error)`
| 插入单个设备的多条数据。 | `tablet`: 要插入的`Tablet`数据<br>`sorted`: 数据是否已排序
|
+| `InsertAlignedTablet(tablet Tablet, sorted bool) (r common.TSStatus, err
error)`
| 插入单个对齐设备的多条数据。 | `tablet`: 要插入的`Tablet`数据<br>`sorted`:
数据是否已排序
|
+| `InsertTablets``(tablets []Tablet, sorted bool) (r common.TSStatus, err
error)`
| 批量插入多个 Tablet 数据。 | `tablets`: 要插入的多个`Tablet
`数据<br>`sorted`: 数据是否已排序
|
+| `InsertAlignedTablets(tablets []Tablet, sorted bool) (r common.TSStatus, err
error)`
| 批量插入多个对齐设备的数据。 | `tablets`: 要插入的多个`Tablet `数据<br>`sorted`:
数据是否已排序
|
+
+### 3.3 SQL与查询接口
+
+以下接口需通过获取的 Session 进行调用
+
+| 接口名称
|
功能描述 | 参数说明
|
+|----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|----------------------------------------------------------------------------------------------------------------------|
+| `ExecuteStatement(sql string)`*`(`*`SessionDataSet, error)`
|
执行SQL（主要查询），返回`SessionDataSet`。 | `sql`：要执行的SQL查询语句
|
+| `ExecuteQueryStatement(sql string, timeoutMs int64) (SessionDataSet, error)`
|
执行查询SQL，可指定超时，返回`SessionDataSet`。 | `sql`：要执行的SQL查询语句<br>`timeoutMs`:
查询超时时间（毫秒）
|
+| `ExecuteNonQueryStatementExecuteNonQueryStatement(sql string) (r
common.TSStatus, err error)`
| 执行不返回结果集的SQL（如INSERT, CREATE, DELETE）。 | `sql`：要执行的SQL语句
|
+| `ExecuteRawDataQuery(paths []string, startTime int64, endTime int64)
(*SessionDataSet, error)`
| 查询指定时间序列在时间范围内的原始数据。 | `paths`: 查询路径列表<br>`startTime`:
起始时间戳<br>`endTime`: 结束时间戳
|
+| `ExecuteAggregationQuery(paths []string, aggregations
[]common.TAggregationType, startTime, endTime, interval, timeoutMs int64)
(SessionDataSet, error)` | 执行聚合查询（COUNT, AVG等）。 | `paths`:
查询路径列表<br>`aggregations`: 聚合类型列表<br>`startTime, endTime, interval`:
起始时间、结束时间和间隔时间<br>`timeoutMs`: 查询超时时间 |
+| `ExecuteBatchStatement(sqls []string) (r common.TSStatus, err error)`
|
批量执行多条SQL语句。 | `sqls`：要执行的SQL语句
|
+
+### 3.4 元数据操作接口
+
+以下接口需通过获取的 Session 进行调用
+
+| 接口名称
| 功能描述 |
参数说明
|
+|
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
+| `SetStorageGroup(storageGroupId string) (r common.TSStatus, err error)`
| 创建数据库（存储组）。 |
`storageGroupId`：数据库（存储组）名称
|
+| `DeleteStorageGroup(storageGroupId string) (r common.TSStatus, err error)`
| 删除一个数据库（存储组）。 |
`storageGroupId`：要删除的数据库（存储组）名称
|
+| `DeleteStorageGroups(storageGroupIds ...string) (r common.TSStatus, err
error)`
| 删除多个数据库（存储组）。
| `storageGroupIds`：要删除的数据库（存储组）名称列表
|
+| `CreateTimeseries(path string, dataType TSDataType, encoding TSEncoding,
compressor TSCompressionType, attributes map[string]string, tags
map[string]string) (r common.TSStatus, err error)` |
创建非对齐时间序列。 | `path`: 时间序列路径<br>`dataType`: 数据类型<br>`encoding`:
编码方式<br>`compressor`: 压缩算法<br>`attributes`: （可选）序列属性<br>`tags`: （可选）序列标签
|
+| `CreateAlignedTimeseries(prefixPath string, measurements []string, dataTypes
[]TSDataType, encodings []TSEncoding, compressors []TSCompressionType,
measurementAlias []string) (r common.TSStatus, err error)` | 创建一组对齐时间序列。
| `prefixPath`: 时间序列路径前缀<br>`measurements`: 测点名称列表<br>`dataTypes,
encodings, compressors`: 每个测点对应的数据类型、编码和压缩算法列表<br>`measurementAlias`:
（可选）每个测点的别名列表 |
+| `DeleteTimeseries(paths []string) (r common.TSStatus, err error)`
| 删除多条时间序列（含数据）。 |
`paths`：要删除的时间序列路径列表
|
+| `DeleteData(paths []string, startTime int64, endTime int64) (r
common.TSStatus, err error)`
|
删除指定时间序列在时间段内的数据（保留元数据）。 | `paths`: 要删除的时间序列路径列表<br>`startTime`:
起始时间戳<br>`endTime`: 结束时间戳。
|
+| `SetTimeZone(timeZone string) (r common.TSStatus, err error)`
| 设置当前会话时区。 |
`timeZone`: 时区字符串，例如 ”UTC”, ”Asia/Shanghai”, ”GMT+8”
|
+| `GetTimeZone() (string, error)`
| 获取当前会话时区。 |
无
|
+
+### 3.5 关键配置结构 (PoolConfig)
+
+| 字段 | 类型 | 必填 | 描述
|
+| ----------------- | ---------------- | ------------------- |
----------------------------------------------------------- |
+| `Host` | `string` | 与NodeUrls二选一 | 单节点主机地址。
|
+| `Port` | `string` | 与NodeUrls二选一 | 单节点端口。
|
+| `NodeUrls` | `[]string` | 与Host/Port二选一 | 集群节点地址列表，格式为`”host:port”`。
|
+| `UserName` | `string` | 是 | 用户名。
|
+| `Password` | `string` | 是 | 密码。
|
+| `FetchSize` | `int32` | 否 | 查询结果集获取大小，默认1024。
|
+| `TimeZone` | `string` | 否 |
会话时区，如`”Asia/Shanghai”`，默认使用服务端时区。 |
+| `Database` | `string` | 否 | 表模型适用，用于设置会话默认数据库。
|
