README ¶
InfluxDB v3 Go client
The influxdb3
Go package provides an easy and convenient way to interact with InfluxDB v3, the time series data platform designed to handle high write and query workloads.
Use this package to write and query data stored in your InfluxDB v3 instance. Query using SQL or InfluxQL and retrieve data in Arrow Columnar Format using InfluxDB's native Flight RPC API.
We also offer this Getting Started: InfluxDB 3.0 Go Client Library video that you can use to learn more about the library and see code examples.
Prerequisites
InfluxDB v3 credentials
To use this client, you'll need the following credentials for writing and querying data in an InfluxDB v3 instance.
- your InfluxDB instance Host URL--for example, your Cloud Serverless region URL
https://us-east-1-1.aws.cloud2.influxdata.com/
. - the name of the database or Cloud Serverless bucket where you want to write or query data.
- your database token or Cloud Serverless API token (generated by your InfluxDB instance) with read/write permission to the specified database.
Install the package
In a Go module
-
In your terminal, create a module for your project--for example:
go mod init iot-starter && cd $_
-
Install the latest version of the InfluxDB client:
go get github.com/InfluxCommunity/influxdb3-go
Outside a module (standalone)
go install github.com/InfluxCommunity/influxdb3-go@latest
Usage
In a Go file, import the influxdb3
package to use it in your code--for example:
import (
"context"
"encoding/json"
"fmt"
"os"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
Instantiate a client with InfluxDB credentials
influxdb3.Client
is the entrypoint for writing or querying data in InfluxDB.
Choose one of the following ways to provide your InfluxDB credentials (URL, token, and database) and instantiate a client:
- Instantiate using a configuration object
- Instantiate using a connection string
- Instantiate using environment variables
Instantiate using a configuration object
Call the influxdb3.New(config influxdb3.ClientConfig)
function with a ClientConfig
struct that contains your credentials--for example:
// Instantiate the client.
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://cluster.influxdata.io/",
Token: "DATABASE_TOKEN",
Database: "DATABASE_NAME",
})
Replace the following with your own credentials:
https://cluster.influxdata.io/
: your InfluxDB host URLDATABASE_TOKEN
: your InfluxDB database token or API token with read/write permissionDATABASE_NAME
: the name of your InfluxDB database or bucket Alternatively, you can useWriteOptions
orQueryOptions
to specify the database name.
Instantiate using a connection string
Call the influxdb3.NewFromConnectionString(connectionString string)
function with a connection string that contains your credentials in URL format--for example:
// Instantiate the client.
client, err := influxdb3.NewFromConnectionString(
"https://cluster.influxdata.io/?token=DATABASE_TOKEN&database=DATABASE_NAME"
)
Replace the following with your own credentials:
https://cluster.influxdata.io/
: your InfluxDB host URLDATABASE_TOKEN
: your InfluxDB database token or API token with read/write permissionDATABASE_NAME
: the name of your InfluxDB database or bucket Alternatively, you can useWriteOptions
orQueryOptions
to specify the database name.
Instantiate using environment variables
-
Set the following environment variables to store your InfluxDB credentials:
linux/macos
export INFLUX_URL="https://cluster.influxdata.io/" export INFLUX_TOKEN="DATABASE_TOKEN" export INFLUX_DATABASE="DATABASE_NAME"
windows
setx INFLUX_URL "https://cluster.influxdata.io/" setx INFLUX_TOKEN "DATABASE_TOKEN" setx INFLUX_DATABASE "DATABASE_NAME"
Replace the following with your own credentials:
https://cluster.influxdata.io/
: your InfluxDB host URLDATABASE_TOKEN
: your InfluxDB database token or API token with read/write permissionDATABASE_NAME
: the name of your InfluxDB database or bucket Alternatively, you can useWriteOptions
orQueryOptions
to specify the database name.
-
Call
influxdb3.Client.NewFromEnv()
to instantiate a client using the environment variables.// Create a new client using INFLUX_* environment variables. client, err := influxdb3.NewFromEnv()
Close the client
In your code, make sure to call client.Close()
when you have finished using the client.
You can use Go's defer
to close the client and raise any errors before your function exits--for example:
// Create a new client using INFLUX_* environment variables.
client, err := influxdb3.NewFromEnv()
// Close the client when finished.
// Go calls the `defer` function before exiting.
defer func () {
err := client.Close()
if err != nil {
panic(err)
}
}()
Write data
You can provide data to the influxdb3
as line protocol, a Point
, or a struct
.
InfluxDB clients write (insert) all data as line protocol to InfluxDB.
Using line protocol
You can provide data as "raw" line protocol--for example:
line := "stat,location=Paris temperature=23.5,humidity=45i"
err = client.Write(context.Background(), []byte(line))
Using a Point
You can build data as a Point
and let influxdb3
convert it to line protocol--for example:
p1 := influxdb3.Point{
influxdb3.NewPoint("stat",
map[string]string{
"location": "Paris",
},
map[string]any{
"temperature": 24.5,
"humidity": 40,
},
time.Now(),
),
}
points := []*influxdb3.Point{p1}
err = client.WritePoints(context.Background(), points)
Using an annotated struct
You can build data as a struct
and let influxdb3
convert it to line protocol--for example:
s1 := struct {
Measurement string `lp:"measurement"`
Sensor string `lp:"tag,location"`
Temp float64 `lp:"field,temperature"`
Hum int `lp:"field,humidity"`
Time time.Time `lp:"timestamp"`
Description string `lp:"-"`
}{
"stat",
"Paris",
23.5,
55,
time.Now(),
"Paris weather conditions",
}
data := []any{s1}
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. By default, the client sends the query as SQL.
influxdb3
provides an iterator for processing data rows--for example:
// Query using SQL.
query := `
SELECT *
FROM stat
WHERE
time >= now() - interval '5 minutes'
AND
location IN ('Paris')
`
iterator, err := client.Query(context.Background(), query)
if err != nil {
panic(err)
}
// Process the result.
for iterator.Next() {
value := iterator.Value()
fmt.Printf("temperature in Paris is %f\n", value["temperature"])
fmt.Printf("humidity in Paris is %d%%\n", value["humidity"])
}
To query with InfluxQL, call the Query()
function and specify the influxdb3.WithQueryType(influxdb3.InfluxQL)
option--for example:
// Query using InfluxQL.
query := `
SELECT *
FROM stat
WHERE
time >= now() - 5m
AND
location IN ('Paris')
`
// Specify the InfluxQL QueryType in options.
iterator, err := client.Query(context.Background(), query, influxdb3.WithQueryType(influxdb3.InfluxQL))
if err != nil {
panic(err)
}
// Process the result.
To use parameterized queries with SQL or InfluxQL,
call the QueryWithParameters()
function and pass the query text and a QueryParameters
struct that defines parameter name-value pairs.
Parameterized query with SQL
// Specify $parameter placeholders in WHERE predicate expressions.
query := `
SELECT *
FROM stat
WHERE
time >= now() - interval '5 minutes'
AND
location = $location
`
// Assign parameter names to values.
parameters := influxdb3.QueryParameters{
"location": "Paris",
}
iterator, err := client.QueryWithParameters(context.Background(), query, parameters)
// Process the result.
Parameterized query with InfluxQL
When using InfluxQL, pass the influxdb3.WithQueryType(influxdb3.InfluxQL)
option.
// Specify $parameter placeholders in WHERE predicate expressions.
query := `
SELECT *
FROM stat
WHERE
time >= now() - '5m'
AND
location = $location
`
// Assign parameter names to values.
parameters := influxdb3.QueryParameters{
"location": "Paris",
}
// Specify the query type for an InfluxQL query.
iterator, err := client.QueryWithParameters(context.Background(), query, parameters,
influxdb3.WithQueryType(influxdb3.InfluxQL))
// Process the result.
For more information, see the InfluxDB documentation.
Run examples
See the examples
folder for complete code examples that you can run.
To run the examples, do the following:
-
Follow instructions to Install in a Go module.
-
Clone this repository.
-
Change to the
examples
folder. -
Set environment variables or edit the example file to instantiate a client with your credentials.
-
Run the Go file--for example, in your terminal:
go run ./IOx/iox.go
Feedback
For help, please use our Community Slack or Community Page.
Submit bugs or issues to the repository on GitHub: https://github.com/InfluxCommunity/influxdb3-go
Contribution
To contribute to this project, fork the repository on GitHub and send a pull request to the main
branch.
License
The InfluxDB v3 Go Client is released under the MIT License
Directories ¶
Path | Synopsis |
---|---|
examples
|
|
Package influxdb3 provides client for InfluxDB server.
|
Package influxdb3 provides client for InfluxDB server. |
batching
Package batching provides a batcher to collect points and emit them as batches.
|
Package batching provides a batcher to collect points and emit them as batches. |
gzip
Package gzip provides GZip related functionality
|
Package gzip provides GZip related functionality |