feat: respect iox::column_type::field metadata when mapping query r…

…esults into values

CHANGELOG.md

@@ -1,4 +1,20 @@
-## 0.15.0 [unreleased]
+## 1.0.0 [unreleased]
+
+### Breaking Changes
+
+:warning: **This is a breaking change release.**
+
+> Previously, the Query API did not respect the metadata type for columns returned from InfluxDB v3. This release fixes this issue. As a result, the type of some columns may differ from previous versions. For example, the timestamp column will now be `time.Time` instead of `arrow.Timestamp`.
+
+### Features
+
+1. [#114](https://github.com/InfluxCommunity/influxdb3-go/pull/114): Query API respects metadata types for columns returned from InfluxDB v3.
+   Tags are mapped as a "string", timestamp as "time.Time", and fields as their respective types:
+    - iox::column_type::field::integer: => int64
+    - iox::column_type::field::uinteger: => uint64
+    - iox::column_type::field::float: => float64
+    - iox::column_type::field::string: => string
+    - iox::column_type::field::boolean: => bool
 
 ## 0.14.0 [2024-11-11]
 

README.md

@@ -251,7 +251,9 @@ err = client.WriteData(context.Background(), data)
 
 ### Query
 
-Use SQL or InfluxQL to query an InfluxDB v3 database or (Cloud Serverless) bucket and retrieve data in Arrow Columnar format.
+Use SQL or InfluxQL to query an InfluxDB v3 database or Cloud Serverless bucket to retrieve data.
+The client can return query results in the following formats: structured `PointValues` object, key-value pairs, or Arrow Columnar Format.
+
 By default, the client sends the query as SQL.
 
 `influxdb3` provides an iterator for processing data rows--for example:
@@ -275,6 +277,8 @@ if err != nil {
 
 // Process the result.
 for iterator.Next() {
+    // The query iterator returns each row as a map[string]interface{}.
+    // The keys are the column names, allowing you to access the values by column name.
     value := iterator.Value()
 
     fmt.Printf("temperature in Paris is %f\n", value["temperature"])

examples/Basic/basic.go

@@ -100,6 +100,8 @@ func main() {
 		panic(err)
 	}
 	for iterator.Next() {
+		// The query iterator returns each row as a map[string]interface{}.
+		// The keys are the column names, allowing you to access the values by column name.
 		value := iterator.Value()
 		fmt.Printf("%s at %v:\n", value["location"],
 			(value["time"].(arrow.Timestamp)).ToTime(arrow.Nanosecond).Format(time.RFC822))

examples/README.md

@@ -1,6 +1,6 @@
 # Examples
 
-- [Write and query data](Basic/basic.go) - A complete Go example that demonstrates the different ways of writing data, and then queries your data stored in InfluxDB v3 (formerly InfluxDB IOx).
+- [Write and query data](Basic/basic.go) - A complete Go example that demonstrates the different ways of writing data, and then queries your data stored in InfluxDB v3.
 - [Downsampling](Downsampling/downsampling.go) - A complete Go example that uses a downsampling query and then writes downsampled data back to a different table.
 - [HTTP Error Handling](HTTPErrorHandled/httpErrorHandled.go) - A complete Go example for reading HTTP headers in case of an server error occurs.
 - [Batching write](Batching/batching.go) - A complete Go example that demonstrates how to write Point data in batches.

influxdb3/client_e2e_test.go

@@ -39,7 +39,6 @@ import (
 
 	"github.com/InfluxCommunity/influxdb3-go/influxdb3"
 	"github.com/InfluxCommunity/influxdb3-go/influxdb3/batching"
-	"github.com/apache/arrow/go/v15/arrow"
 	"github.com/influxdata/line-protocol/v2/lineprotocol"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -138,7 +137,7 @@ func TestWriteAndQueryExample(t *testing.T) {
 	assert.Equal(t, uint64(800), value["uindex"])
 	assert.Equal(t, true, value["valid"])
 	assert.Equal(t, "a1", value["text"])
-	assert.Equal(t, now, value["time"].(arrow.Timestamp).ToTime(arrow.Nanosecond))
+	assert.Equal(t, now, value["time"])
 
 	// row #2
 
@@ -151,7 +150,7 @@ func TestWriteAndQueryExample(t *testing.T) {
 	assert.Equal(t, uint64(150), value["uindex"])
 	assert.Equal(t, false, value["valid"])
 	assert.Equal(t, "b1", value["text"])
-	assert.Equal(t, now.Add(1*time.Second), value["time"].(arrow.Timestamp).ToTime(arrow.Nanosecond))
+	assert.Equal(t, now.Add(1*time.Second), value["time"])
 
 	assert.False(t, iterator.Done())
 
@@ -233,7 +232,7 @@ func TestQueryWithParameters(t *testing.T) {
 	assert.Equal(t, uint64(800), value["uindex"])
 	assert.Equal(t, true, value["valid"])
 	assert.Equal(t, "a1", value["text"])
-	assert.Equal(t, now, value["time"].(arrow.Timestamp).ToTime(arrow.Nanosecond))
+	assert.Equal(t, now, value["time"])
 
 	assert.False(t, iterator.Done())
 	assert.False(t, iterator.Next())

influxdb3/query.go

@@ -74,42 +74,42 @@ func (c *Client) setQueryClient(flightClient flight.Client) {
 // QueryParameters is a type for query parameters.
 type QueryParameters = map[string]any
 
-// Query queries data from InfluxDB IOx.
+// Query queries data from InfluxDB v3.
 // Parameters:
 //   - ctx: The context.Context to use for the request.
 //   - query: The query string to execute.
 //   - options: The optional query options. See QueryOption for available options.
 //
 // Returns:
-//   - A custom iterator (*QueryIterator).
+//   - A result iterator (*QueryIterator).
 //   - An error, if any.
 func (c *Client) Query(ctx context.Context, query string, options ...QueryOption) (*QueryIterator, error) {
 	return c.query(ctx, query, nil, newQueryOptions(&DefaultQueryOptions, options))
 }
 
-// QueryWithParameters queries data from InfluxDB IOx with parameterized query.
+// QueryWithParameters queries data from InfluxDB v3 with parameterized query.
 // Parameters:
 //   - ctx: The context.Context to use for the request.
 //   - query: The query string to execute.
 //   - parameters: The query parameters.
 //   - options: The optional query options. See QueryOption for available options.
 //
 // Returns:
-//   - A custom iterator (*QueryIterator).
+//   - A result iterator (*QueryIterator).
 //   - An error, if any.
 func (c *Client) QueryWithParameters(ctx context.Context, query string, parameters QueryParameters,
 	options ...QueryOption) (*QueryIterator, error) {
 	return c.query(ctx, query, parameters, newQueryOptions(&DefaultQueryOptions, options))
 }
 
-// QueryWithOptions Query data from InfluxDB IOx with query options.
+// QueryWithOptions Query data from InfluxDB v3 with query options.
 // Parameters:
 //   - ctx: The context.Context to use for the request.
 //   - options: Query options (query type, optional database).
 //   - query: The query string to execute.
 //
 // Returns:
-//   - A custom iterator (*QueryIterator) that can also be used to get raw flightsql reader.
+//   - A result iterator (*QueryIterator).
 //   - An error, if any.
 //
 // Deprecated: use Query with variadic QueryOption options.