diff --git a/content/influxdb/cloud-dedicated/get-started/query.md b/content/influxdb/cloud-dedicated/get-started/query.md index eb08cef2c..01aecaa6f 100644 --- a/content/influxdb/cloud-dedicated/get-started/query.md +++ b/content/influxdb/cloud-dedicated/get-started/query.md @@ -4,7 +4,7 @@ seotitle: Query data | Get started with InfluxDB Cloud Dedicated list_title: Query data description: > Get started querying data in InfluxDB Cloud Dedicated by learning about SQL and - InfluxQL, and using tools like InfluxDB client libraries. + InfluxQL, and using tools like the influx3 CLI and InfluxDB client libraries. menu: influxdb_cloud_dedicated: name: Query data @@ -16,7 +16,7 @@ related: - /influxdb/cloud-dedicated/query-data/ - /influxdb/cloud-dedicated/query-data/sql/ - /influxdb/cloud-dedicated/query-data/execute-queries/ - - /influxdb/cloud-dedicated/reference/client-libraries/flight-sql/ + - /influxdb/cloud-dedicated/reference/client-libraries/v3/ --- {{% cloud-name %}} supports multiple query languages: @@ -46,7 +46,7 @@ The examples in this section of the tutorial query the {{< req type="key" text="Covered in this tutorial" color="magenta" >}} - [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req "\* " >}} - [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) -- [Flight clients](?t=Go#execute-an-sql-query){{< req "\* " >}} +- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight/){{< req "\* " >}} - [Superset](/influxdb/cloud-dedicated/query-data/sql/execute-queries/superset/) - [Grafana](/influxdb/cloud-dedicated/query-data/sql/execute-queries/grafana/) - [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/primers/api/v1/#query-using-the-v1-api) @@ -103,6 +103,8 @@ SELECT * FROM home ``` ##### Select all data in a measurement within time bounds + +{{% influxdb/custom-timestamps %}} ```sql SELECT * @@ -112,6 +114,7 @@ WHERE time >= '2022-01-01T08:00:00Z' AND time <= '2022-01-01T20:00:00Z' ``` +{{% /influxdb/custom-timestamps %}} ##### Select a specific field within relative time bounds ```sql @@ -129,6 +132,8 @@ SELECT * FROM home WHERE room = 'Kitchen' ``` ##### Select data based on tag value within time bounds + +{{% influxdb/custom-timestamps %}} ```sql SELECT * @@ -139,8 +144,12 @@ WHERE AND time <= '2022-01-01T20:00:00Z' AND room = 'Living Room' ``` +{{% /influxdb/custom-timestamps %}} + ##### Downsample data by applying interval-based aggregates + +{{% influxdb/custom-timestamps %}} ```sql SELECT DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time, @@ -154,6 +163,7 @@ GROUP BY room ORDER BY room, _time ``` +{{% /influxdb/custom-timestamps %}} ### Execute an SQL query @@ -181,6 +191,12 @@ WHERE ``` {{% /influxdb/custom-timestamps %}} +{{% note %}} +Some examples in this getting started tutorial assume your InfluxDB +credentials (**url**, **organization**, and **token**) are provided by +[environment variables](/influxdb/cloud-dedicated/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials). +{{% /note %}} + {{< tabs-wrapper >}} {{% tabs %}} [influx3 CLI](#influx3-cli) @@ -254,8 +270,8 @@ _If your project's virtual environment is already running, skip to step 3._ {{% tab-content %}} {{% influxdb/custom-timestamps %}} -Use the `influxdb_client_3` module to integrate {{< cloud-name >}} with your Python code. -This module supports writing data to InfluxDB and querying data using SQL or InfluxQL. +Use the `influxdb_client_3` client library module to integrate {{< cloud-name >}} with your Python code. +The client library supports writing data to InfluxDB and querying data using SQL or InfluxQL. The following steps include setting up a Python virtual environment already covered in [Get started writing data](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb). @@ -329,7 +345,7 @@ _If your project's virtual environment is already running, skip to step 3._ - **host**: {{% cloud-name %}} cluster URL (without `https://` protocol or trailing slash) - **token**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with - read access to the **get-started** database. + read access to the specified database. _For security reasons, we recommend setting this as an environment variable rather than including the raw token string._ - **database**: the name of the {{% cloud-name %}} database to query @@ -407,85 +423,58 @@ _If your project's virtual environment is already running, skip to step 3._ import ( "context" - "crypto/x509" - "encoding/json" "fmt" + "io" "os" + "text/tabwriter" - "github.com/apache/arrow/go/v12/arrow/flight/flightsql" - "google.golang.org/grpc" - "google.golang.org/grpc/credentials" - "google.golang.org/grpc/metadata" + "github.com/apache/arrow/go/v12/arrow" + "github.com/InfluxCommunity/influxdb3-go/influx" ) - func dbQuery(ctx context.Context) error { - url := "cluster-id.influxdb.io:443" + func Query() error { - // INFLUX_TOKEN is an environment variable you created for your database READ token + // INFLUX_TOKEN is an environment variable you created for your database read token token := os.Getenv("INFLUX_TOKEN") database := "get-started" - // Create a gRPC transport - pool, err := x509.SystemCertPool() - if err != nil { - return fmt.Errorf("x509: %s", err) - } - transport := grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(pool, "")) - opts := []grpc.DialOption{ - transport, - } + client, err := influx.New(influx.Configs{ + HostURL: "https://cluster-id.influxdb.io", + AuthToken: token, + }) - // Create query client - client, err := flightsql.NewClient(url, nil, nil, opts...) - if err != nil { - return fmt.Errorf("flightsql: %s", err) - } - - ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+token) - ctx = metadata.AppendToOutgoingContext(ctx, "database", database) + defer func (client *influx.Client) { + err := client.Close() + if err != nil { + panic(err) + } + }(client) // Execute query - query := `SELECT - * - FROM - home - WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z'` + query := `SELECT * + FROM home + WHERE time >= '2022-01-02T08:00:00Z' + AND time <= '2022-01-02T20:00:00Z'` + + iterator, err := client.Query(context.Background(), database, query) - info, err := client.Execute(ctx, query) if err != nil { - return fmt.Errorf("flightsql flight info: %s", err) - } - reader, err := client.DoGet(ctx, info.Endpoint[0].Ticket) - if err != nil { - return fmt.Errorf("flightsql do get: %s", err) + panic(err) } - // Print results as JSON - for reader.Next() { - record := reader.Record() - b, err := json.MarshalIndent(record, "", " ") - if err != nil { - return err - } - fmt.Println("RECORD BATCH") - fmt.Println(string(b)) + w := tabwriter.NewWriter(io.Discard, 4, 4, 1, ' ', 0) + w.Init(os.Stdout, 0, 8, 0, '\t', 0) + fmt.Fprintln(w, "time\troom\ttemp\thum\tco") - if err := reader.Err(); err != nil { - return fmt.Errorf("flightsql reader: %s", err) - } + for iterator.Next() { + row := iterator.Value() + day := (row["time"].(arrow.Timestamp)).ToTime(arrow.TimeUnit(arrow.Nanosecond)) + fmt.Fprintf(w, "%s\t%s\t%.2f\t%.2f\t%d\n", day, row["room"], row["temp"], row["hum"], row["co"]) } + w.Flush() return nil } - - func main() { - if err := dbQuery(context.Background()); err != nil { - fmt.Fprintf(os.Stderr, "error: %v\n", err) - os.Exit(1) - } - } ``` The sample code does the following: @@ -493,247 +482,119 @@ _If your project's virtual environment is already running, skip to step 3._ 1. Imports the following packages: - `context` - - `crypto/x509` - - `encoding/json` - `fmt` + - `io` - `os` - - `github.com/apache/arrow/go/v12/arrow/flight/flightsql` - - `google.golang.org/grpc` - - `google.golang.org/grpc/credentials` - - `google.golang.org/grpc/metadata` + - `text/tabwriter` + - `github.com/apache/arrow/go/v12/arrow` + - `github.com/InfluxCommunity/influxdb3-go/influx` - 2. Creates a `dbQuery` function that does the following: + 2. Defines a `Query()` function that does the following: - 1. Defines variables for InfluxDB credentials. + 1. Instantiates `influx.Client` with InfluxDB credentials. - - **url**: {{% cloud-name %}} region hostname and port (`:443`) _(no protocol)_ - - **token**: a [database token](/influxdb/cloud-dedicated/admin/tokens) with _read_ access to the specified database. + - **HostURL**: your {{% cloud-name %}} cluster URL. + - **AuthToken**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database. _For security reasons, we recommend setting this as an environment variable rather than including the raw token string._ - - **database**: the name of the {{% cloud-name %}} database to query - 2. Defines an `opts` options list that includes a gRPC transport for communicating - with {{% cloud-name %}} over the _gRPC+TLS_ protocol. + 2. Defines a deferred function to close the client after execution. + 3. Defines a string variable for the SQL query. - 3. Calls the `flightsql.NewClient()` method with `url` and `opts` to create a new Flight SQL client. + 4. Calls the `influx.Client.query()` method to send the query request with the database name and SQL string. The `query()` method returns an `iterator` for data in the response stream. + 5. Iterates over rows and prints the data in table format to stdout. - 4. Appends the following InfluxDB credentials as key-value pairs to the outgoing context: +3. In your editor, open the `main.go` file you created in the + [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Go#write-line-protocol-to-influxdb) and insert code to call the `Query()` function--for example: - - **authorization**: Bearer - - **database-name**: Database name + ```go + package main - 5. Define the SQL query to execute. + func main() { + WriteLineProtocol() + Query() + } + ``` - 6. Calls the `client.execute()` method to send the query request. - 7. Calls the `client.doGet()` method with the _ticket_ from the query response to retrieve result data from the endpoint. - 8. Creates a reader to read the Arrow table returned by the endpoint and print - the results as JSON. + When the `main` package is executed, `main()` writes and queries data stored in {{% cloud-name %}}. - 3. Creates a `main` module function that executes the `dbQuery` function. +3. In your terminal, enter the following command to install the necessary packages, build the module, and run the program: -3. In your terminal, enter the following command to install all the necessary packages and run the program to query {{% cloud-name %}}. + ```sh + go mod tidy && go build && go run influxdb_go_client + ``` -```sh -go get ./... -go run ./query.go -``` + The program writes the data and prints the query results to the console. {{< expand-wrapper >}} -{{% expand "View program output" %}} -```json -RECORD BATCH -[ - { - "co": 0, - "hum": 35.9, - "room": "Kitchen", - "temp": 21, - "time": "2022-01-01 08:00:00" - }, - { - "co": 0, - "hum": 36.2, - "room": "Kitchen", - "temp": 23, - "time": "2022-01-01 09:00:00" - }, - { - "co": 0, - "hum": 36.1, - "room": "Kitchen", - "temp": 22.7, - "time": "2022-01-01 10:00:00" - }, - { - "co": 0, - "hum": 36, - "room": "Kitchen", - "temp": 22.4, - "time": "2022-01-01 11:00:00" - }, - { - "co": 0, - "hum": 36, - "room": "Kitchen", - "temp": 22.5, - "time": "2022-01-01 12:00:00" - }, - { - "co": 1, - "hum": 36.5, - "room": "Kitchen", - "temp": 22.8, - "time": "2022-01-01 13:00:00" - }, - { - "co": 1, - "hum": 36.3, - "room": "Kitchen", - "temp": 22.8, - "time": "2022-01-01 14:00:00" - }, - { - "co": 3, - "hum": 36.2, - "room": "Kitchen", - "temp": 22.7, - "time": "2022-01-01 15:00:00" - }, - { - "co": 7, - "hum": 36, - "room": "Kitchen", - "temp": 22.4, - "time": "2022-01-01 16:00:00" - }, - { - "co": 9, - "hum": 36, - "room": "Kitchen", - "temp": 22.7, - "time": "2022-01-01 17:00:00" - }, - { - "co": 18, - "hum": 36.9, - "room": "Kitchen", - "temp": 23.3, - "time": "2022-01-01 18:00:00" - }, - { - "co": 22, - "hum": 36.6, - "room": "Kitchen", - "temp": 23.1, - "time": "2022-01-01 19:00:00" - }, - { - "co": 26, - "hum": 36.5, - "room": "Kitchen", - "temp": 22.7, - "time": "2022-01-01 20:00:00" - }, - { - "co": 0, - "hum": 35.9, - "room": "Living Room", - "temp": 21.1, - "time": "2022-01-01 08:00:00" - }, - { - "co": 0, - "hum": 35.9, - "room": "Living Room", - "temp": 21.4, - "time": "2022-01-01 09:00:00" - }, - { - "co": 0, - "hum": 36, - "room": "Living Room", - "temp": 21.8, - "time": "2022-01-01 10:00:00" - }, - { - "co": 0, - "hum": 36, - "room": "Living Room", - "temp": 22.2, - "time": "2022-01-01 11:00:00" - }, - { - "co": 0, - "hum": 35.9, - "room": "Living Room", - "temp": 22.2, - "time": "2022-01-01 12:00:00" - }, - { - "co": 0, - "hum": 36, - "room": "Living Room", - "temp": 22.4, - "time": "2022-01-01 13:00:00" - }, - { - "co": 0, - "hum": 36.1, - "room": "Living Room", - "temp": 22.3, - "time": "2022-01-01 14:00:00" - }, - { - "co": 1, - "hum": 36.1, - "room": "Living Room", - "temp": 22.3, - "time": "2022-01-01 15:00:00" - }, - { - "co": 4, - "hum": 36, - "room": "Living Room", - "temp": 22.4, - "time": "2022-01-01 16:00:00" - }, - { - "co": 5, - "hum": 35.9, - "room": "Living Room", - "temp": 22.6, - "time": "2022-01-01 17:00:00" - }, - { - "co": 9, - "hum": 36.2, - "room": "Living Room", - "temp": 22.8, - "time": "2022-01-01 18:00:00" - }, - { - "co": 14, - "hum": 36.3, - "room": "Living Room", - "temp": 22.5, - "time": "2022-01-01 19:00:00" - }, - { - "co": 17, - "hum": 36.4, - "room": "Living Room", - "temp": 22.2, - "time": "2022-01-01 20:00:00" - } -] +{{% expand "View returned table" %}} +```sh +time room co hum temp +2022-01-02 11:46:40 +0000 UTC Kitchen 0 35.90 21.00 +2022-01-02 12:46:40 +0000 UTC Kitchen 0 36.20 23.00 +2022-01-02 13:46:40 +0000 UTC Kitchen 0 36.10 22.70 +2022-01-02 14:46:40 +0000 UTC Kitchen 0 36.00 22.40 +2022-01-02 15:46:40 +0000 UTC Kitchen 0 36.00 22.50 +2022-01-02 16:46:40 +0000 UTC Kitchen 1 36.50 22.80 +2022-01-02 17:46:40 +0000 UTC Kitchen 1 36.30 22.80 +2022-01-02 18:46:40 +0000 UTC Kitchen 3 36.20 22.70 +2022-01-02 19:46:40 +0000 UTC Kitchen 7 36.00 22.40 +2022-01-02 11:46:40 +0000 UTC Living Room 0 35.90 21.10 +2022-01-02 12:46:40 +0000 UTC Living Room 0 35.90 21.40 +2022-01-02 13:46:40 +0000 UTC Living Room 0 36.00 21.80 +2022-01-02 14:46:40 +0000 UTC Living Room 0 36.00 22.20 +2022-01-02 15:46:40 +0000 UTC Living Room 0 35.90 22.20 +2022-01-02 16:46:40 +0000 UTC Living Room 0 36.00 22.40 +2022-01-02 17:46:40 +0000 UTC Living Room 0 36.10 22.30 +2022-01-02 18:46:40 +0000 UTC Living Room 1 36.10 22.30 +2022-01-02 19:46:40 +0000 UTC Living Room 4 36.00 22.40 ``` {{% /expand %}} {{< /expand-wrapper >}} - {{% /influxdb/custom-timestamps %}} +{{% /influxdb/custom-timestamps %}} {{% /tab-content %}} {{< /tabs-wrapper >}} +### Query results + +{{< expand-wrapper >}} +{{% expand "View query results" %}} + +{{% influxdb/custom-timestamps %}} +| time | room | co | hum | temp | +| :------------------- | :---------- | --: | ---: | ---: | +| 2022-01-01T08:00:00Z | Kitchen | 0 | 35.9 | 21 | +| 2022-01-01T09:00:00Z | Kitchen | 0 | 36.2 | 23 | +| 2022-01-01T10:00:00Z | Kitchen | 0 | 36.1 | 22.7 | +| 2022-01-01T11:00:00Z | Kitchen | 0 | 36 | 22.4 | +| 2022-01-01T12:00:00Z | Kitchen | 0 | 36 | 22.5 | +| 2022-01-01T13:00:00Z | Kitchen | 1 | 36.5 | 22.8 | +| 2022-01-01T14:00:00Z | Kitchen | 1 | 36.3 | 22.8 | +| 2022-01-01T15:00:00Z | Kitchen | 3 | 36.2 | 22.7 | +| 2022-01-01T16:00:00Z | Kitchen | 7 | 36 | 22.4 | +| 2022-01-01T17:00:00Z | Kitchen | 9 | 36 | 22.7 | +| 2022-01-01T18:00:00Z | Kitchen | 18 | 36.9 | 23.3 | +| 2022-01-01T19:00:00Z | Kitchen | 22 | 36.6 | 23.1 | +| 2022-01-01T20:00:00Z | Kitchen | 26 | 36.5 | 22.7 | +| 2022-01-01T08:00:00Z | Living Room | 0 | 35.9 | 21.1 | +| 2022-01-01T09:00:00Z | Living Room | 0 | 35.9 | 21.4 | +| 2022-01-01T10:00:00Z | Living Room | 0 | 36 | 21.8 | +| 2022-01-01T11:00:00Z | Living Room | 0 | 36 | 22.2 | +| 2022-01-01T12:00:00Z | Living Room | 0 | 35.9 | 22.2 | +| 2022-01-01T13:00:00Z | Living Room | 0 | 36 | 22.4 | +| 2022-01-01T14:00:00Z | Living Room | 0 | 36.1 | 22.3 | +| 2022-01-01T15:00:00Z | Living Room | 1 | 36.1 | 22.3 | +| 2022-01-01T16:00:00Z | Living Room | 4 | 36 | 22.4 | +| 2022-01-01T17:00:00Z | Living Room | 5 | 35.9 | 22.6 | +| 2022-01-01T18:00:00Z | Living Room | 9 | 36.2 | 22.8 | +| 2022-01-01T19:00:00Z | Living Room | 14 | 36.3 | 22.5 | +| 2022-01-01T20:00:00Z | Living Room | 17 | 36.4 | 22.2 | +{{% /influxdb/custom-timestamps %}} + +{{% /expand %}} +{{< /expand-wrapper >}} + **Congratulations!** You've learned the basics of querying data in InfluxDB with SQL. For a deep dive into all the ways you can query {{% cloud-name %}}, see the [Query data in InfluxDB](/influxdb/cloud-dedicated/query-data/) section of documentation. diff --git a/content/influxdb/cloud-dedicated/get-started/write.md b/content/influxdb/cloud-dedicated/get-started/write.md index ab76250e0..5dbf94907 100644 --- a/content/influxdb/cloud-dedicated/get-started/write.md +++ b/content/influxdb/cloud-dedicated/get-started/write.md @@ -141,8 +141,8 @@ to an {{% cloud-name %}} database. To learn more about available tools and options, see [Write data](/influxdb/cloud-dedicated/write-data/). {{% note %}} -All API, cURL, and client library examples in this getting started tutorial assume your InfluxDB -**host**, **organization**, **url**, and **token** are provided by +Some examples in this getting started tutorial assume your InfluxDB +credentials (**url**, **organization**, and **token**) are provided by [environment variables](/influxdb/cloud-dedicated/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials). {{% /note %}} @@ -258,11 +258,12 @@ With the {{% cloud-name %}} v2 API `/api/v2/write` endpoint, `Authorization: Bea The following example uses cURL and the InfluxDB v2 API to write line protocol to InfluxDB: +{{% code-placeholders "DATABASE_TOKEN"%}} {{% influxdb/custom-timestamps %}} ```sh curl --request POST \ -"$INFLUX_HOST/api/v2/write?bucket=get-started&precision=s" \ - --header "Authorization: Bearer $INFLUX_TOKEN" \ +"https://cluster-id.influxdb.io/api/v2/write?bucket=get-started&precision=s" \ + --header "Authorization: Bearer DATABASE_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary " @@ -295,6 +296,7 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 " ``` {{% /influxdb/custom-timestamps %}} +{{% /code-placeholders %}} {{% /tab-content %}} {{% tab-content %}} @@ -423,7 +425,7 @@ dependencies to your current project. {{% influxdb/custom-timestamps %}} To write data to {{% cloud-name %}} using Go, use the -[influxdb-client-go module](https://github.com/influxdata/influxdb-client-go). +InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommunity/influxdb3-go). 1. Inside of your project directory, create a new module directory and navigate into it. @@ -450,87 +452,85 @@ To write data to {{% cloud-name %}} using Go, use the import ( "context" + "os" "fmt" "log" - "os" - "time" - influxdb2 "github.com/influxdata/influxdb-client-go/v2" + "github.com/InfluxCommunity/influxdb3-go/influx" ) // Write line protocol data to InfluxDB - func dbWrite(ctx context.Context) error { - - // INFLUX_URL is an environment variable you assigned to your - // cluster URL. - url := os.Getenv("INFLUX_URL") - + func WriteLineProtocol() error { + url := "https://cluster-id.influxdb.io" // INFLUX_TOKEN is an environment variable you assigned to your // database token value. token := os.Getenv("INFLUX_TOKEN") - client := influxdb2.NewClientWithOptions(url, - token, - influxdb2.DefaultOptions().SetPrecision(time.Second)) + database := os.Getenv("INFLUX_DATABASE") + + // Initialize a client with URL and token, + // and set the timestamp precision for writes. + client, err := influx.New(influx.Configs{ + HostURL: url, + AuthToken: token, + WriteParams: influx.WriteParams{Precision: lineprotocol.Second}, + }) - // Define write API - org := "ignored" - bucket := "get-started" - writeAPI := client.WriteAPIBlocking(org, bucket) + // Close the client when the function returns. + defer func (client *influx.Client) { + err := client.Close() + if err != nil { + panic(err) + } + }(client) // Define line protocol records to write. // Use a raw string literal (denoted by backticks) // to preserve backslashes and prevent interpretation // of escape sequences--for example, escaped spaces in tag values. lines := [...]string{ - `home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000`, - `home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000`, - `home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600`, - `home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600`, - `home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200`, - `home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200`, - `home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800`, - `home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800`, - `home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400`, - `home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400`, - `home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000`, - `home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000`, - `home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600`, - `home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600`, - `home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200`, - `home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200`, - `home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800`, - `home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800`, - `home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400`, - `home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400`, - `home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000`, - `home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000`, - `home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600`, - `home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600`, - `home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200`, - `home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200`, + `home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641124000`, + `home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641124000`, + `home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641127600`, + `home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641127600`, + `home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641131200`, + `home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641131200`, + `home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641134800`, + `home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641134800`, + `home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641138400`, + `home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641138400`, + `home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641142000`, + `home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641142000`, + `home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641145600`, + `home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641145600`, + `home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641149200`, + `home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641149200`, + `home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641152800`, + `home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641152800`, + `home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641156400`, + `home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641156400`, + `home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641160000`, + `home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641160000`, + `home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641163600`, + `home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641163600`, + `home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641167200`, + `home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641167200`, } - + // Iterate over the lines array and write each line // separately to InfluxDB - - for _, lp := range lines { - err := writeAPI.WriteRecord(context.Background(), lp) + for _, record := range lines { + err = client.Write(context.Background(), database, []byte(record)) if err != nil { log.Fatalf("Error writing line protocol: %v", err) } } - fmt.Println("Data has been written successfully.") - client.Close() - return nil - } - - // Module main function - func main() { - if err := dbWrite(context.Background()); err != nil { - fmt.Fprintf(os.Stderr, "error: %v\n", err) - os.Exit(1) + if err != nil { + panic(err) } + + fmt.Println("Data has been written successfully.") + return nil } ``` @@ -538,42 +538,39 @@ To write data to {{% cloud-name %}} using Go, use the 1. Imports required packages. - 2. Defines a `dbWrite()` function that does the following: + 2. Defines a `WriteLineProtocol()` function that does the following: - 1. Calls the `influxdb2.NewClientWithOptions()` with InfluxDB URL, - database token, and options to create client. + 1. To instantiate the client, calls the `influx.New(influx.Configs)` function and passes the InfluxDB URL, + database token, and [timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) for writing data to {{% cloud-name %}}. - **Because the timestamps in the sample line protocol are in second - precision, the example passes `DefaultOptions.SetPrecision(time.Second)` - for the `precision` option in order to set the timestamp precision to - seconds.** - - 2. Calls the `writeClient.WriteAPIBlocking()` method to - create a `writeAPI` client configured to write to the database - (the method requires an `org` argument, but InfluxDB ignores it). + 2. Defines a deferred function that closes the client when the function returns. 3. Defines an array of line protocol strings where each string represents a data record. 4. Iterates through the array of line protocol and calls the - write client's `WriteRecord()` method + write client's `Write()` method to write each line of line protocol separately to InfluxDB. - - 3. Defines a `main` function that executes the `dbWrite` function for the module. -5. In your terminal, enter the following command to install the packages listed - in `imports`: +4. In your editor, create a `main.go` file and enter the following sample code that calls the `WriteLineProtocol()` function: - ```sh - go get ./... + ```go + package main + + // Module main function + func main() { + WriteLineProtocol() + } ``` -6. To execute the module and write the line protocol - to your {{% cloud-name %}} database, enter the following command: +5. In your terminal, enter the following command to install the packages listed in `imports`, build the `influxdb_go_client` module, and execute the `main()` function: ```sh - go run ./write.go + go mod tidy && go build && go run influxdb_go_client ``` + + The program writes the line protocol to your {{% cloud-name %}} database. + {{% /influxdb/custom-timestamps %}} {{% /tab-content %}} diff --git a/content/influxdb/cloud-dedicated/reference/client-libraries/flight/go-flight.md b/content/influxdb/cloud-dedicated/reference/client-libraries/flight/go-flight.md index f20e0ac98..0b309e506 100644 --- a/content/influxdb/cloud-dedicated/reference/client-libraries/flight/go-flight.md +++ b/content/influxdb/cloud-dedicated/reference/client-libraries/flight/go-flight.md @@ -5,8 +5,6 @@ menu: influxdb_cloud_dedicated: name: Go parent: Arrow Flight clients - params: - url: https://pkg.go.dev/github.com/apache/arrow/go/v12/arrow/flight#Client identifier: go-flight-client influxdb/cloud-dedicated/tags: [Go, gRPC, SQL, Flight SQL, client libraries] aliases: @@ -14,7 +12,195 @@ aliases: weight: 201 --- -[Apache Arrow for Go](https://pkg.go.dev/github.com/apache/arrow/go/v12) integrates with golang scripts and applications to query data stored in InfluxDB. -See the [Flight SQL example](/influxdb/cloud-dedicated/get-started/query/?t=Go#execute-an-sql-query). +[Apache Arrow for Go](https://pkg.go.dev/github.com/apache/arrow/go/v12) integrates with Go scripts and applications to query data stored in InfluxDB. + +## Flight SQL client + +### Example query using Flight SQL + +The following example shows how to use the Arrow Flight SQL client for Go to query an {{% cloud-name %}} database: + +1. In your editor, open a new file named `query.go` and enter the following sample code: + + ```go + package main + + import ( + "context" + "crypto/x509" + "encoding/json" + "fmt" + "os" + + "github.com/apache/arrow/go/v12/arrow/flight/flightsql" + "google.golang.org/grpc" + "google.golang.org/grpc/credentials" + "google.golang.org/grpc/metadata" + ) + + func dbQuery(ctx context.Context) error { + url := "cluster-id.influxdb.io:443" + + // INFLUX_TOKEN is an environment variable you created for your database READ token + token := os.Getenv("INFLUX_TOKEN") + database := "get-started" + + // Create a gRPC transport + pool, err := x509.SystemCertPool() + if err != nil { + return fmt.Errorf("x509: %s", err) + } + transport := grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(pool, "")) + opts := []grpc.DialOption{ + transport, + } + + // Create query client + client, err := flightsql.NewClient(url, nil, nil, opts...) + if err != nil { + return fmt.Errorf("flightsql: %s", err) + } + + ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+token) + ctx = metadata.AppendToOutgoingContext(ctx, "database", database) + + // Execute query + query := `SELECT + * + FROM + home + WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z'` + + info, err := client.Execute(ctx, query) + if err != nil { + return fmt.Errorf("flightsql flight info: %s", err) + } + reader, err := client.DoGet(ctx, info.Endpoint[0].Ticket) + if err != nil { + return fmt.Errorf("flightsql do get: %s", err) + } + + // Print results as JSON + for reader.Next() { + record := reader.Record() + b, err := json.MarshalIndent(record, "", " ") + if err != nil { + return err + } + fmt.Println("RECORD BATCH") + fmt.Println(string(b)) + + if err := reader.Err(); err != nil { + return fmt.Errorf("flightsql reader: %s", err) + } + } + + return nil + } + + func main() { + if err := dbQuery(context.Background()); err != nil { + fmt.Fprintf(os.Stderr, "error: %v\n", err) + os.Exit(1) + } + } + ``` + + The sample does the following: + + 1. Imports the following packages: + + - `context` + - `crypto/x509` + - `encoding/json` + - `fmt` + - `os` + - `github.com/apache/arrow/go/v12/arrow/flight/flightsql` + - `google.golang.org/grpc` + - `google.golang.org/grpc/credentials` + - `google.golang.org/grpc/metadata` + + 2. Creates a `dbQuery` function that does the following: + + 1. Defines variables for InfluxDB credentials. + + - **url**: {{% cloud-name %}} cluster hostname and port (`:443`) _(no protocol)_ + - **token**: a [database token](/influxdb/cloud-dedicated/get-started/setup/#create-an-all-access-api-token) with _read_ access to the specified bucket. + _For security reasons, we recommend setting this as an environment + variable rather than including the raw token string._ + - **database**: the name of the {{% cloud-name %}} database to query + + 2. Defines an `opts` options list that includes a gRPC transport for communicating + with InfluxDB over the _gRPC+TLS_ protocol. + 3. Calls the `flightsql.NewClient()` method with `url` and `opts` to create a new Flight SQL client. + 4. Appends the following InfluxDB credentials as key-value pairs to the outgoing context: + + - **authorization**: Bearer + - **database-name**: Database name + + 5. Defines the SQL query to execute. + 6. Calls the `client.execute()` method to send the query request. + 7. Calls the `client.doGet()` method with the _ticket_ from the query response to retrieve result data from the endpoint. + 8. Creates a reader to read the Arrow table returned by the endpoint and print + the results as JSON. + + 3. Creates a `main` module function that executes the `dbQuery` function. + +2. Enter the following commands to install all the necessary packages and run the program to query {{% cloud-name %}}: + + ```sh + go get ./... + go run ./query.go + ``` + +{{% influxdb/custom-timestamps %}} +{{< expand-wrapper >}} +{{% expand "View program output" %}} +```json +RECORD BATCH +[ + { + "co": 0, + "hum": 35.9, + "room": "Kitchen", + "temp": 21, + "time": "2022-01-01 08:00:00" + }, + { + "co": 0, + "hum": 36.2, + "room": "Kitchen", + "temp": 23, + "time": "2022-01-01 09:00:00" + }, + { + "co": 0, + "hum": 36.1, + "room": "Kitchen", + "temp": 22.7, + "time": "2022-01-01 10:00:00" + }, + { + "co": 0, + "hum": 36, + "room": "Kitchen", + "temp": 22.4, + "time": "2022-01-01 11:00:00" + }, + { + "co": 0, + "hum": 36, + "room": "Kitchen", + "temp": 22.5, + "time": "2022-01-01 12:00:00" + }, + ... +] +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} For more information, see the [Go Arrow Flight Client documentation](https://pkg.go.dev/github.com/apache/arrow/go/v12/arrow/flight#Client). diff --git a/content/influxdb/cloud-serverless/get-started/query.md b/content/influxdb/cloud-serverless/get-started/query.md index 04c6044b0..176476414 100644 --- a/content/influxdb/cloud-serverless/get-started/query.md +++ b/content/influxdb/cloud-serverless/get-started/query.md @@ -4,7 +4,7 @@ seotitle: Query data | Get started with InfluxDB list_title: Query data description: > Get started querying data in InfluxDB by learning about SQL and InfluxQL, and - using tools like the InfluxDB UI, `influx` CLI, InfluxDB API, and InfluxDB client libraries. + using tools like the InfluxDB UI, the influx3 CLI, and InfluxDB client libraries. menu: influxdb_cloud_serverless: name: Query data @@ -16,7 +16,7 @@ related: - /influxdb/cloud-serverless/query-data/ - /influxdb/cloud-serverless/query-data/sql/ - /influxdb/cloud-serverless/query-data/execute-queries/ - - /influxdb/cloud-serverless/reference/client-libraries/flight-sql/ + - /influxdb/cloud-dedicated/reference/client-libraries/v3/ --- {{% cloud-name %}} supports multiple query languages: @@ -47,7 +47,7 @@ The examples in this section of the tutorial query the [**get-started** bucket]( - [InfluxDB user interface (UI)](?t=InfluxDB+UI#execute-an-sql-query){{< req "\* " >}} - [`influx3` data CLI](?t=influx3+CLI#execute-an-sql-query){{< req "\* " >}} - [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) -- [Flight clients](?t=Go#execute-an-sql-query){{< req "\* " >}} +- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight/){{< req "\* " >}} - [Superset](/influxdb/cloud-serverless/query-data/sql/execute-queries/superset/) - [Grafana](/influxdb/cloud-serverless/query-data/sql/execute-queries/grafana/) - [Chronograf](/{{< latest "chronograf" >}}/) @@ -129,6 +129,8 @@ SELECT * FROM home WHERE room = 'Kitchen' ``` ##### Select data based on tag value within time bounds + +{{% influxdb/custom-timestamps %}} ```sql SELECT * @@ -139,8 +141,12 @@ WHERE AND time <= '2022-01-01T20:00:00Z' AND room = 'Living Room' ``` +{{% /influxdb/custom-timestamps %}} + ##### Downsample data by applying interval-based aggregates + +{{% influxdb/custom-timestamps %}} ```sql SELECT DATE_BIN(INTERVAL '1 hour', time, '2022-01-01T00:00:00Z'::TIMESTAMP) as _time, @@ -154,6 +160,7 @@ GROUP BY room ORDER BY room, _time ``` +{{% /influxdb/custom-timestamps %}} ### Execute an SQL query @@ -183,8 +190,8 @@ WHERE {{% /influxdb/custom-timestamps %}} {{% note %}} -All API, cURL, and client library examples in this getting started tutorial assume your InfluxDB -**host**, **organization**, **url**, and **token** are provided by +Some examples in this getting started tutorial assume your InfluxDB +credentials (**url**, **organization**, and **token**) are provided by [environment variables](/influxdb/cloud-serverless/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials). {{% /note %}} @@ -258,21 +265,21 @@ _If your project's virtual environment is already running, skip to step 3._ 4. Create the `config.json` configuration. - ```sh - influx3 config \ + ```sh + influx3 config \ --name="config-serverless" \ --database="get-started" \ --host="cloud2.influxdata.com" \ --token="API_TOKEN" \ --org="ORG_ID" - ``` + ``` - Replace the following: + Replace the following: - - **`API_TOKEN`**: an InfluxDB [API token](/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) with _read_ access to the **get-started** bucket - - **`ORG_ID`**: an InfluxDB [organization ID](/influxdb/cloud-serverless/admin/organizations/) + - **`API_TOKEN`**: an InfluxDB [API token](/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) with _read_ access to the **get-started** bucket + - **`ORG_ID`**: an InfluxDB [organization ID](/influxdb/cloud-serverless/admin/organizations/) -5. Enter the `influx3 sql` command and your SQL query statement. +5. Enter the `influx3 sql` command and your SQL query statement. ```sh influx3 sql "SELECT * @@ -441,85 +448,58 @@ _If your project's virtual environment is already running, skip to step 3._ import ( "context" - "crypto/x509" - "encoding/json" "fmt" + "io" "os" + "text/tabwriter" - "github.com/apache/arrow/go/v12/arrow/flight/flightsql" - "google.golang.org/grpc" - "google.golang.org/grpc/credentials" - "google.golang.org/grpc/metadata" + "github.com/apache/arrow/go/v12/arrow" + "github.com/InfluxCommunity/influxdb3-go/influx" ) - func dbQuery(ctx context.Context) error { - url := "cloud2.influxdata.com:443" + func Query() error { - // INFLUX_TOKEN is an environment variable you created for your API token + // INFLUX_TOKEN is an environment variable you created for your API read token token := os.Getenv("INFLUX_TOKEN") database := "get-started" - // Create a gRPC transport - pool, err := x509.SystemCertPool() - if err != nil { - return fmt.Errorf("x509: %s", err) - } - transport := grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(pool, "")) - opts := []grpc.DialOption{ - transport, - } + client, err := influx.New(influx.Configs{ + HostURL: "https://cloud2.influxdata.com", + AuthToken: token, + }) - // Create query client - client, err := flightsql.NewClient(url, nil, nil, opts...) - if err != nil { - return fmt.Errorf("flightsql: %s", err) - } - - ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+token) - ctx = metadata.AppendToOutgoingContext(ctx, "database", database) + defer func (client *influx.Client) { + err := client.Close() + if err != nil { + panic(err) + } + }(client) // Execute query - query := `SELECT - * - FROM - home - WHERE - time >= '2022-01-01T08:00:00Z' - AND time <= '2022-01-01T20:00:00Z'` + query := `SELECT * + FROM home + WHERE time >= '2022-01-02T08:00:00Z' + AND time <= '2022-01-02T20:00:00Z'` + + iterator, err := client.Query(context.Background(), database, query) - info, err := client.Execute(ctx, query) if err != nil { - return fmt.Errorf("flightsql flight info: %s", err) - } - reader, err := client.DoGet(ctx, info.Endpoint[0].Ticket) - if err != nil { - return fmt.Errorf("flightsql do get: %s", err) + panic(err) } - // Print results as JSON - for reader.Next() { - record := reader.Record() - b, err := json.MarshalIndent(record, "", " ") - if err != nil { - return err - } - fmt.Println("RECORD BATCH") - fmt.Println(string(b)) + w := tabwriter.NewWriter(io.Discard, 4, 4, 1, ' ', 0) + w.Init(os.Stdout, 0, 8, 0, '\t', 0) + fmt.Fprintln(w, "time\troom\ttemp\thum\tco") - if err := reader.Err(); err != nil { - return fmt.Errorf("flightsql reader: %s", err) - } + for iterator.Next() { + row := iterator.Value() + day := (row["time"].(arrow.Timestamp)).ToTime(arrow.TimeUnit(arrow.Nanosecond)) + fmt.Fprintf(w, "%s\t%s\t%.2f\t%.2f\t%d\n", day, row["room"], row["temp"], row["hum"], row["co"]) } + w.Flush() return nil } - - func main() { - if err := dbQuery(context.Background()); err != nil { - fmt.Fprintf(os.Stderr, "error: %v\n", err) - os.Exit(1) - } - } ``` The sample code does the following: @@ -527,243 +507,76 @@ _If your project's virtual environment is already running, skip to step 3._ 1. Imports the following packages: - `context` - - `crypto/x509` - - `encoding/json` - `fmt` + - `io` - `os` - - `github.com/apache/arrow/go/v12/arrow/flight/flightsql` - - `google.golang.org/grpc` - - `google.golang.org/grpc/credentials` - - `google.golang.org/grpc/metadata` + - `text/tabwriter` + - `github.com/apache/arrow/go/v12/arrow` + - `github.com/InfluxCommunity/influxdb3-go/influx` - 2. Creates a `dbQuery` function that does the following: + 2. Defines a `Query()` function that does the following: - 1. Defines variables for InfluxDB credentials. + 1. Instantiates `influx.Client` with InfluxDB credentials. - - **url**: {{% cloud-name %}} region hostname and port (`:443`) _(no protocol)_ - - **token**: an [API token](/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) with _read_ access to the specified bucket. + - **HostURL**: your {{% cloud-name %}} region URL. + - **AuthToken**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket. _For security reasons, we recommend setting this as an environment variable rather than including the raw token string._ - - **database**: the name of the {{% cloud-name %}} bucket to query - 2. Defines an `opts` options list that includes a gRPC transport for communicating - with {{% cloud-name %}} over the _gRPC+TLS_ protocol. + 2. Defines a deferred function to close the client after execution. + 3. Defines a string variable for the SQL query. - 3. Calls the `flightsql.NewClient()` method with `url` and `opts` to create a new Flight SQL client. + 4. Calls the `influx.Client.query()` method to send the query request with the database (bucket) name and SQL string. The `query()` method returns an `iterator` for data in the response stream. + 5. Iterates over rows and prints the data in table format to stdout. - 4. Appends the following InfluxDB credentials as key-value pairs to the outgoing context: +3. In your editor, open the `main.go` file you created in the + [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Go#write-line-protocol-to-influxdb) and insert code to call the `Query()` function--for example: - - **authorization**: Bearer - - **database-name**: Bucket name + ```go + package main - 5. Define the SQL query to execute. + func main() { + WriteLineProtocol() + Query() + } + ``` - 6. Calls the `client.execute()` method to send the query request. - 7. Calls the `client.doGet()` method with the _ticket_ from the query response to retrieve result data from the endpoint. - 8. Creates a reader to read the Arrow table returned by the endpoint and print - the results as JSON. + When the `main` package is executed, `main()` writes and queries data stored in {{% cloud-name %}}. - 3. Creates a `main` module function that executes the `dbQuery` function. +3. In your terminal, enter the following command to install the necessary packages, build the module, and run the program: -3. In your terminal, enter the following command to install all the necessary packages and run the program to query {{% cloud-name %}}. + ```sh + go mod tidy && go build && go run influxdb_go_client + ``` -```sh -go get ./... -go run ./query.go -``` + The program writes the data and prints the query results to the console. {{< expand-wrapper >}} -{{% expand "View program output" %}} -```json -RECORD BATCH -[ - { - "co": 0, - "hum": 35.9, - "room": "Kitchen", - "temp": 21, - "time": "2022-01-01 08:00:00" - }, - { - "co": 0, - "hum": 36.2, - "room": "Kitchen", - "temp": 23, - "time": "2022-01-01 09:00:00" - }, - { - "co": 0, - "hum": 36.1, - "room": "Kitchen", - "temp": 22.7, - "time": "2022-01-01 10:00:00" - }, - { - "co": 0, - "hum": 36, - "room": "Kitchen", - "temp": 22.4, - "time": "2022-01-01 11:00:00" - }, - { - "co": 0, - "hum": 36, - "room": "Kitchen", - "temp": 22.5, - "time": "2022-01-01 12:00:00" - }, - { - "co": 1, - "hum": 36.5, - "room": "Kitchen", - "temp": 22.8, - "time": "2022-01-01 13:00:00" - }, - { - "co": 1, - "hum": 36.3, - "room": "Kitchen", - "temp": 22.8, - "time": "2022-01-01 14:00:00" - }, - { - "co": 3, - "hum": 36.2, - "room": "Kitchen", - "temp": 22.7, - "time": "2022-01-01 15:00:00" - }, - { - "co": 7, - "hum": 36, - "room": "Kitchen", - "temp": 22.4, - "time": "2022-01-01 16:00:00" - }, - { - "co": 9, - "hum": 36, - "room": "Kitchen", - "temp": 22.7, - "time": "2022-01-01 17:00:00" - }, - { - "co": 18, - "hum": 36.9, - "room": "Kitchen", - "temp": 23.3, - "time": "2022-01-01 18:00:00" - }, - { - "co": 22, - "hum": 36.6, - "room": "Kitchen", - "temp": 23.1, - "time": "2022-01-01 19:00:00" - }, - { - "co": 26, - "hum": 36.5, - "room": "Kitchen", - "temp": 22.7, - "time": "2022-01-01 20:00:00" - }, - { - "co": 0, - "hum": 35.9, - "room": "Living Room", - "temp": 21.1, - "time": "2022-01-01 08:00:00" - }, - { - "co": 0, - "hum": 35.9, - "room": "Living Room", - "temp": 21.4, - "time": "2022-01-01 09:00:00" - }, - { - "co": 0, - "hum": 36, - "room": "Living Room", - "temp": 21.8, - "time": "2022-01-01 10:00:00" - }, - { - "co": 0, - "hum": 36, - "room": "Living Room", - "temp": 22.2, - "time": "2022-01-01 11:00:00" - }, - { - "co": 0, - "hum": 35.9, - "room": "Living Room", - "temp": 22.2, - "time": "2022-01-01 12:00:00" - }, - { - "co": 0, - "hum": 36, - "room": "Living Room", - "temp": 22.4, - "time": "2022-01-01 13:00:00" - }, - { - "co": 0, - "hum": 36.1, - "room": "Living Room", - "temp": 22.3, - "time": "2022-01-01 14:00:00" - }, - { - "co": 1, - "hum": 36.1, - "room": "Living Room", - "temp": 22.3, - "time": "2022-01-01 15:00:00" - }, - { - "co": 4, - "hum": 36, - "room": "Living Room", - "temp": 22.4, - "time": "2022-01-01 16:00:00" - }, - { - "co": 5, - "hum": 35.9, - "room": "Living Room", - "temp": 22.6, - "time": "2022-01-01 17:00:00" - }, - { - "co": 9, - "hum": 36.2, - "room": "Living Room", - "temp": 22.8, - "time": "2022-01-01 18:00:00" - }, - { - "co": 14, - "hum": 36.3, - "room": "Living Room", - "temp": 22.5, - "time": "2022-01-01 19:00:00" - }, - { - "co": 17, - "hum": 36.4, - "room": "Living Room", - "temp": 22.2, - "time": "2022-01-01 20:00:00" - } -] +{{% expand "View returned table" %}} +```sh +time room co hum temp +2022-01-02 11:46:40 +0000 UTC Kitchen 0 35.90 21.00 +2022-01-02 12:46:40 +0000 UTC Kitchen 0 36.20 23.00 +2022-01-02 13:46:40 +0000 UTC Kitchen 0 36.10 22.70 +2022-01-02 14:46:40 +0000 UTC Kitchen 0 36.00 22.40 +2022-01-02 15:46:40 +0000 UTC Kitchen 0 36.00 22.50 +2022-01-02 16:46:40 +0000 UTC Kitchen 1 36.50 22.80 +2022-01-02 17:46:40 +0000 UTC Kitchen 1 36.30 22.80 +2022-01-02 18:46:40 +0000 UTC Kitchen 3 36.20 22.70 +2022-01-02 19:46:40 +0000 UTC Kitchen 7 36.00 22.40 +2022-01-02 11:46:40 +0000 UTC Living Room 0 35.90 21.10 +2022-01-02 12:46:40 +0000 UTC Living Room 0 35.90 21.40 +2022-01-02 13:46:40 +0000 UTC Living Room 0 36.00 21.80 +2022-01-02 14:46:40 +0000 UTC Living Room 0 36.00 22.20 +2022-01-02 15:46:40 +0000 UTC Living Room 0 35.90 22.20 +2022-01-02 16:46:40 +0000 UTC Living Room 0 36.00 22.40 +2022-01-02 17:46:40 +0000 UTC Living Room 0 36.10 22.30 +2022-01-02 18:46:40 +0000 UTC Living Room 1 36.10 22.30 +2022-01-02 19:46:40 +0000 UTC Living Room 4 36.00 22.40 ``` {{% /expand %}} {{< /expand-wrapper >}} - {{% /influxdb/custom-timestamps %}} +{{% /influxdb/custom-timestamps %}} {{% /tab-content %}} {{< /tabs-wrapper >}} diff --git a/content/influxdb/cloud-serverless/get-started/write.md b/content/influxdb/cloud-serverless/get-started/write.md index a99a6f83b..45c2a0042 100644 --- a/content/influxdb/cloud-serverless/get-started/write.md +++ b/content/influxdb/cloud-serverless/get-started/write.md @@ -143,8 +143,8 @@ to an {{% cloud-name %}} bucket. To learn more about available tools and options, see [Write data](influxdb/cloud-serverless/write-data/). {{% note %}} -All API, cURL, and client library examples in this getting started tutorial assume your InfluxDB -**host**, **organization**, **url**, and **token** are provided by +Some examples in this getting started tutorial assume your InfluxDB +credentials (**url**, **organization**, and **token**) are provided by [environment variables](/influxdb/cloud-serverless/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials). {{% /note %}} @@ -320,7 +320,7 @@ To learn more, see how to [use Telegraf to write data](/influxdb/cloud-serverles To write data to InfluxDB using the InfluxDB HTTP API, send a request to the InfluxDB API `/api/v2/write` endpoint using the `POST` request method. -{{< api-endpoint endpoint="http://localhost:8086/api/v2/write" method="post" api-ref="/influxdb/cloud-serverless/api/#operation/PostWrite" >}} +{{< api-endpoint endpoint="https://cloud2.influxdata.com/api/v2/write" method="post" api-ref="/influxdb/cloud-serverless/api/#operation/PostWrite" >}} Include the following with your request: @@ -336,11 +336,12 @@ Include the following with your request: The following example uses cURL and the InfluxDB v2 API to write line protocol to InfluxDB: +{{% code-placeholders "API_TOKEN"%}} {{% influxdb/custom-timestamps %}} ```sh curl --request POST \ "https://cloud2.influxdata.com/api/v2/write?bucket=get-started&precision=s" \ - --header "Authorization: Token $INFLUX_TOKEN" \ + --header "Authorization: Token API_TOKEN" \ --header "Content-Type: text/plain; charset=utf-8" \ --header "Accept: application/json" \ --data-binary " @@ -373,6 +374,7 @@ home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200 " ``` {{% /influxdb/custom-timestamps %}} +{{% /code-placeholders %}} {{% /tab-content %}} {{% tab-content %}} @@ -528,87 +530,85 @@ To write data to {{% cloud-name %}} using Go, use the import ( "context" + "os" "fmt" "log" - "os" - "time" - influxdb2 "github.com/influxdata/influxdb-client-go/v2" + "github.com/InfluxCommunity/influxdb3-go/influx" ) // Write line protocol data to InfluxDB - func dbWrite(ctx context.Context) error { - - // INFLUX_URL is an environment variable you assigned to your - // region URL. - url := os.Getenv("INFLUX_URL") - + func WriteLineProtocol() error { + url := "https://cloud2.influxdata.com" // INFLUX_TOKEN is an environment variable you assigned to your // API token value. token := os.Getenv("INFLUX_TOKEN") - client := influxdb2.NewClientWithOptions(url, - token, - influxdb2.DefaultOptions().SetPrecision(time.Second)) + database := os.Getenv("INFLUX_DATABASE") + + // Initialize a client with URL and token, + // and set the timestamp precision for writes. + client, err := influx.New(influx.Configs{ + HostURL: url, + AuthToken: token, + WriteParams: influx.WriteParams{Precision: lineprotocol.Second}, + }) - // Define write API - org := "ignored" - bucket := "get-started" - writeAPI := client.WriteAPIBlocking(org, bucket) + // Close the client when the function returns. + defer func (client *influx.Client) { + err := client.Close() + if err != nil { + panic(err) + } + }(client) // Define line protocol records to write. // Use a raw string literal (denoted by backticks) // to preserve backslashes and prevent interpretation // of escape sequences--for example, escaped spaces in tag values. lines := [...]string{ - `home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000`, - `home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000`, - `home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600`, - `home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600`, - `home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200`, - `home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200`, - `home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800`, - `home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800`, - `home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400`, - `home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400`, - `home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000`, - `home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000`, - `home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600`, - `home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600`, - `home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200`, - `home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200`, - `home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800`, - `home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800`, - `home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400`, - `home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400`, - `home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000`, - `home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000`, - `home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600`, - `home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600`, - `home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200`, - `home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200`, + `home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641124000`, + `home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641124000`, + `home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641127600`, + `home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641127600`, + `home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641131200`, + `home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641131200`, + `home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641134800`, + `home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641134800`, + `home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641138400`, + `home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641138400`, + `home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641142000`, + `home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641142000`, + `home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641145600`, + `home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641145600`, + `home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641149200`, + `home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641149200`, + `home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641152800`, + `home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641152800`, + `home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641156400`, + `home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641156400`, + `home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641160000`, + `home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641160000`, + `home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641163600`, + `home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641163600`, + `home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641167200`, + `home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641167200`, } - + // Iterate over the lines array and write each line // separately to InfluxDB - - for _, lp := range lines { - err := writeAPI.WriteRecord(context.Background(), lp) + for _, record := range lines { + err = client.Write(context.Background(), database, []byte(record)) if err != nil { log.Fatalf("Error writing line protocol: %v", err) } } - fmt.Println("Data has been written successfully.") - client.Close() - return nil - } - - // Module main function - func main() { - if err := dbWrite(context.Background()); err != nil { - fmt.Fprintf(os.Stderr, "error: %v\n", err) - os.Exit(1) + if err != nil { + panic(err) } + + fmt.Println("Data has been written successfully.") + return nil } ``` @@ -616,42 +616,39 @@ To write data to {{% cloud-name %}} using Go, use the 1. Imports required packages. - 2. Defines a `dbWrite()` function that does the following: + 2. Defines a `WriteLineProtocol()` function that does the following: - 1. Calls the `influxdb2.NewClientWithOptions()` with InfluxDB URL, - API token, and options to create client. + 1. To instantiate the client, calls the `influx.New(influx.Configs)` function and passes the InfluxDB URL, + database token, and [timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) for writing data to {{% cloud-name %}}. - **Because the timestamps in the sample line protocol are in second - precision, the example passes `DefaultOptions.SetPrecision(time.Second)` - for the `precision` option in order to set the timestamp precision to - seconds.** - - 2. Calls the `writeClient.WriteAPIBlocking()` method to - create a `writeAPI` client configured to write to the bucket - (the method requires an `org` argument, but InfluxDB ignores it). + 2. Defines a deferred function that closes the client when the function returns. 3. Defines an array of line protocol strings where each string represents a data record. 4. Iterates through the array of line protocol and calls the - write client's `WriteRecord()` method + write client's `Write()` method to write each line of line protocol separately to InfluxDB. - - 3. Defines a `main` function that executes the `dbWrite` function for the module. -5. In your terminal, enter the following command to install the packages listed - in `imports`: +4. In your editor, create a `main.go` file and enter the following sample code that calls the `WriteLineProtocol()` function: - ```sh - go get ./... + ```go + package main + + // Module main function + func main() { + WriteLineProtocol() + } ``` -6. To execute the module and write the line protocol - to your {{% cloud-name %}} bucket, enter the following command: +5. In your terminal, enter the following command to install the packages listed in `imports`, build the `influxdb_go_client` module, and execute the `main()` function: ```sh - go run ./write.go + go mod tidy && go build && go run influxdb_go_client ``` + + The program writes the line protocol to your {{% cloud-name %}} bucket. + {{% /influxdb/custom-timestamps %}} {{% /tab-content %}} diff --git a/content/influxdb/cloud-serverless/reference/client-libraries/flight/go-flight.md b/content/influxdb/cloud-serverless/reference/client-libraries/flight/go-flight.md index 2e15859f7..5d39ea147 100644 --- a/content/influxdb/cloud-serverless/reference/client-libraries/flight/go-flight.md +++ b/content/influxdb/cloud-serverless/reference/client-libraries/flight/go-flight.md @@ -5,8 +5,6 @@ menu: influxdb_cloud_serverless: name: Go parent: Arrow Flight clients - params: - url: https://pkg.go.dev/github.com/apache/arrow/go/v12/arrow/flight#Client identifier: go-flight-client influxdb/cloud-serverless/tags: [Golang, gRPC, SQL, Flight SQL, client libraries] aliases: @@ -14,7 +12,195 @@ aliases: weight: 201 --- -[Apache Arrow for Go](https://pkg.go.dev/github.com/apache/arrow/go/v12) integrates with golang scripts and applications to query data stored in InfluxDB. -See the [Flight SQL example](/influxdb/cloud-serverless/get-started/query/?t=Go#execute-an-sql-query). +[Apache Arrow for Go](https://pkg.go.dev/github.com/apache/arrow/go/v12) integrates with Go scripts and applications to query data stored in InfluxDB. + +## Flight SQL client + +### Example query using Flight SQL + +The following example shows how to use the Arrow Flight SQL client for Go to query an {{% cloud-name %}} bucket: + +1. In your editor, open a new file named `query.go` and enter the following sample code: + + ```go + package main + + import ( + "context" + "crypto/x509" + "encoding/json" + "fmt" + "os" + + "github.com/apache/arrow/go/v12/arrow/flight/flightsql" + "google.golang.org/grpc" + "google.golang.org/grpc/credentials" + "google.golang.org/grpc/metadata" + ) + + func dbQuery(ctx context.Context) error { + url := "cloud2.influxdata.com:443" + + // INFLUX_TOKEN is an environment variable you created for your API token + token := os.Getenv("INFLUX_TOKEN") + database := "get-started" + + // Create a gRPC transport + pool, err := x509.SystemCertPool() + if err != nil { + return fmt.Errorf("x509: %s", err) + } + transport := grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(pool, "")) + opts := []grpc.DialOption{ + transport, + } + + // Create query client + client, err := flightsql.NewClient(url, nil, nil, opts...) + if err != nil { + return fmt.Errorf("flightsql: %s", err) + } + + ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+token) + ctx = metadata.AppendToOutgoingContext(ctx, "database", database) + + // Execute query + query := `SELECT + * + FROM + home + WHERE + time >= '2022-01-01T08:00:00Z' + AND time <= '2022-01-01T20:00:00Z'` + + info, err := client.Execute(ctx, query) + if err != nil { + return fmt.Errorf("flightsql flight info: %s", err) + } + reader, err := client.DoGet(ctx, info.Endpoint[0].Ticket) + if err != nil { + return fmt.Errorf("flightsql do get: %s", err) + } + + // Print results as JSON + for reader.Next() { + record := reader.Record() + b, err := json.MarshalIndent(record, "", " ") + if err != nil { + return err + } + fmt.Println("RECORD BATCH") + fmt.Println(string(b)) + + if err := reader.Err(); err != nil { + return fmt.Errorf("flightsql reader: %s", err) + } + } + + return nil + } + + func main() { + if err := dbQuery(context.Background()); err != nil { + fmt.Fprintf(os.Stderr, "error: %v\n", err) + os.Exit(1) + } + } + ``` + + The sample does the following: + + 1. Imports the following packages: + + - `context` + - `crypto/x509` + - `encoding/json` + - `fmt` + - `os` + - `github.com/apache/arrow/go/v12/arrow/flight/flightsql` + - `google.golang.org/grpc` + - `google.golang.org/grpc/credentials` + - `google.golang.org/grpc/metadata` + + 2. Creates a `dbQuery` function that does the following: + + 1. Defines variables for InfluxDB credentials. + + - **url**: {{% cloud-name %}} region hostname and port (`:443`) _(no protocol)_ + - **token**: an [API token](/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) with _read_ access to the specified bucket. + _For security reasons, we recommend setting this as an environment + variable rather than including the raw token string._ + - **database**: the name of the {{% cloud-name %}} bucket to query + + 2. Defines an `opts` options list that includes a gRPC transport for communicating + with InfluxDB over the _gRPC+TLS_ protocol. + 3. Calls the `flightsql.NewClient()` method with `url` and `opts` to create a new Flight SQL client. + 4. Appends the following InfluxDB credentials as key-value pairs to the outgoing context: + + - **authorization**: Bearer + - **database-name**: Bucket name + + 5. Defines the SQL query to execute. + 6. Calls the `client.execute()` method to send the query request. + 7. Calls the `client.doGet()` method with the _ticket_ from the query response to retrieve result data from the endpoint. + 8. Creates a reader to read the Arrow table returned by the endpoint and print + the results as JSON. + + 3. Creates a `main` module function that executes the `dbQuery` function. + +2. Enter the following commands to install all the necessary packages and run the program to query {{% cloud-name %}}: + + ```sh + go get ./... + go run ./query.go + ``` + +{{% influxdb/custom-timestamps %}} +{{< expand-wrapper >}} +{{% expand "View program output" %}} +```json +RECORD BATCH +[ + { + "co": 0, + "hum": 35.9, + "room": "Kitchen", + "temp": 21, + "time": "2022-01-01 08:00:00" + }, + { + "co": 0, + "hum": 36.2, + "room": "Kitchen", + "temp": 23, + "time": "2022-01-01 09:00:00" + }, + { + "co": 0, + "hum": 36.1, + "room": "Kitchen", + "temp": 22.7, + "time": "2022-01-01 10:00:00" + }, + { + "co": 0, + "hum": 36, + "room": "Kitchen", + "temp": 22.4, + "time": "2022-01-01 11:00:00" + }, + { + "co": 0, + "hum": 36, + "room": "Kitchen", + "temp": 22.5, + "time": "2022-01-01 12:00:00" + }, + ... +] +``` +{{% /influxdb/custom-timestamps %}} +{{% /expand %}} +{{< /expand-wrapper >}} For more information, see the [Go Arrow Flight Client documentation](https://pkg.go.dev/github.com/apache/arrow/go/v12/arrow/flight#Client).