feat: helper function to constrain column type

client_test.go

@@ -378,25 +378,49 @@ func TestDataTypes(t *testing.T) {
 	metric.SetTimestampAlias("time_v")
 
 	series := Series{}
-	series.AddTag("int64_v", data.int64V)
-	series.AddTag("int32_v", data.int32V)
-	series.AddTag("int16_v", data.int16V)
-	series.AddTag("int8_v", data.int8V)
-	series.AddTag("int_v", data.intV)
-
-	series.AddTag("uint64_v", data.uint64V)
-	series.AddField("uint32_v", data.uint32V)
-	series.AddField("uint16_v", data.uint16V)
-	series.AddField("uint8_v", data.uint8V)
-	series.AddField("uint_v", data.uintV)
-
-	series.AddField("float64_v", data.float64V)
-	series.AddField("float32_v", data.float32V)
-
-	series.AddField("string_v", data.stringV)
-	series.AddField("byte_v", data.byteV)
-	series.AddField("bool_v", data.boolV)
-	series.SetTimestamp(data.timeV)
+	// int
+	assert.Nil(t, series.AddIntTag("int64_v_tag", data.int64V))
+	assert.Nil(t, series.AddTag("int32_v_tag", data.int32V))
+	assert.Nil(t, series.AddTag("int16_v_tag", data.int16V))
+	assert.Nil(t, series.AddTag("int8_v_tag", data.int8V))
+	assert.Nil(t, series.AddTag("int_v_tag", data.intV))
+	assert.Nil(t, series.AddIntField("int64_v_field", data.int64V))
+	assert.Nil(t, series.AddField("int32_v_field", data.int32V))
+	assert.Nil(t, series.AddField("int16_v_field", data.int16V))
+	assert.Nil(t, series.AddField("int8_v_field", data.int8V))
+	assert.Nil(t, series.AddField("int_v_field", data.intV))
+
+	// uint
+	assert.Nil(t, series.AddUintTag("uint64_v_tag", data.uint64V))
+	assert.Nil(t, series.AddTag("uint32_v_tag", data.uint32V))
+	assert.Nil(t, series.AddTag("uint16_v_tag", data.uint16V))
+	assert.Nil(t, series.AddTag("uint8_v_tag", data.uint8V))
+	assert.Nil(t, series.AddTag("uint_v_tag", data.uintV))
+	assert.Nil(t, series.AddUintField("uint64_v_field", data.uint64V))
+	assert.Nil(t, series.AddField("uint32_v_field", data.uint32V))
+	assert.Nil(t, series.AddField("uint16_v_field", data.uint16V))
+	assert.Nil(t, series.AddField("uint8_v_field", data.uint8V))
+	assert.Nil(t, series.AddField("uint_v_field", data.uintV))
+
+	// float
+	assert.Nil(t, series.AddFloatTag("float64_v_tag", data.float64V))
+	assert.Nil(t, series.AddTag("float32_v_tag", data.float32V))
+	assert.Nil(t, series.AddFloatField("float64_v_field", data.float64V))
+	assert.Nil(t, series.AddField("float32_v_field", data.float32V))
+
+	// string
+	assert.Nil(t, series.AddStringTag("string_v_tag", data.stringV))
+	assert.Nil(t, series.AddStringField("string_v_field", data.stringV))
+
+	// bytes
+	assert.Nil(t, series.AddBytesTag("byte_v_tag", data.byteV))
+	assert.Nil(t, series.AddBytesField("byte_v_field", data.byteV))
+
+	// bool
+	assert.Nil(t, series.AddBoolTag("bool_v_tag", data.boolV))
+	assert.Nil(t, series.AddBoolField("bool_v_field", data.boolV))
+
+	assert.Nil(t, series.SetTimestamp(data.timeV))
 	metric.AddSeries(series)
 
 	req := InsertRequest{}
@@ -415,36 +439,84 @@ func TestDataTypes(t *testing.T) {
 	assert.Equal(t, 1, len(resMetric.GetSeries()))
 
 	series = resMetric.GetSeries()[0]
-	int64V, ok := series.GetInt("int64_v")
+	// int
+	int64V, ok := series.GetInt("int64_v_tag")
 	assert.True(t, ok)
-	int32V, ok := series.GetInt("int32_v")
+	int32V, ok := series.GetInt("int32_v_tag")
 	assert.True(t, ok)
-	int16V, ok := series.GetInt("int16_v")
+	int16V, ok := series.GetInt("int16_v_tag")
 	assert.True(t, ok)
-	int8V, ok := series.GetInt("int8_v")
+	int8V, ok := series.GetInt("int8_v_tag")
 	assert.True(t, ok)
-	intV, ok := series.GetInt("int_v")
+	intV, ok := series.GetInt("int_v_tag")
 	assert.True(t, ok)
-	uint64V, ok := series.GetUint("uint64_v")
+
+	_, ok = series.GetInt("int64_v_field")
+	assert.True(t, ok)
+	_, ok = series.GetInt("int32_v_field")
+	assert.True(t, ok)
+	_, ok = series.GetInt("int16_v_field")
+	assert.True(t, ok)
+	_, ok = series.GetInt("int8_v_field")
+	assert.True(t, ok)
+	_, ok = series.GetInt("int_v_field")
+	assert.True(t, ok)
+
+	// uint
+	uint64V, ok := series.GetUint("uint64_v_tag")
 	assert.True(t, ok)
-	uint32V, ok := series.GetUint("uint32_v")
+	uint32V, ok := series.GetUint("uint32_v_tag")
 	assert.True(t, ok)
-	uint16V, ok := series.GetUint("uint16_v")
+	uint16V, ok := series.GetUint("uint16_v_tag")
 	assert.True(t, ok)
-	uint8V, ok := series.GetUint("uint8_v")
+	uint8V, ok := series.GetUint("uint8_v_tag")
 	assert.True(t, ok)
-	uintV, ok := series.GetUint("uint_v")
+	uintV, ok := series.GetUint("uint_v_tag")
 	assert.True(t, ok)
-	float64V, ok := series.GetFloat("float64_v")
+
+	_, ok = series.GetUint("uint64_v_field")
+	assert.True(t, ok)
+	_, ok = series.GetUint("uint32_v_field")
 	assert.True(t, ok)
-	float32V, ok := series.GetFloat("float32_v")
+	_, ok = series.GetUint("uint16_v_field")
 	assert.True(t, ok)
-	stringV, ok := series.GetString("string_v")
+	_, ok = series.GetUint("uint8_v_field")
 	assert.True(t, ok)
-	byteV, ok := series.GetBytes("byte_v")
+	_, ok = series.GetUint("uint_v_field")
+	assert.True(t, ok)
+
+	// float
+	float64V, ok := series.GetFloat("float64_v_tag")
+	assert.True(t, ok)
+	float32V, ok := series.GetFloat("float32_v_tag")
+	assert.True(t, ok)
+
+	_, ok = series.GetFloat("float64_v_field")
 	assert.True(t, ok)
-	boolV, ok := series.GetBool("bool_v")
+	_, ok = series.GetFloat("float32_v_field")
 	assert.True(t, ok)
+
+	// string
+	stringV, ok := series.GetString("string_v_tag")
+	assert.True(t, ok)
+
+	_, ok = series.GetString("string_v_field")
+	assert.True(t, ok)
+
+	// bytes
+	byteV, ok := series.GetBytes("byte_v_tag")
+	assert.True(t, ok)
+
+	_, ok = series.GetBytes("byte_v_field")
+	assert.True(t, ok)
+
+	// bool
+	boolV, ok := series.GetBool("bool_v_tag")
+	assert.True(t, ok)
+
+	_, ok = series.GetBool("bool_v_field")
+	assert.True(t, ok)
+
 	timeV := series.GetTimestamp()
 
 	querydata := datatype{

doc.go

@@ -1,6 +1,34 @@
 // Package greptime provides API for using GreptimeDB client in Go.
 //
+// # Basic Insert and Query
+//
 // call [NewClient] with [Config] to init a concurrent safe [Client], and
 // prepare rows of data by [Metric] and [Series], call [Client.Insert] to insert
-// metric into greptimedb, and call [Client.Query] to retrieve data from greptimedb.
+// [InsertRequest] into greptimedb, and call [Client.Query] to retrieve data from
+// greptimedb via [QueryRequest].
+//
+// # Series
+//
+// You don't need to create the table, it will be created automatically via [Series] fields.
+// What you have to know about [Series] in advance:
+//
+//   - Tag is like index, it helps you to retrive data more efficiently
+//   - Field is like value, it can be used to analyze, calculate, aggregate, etc,.
+//   - Timestamp is required for timeseries data
+//
+// Once the schema is created automatically, it can not be changed by [Client], it
+// will fail if the column type does not match
+//
+// # Metric
+//
+// [Metric] is like multiple [Series], it will check if all of the [Series] are valid:
+//
+//   - the same column name in different series: data type MUST BE the same
+//   - Tag and Field MUST NOT contain the same column name
+//   - timestamp MUST NOT BE empty
+//
+// Also, [Metric] can set:
+//
+//   - [Metric.SetTimePrecision]
+//   - [Metric.SetTimestampAlias]
 package greptime

doc_test.go

@@ -9,17 +9,6 @@ import (
 	"google.golang.org/grpc/credentials/insecure"
 )
 
-type Monitor struct {
-	host   string
-	cpu    float64
-	memory int64
-	ts     time.Time
-}
-
-func (m Monitor) String() string {
-	return fmt.Sprintf("{%s,%.2f,%d}", m.host, m.cpu, m.memory)
-}
-
 func Example() {
 	// leave `addr`, `database`, `username`, `password` untouched in local machine,
 	// but in GreptimeCloud you need to create a service in advance
@@ -48,11 +37,11 @@ func Example() {
 	}
 
 	// inserting
-	series := Series{}                 // Create one row of data
-	series.AddTag("host", "localhost") // add index column, for query efficiency
-	series.AddField("cpu", 0.90)       // add value column
-	series.AddField("memory", 1024)    // add value column
-	series.SetTimestamp(time.Now())    // requird
+	series := Series{}                       // Create one row of data
+	series.AddStringTag("host", "localhost") // add index column, for query efficiency
+	series.AddFloatField("cpu", 0.90)        // add value column
+	series.AddIntField("memory", 1024)       // add value column
+	series.SetTimestamp(time.Now())          // requird
 
 	metric := Metric{} // Create a Metric and add the Series
 	metric.AddSeries(series)
@@ -83,18 +72,24 @@ func Example() {
 		return
 	}
 
+	type Monitor struct {
+		host   string
+		cpu    float64
+		memory int64
+		ts     time.Time
+	}
+
 	monitors := []Monitor{}
 	for _, series := range resMetric.GetSeries() {
 		one := &Monitor{}
 		host, exist := series.Get("host") // you can directly call Get and do the type assertion
 		if exist {
 			one.host = host.(string)
 		}
-		one.cpu, _ = series.GetFloat("cpu")     // you can directly GetFloat
-		one.memory, _ = series.GetInt("memory") // you can directly GetInt
+		one.cpu, _ = series.GetFloat("cpu")     // also, you can directly GetFloat
+		one.memory, _ = series.GetInt("memory") // also, you can directly GetInt
 		one.ts = series.GetTimestamp()          // GetTimestamp
 		monitors = append(monitors, *one)
 	}
-	fmt.Println(len(monitors) == 1)
-	fmt.Println(monitors[0])
+	fmt.Println(monitors)
 }