Skip to content

Commit a344a28

Browse files
authored
chore: remove SDK template (#1948)
1 parent 3009efe commit a344a28

File tree

12 files changed

+490
-886
lines changed

12 files changed

+490
-886
lines changed

docs/user-guide/ingest-data/for-iot/grpc-sdks/go.md

Lines changed: 61 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,21 @@ keywords: [Go SDK, gRPC, data ingestion, installation, connection, low-level API
33
description: Guide on using the Go ingester SDK for GreptimeDB, including installation, connection, data model, and examples of low-level and high-level APIs.
44
---
55

6-
import DocTemplate from './template.md'
7-
86
# Go
97

10-
<DocTemplate>
11-
12-
<div id="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).
1312

1413
The Go ingester SDK provided by GreptimeDB is a lightweight,
1514
concurrent-safe library that is easy to use with the metric struct.
1615

17-
</div>
18-
19-
<div id="quick-start-demos">
16+
## Quick start demos
2017

2118
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.
2219

23-
</div>
24-
25-
<div id="ingester-lib-installation">
20+
## Installation
2621

2722
Use the following command to install the GreptimeDB client library for Go:
2823

@@ -41,9 +36,11 @@ import (
4136
)
4237
```
4338

44-
</div>
39+
## Connect to database
4540

46-
<div id="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.
4744

4845
```go
4946
cfg := greptime.NewConfig("127.0.0.1").
@@ -60,9 +57,20 @@ cfg := greptime.NewConfig("127.0.0.1").
6057
cli, _ := greptime.NewClient(cfg)
6158
defer cli.Close()
6259
```
63-
</div>
6460

65-
<div id="set-table-options">
61+
## Data model
62+
63+
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).
6674

6775
You can set table options using the `ingesterContext` context.
6876
For example, to set the `ttl` option, use the following code:
@@ -85,9 +93,24 @@ if err != nil {
8593
}
8694
```
8795

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:
89110

90-
<div id="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`.
91114

92115
```go
93116
// Construct the table schema for CPU metrics
@@ -114,9 +137,7 @@ if err != nil {
114137

115138
```
116139

117-
</div>
118-
119-
<div id="create-rows">
140+
To improve the efficiency of writing data, you can create multiple rows at once to write to GreptimeDB.
120141

121142
```go
122143
cpuMetric, err := table.New("cpu_metric")
@@ -145,9 +166,9 @@ if err != nil {
145166
}
146167
```
147168

148-
</div>
169+
### Insert data
149170

150-
<div id="insert-rows">
171+
The following example shows how to insert rows to tables in GreptimeDB.
151172

152173
```go
153174
resp, err := cli.Write(ctx, cpuMetric, memMetric)
@@ -157,9 +178,9 @@ if err != nil {
157178
log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue())
158179
```
159180

160-
</div>
181+
### Streaming insert
161182

162-
<div id="streaming-insert">
183+
Streaming insert is useful when you want to insert a large amount of data such as importing historical data.
163184

164185
```go
165186
err := cli.StreamWrite(ctx, cpuMetric, memMetric)
@@ -175,10 +196,15 @@ In general, you do not need to close the stream writing when continuously writin
175196
affected, err := cli.CloseStream(ctx)
176197
```
177198

178-
</div>
199+
## High-level API
179200

201+
The high-level API uses an ORM style object to write data to GreptimeDB.
202+
It allows you to create, insert, and update data in a more object-oriented way,
203+
providing developers with a friendlier experience.
204+
However, it is not as efficient as the low-level API.
205+
This is because the ORM style object may consume more resources and time when converting the objects.
180206

181-
<div id="high-level-style-object">
207+
### Create row objects
182208

183209
```go
184210
type CpuMetric struct {
@@ -202,39 +228,16 @@ cpuMetrics := []CpuMetric{
202228
}
203229
```
204230

205-
<!-- SDK TODO -->
206-
<!-- ```go
207-
type MemMetric struct {
208-
Host string `greptime:"tag;column:host;type:string"`
209-
Memory float64 `greptime:"field;column:mem_usage;type:float64"`
210-
Ts time.Time `greptime:"timestamp;column:ts;type:timestamp;precision:millisecond"`
211-
}
212-
213-
func (MemoryMetric) TableName() string {
214-
return "mem_metric"
215-
}
216-
217-
memMetrics := []MemMetric{
218-
{
219-
Host: "127.0.0.1",
220-
Memory: 112,
221-
Ts: time.Now(),
222-
}
223-
}
224-
``` -->
225-
226-
</div>
227-
228-
<div id="high-level-style-insert-data">
231+
### Insert data
229232

230233
```go
231234
resp, err := cli.WriteObject(ctx, cpuMetrics)
232235
log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue())
233236
```
234237

235-
</div>
238+
### Streaming insert
236239

237-
<div id="high-level-style-streaming-insert">
240+
Streaming insert is useful when you want to insert a large amount of data such as importing historical data.
238241

239242
```go
240243
err := cli.StreamWriteObject(ctx, cpuMetrics)
@@ -247,9 +250,12 @@ In general, you do not need to close the stream writing when continuously writin
247250
affected, err := cli.CloseStream(ctx)
248251
```
249252

250-
</div>
253+
## Insert data in JSON type
251254

252-
<div id="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.
253259

254260
In the [low-level API](#low-level-api),
255261
you can specify the column type as `types.JSON` using the `AddFieldColumn` method to add a JSON column.
@@ -302,12 +308,8 @@ sensor := SensorReadings{
302308

303309
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.
304310

305-
</div>
306311

307-
<div id="ingester-lib-reference">
312+
## Ingester library reference
308313

309314
- [API Documentation](https://pkg.go.dev/github.com/GreptimeTeam/greptimedb-ingester-go)
310315

311-
</div>
312-
313-
</DocTemplate>

0 commit comments

Comments
 (0)