Using the Go InfluxDB v3 Client Library

By Anais Dotis-Georgiou / Product
Sep 07, 2023

In this tutorial, we’ll learn how to use the Go InfluxDB v3 Client Library. InfluxDB 3.0 is the latest version of InfluxDB and it comes with significant performance improvements over previous versions. Be sure to check out our latest benchmarks, which include the following highlights:

• InfluxDB 3.0 provides 45x better write throughput over InfluxDB OSS.
• InfluxDB 3.0 has 4.5x better storage compression compared to InfluxDB OSS.
• InfluxDB 3.0 is more efficient for given hardware resources and can reduce storage costs by >90% as compared to InfluxDB OSS.
• InfluxDB 3.0 queries are 2.5-45x faster across a broad range of query types for recent data (5m) as compared to InfluxDB OSS.
• InfluxDB 3.0 queries are 5-25x faster across a broad range of query types for past 1-hour time ranges as compared to InfluxDB OSS.

The Go InfluxDB v3 Client Library is a software package that provides a set of tools and functions for interacting with InfluxDB using the Go programming language. It allows developers to efficiently query and write time series data from/to InfluxDB 3.0, simplifying the integration of InfluxDB into Go applications. Like previous versions of the Go Client Library, v3 implements writes via the /write API endpoint. Queries are a bit different than previous versions because it uses the Apache Arrow Flight Client Libraries and utilizes the Arrow Format and Flight gRPC protocol to provide efficient serialization and deserialization and bidirectional streaming.

Requirements, installation, and initialization

To follow this tutorial you’ll need the following:

• InfluxDB Cloud 3.0 account
• Database Name (also referred to as a Bucket)
• Authentication token

Add the latest version of the client package to your project dependencies (go.mod):

go get github.com/InfluxCommunity/influxdb3-go/influxdb3

To initialize the client you’ll need to import your packages into your main.go file and provide your credentials:

package main.go

import (
	"context"
	"fmt"
	"os"
	"time"

	"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
func main() {
	// Use env variables to initialize client
	url := os.Getenv("INFLUXDB_URL")
	token := os.Getenv("INFLUXDB_TOKEN")
	database := os.Getenv("INFLUXDB_DATABASE")

	// Create a new client using an InfluxDB server base URL and an authentication token
client, err := influxdb3.New(influxdb3.ClientConfig{
    Host: url,
    Token: token,
    Database: database,
})

Write data with the Go InfluxDB v3 Client Library

To write data to InfluxDB, call client.Write with data in line protocol format and the database (or bucket) name. Line protocol is the ingest format for InfluxDB. When writing a line protocol point to InfluxDB, use tags to store metadata in your instance. Fields contain your actual time series values. However, both fields and tags convert to columns in a table in InfluxDB. In practice these columns function the same way in the database, so this distinction is solely for organizational purposes for the user. Data is written synchronously. The following is an example of writing line protocol to InfluxDB:

line := "stat,unit=temperature avg=23.5,max=45.0"
err = client.Write(context.Background(), database, []byte(line))
if err != nil {
		panic(err)
	}

Another approach is to use the client.WritePoints method to write Point objects. You can also append points or line protocol to an array and write an array of points to InfluxDB by passing in the array into the client.WritePoints method.

// Create point using full params constructor
	p := influx.NewPoint("stat",
		map[string]string{"unit": "temperature"},
		map[string]interface{}{"avg": 24.5, "max": 45.0},
		time.Now())
	// write point synchronously
	err = client.WritePoints(context.Background(), database, p)
	if err != nil {
		panic(err)
	}

Important note about upserts

You can upsert a field but not a tag. For example, if you add a second point (notice the addition of “2” to field values) you would upsert those field values and your previous values will be overwritten with the new field values:

# Adding first point
line := "stat,unit=temperature avg=23.5,max=45.0 1690218372000000000"
err = client.Write(context.Background(), database, []byte(line))
if err != nil {
		panic(err)
	}

# Adding second point
line := "stat,unit=temperature avg=23.52,max=45.2 1690218378000000000"
err = client.Write(context.Background(), database, []byte(line))
if err != nil {
		panic(err)

However, if you add a second point (notice the addition of “2” to the tags) you would not upsert those values. You would simply add more tag values.

# Adding first point
line := "stat,unit=temperature avg=23.5,max=45.0 1690218372000000000"
err = client.Write(context.Background(), database, []byte(line))
if err != nil {
		panic(err)
	}

# Adding second point
line := "stat,unit=temperature2 avg=23.52,max=45.2 1690218378000000000"
err = client.Write(context.Background(), database, []byte(line))
if err != nil {
		panic(err)

Query data with the Go InfluxDB v3 Client Library

You can use the Go InfluxDB v3 Client Library to query InfluxDB 3.0 using SQL and InfluxQL (a SQL-like query language for InfluxDB, purpose-built for time series data).

SQL

By default, the client.Query method uses SQL to query InfluxDB. You simply need to construct your SQL query and pass it into the method along with the database you wish to query.

query := `
			SELECT *
			FROM "stat"
			WHERE
			time >= now() - interval '5 minute'
			AND
			"unit" IN ('temperature')
	`

	iterator, err := client.Query(context.Background(), query)

	if err != nil {
		panic(err)
	}

	for iterator.Next() {
		value := iterator.Value()

		fmt.Printf("avg is %f\n", value["avg"])
		fmt.Printf("max is %f\n", value["max"])
	}

InfluxQL

You can use the client.QueryWithOptions method to query InfluxDB using InfluxQL. In this approach, you create options and pass them into the method.

influxQLQuery := "SHOW MEASUREMENTS"

	options := influxdb3.QueryOptions{
		QueryType: influxdb3.InfluxQL,
	}

	iterator, err := client.QueryWithOptions(context.Background(), &options, influxQLQuery)

	if err != nil {
		panic(err)
	}

	for iterator.Next() {
		value := iterator.Value()
		fmt.Printf("measurement is:", value["name"])
	}

Final thoughts

InfluxDB is a great tool for storing all of your time series data. It’s written on top of the Apache Ecosystem and leverages technologies like DataFusion, Arrow, and Parquet to enable efficient writes, storage, and querying. It also offers interoperability with a lot of other tools so you can leverage them for your specific predictive analytics needs. The Go Client Library helps support this interoperability.

Get started with InfluxDB Cloud 3.0 here. If you need any help, please reach out using our community site or Slack channel. I’d love to hear about what you’re trying to achieve and what features you’d like InfluxDB to have.