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
  13. client, _ := greptime.NewClient(cfg)

行对象

表中的每条行数据包含三种类型的列:TagTimestampField。更多信息请参考 数据模型。 列值的类型可以是 StringFloatIntTimestamp 等。更多信息请参考 数据类型

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

创建行数据

下面的例子展示了如何创建包含 TagTimestampField 列的行。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())
  5. seriesHost2 := greptime.Series{}
  6. seriesHost2.AddStringTag("host", "host2")
  7. seriesHost2.AddFloatField("cpu", 0.70)
  8. seriesHost2.SetTimestamp(time.Now())
  9. metric := greptime.Metric{}
  10. 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())
  5. seriesHost2 := greptime.Series{}
  6. seriesHost2.AddStringTag("host", "host2")
  7. seriesHost2.AddFloatField("cpu", 0.70)
  8. seriesHost2.SetTimestamp(time.Now())
  9. metric := greptime.Metric{}
  10. metric.AddSeries(seriesHost1, seriesHost2)
  11. monitorReq := greptime.InsertRequest{}
  12. monitorReq.WithTable("monitor").WithMetric(metric)
  13. insertsRequest := greptime.InsertsRequest{}
  14. insertsRequest.Append(monitorReq)
  15. res, err := client.Insert(context.Background(), insertsRequest)
  16. if err != nil {
  17. fmt.Printf("fail to insert, err: %+v\n", err)
  18. // error handling
  19. // ...
  20. }
  21. 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)
  13. // update the row data
  14. newSeries := greptime.Series{}
  15. // The same tag `host1`
  16. newSeries.AddStringTag("host", "host1")
  17. // The same time index `1703832681000`
  18. newSeries.SetTimestamp(1703832681000)
  19. // The new field value `0.80`
  20. newSeries.AddFloatField("cpu", 0.80)
  21. // overwrite the existing data
  22. metric := greptime.Metric{}
  23. metric.AddSeries(newSeries)
  24. monitorReq := greptime.InsertRequest{}
  25. monitorReq.WithTable("monitor").WithMetric(metric)
  26. insertsRequest := greptime.InsertsRequest{}
  27. insertsRequest.Append(monitorReq)
  28. 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
  7. DB *gorm.DB
  8. }
  9. m := &Mysql{
  10. Host: "127.0.0.1",
  11. Port: "4002", // default port for MySQL
  12. User: "username",
  13. Password: "password",
  14. Database: "public",
  15. }
  16. dsn := fmt.Sprintf("tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
  17. m.Host, m.Port, m.Database)
  18. dsn = fmt.Sprintf("%s:%s@%s", m.User, m.Password, dsn)
  19. db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
  20. if err != nil {
  21. //error handling
  22. }
  23. 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. }
  6. func (Monitor) TableName() string {
  7. return "monitor"
  8. }
  9. var monitor Monitor
  10. db.Raw("SELECT host, cpu, ts FROM users WHERE ts > ?", 1701360000000).Scan(&result)

查询库参考

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