---
title: Use Go to query data
description: Use the influxdb3-go Go package and SQL or InfluxQL to query data stored in InfluxDB. Execute queries and retrieve data over the Flight+gRPC protocol, and then process data using common Go tools.
url: https://docs.influxdata.com/influxdb3/clustered/query-data/execute-queries/client-libraries/go/
estimated_tokens: 10922
product: InfluxDB Clustered
version: clustered
---

# Use Go to query data

-   InfluxQL
-   SQL

Use the InfluxDB `influxdb3-go` Go client library package and SQL or InfluxQL to query data stored in InfluxDB. Execute queries and retrieve data over the Flight+gRPC protocol, and then process data using common Go tools.

-   [Get started using Go to query InfluxDB](#get-started-using-go-to-query-influxdb)
    -   [Install Go](#install-go)
    -   [Create a Go module directory](#create-a-go-module-directory)
    -   [Install dependencies](#install-dependencies)
    -   [Execute a query](#execute-a-query)
        -   [Query using SQL](#query-using-sql)
        -   [Query using InfluxQL](#query-using-influxql)
    -   [Run the example](#run-the-example)

## Get started using Go to query InfluxDB

The following example shows how to use Go with the `influxdb3-go` module to create a client and query an InfluxDB Clustered database.

### Install Go

Follow the [Go download and installation instructions](https://go.dev/doc/install) to install a recent version of the Go programming language for your system.

### Create a Go module directory

1. Inside of your project directory, create a new module directory and navigate into it.
    
    ```sh
    mkdir influxdb_go_client && cd $_
    ```
    
2. Enter the following command to initialize a new Go module:
    
    ```sh
    go mod init influxdb_go_client
    ```
    

### Install dependencies

In your terminal, enter the following command to download and install the client library:

```sh
go get github.com/InfluxCommunity/influxdb3-go/v2
```

-   [`influxdb3-go`](https://github.com/InfluxCommunity/influxdb3-go) \*: Provides the `influxdb3` package and also installs the [Apache `arrow` module](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries.

With the dependencies installed, you’re ready to query and analyze data stored in an InfluxDB database.

### Execute a query

The following examples show how to create an [InfluxDB client](/influxdb3/clustered/reference/client-libraries/v3/go/#function-new), use client query methods to select all fields in a measurement, and then access query result data and metadata.

In your `influxdb_go_client` module directory, create a file named `query.go` and enter one of the following samples to query using SQL or InfluxQL.

Replace the following configuration values in the sample code:

-   `DATABASE_NAME`: the name of the [database](/influxdb3/clustered/admin/databases/) to query
-   `DATABASE_TOKEN`: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) with *read* permission on the specified database

<!-- Tabbed content: Select one of the following options -->

**SQL:**

#### Query using SQL

```go
// query.go
package main

import (
    "context"
    "fmt"
    "io"
    "os"
    "text/tabwriter"
    "time"

    "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3"
)

func Query() error {

    // Instantiate the client.
    client, err := influxdb3.New(influxdb3.ClientConfig{
        Host:       "https://cluster-host.com",
        Token:      "DATABASE_TOKEN",
        Database:   "DATABASE_NAME",
    })

    defer func(client *influxdb3.Client) {
        err := client.Close()
        if err != nil {
            panic(err)
        }
    }(client)

    query := `SELECT *
        FROM home
        WHERE time >= '2022-01-02T08:00:00Z'
        AND time <= '2022-01-02T20:00:00Z'`

    // Example 1: Query data and then read the schema and all data in the result stream.
    iterator, err := client.Query(context.Background(), query)

    fmt.Fprintln(os.Stdout, "Read all data in the stream:")
    data, err := iterator.Raw().Reader.Read()
    fmt.Fprintln(os.Stdout, data)

    if err != nil {
        panic(err)
    }

    // Example 2: Query data, view the result schema, and then process result data by row.
    iterator2, err = client.Query(context.Background(), query)
    fmt.Fprintln(os.Stdout, "View the query result schema:")
    schema := iterator2.Raw().Reader.Schema()
    fmt.Fprintln(os.Stdout, schema)

    w := tabwriter.NewWriter(io.Discard, 4, 4, 1, ' ', 0)
    w.Init(os.Stdout, 0, 8, 0, '\t', 0)

    fmt.Fprintln(w, "Process each row as key-value pairs:")
    for iterator2.Next() {
        row := iterator2.Value()
        // Use Go time package to format unix timestamp
        // as a time with timezone layout (RFC3339)
        time := (row["time"].(time.Time)).
            Format(time.RFC3339)
        fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n",
            time, row["room"], row["co"], row["hum"], row["temp"])
    }
    w.Flush()
}
```

The sample code does the following:

1. Defines a `main` package for your module and imports packages you’ll use in your code.
2. Defines a `Query()` function.
3. Instantiates the `influxdb3` client with InfluxDB credentials and assigns it to a `client` variable.
4. Defines a deferred function that closes the client when `Query()` has finished executing.
5. Defines an SQL query to execute.
6. Calls the client’s `Query(ctx context.Context, query string)` method and passes the SQL string as the `query` argument. `Query()` returns the following:
    -   `*influxdb3.QueryIterator`: A custom iterator for reading data from the query result stream.
    -   `error`: A Flight request error.

**InfluxQL:**

#### Query using InfluxQL

```go
// query.go

package main

import (
    "context"
    "fmt"
    "io"
    "os"
    "text/tabwriter"
    "time"

    "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3"
)

func InfluxQL() error {

    // Instantiate the client.
    client, err := influxdb3.New(influxdb3.ClientConfig{
        Host:       "https://cluster-host.com",
        Token:      "DATABASE_TOKEN",
        Database:   "DATABASE_NAME",
    })

    defer func(client *influxdb3.Client) {
        err := client.Close()
        if err != nil {
            panic(err)
        }
    }(client)

    query := `SELECT *
        FROM home
        WHERE time >= 1641124000s
        AND time <= 1641124000s + 8h`

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

    // Example 1: Query data and then read the schema and all data in the result stream.
    iterator, err := client.QueryWithOptions(context.Background(), &queryOptions, query)

    fmt.Fprintln(os.Stdout, "Read all data in the stream:")
    data, err := iterator.Raw().Reader.Read()
    fmt.Fprintln(os.Stdout, data)

    if err != nil {
        panic(err)
    }

    // Example 2: Query data, view the result schema, and then process result data row by row.
    iterator2, err = client.QueryWithOptions(context.Background(), &queryOptions, query)

    fmt.Fprintln(os.Stdout, "View the query result schema:")
    schema := iterator2.Raw().Reader.Schema()
    fmt.Fprintln(os.Stdout, schema)

    w := tabwriter.NewWriter(io.Discard, 4, 4, 1, ' ', 0)
    w.Init(os.Stdout, 0, 8, 0, '\t', 0)

    fmt.Fprintln(w, "Process each row as key-value pairs:")
    for iterator2.Next() {
        row := iterator2.Value()
        // Use Go time package to format unix timestamp
        // as a time with timezone layout (RFC3339)
        time := (row["time"].(time.Time)).
            Format(time.RFC3339)
        fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n",
            time, row["room"], row["co"], row["hum"], row["temp"])
    }
    w.Flush()
}
```

The sample code does the following:

1. Defines a `main` package for your module and imports packages you’ll use in your code.
    
2. Defines a `Query()` function.
    
3. Instantiates the `influxdb3` client with InfluxDB credentials and assigns it to a `client` variable.
    
4. Defines a deferred function that closes the client when `Query()` has finished executing.
    
5. Defines an InfluxQL query to execute.
    
6. Calls the following client method:
    
    [`QueryWithOptions(ctx context.Context, options *QueryOptions, query string)`](https://github.com/InfluxCommunity/influxdb3-go/blob/9225231e68ac1b90e8519e7d5d12706e66758041/influxdb3/query.go#L90)
    
    and passes the following arguments:
    
    -   **options**: A `QueryOptions` struct with the `QueryType` property set to `influxdb3.InfluxQL`.
    -   **query**: A string. The SQL or InfluxQL query to execute. `QueryWithOptions` returns the following:
        -   `*influxdb3.QueryIterator`: A custom iterator that provides access to query result data and metadata.
        -   `error`: A Flight request error.

<!-- End tabbed content -->

### Run the example

1. In your `influxdb_go_client` module directory, create a file named `main.go`.
    
2. In `main.go`, enter the following sample code to define a `main()` executable function that calls the `Query()` function:
    
    ```go
    package main
    
    func main() {
      Query()
    }
    ```
    
3. In your terminal, enter the following command to install the necessary packages, build the module, and run the program:
    
    ```sh
    go build && go run influxdb_go_client
    ```
    
    The program executes the `main()` function that writes the data and prints the query results to the console.
    

#### Related

-   [Go client library for InfluxDB 3](/influxdb3/clustered/reference/client-libraries/v3/go/)
-   [SQL reference documentation](/influxdb3/clustered/reference/sql/)
-   [Apache Arrow Flight RPC clients](/influxdb3/clustered/reference/client-libraries/flight/)

[Flight client](/influxdb3/clustered/tags/flight-client/) [query](/influxdb3/clustered/tags/query/) [flight](/influxdb3/clustered/tags/flight/) [go](/influxdb3/clustered/tags/go/) [sql](/influxdb3/clustered/tags/sql/) [influxql](/influxdb3/clustered/tags/influxql/)