Skip to content

Commit

Permalink
docs: Update and cleanup READMEs and examples (#72)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jstirnaman
jstirnaman authored Apr 4, 2024
1 parent 5bbcc4a commit f9d4c3e
Show file tree
Hide file tree
Showing 4 changed files with 257 additions and 86 deletions.
276 changes: 221 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,59 +25,50 @@
</a>
</p>

# InfluxDB 3 Go Client
# InfluxDB v3 Go client

The go package that provides an easy and convenient way to interact with InfluxDB 3.
This package supports both writing data to InfluxDB and querying data using the FlightSQL client,
which allows you to execute SQL queries against InfluxDB IOx.
The `influxdb3` Go package provides an easy and convenient way to interact with [InfluxDB v3](https://www.influxdata.com/get-influxdb/), the time series data platform designed to handle high write and query workloads.

## Installation
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](https://arrow.apache.org/docs/format/Columnar.html#format-ipc) using InfluxDB's native Flight RPC API.

Add the latest version of the client package to your project dependencies:
## Prerequisites

```sh
go get github.com/InfluxCommunity/influxdb3-go
```
### InfluxDB v3 credentials

## Usage
To use this client, you'll need the following credentials for writing and querying data in an InfluxDB v3 instance.

Client can be instantiated using
- 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.

* `influxb3.ClientConfig`
* environment variables
* connection string
## Install the package

### Environment variables
### In a Go module

Set environment variables:
1. In your terminal, create a module for your project--for example:

* `INFLUX_URL` region of your influxdb cloud e.g. *`https://us-east-1-1.aws.cloud2.influxdata.com/`*
* `INFLUX_TOKEN` read/write token generated in cloud
* `INFLUX_DATABASE` name of database e.g .*`my-database`*
```sh
go mod init iot-starter && cd $_
```

<details>
<summary>linux/macos</summary>
2. Install the latest version of the InfluxDB client:

```sh
export INFLUX_URL="<url>"
export INFLUX_TOKEN="<token>"
export INFLUX_DATABASE="<database>"
```
<!--pytest-codeblocks:cont-->

</details>
```sh
go get github.com/InfluxCommunity/influxdb3-go
```

<details>
<summary>windows</summary>
### Outside a module (standalone)

```powershell
setx INFLUX_URL "<url>"
setx INFLUX_TOKEN "<token>"
setx INFLUX_DATABASE "<database>"
```sh
go install github.com/InfluxCommunity/influxdb3-go@latest
```

</details>
## Usage

To get started with influxdb client import `influxdb3-go` package.
In a Go file, import the `influxdb3` package to use it in your code--for example:

```go
import (
Expand All @@ -90,13 +81,105 @@ import (
)
```

Create `influxdb3.Client` with `New` function. Make sure to `Close` the client at the end.
### 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-configuration-object)
- [Instantiate using a connection string](#instantiate-using-a-connection-string)
- [Instantiate using environment variables](#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](#influxdb-v3-credentials)--for example:

```go
// 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](#influxdb-v3-credentials):

- `https://cluster.influxdata.io/`: your InfluxDB host URL
- `DATABASE_TOKEN`: your InfluxDB database token or API token with read/write permission
- `DATABASE_NAME`: the name of your InfluxDB database or bucket
Alternatively, you can use `WriteOptions` or `QueryOptions` 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:

```go
// Instantiate the client.
client, err := influxdb3.NewFromConnectionString(
"https://cluster.influxdata.io/?token=DATABASE_TOKEN&database=DATABASE_NAME"
)
```

Replace the following with your own [credentials](#influxdb-v3-credentials):

- `https://cluster.influxdata.io/`: your InfluxDB host URL
- `DATABASE_TOKEN`: your InfluxDB database token or API token with read/write permission
- `DATABASE_NAME`: the name of your InfluxDB database or bucket
Alternatively, you can use `WriteOptions` or `QueryOptions` to specify the database name.

### Instantiate using environment variables

1. Set the following environment variables to store your InfluxDB credentials:

<details>
<summary>linux/macos</summary>

```sh
export INFLUX_URL="https://cluster.influxdata.io/"
export INFLUX_TOKEN="DATABASE_TOKEN"
export INFLUX_DATABASE="DATABASE_NAME"
```

</details>

<details>
<summary>windows</summary>

```powershell
setx INFLUX_URL "https://cluster.influxdata.io/"
setx INFLUX_TOKEN "DATABASE_TOKEN"
setx INFLUX_DATABASE "DATABASE_NAME"
```

</details>

Replace the following with your own [credentials](#influxdb-v3-credentials):

- `https://cluster.influxdata.io/`: your InfluxDB host URL
- `DATABASE_TOKEN`: your InfluxDB database token or API token with read/write permission
- `DATABASE_NAME`: the name of your InfluxDB database or bucket
Alternatively, you can use `WriteOptions` or `QueryOptions` to specify the database name.

2. Call `influxdb3.Client.NewFromEnv()` to instantiate a client using the environment variables.

```go
// 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:

```go
// Create a new client using INFLUX_* environment variables
client, err := influxdb3.New()
// Create a new client using INFLUX_* environment variables.
client, err := influxdb3.NewFromEnv()

// Close client at the end and escalate an error if occurs
// Close the client when finished.
// Go calls the `defer` function before exiting.
defer func () {
err := client.Close()
if err != nil {
Expand All @@ -107,14 +190,21 @@ defer func () {

### Write data

The `client` can insert data using [line-protocol](https://docs.influxdata.com/influxdb/cloud-serverless/reference/syntax/line-protocol/):
You can provide data to the `influxdb3` as [line protocol](https://docs.influxdata.com/influxdb/cloud-serverless/reference/syntax/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:

```go
line := "stat,location=Paris temperature=23.5,humidity=45i"
err = client.Write(context.Background(), []byte(line))
```

The `client` can also write points
#### Using a `Point`

You can build data as a `Point` and let `influxdb3` convert it to line protocol--for example:

```go
p1 := influxdb3.Point{
Expand All @@ -133,7 +223,9 @@ points := []*influxdb3.Point{p1}
err = client.WritePoints(context.Background(), points)
```

and/or annotated structs
#### Using an annotated struct

You can build data as a `struct` and let `influxdb3` convert it to line protocol--for example:

```go
s1 := struct {
Expand All @@ -157,23 +249,29 @@ err = client.WriteData(context.Background(), data)

### Query

Use FlightSQL to query and print result.
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:

```go
// Query using SQL.
query := `
SELECT *
FROM stat
WHERE
time >= now() - interval '5 minute'
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()

Expand All @@ -182,43 +280,111 @@ for iterator.Next() {
}
```

Queries can be parameterized:
To query with InfluxQL, call the `Query()` function and specify the `influxdb3.WithQueryType(influxdb3.InfluxQL)` option--for example:

```go
// Query using InfluxQL.
query := `
SELECT *
FROM stat
WHERE
time >= now() - interval '5 minute'
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

```go
// 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 result
// Process the result.
```

#### Parameterized query with InfluxQL

When using InfluxQL, pass the `influxdb3.WithQueryType(influxdb3.InfluxQL)` option.

```go
// 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.
```

## Examples
For more information, see the [InfluxDB documentation](https://docs.influxdata.com/).

## Run examples

See the [`examples` folder](./examples/README.md) for complete code examples that you can run.

To run the examples, do the following:

1. Follow instructions to [Install in a Go module](#install-in-a-go-module).
2. Clone this repository.
3. Change to the [`examples`](./examples/README.md) folder.
4. [Set environment variables](#instantiate-using-environment-variables) or edit the example file to [instantiate a client with your credentials](#instantiate-a-client-with-influxdb-credentials).
5. Run the Go file--for example, in your terminal:

Prepare environment like in [Usage](#usage) and check ['examples'](./examples/README.md) folder.
```sh
go run ./IOx/iox.go
```

## Feedback

If you need help, please use our [Community Slack](https://app.slack.com/huddle/TH8RGQX5Z/C02UDUPLQKA)
For help, please use our [Community Slack](https://app.slack.com/huddle/TH8RGQX5Z/C02UDUPLQKA)
or [Community Page](https://community.influxdata.com/).

New features and bugs can be reported on GitHub: <https://github.com/InfluxCommunity/influxdb3-go>
Submit bugs or issues to the repository on GitHub: <https://github.com/InfluxCommunity/influxdb3-go>

## Contribution

If you would like to contribute code you can do through GitHub by forking the repository and sending a pull request into
the `main` branch.
To contribute to this project, fork the repository on GitHub and send a pull request to the `main` branch.

## License

The InfluxDB 3 Go Client is released under the [MIT License](https://opensource.org/licenses/MIT).
which allows you to execute SQL queries on InfluxDB IOx.
The InfluxDB v3 Go Client is released under the [MIT License](https://opensource.org/licenses/MIT)
Loading

0 comments on commit f9d4c3e

Please sign in to comment.