You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/user-guide/ingest-data/for-iot/grpc-sdks/go.md
+61-59Lines changed: 61 additions & 59 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,26 +3,21 @@ keywords: [Go SDK, gRPC, data ingestion, installation, connection, low-level API
3
3
description: Guide on using the Go ingester SDK for GreptimeDB, including installation, connection, data model, and examples of low-level and high-level APIs.
4
4
---
5
5
6
-
import DocTemplate from './template.md'
7
-
8
6
# Go
9
7
10
-
<DocTemplate>
11
-
12
-
<divid="ingester-lib-introduction">
8
+
GreptimeDB offers ingester libraries for high-throughput data writing.
9
+
It utilizes the gRPC protocol,
10
+
which supports schemaless writing and eliminates the need to create tables before writing data.
11
+
For more information, refer to [Automatic Schema Generation](/user-guide/ingest-data/overview.md#automatic-schema-generation).
13
12
14
13
The Go ingester SDK provided by GreptimeDB is a lightweight,
15
14
concurrent-safe library that is easy to use with the metric struct.
16
15
17
-
</div>
18
-
19
-
<divid="quick-start-demos">
16
+
## Quick start demos
20
17
21
18
To quickly get started, you can explore the [quick start demos](https://github.com/GreptimeTeam/greptimedb-ingester-go/tree/main/examples) to understand how to use the GreptimeDB Go ingester SDK.
22
19
23
-
</div>
24
-
25
-
<divid="ingester-lib-installation">
20
+
## Installation
26
21
27
22
Use the following command to install the GreptimeDB client library for Go:
28
23
@@ -41,9 +36,11 @@ import (
41
36
)
42
37
```
43
38
44
-
</div>
39
+
## Connect to database
45
40
46
-
<divid="ingester-lib-connect">
41
+
If you have set the [`--user-provider` configuration](/user-guide/deployments-administration/authentication/overview.md) when starting GreptimeDB,
42
+
you will need to provide a username and password to connect to GreptimeDB.
43
+
The following example shows how to set the username and password when using the library to connect to GreptimeDB.
Each row item in a table consists of three types of columns: `Tag`, `Timestamp`, and `Field`. For more information, see [Data Model](/user-guide/concepts/data-model.md).
64
+
The types of column values could be `String`, `Float`, `Int`, `Timestamp`, `JSON` etc. For more information, see [Data Types](/reference/sql/data-types.md).
65
+
66
+
## Set table options
67
+
68
+
Although the time series table is created automatically when writing data to GreptimeDB via the SDK,
69
+
you can still configure table options.
70
+
The SDK supports the following table options:
71
+
72
+
-`auto_create_table`: Default is `True`. If set to `False`, it indicates that the table already exists and does not need automatic creation, which can improve write performance.
73
+
-`ttl`, `append_mode`, `merge_mode`: For more details, refer to the [table options](/reference/sql/create.md#table-options).
66
74
67
75
You can set table options using the `ingesterContext` context.
68
76
For example, to set the `ttl` option, use the following code:
@@ -85,9 +93,24 @@ if err != nil {
85
93
}
86
94
```
87
95
88
-
</div>
96
+
For how to write data to GreptimeDB, see the following sections.
97
+
98
+
## Low-level API
99
+
100
+
The GreptimeDB low-level API provides a straightforward method to write data to GreptimeDB
101
+
by adding rows to the table object with a predefined schema.
102
+
103
+
### Create row objects
104
+
105
+
This following code snippet begins by constructing a table named `cpu_metric`,
106
+
which includes columns `host`, `cpu_user`, `cpu_sys`, and `ts`.
107
+
Subsequently, it inserts a single row into the table.
108
+
109
+
The table consists of three types of columns:
89
110
90
-
<divid="low-level-object">
111
+
-`Tag`: The `host` column, with values of type `String`.
112
+
-`Field`: The `cpu_user` and `cpu_sys` columns, with values of type `Float`.
113
+
-`Timestamp`: The `ts` column, with values of type `Timestamp`.
91
114
92
115
```go
93
116
// Construct the table schema for CPU metrics
@@ -114,9 +137,7 @@ if err != nil {
114
137
115
138
```
116
139
117
-
</div>
118
-
119
-
<divid="create-rows">
140
+
To improve the efficiency of writing data, you can create multiple rows at once to write to GreptimeDB.
120
141
121
142
```go
122
143
cpuMetric, err:= table.New("cpu_metric")
@@ -145,9 +166,9 @@ if err != nil {
145
166
}
146
167
```
147
168
148
-
</div>
169
+
### Insert data
149
170
150
-
<divid="insert-rows">
171
+
The following example shows how to insertrows to tables in GreptimeDB.
Streaming insert is useful when you want to insert a large amount of data such as importing historical data.
238
241
239
242
```go
240
243
err:= cli.StreamWriteObject(ctx, cpuMetrics)
@@ -247,9 +250,12 @@ In general, you do not need to close the stream writing when continuously writin
247
250
affected, err:= cli.CloseStream(ctx)
248
251
```
249
252
250
-
</div>
253
+
## Insert data in JSON type
251
254
252
-
<divid="ingester-json-type">
255
+
GreptimeDB supports storing complex data structures using [JSON type data](/reference/sql/data-types.md#json-type).
256
+
With this ingester library, you can insert JSON data using string values.
257
+
For instance, if you have a table named `sensor_readings` and wish to add a JSON column named `attributes`,
258
+
refer to the following code snippet.
253
259
254
260
In the [low-level API](#low-level-api),
255
261
you can specify the column type as `types.JSON` using the `AddFieldColumn` method to add a JSON column.
@@ -302,12 +308,8 @@ sensor := SensorReadings{
302
308
303
309
For the executable code for inserting JSON data, please refer to the [example](https://github.com/GreptimeTeam/greptimedb-ingester-go/tree/main/examples/jsondata) in the SDK repository.
0 commit comments