Go

GreptimeDB 使用不同的客户端库来写入和查询数据。 你根据需求可以选择合适的客户端库。

写入数据

GreptimeDB 提供了一个 ingester 库来帮助你写入数据。 它使用 gRPC 协议，支持自动生成表结构，无需在写入数据前创建表。 更多信息请参考 自动生成表结构。

GreptimeDB 提供的 Go Ingest SDK 是一个轻量级、并发安全的库，使用起来非常简单。

安装

使用下方的命令安装 Go Ingest SDK：

shell

1. go get github.com/GreptimeTeam/greptimedb-client-go@v0.1.2 google.golang.org/grpc google.golang.org/grpc/credentials/insecure

引入到代码中：

go

1. import (
2. greptime "github.com/GreptimeTeam/greptimedb-client-go"
3. "google.golang.org/grpc"
4. "google.golang.org/grpc/credentials/insecure"
5. )

连接数据库

连接 GreptimeDB 时，通常需要用户名和密码。 关于如何设置 GreptimeDB 的鉴权方式，请参考鉴权。 这里我们在使用 ingester 库连接 GreptimeDB 时设置用户名和密码。

go

1. options := []grpc.DialOption{
2. grpc.WithTransportCredentials(insecure.NewCredentials()),
3. }
4. // To connect a database that needs authentication, for example, those on Greptime Cloud,
5. // `Username` and `Password` are needed when connecting to a database that requires authentication.
6. // Leave the two fields empty if connecting a database without authentication.
7. cfg := greptime.NewCfg("127.0.0.1").
8. WithDatabase("public").      // change to your real database
9. WithPort(4001).              // default port
10. WithAuth("username", "password").            // `Username` and `Password`
11. WithDialOptions(options...). // specify your gRPC dail options
12. WithCallOptions()            // specify your gRPC call options

14. client, _ := greptime.NewClient(cfg)

行对象

表中的每条行数据包含三种类型的列：Tag、Timestamp 和 Field。更多信息请参考 数据模型。 列值的类型可以是 String、Float、Int、Timestamp 等。更多信息请参考 数据类型。

Go Ingest SDK 使用 Series 来表示一行数据，多个 Series 可以添加到 Metric 中，然后写入到 GreptimeDB 中。

创建行数据

下面的例子展示了如何创建包含 Tag、Timestamp 和 Field 列的行。Tag 列是 String 类型，Timestamp 列是 Timestamp 类型，Field 列是 Float 类型。

为了提高写入数据的效率，你可以一次创建多行数据写入 GreptimeDB。

go

1. seriesHost1 := greptime.Series{}
2. seriesHost1.AddStringTag("host", "host1")
3. seriesHost1.AddFloatField("cpu", 0.90)
4. seriesHost1.SetTimestamp(time.Now())

6. seriesHost2 := greptime.Series{}
7. seriesHost2.AddStringTag("host", "host2")
8. seriesHost2.AddFloatField("cpu", 0.70)
9. seriesHost2.SetTimestamp(time.Now())

11. metric := greptime.Metric{}
12. metric.AddSeries(seriesHost1, seriesHost2)

保存行数据

下方的例子展示了如何将行数据保存到 GreptimeDB 中。

go

1. seriesHost1 := greptime.Series{}
2. seriesHost1.AddStringTag("host", "host1")
3. seriesHost1.AddFloatField("cpu", 0.90)
4. seriesHost1.SetTimestamp(time.Now())

6. seriesHost2 := greptime.Series{}
7. seriesHost2.AddStringTag("host", "host2")
8. seriesHost2.AddFloatField("cpu", 0.70)
9. seriesHost2.SetTimestamp(time.Now())

11. metric := greptime.Metric{}
12. metric.AddSeries(seriesHost1, seriesHost2)

14. monitorReq := greptime.InsertRequest{}
15. monitorReq.WithTable("monitor").WithMetric(metric)

