From a16fc706528142f4aa894ef003ceb4c8de435ebe Mon Sep 17 00:00:00 2001 From: yuanbohan Date: Tue, 27 Feb 2024 16:38:28 +0800 Subject: [PATCH] refactor: use write object interface name (#24) * use write object interface name * bump version --- README.md | 94 ++++++++++++++-------------- client.go | 16 ++--- client_test.go | 4 +- examples/README.md | 6 +- examples/{tag => object}/README.md | 0 examples/{tag => object}/main.go | 12 ++-- examples/{schema => table}/README.md | 0 examples/{schema => table}/main.go | 0 version.go | 2 +- 9 files changed, 66 insertions(+), 68 deletions(-) rename examples/{tag => object}/README.md (100%) rename examples/{tag => object}/main.go (91%) rename examples/{schema => table}/README.md (100%) rename examples/{schema => table}/main.go (100%) diff --git a/README.md b/README.md index 7bbc493..1a19312 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,9 @@ go get -u github.com/GreptimeTeam/greptimedb-ingester-go ```go import greptime "github.com/GreptimeTeam/greptimedb-ingester-go" - ``` -### Example - -#### Config +### Config Initiate a Config for Client @@ -33,53 +30,26 @@ cfg := greptime.NewConfig(""). WithDatabase("") ``` -#### Client +### Client ```go cli, err := greptime.NewClient(cfg) ``` -#### Insert & StreamInsert +### Insert & StreamInsert - you can Insert data into GreptimeDB via different style: - - [Table/Column/Row style](#with-schema-predefined) + + - [Table style](#with-table) - [ORM style](#with-struct-tag) - streaming insert is to Send data into GreptimeDB without waiting for response. -##### Datatypes supported - -The **GreptimeDB** column is for the datatypes supported in library, and the **Go** column is the matched Go type. - -| GreptimeDB | Go | Description | -|----------------------------------|------------------|----------------------------------------| -| INT8 | int8 | | -| INT16 | int16 | | -| INT32 | int32 | | -| INT64, INT | int64 | | -| UINT8 | uint8 | | -| UINT16 | uint16 | | -| UINT32 | uint32 | | -| UINT64, UINT | uint64 | | -| FLOAT32 | float32 | | -| FLOAT64, FLOAT | float64 | | -| BOOLEAN, BOOL | bool | | -| STRING | string | | -| BINARY, BYTES | []byte | | -| DATE | *Int* or time.Time | the day elapsed since 1970-1-1 | -| DATETIME | *Int* or time.Time | the millisecond elapsed since 1970-1-1 | -| TIMESTAMP_SECOND | *Int* or time.Time | | -| TIMESTAMP_MILLISECOND, TIMESTAMP | *Int* or time.Time | | -| TIMESTAMP_MICROSECOND | *Int* or time.Time | | -| TIMESTAMP_NANOSECOND | *Int* or time.Time | | - -NOTE: *Int* is for all of Integer and Unsigned Integer in Go - -##### With Schema predefined +#### With Table you can define schema via Table and Column, and then AddRow to include the real data you want to write. -###### define table schema, and add rows +##### define table schema, and add rows ```go import( @@ -98,13 +68,13 @@ err := tbl.AddRow(2, "127.0.0.2", time.Now()) ... ``` -###### Write into GreptimeDB +##### Write into GreptimeDB ```go resp, err := cli.Write(context.Background(), tbl) ``` -###### Stream Write into GreptimeDB +##### Stream Write into GreptimeDB ```go err := cli.StreamWrite(context.Background(), tbl) @@ -112,11 +82,11 @@ err := cli.StreamWrite(context.Background(), tbl) affected, err := cli.CloseStream(ctx) ``` -##### With Struct Tag +#### With Struct Tag If you prefer ORM style, and define column-field relationship via struct field tag, you can try the following way. -###### Tag +##### Tag - `greptime` is the struct tag key - `tag`, `field`, `timestamp` is for [SemanticType][data-model], and the value is ignored @@ -126,7 +96,7 @@ If you prefer ORM style, and define column-field relationship via struct field t type supported is the same as described [Datatypes supported](#datatypes-supported), and case insensitive -###### define struct with tags +##### define struct with tags ```go type Monitor struct { @@ -141,7 +111,7 @@ func (Monitor) TableName() string { } ``` -###### instance your struct +##### instance your struct ```go monitors := []Monitor{ @@ -158,21 +128,49 @@ monitors := []Monitor{ } ``` -###### Create into GreptimeDB +##### WriteObject into GreptimeDB ```go -resp, err := cli.Create(context.Background(), monitors) +resp, err := cli.WriteObject(context.Background(), monitors) ``` -###### Stream Create into GreptimeDB +##### Stream WriteObject into GreptimeDB ```go -err := cli.StreamCreate(context.Background(), monitors) +err := cli.StreamWriteObject(context.Background(), monitors) ... affected, err := cli.CloseStream(ctx) ``` -#### Query +## Datatypes supported + +The **GreptimeDB** column is for the datatypes supported in library, and the **Go** column is the matched Go type. + +| GreptimeDB | Go | Description | +|----------------------------------|------------------|----------------------------------------| +| INT8 | int8 | | +| INT16 | int16 | | +| INT32 | int32 | | +| INT64, INT | int64 | | +| UINT8 | uint8 | | +| UINT16 | uint16 | | +| UINT32 | uint32 | | +| UINT64, UINT | uint64 | | +| FLOAT32 | float32 | | +| FLOAT64, FLOAT | float64 | | +| BOOLEAN, BOOL | bool | | +| STRING | string | | +| BINARY, BYTES | []byte | | +| DATE | *Int* or time.Time | the day elapsed since 1970-1-1 | +| DATETIME | *Int* or time.Time | the millisecond elapsed since 1970-1-1 | +| TIMESTAMP_SECOND | *Int* or time.Time | | +| TIMESTAMP_MILLISECOND, TIMESTAMP | *Int* or time.Time | | +| TIMESTAMP_MICROSECOND | *Int* or time.Time | | +| TIMESTAMP_NANOSECOND | *Int* or time.Time | | + +NOTE: *Int* is for all of Integer and Unsigned Integer in Go + +## Query You can use ORM library like [gorm][gorm] with MySQL or PostgreSQL driver to [connect][connect] GreptimeDB and retrieve data from it. diff --git a/client.go b/client.go index 4048332..91d387a 100644 --- a/client.go +++ b/client.go @@ -71,7 +71,7 @@ func (c *Client) Write(ctx context.Context, tables ...*table.Table) (*gpb.Grepti return c.client.Handle(ctx, request_) } -// Create is like [Write] to write the data into GreptimeDB, but schema is defined in the struct tag. +// WriteObject is like [Write] to write the data into GreptimeDB, but schema is defined in the struct tag. // // type Monitor struct { // ID int64 `greptime:"tag;column:id;type:int64"` @@ -108,9 +108,9 @@ func (c *Client) Write(ctx context.Context, tables ...*table.Table) (*gpb.Grepti // }, // } // -// resp, err := client.Create(context.Background(), monitors) -func (c *Client) Create(ctx context.Context, body any) (*gpb.GreptimeResponse, error) { - tbl, err := schema.Parse(body) +// resp, err := client.WriteObject(context.Background(), monitors) +func (c *Client) WriteObject(ctx context.Context, obj any) (*gpb.GreptimeResponse, error) { + tbl, err := schema.Parse(obj) if err != nil { return nil, err } @@ -150,7 +150,7 @@ func (c *Client) StreamWrite(ctx context.Context, tables ...*table.Table) error return c.stream.Send(request_) } -// StreamCreate is like [StreamWrite] to send the data into GreptimeDB, but schema is defined in the struct tag. +// StreamWriteObject is like [StreamWrite] to send the data into GreptimeDB, but schema is defined in the struct tag. // // type monitor struct { // ID int64 `greptime:"tag;column:id;type:int64"` @@ -187,8 +187,8 @@ func (c *Client) StreamWrite(ctx context.Context, tables ...*table.Table) error // }, // } // -// resp, err := client.StreamCreate(context.Background(), monitors) -func (c *Client) StreamCreate(ctx context.Context, body any) error { +// resp, err := client.StreamWriteObject(context.Background(), monitors) +func (c *Client) StreamWriteObject(ctx context.Context, body any) error { tbl, err := schema.Parse(body) if err != nil { return err @@ -197,7 +197,7 @@ func (c *Client) StreamCreate(ctx context.Context, body any) error { } // CloseStream closes the stream. Once we’ve finished writing our client’s requests to the stream -// using client.StreamWrite or client.StreamCreate, we need to call client.CloseStream to let +// using client.StreamWrite or client.StreamWriteObject, we need to call client.CloseStream to let // GreptimeDB know that we’ve finished writing and are expecting to receive a response. func (c *Client) CloseStream(ctx context.Context) (*gpb.AffectedRows, error) { resp, err := c.stream.CloseAndRecv() diff --git a/client_test.go b/client_test.go index 72d5342..82460bb 100644 --- a/client_test.go +++ b/client_test.go @@ -336,7 +336,7 @@ func TestCreateMonitors(t *testing.T) { }, } - resp, err := cli.Create(context.Background(), monitors) + resp, err := cli.WriteObject(context.Background(), monitors) assert.Nil(t, err) assert.Zero(t, resp.GetHeader().GetStatus().GetStatusCode()) assert.Empty(t, resp.GetHeader().GetStatus().GetErrMsg()) @@ -607,7 +607,7 @@ func TestStreamCreate(t *testing.T) { }, } - err = cli.StreamCreate(context.Background(), monitors) + err = cli.StreamWriteObject(context.Background(), monitors) assert.Nil(t, err) affected, err := cli.CloseStream(context.Background()) assert.EqualValues(t, 2, affected.GetValue()) diff --git a/examples/README.md b/examples/README.md index fd3852c..e768db7 100644 --- a/examples/README.md +++ b/examples/README.md @@ -11,7 +11,7 @@ docker run --rm -p 4000-4003:4000-4003 \ --postgres-addr 0.0.0.0:4003 ``` -## Insert +## Examples -- [schema](schema/README.md) -- [tag](tag/README.md) +- [write table](table/README.md) +- [write object](object/README.md) diff --git a/examples/tag/README.md b/examples/object/README.md similarity index 100% rename from examples/tag/README.md rename to examples/object/README.md diff --git a/examples/tag/main.go b/examples/object/main.go similarity index 91% rename from examples/tag/main.go rename to examples/object/main.go index 0b628b4..496bccb 100644 --- a/examples/tag/main.go +++ b/examples/object/main.go @@ -73,17 +73,17 @@ func data() []Monitor { } } -func create() { - resp, err := client.Create(context.Background(), data()) +func writeObject() { + resp, err := client.WriteObject(context.Background(), data()) if err != nil { log.Fatal(err) } log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue()) } -func streamCreate() { +func streamWriteObject() { ctx := context.Background() - if err := client.StreamCreate(ctx, data()); err != nil { + if err := client.StreamWriteObject(ctx, data()); err != nil { log.Println(err) } affected, err := client.CloseStream(ctx) @@ -94,7 +94,7 @@ func streamCreate() { } func main() { - create() + writeObject() time.Sleep(time.Millisecond * 100) - streamCreate() + streamWriteObject() } diff --git a/examples/schema/README.md b/examples/table/README.md similarity index 100% rename from examples/schema/README.md rename to examples/table/README.md diff --git a/examples/schema/main.go b/examples/table/main.go similarity index 100% rename from examples/schema/main.go rename to examples/table/main.go diff --git a/version.go b/version.go index a5b5e89..7fac8f1 100644 --- a/version.go +++ b/version.go @@ -14,4 +14,4 @@ package greptime -const Version = "v0.2.0" // THIS MUST BE THE SAME AS THE VERSION in GitHub release +const Version = "v0.3.0" // THIS MUST BE THE SAME AS THE VERSION in GitHub release