From ddd87b4c72a95aecc8d81c41b70c03b5cd48e23c Mon Sep 17 00:00:00 2001 From: yuanbohan Date: Wed, 7 Feb 2024 14:15:14 +0800 Subject: [PATCH] docs: more docs (#21) * more docs * lisence --- .licenserc.yaml | 1 + README.md | 81 ++++++++++++++++----------------------- examples/schema/README.md | 56 +++++++++++++++++++++++++++ examples/schema/main.go | 25 ++++++------ examples/tag/README.md | 56 +++++++++++++++++++++++++++ examples/tag/main.go | 12 +++--- 6 files changed, 162 insertions(+), 69 deletions(-) create mode 100644 examples/schema/README.md create mode 100644 examples/tag/README.md diff --git a/.licenserc.yaml b/.licenserc.yaml index ffc7ab6..ae32022 100644 --- a/.licenserc.yaml +++ b/.licenserc.yaml @@ -17,6 +17,7 @@ header: - '.gitignore' - 'LICENSE' - '*.md' + - 'examples/**/*.md' - "*.yml" - "*.yaml" - 'go.mod' diff --git a/README.md b/README.md index b6b71b9..954a1ff 100644 --- a/README.md +++ b/README.md @@ -6,17 +6,6 @@ Provide API to insert data into GreptimeDB. -start GreptimeDB via Docker - -```shell -docker run --rm -p 4000-4003:4000-4003 \ ---name greptime greptime/greptimedb standalone start \ ---http-addr 0.0.0.0:4000 \ ---rpc-addr 0.0.0.0:4001 \ ---mysql-addr 0.0.0.0:4002 \ ---postgres-addr 0.0.0.0:4003 -``` - ## Basic Example - [schema](examples/schema/main.go) @@ -67,46 +56,40 @@ stream, err := client.NewStreamClient(cfg) #### Insert & StreamInsert -streaming insert is to Send data into GreptimeDB without waiting for response. +- you can Insert data into GreptimeDB via: + - [define schema](#with-schema-predefined) + - [define struct](#with-struct-tag) +- streaming insert is to Send data into GreptimeDB without waiting for response. ##### Datatypes supported -###### Go - -- int, int8, int16, int32, int64 -- uint, uint8, uint16, uint32, uint64 -- float32, float64 -- bool -- string -- []byte, []uint8, [N]byte, [N]uint8 -- time.Time - -###### GreptimeDB - -- INT, INT8, INT16, INT32, INT64 -- UINT, UINT8, UINT16, UINT32, UINT64 -- FLOAT, FLOAT32, FLOAT64 -- BOOL, BOOLEAN -- STRING -- BINARY, BYTES -- DATE // the day elapsed since January 1, 1970. -- DATETIME // the milliseconds elapsed since January 1, 1970. -- TIMESTAMP -- TIMESTAMP_SECOND -- TIMESTAMP_MILLISECOND -- TIMESTAMP_MICROSECOND -- TIMESTAMP_NANOSECOND - -NOTE: the following are the same - -- INT, INT64 -- UINT, UINT64 -- FLOAT, FLOAT64 -- BOOL, BOOLEAN -- BINARY, BYTES -- TIMESTAMP, TIMESTAMP_MILLISECOND - -##### With Schema predefined explicitly +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 ###### define table schema, and add rows @@ -134,7 +117,7 @@ resp, err := cli.Write(context.Background(), tbl) err := streamClient.Send(context.Background(), tbl) ``` -##### With Schema defined in struct Tag +##### With Struct Tag ###### Tag diff --git a/examples/schema/README.md b/examples/schema/README.md new file mode 100644 index 0000000..0a33aa3 --- /dev/null +++ b/examples/schema/README.md @@ -0,0 +1,56 @@ +# Insert data into GreptimeDB + +## start GreptimeDB via Docker + +```shell +docker run --rm -p 4000-4003:4000-4003 \ +--name greptime greptime/greptimedb standalone start \ +--http-addr 0.0.0.0:4000 \ +--rpc-addr 0.0.0.0:4001 \ +--mysql-addr 0.0.0.0:4002 \ +--postgres-addr 0.0.0.0:4003 +``` + +## Insert + +```go +go run main.go +``` + +Output: + +```log +2024/02/07 11:26:26 affected rows: 2 +``` + +## Query + +```shell +mysql -h 127.0.0.1 -P 4002 public +``` + +```shell +Reading table information for completion of table and column names +You can turn off this feature to get a quicker startup with -A + +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 8 +Server version: 5.1.10-alpha-msql-proxy Greptime + +Copyright (c) 2000, 2023, Oracle and/or its affiliates. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> select * from monitors_with_schema; ++------+-------+-------------+----------------------------+ +| id | host | temperature | timestamp | ++------+-------+-------------+----------------------------+ +| 1 | hello | 1.1 | 2024-02-07 03:26:26.467898 | +| 2 | hello | 2.2 | 2024-02-07 03:26:26.467900 | ++------+-------+-------------+----------------------------+ +2 rows in set (0.03 sec) +``` diff --git a/examples/schema/main.go b/examples/schema/main.go index 04fa319..c293ef8 100644 --- a/examples/schema/main.go +++ b/examples/schema/main.go @@ -35,13 +35,13 @@ func init() { cli_, err := client.New(cfg) if err != nil { - log.Fatal(err) + log.Panic(err) } cli = cli_ stream_, err := client.NewStreamClient(cfg) if err != nil { - log.Fatal(err) + log.Panic(err) } stream = stream_ } @@ -49,42 +49,41 @@ func init() { func main() { tbl, err := table.New("monitors_with_schema") if err != nil { - log.Fatal(err) + log.Println(err) } // add column at first. This is to define the schema of the table. if err := tbl.AddTagColumn("id", types.INT64); err != nil { - log.Fatal(err) + log.Println(err) } if err := tbl.AddFieldColumn("host", types.STRING); err != nil { - log.Fatal(err) + log.Println(err) } if err := tbl.AddFieldColumn("temperature", types.FLOAT); err != nil { - log.Fatal(err) + log.Println(err) } if err := tbl.AddTimestampColumn("timestamp", types.TIMESTAMP_MICROSECOND); err != nil { - log.Fatal(err) + log.Println(err) } if err := tbl.AddRow(1, "hello", 1.1, time.Now()); err != nil { - log.Fatal(err) + log.Println(err) } if err := tbl.AddRow(2, "hello", 2.2, time.Now()); err != nil { - log.Fatal(err) + log.Println(err) } { // client write data into GreptimeDB resp, err := cli.Write(context.Background(), tbl) if err != nil { - log.Fatal(err) + log.Println(err) } log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue()) } { // stream client send data into GreptimeDB - err := stream.Send(context.Background(), tbl) - if err != nil { - log.Fatal(err) + if err := stream.Send(context.Background(), tbl); err != nil { + log.Println(err) } } diff --git a/examples/tag/README.md b/examples/tag/README.md new file mode 100644 index 0000000..947f775 --- /dev/null +++ b/examples/tag/README.md @@ -0,0 +1,56 @@ +# Insert data into GreptimeDB + +## start GreptimeDB via Docker + +```shell +docker run --rm -p 4000-4003:4000-4003 \ +--name greptime greptime/greptimedb standalone start \ +--http-addr 0.0.0.0:4000 \ +--rpc-addr 0.0.0.0:4001 \ +--mysql-addr 0.0.0.0:4002 \ +--postgres-addr 0.0.0.0:4003 +``` + +## Insert + +```go +go run main.go +``` + +Output: + +```log +2024/02/07 11:26:26 affected rows: 2 +``` + +## Query + +```shell +mysql -h 127.0.0.1 -P 4002 public +``` + +```shell +Reading table information for completion of table and column names +You can turn off this feature to get a quicker startup with -A + +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 8 +Server version: 5.1.10-alpha-msql-proxy Greptime + +Copyright (c) 2000, 2023, Oracle and/or its affiliates. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> select * from monitors_with_tag; ++------+-----------+--------+------+-------------+---------+----------------------------+ +| id | host | memory | cpu | temperature | running | ts | ++------+-----------+--------+------+-------------+---------+----------------------------+ +| 1 | 127.0.0.1 | 1 | 1 | -1 | 1 | 2024-02-07 03:29:31.625000 | +| 2 | 127.0.0.2 | 2 | 2 | -2 | 1 | 2024-02-07 03:29:31.625000 | ++------+-----------+--------+------+-------------+---------+----------------------------+ +2 rows in set (0.01 sec) +``` diff --git a/examples/tag/main.go b/examples/tag/main.go index 5ceaeb2..5cd5841 100644 --- a/examples/tag/main.go +++ b/examples/tag/main.go @@ -33,13 +33,13 @@ func init() { cli_, err := client.New(cfg) if err != nil { - log.Fatal(err) + log.Panic(err) } cli = cli_ stream_, err := client.NewStreamClient(cfg) if err != nil { - log.Fatal(err) + log.Panic(err) } stream = stream_ } @@ -59,7 +59,6 @@ func (Monitor) TableName() string { } func main() { - monitors := []Monitor{ { ID: 1, @@ -82,17 +81,16 @@ func main() { } { // client write data into GreptimeDB - _, err := cli.Create(context.Background(), monitors) + resp, err := cli.Create(context.Background(), monitors) if err != nil { log.Fatal(err) } + log.Printf("affected rows: %d\n", resp.GetAffectedRows().GetValue()) } { // stream client send data into GreptimeDB - err := stream.Create(context.Background(), monitors) - if err != nil { + if err := stream.Create(context.Background(), monitors); err != nil { log.Fatal(err) } } - }