17. insertsRequest := greptime.InsertsRequest{}
18. insertsRequest.Append(monitorReq)

20. res, err := client.Insert(context.Background(), insertsRequest)
21. if err != nil {
22. fmt.Printf("fail to insert, err: %+v\n", err)
23. // error handling
24. // ...
25. }
26. fmt.Printf("AffectedRows: %d\n", res.GetAffectedRows().Value)

更新行数据

请参考 更新数据了解更新机制。 下面的例子展示了先保存一行数据，然后更新这行数据。

go

1. // save a row data
2. series := greptime.Series{}
3. series.AddStringTag("host", "host1")
4. series.AddFloatField("cpu", 0.90)
5. series.SetTimestamp(1703832681000)
6. metric := greptime.Metric{}
7. metric.AddSeries(series)
8. monitorReq := greptime.InsertRequest{}
9. monitorReq.WithTable("monitor").WithMetric(metric)
10. insertsRequest := greptime.InsertsRequest{}
11. insertsRequest.Append(monitorReq)
12. res, _ := client.Insert(context.Background(), insertsRequest)

14. // update the row data
15. newSeries := greptime.Series{}
16. // The same tag `host1`
17. newSeries.AddStringTag("host", "host1")
18. // The same time index `1703832681000`
19. newSeries.SetTimestamp(1703832681000)
20. // The new field value `0.80`
21. newSeries.AddFloatField("cpu", 0.80)
22. // overwrite the existing data
23. metric := greptime.Metric{}
24. metric.AddSeries(newSeries)
25. monitorReq := greptime.InsertRequest{}
26. monitorReq.WithTable("monitor").WithMetric(metric)
27. insertsRequest := greptime.InsertsRequest{}
28. insertsRequest.Append(monitorReq)
29. res, _ := client.Insert(context.Background(), insertsRequest)

更多示例

有关更多可运行的代码片段和常用方法的解释，请参阅示例。

Ingester 库参考

查询数据

GreptimeDB 使用 SQL 作为主要查询语言，兼容 MySQL 和 PostgreSQL。 因此，我们推荐使用成熟的 SQL 驱动来查询数据。

推荐的查询库

我们推荐使用 Gorm 库来查询数据。

安装

使用下方的命令安装 Gorm：

shell

1. go get -u gorm.io/gorm

以 MySQL 为例安装 driver：

shell

1. go get -u gorm.io/driver/mysql

引入到代码中：

go

1. import (
2. "gorm.io/gorm"
3. "gorm.io/driver/mysql"
4. )

连接到数据库

下方的例子展示了如何连接到 GreptimeDB：

go

1. type Mysql struct {
2. Host     string
3. Port     string
4. User     string
5. Password string
6. Database string

8. DB *gorm.DB
9. }

11. m := &Mysql{
12. Host:     "127.0.0.1",
13. Port:     "4002", // default port for MySQL
14. User:     "username",
15. Password: "password",
16. Database: "public",
17. }

19. dsn := fmt.Sprintf("tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
20. m.Host, m.Port, m.Database)
21. dsn = fmt.Sprintf("%s:%s@%s", m.User, m.Password, dsn)
22. db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
23. if err != nil {
24. //error handling
25. }
26. m.DB = db

Raw SQL

我们推荐使用 Raw SQL 来体验 GreptimeDB 的全部功能。 下面的例子展示了如何使用 Raw SQL 查询数据：

go

1. type Monitor struct {
2. Host        string    `gorm:"column:host;primaryKey"`
3. Ts          time.Time `gorm:"column:ts;primaryKey"`
4. Cpu         float64   `gorm:"column:cpu"`
5. }

7. func (Monitor) TableName() string {
8. return "monitor"
9. }

11. var monitor Monitor
12. db.Raw("SELECT host, cpu, ts FROM users WHERE ts > ?", 1701360000000).Scan(&result)

查询库参考

有关如何使用查询库的更多信息，请参考相应库的文档：