Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Execute queries reorg (#5100) 

* chore(ci): Add git pre-commit hook script with Vale linting

* fix(v3): Get started: update cloud lib parameters and signatures.

* fix(v3): v1-api: move to Execute queries and cleanup params

* fix(v3): Add Execute queries > Client libraries

* fix(v3): Python and Go client library guides: reorg and cleanup.

* fix(v3): Spelling

* chore(v3): Go client lib reference.

* chore(ci): Add upsample to accepted terms.

* fix(v3): Fix pandas guides.

* fix(v3): Get started: query cleanup.

* fix(v3): cleanup go-flight

* fix(v3): Data explorer cleanup.

* fix(v3): clean up client lib index

* fix(v3): API cleanup.

* fix(v3): add metadata

* fix(v3): Cleanup

* fix(v3): Required indicator

* Update content/influxdb/cloud-serverless/query-data/execute-queries/influxdb-v1-api.md

* Apply suggestions from code review

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flightsql-dbapi.md

* Update content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flightsql-dbapi.md

* Update content/influxdb/cloud-dedicated/get-started/query.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/influxdb/cloud-serverless/reference/client-libraries/flight/java-flightsql.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/influxdb/cloud-dedicated/get-started/query.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

---------

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
pull/5106/head
Jason Stirnaman 2023-08-24 15:11:28 -05:00 committed by GitHub
parent f6c7f3c014
commit da36218fb2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
54 changed files with 2802 additions and 1645 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
.ci/git-hooks/pre-commit Executable file
View File

@ -0,0 +1,53 @@
#!/bin/sh
#
# An example hook script to verify what is about to be committed.
# Called by "git commit" with no arguments. The hook should
# exit with non-zero status after issuing an appropriate message if
# it wants to stop the commit.
#
# To enable this hook, rename this file to "pre-commit".
if git rev-parse --verify HEAD >/dev/null 2>&1
then
against=HEAD
else
# Initial commit: diff against an empty tree object
against=$(git hash-object -t tree /dev/null)
fi
# If you want to allow non-ASCII filenames set this variable to true.
allownonascii=$(git config --type=bool hooks.allownonascii)
# Redirect output to stderr.
exec 1>&2
# Cross platform projects tend to avoid non-ASCII filenames; prevent
# them from being added to the repository. We exploit the fact that the
# printable range starts at the space character and ends with tilde.
if [ "$allownonascii" != "true" ] &&
# Note that the use of brackets around a tr range is ok here, (it's
# even required, for portability to Solaris 10's /usr/bin/tr), since
# the square bracket bytes happen to fall in the designated range.
test $(git diff --cached --name-only --diff-filter=A -z $against |
LC_ALL=C tr -d '[ -~]\0' | wc -c) != 0
then
cat <<\EOF
Error: Attempt to add a non-ASCII file name.
This can cause problems if you want to work with people on other platforms.
To be portable it is advisable to rename the file.
If you know what you are doing you can disable this check using:
git config hooks.allownonascii true
EOF
exit 1
fi
# If there are whitespace errors, print the offending file names and fail.
exec git diff-index --check --cached $against --
# Use Vale to lint docs for style, grammar, and spelling.
# Lint cloud-dedicated
exec vale --output=line --relative --minAlertLevel=error $(git diff --cached --name-only --diff-filter=ACMR)

1
.ci/vale/styles/Vocab/InfluxData/accept.txt
View File

@ -81,6 +81,7 @@ uint|UINT
uinteger
unescaped
unix
upsample
upsert
urls
venv

7
content/influxdb/cloud-dedicated/api-compatibility/v1/_index.md
View File

@ -1,6 +1,5 @@
---
title: Use the InfluxDB v1 API with InfluxDB Cloud Dedicated
list_title: Use the InfluxDB v1 API
title: Use the InfluxDB v1 API
description: >
Use InfluxDB v1 API authentication, endpoints, and tools when bringing existing 1.x workloads to InfluxDB Cloud Dedicated.
weight: 3
@ -61,7 +60,7 @@ Learn how to authenticate requests, adjust request parameters for existing v1 wo
## Authenticate API requests
InfluxDB requires each API request to be authenticated with a
{{% cloud-name %}} requires each API request to be authenticated with a
[database token](/influxdb/cloud-dedicated/admin/tokens/).
With the InfluxDB v1 API, you can use database tokens in InfluxDB 1.x username and password
schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Authorization: Bearer` scheme.
@ -428,7 +427,7 @@ Replace the following:
- [Flight clients](/influxdb/cloud-dedicated/reference/client-libraries/flight/)
- [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/query-data/influxql/execute-queries/influxdb-v1-api/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/query-data/execute-queries/influxdb-v1-api/)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}

76
content/influxdb/cloud-dedicated/get-started/query.md
View File

@ -49,7 +49,7 @@ The examples in this section of the tutorial query the
- [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/query-data/influxql/execute-queries/influxdb-v1-api/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-dedicated/query-data/execute-queries/influxdb-v1-api/)
- [Chronograf](/{{< latest "chronograf" >}}/)
## SQL query basics
@ -343,8 +343,10 @@ _If your project's virtual environment is already running, skip to step 3._
{{< expand-wrapper >}}
{{% expand "<span class='req'>Important</span>: If using **Windows**, specify the **Windows** certificate path" %}}
If using a non-POSIX-compliant operating system (such as Windows), specify the root certificate path when instantiating the client.
The following example shows how to use the Python `certifi` package and client library options to pass the certificate path:
When instantiating the client, Python looks for SSL/TLS certificate authority (CA) certificates for verifying the server's authenticity.
If using a non-POSIX-compliant operating system (such as Windows), you need to specify a certificate bundle path that Python can access on your system.
The following example shows how to use the [Python `certifi` package](https://certifiio.readthedocs.io/en/latest/) and client library options to provide a bundle of trusted certificates to the Python Flight client:
1. In your terminal, install the Python `certifi` package.
@ -473,7 +475,7 @@ _If your project's virtual environment is already running, skip to step 3._
"text/tabwriter"
"github.com/apache/arrow/go/v12/arrow"
"github.com/InfluxCommunity/influxdb3-go/influx"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
func Query() error {
@ -481,19 +483,19 @@ _If your project's virtual environment is already running, skip to step 3._
// INFLUX_TOKEN is an environment variable you created
// for your database read token.
token := os.Getenv("INFLUX_TOKEN")
database := "get-started"
// Instantiate the client.
client, err := influx.New(influx.Configs{
HostURL: "https://cluster-id.influxdb.io",
AuthToken: token,
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://{{< influxdb/host >}}",
Token: token,
Database: "get-started",
})
// Close the client when the function returns.
defer func (client *influx.Client) {
defer func(client *influxdb3.Client) {
err := client.Close()
if err != nil {
panic(err)
panic(err)
}
}(client)
@ -504,7 +506,7 @@ _If your project's virtual environment is already running, skip to step 3._
AND time <= '2022-01-01T20:00:00Z'`
// Execute the query.
iterator, err := client.Query(context.Background(), database, query)
iterator, err := client.Query(context.Background(), query)
if err != nil {
panic(err)
@ -541,20 +543,22 @@ _If your project's virtual environment is already running, skip to step 3._
- `os`
- `text/tabwriter`
- `github.com/apache/arrow/go/v12/arrow`
- `github.com/InfluxCommunity/influxdb3-go/influx`
- `github.com/InfluxCommunity/influxdb3-go/influxdb3`
2. Defines a `Query()` function that does the following:
1. Instantiates `influx.Client` with InfluxDB credentials.
- **`HostURL`**: your {{% cloud-name %}} cluster URL
- **`AuthToken`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database.
- **`Host`**: your {{% cloud-name %}} cluster URL
- **`Database`**: The name of your {{% cloud-name %}} database
- **`Token`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with read permission on the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
2. Defines a deferred function to close the client after execution.
3. Defines a string variable for the SQL query.
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.
4. Calls the `influxdb3.Client.Query(sql string)` method and passes the SQL string to query InfluxDB.
`Query(sql string)` method returns an `iterator` for data in the response stream.
5. Iterates over rows, formats the timestamp as an [RFC3339 timestamp](/influxdb/cloud-dedicated/reference/glossary/#rfc3339-timestamp), and prints the data in table format to stdout.
3. In your editor, open the `main.go` file you created in the
@ -654,7 +658,7 @@ _This tutorial assumes you installed Node.js and npm, and created an `influxdb_j
with InfluxDB credentials.
- **`host`**: your {{% cloud-name %}} cluster URL
- **`token`**: an [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database.
- **`token`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with read permission on the database you want to query.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
3. Defines a string variable (`sql`) for the SQL query.
@ -723,21 +727,17 @@ _This tutorial assumes you installed Node.js and npm, and created an `influxdb_j
**/
public static async Task QuerySQL()
{
/** Set InfluxDB credentials **/
const string hostUrl = "https://cluster-id.influxdb.io";
string? database = "get-started";
/** INFLUX_TOKEN is an environment variable you assigned to your
* database READ token value.
**/
string? authToken = System.Environment
string? token = System.Environment
.GetEnvironmentVariable("INFLUX_TOKEN");
/**
* Instantiate the InfluxDB client with credentials.
**/
using var client = new InfluxDBClient(
hostUrl, authToken: authToken, database: database);
"https://{{< influxdb/host >}}", token: token, database: database);
const string sql = @"
SELECT time, room, temp, hum, co
@ -779,12 +779,13 @@ _This tutorial assumes you installed Node.js and npm, and created an `influxdb_j
1. Calls the `new InfluxDBClient()` constructor to instantiate a client configured
with InfluxDB credentials.
- **`hostURL`**: your {{% cloud-name %}} cluster URL.
- **`authToken`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`host`**: your {{% cloud-name %}} cluster URL.
- **`database`**: the name of the {{% cloud-name %}} database to query
- **`token`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with read permission on the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
2. Defines a string variable for the SQL query.
3. Calls the `InfluxDBClient.Query()` method to send the query request with the SQL string. `Query()` returns batches of rows from the response stream as a two-dimensional array--an array of rows in which each row is an array of values.
3. Calls the `InfluxDBClient.Query()` method to send the query request with the SQL string.
`Query()` returns batches of rows from the response stream as a two-dimensional array--an array of rows in which each row is an array of values.
4. Iterates over rows and prints the data in table format to stdout.
3. In your editor, open the `Program.cs` file you created in the
[Write data section](/influxdb/cloud-dedicated/get-started/write/?t=C%23#write-line-protocol-to-influxdb) and insert code to call the `Query()` function--for example:
@ -807,12 +808,8 @@ _This tutorial assumes you installed Node.js and npm, and created an `influxdb_j
}
```
4. To execute the program and query your {{% cloud-name %}} cluster,
enter the following commands in your terminal:
```sh
dotnet build
```
4. To build and execute the program and query your {{% cloud-name %}} cluster,
enter the following command in your terminal:
```sh
dotnet run
@ -857,17 +854,17 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and an `infl
*/
/** Set InfluxDB credentials. **/
final String hostUrl = "https://cluster-id.influxdb.io";
final String host = "https://{{< influxdb/host >}}";
final String database = "get-started";
/** INFLUX_TOKEN is an environment variable you assigned to your
* database READ token value.
**/
final char[] authToken = (System.getenv("INFLUX_TOKEN")).
final char[] token = (System.getenv("INFLUX_TOKEN")).
toCharArray();
try (InfluxDBClient client = InfluxDBClient.getInstance(hostUrl,
authToken, database)) {
try (InfluxDBClient client = InfluxDBClient.getInstance(host,
token, database)) {
String sql =
"""
SELECT time, room, temp, hum, co
@ -908,9 +905,9 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and an `infl
1. Calls `InfluxDBClient.getInstance()` to instantiate a client configured
with InfluxDB credentials.
- **`hostUrl`**: your {{% cloud-name %}} cluster URL
- **`host`**: your {{% cloud-name %}} cluster URL
- **`database`**: the name of the {{% cloud-name %}} database to write to
- **`authToken`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database.
- **`token`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with read permission on the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
2. Defines a string variable (`sql`) for the SQL query.
3. Defines a Markdown table format layout for headings and data rows.
@ -944,7 +941,7 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and an `infl
}
```
- The `App`, `Write`, and `Query` classes are part of the same `com.influxdbv3` package (your project **groupId**).
- The `App`, `Write`, and `Query` classes belong to the `com.influxdbv3` package (your project **groupId**).
- `App` defines a `main()` function that calls `Write.writeLineProtocol()` and `Query.querySQL()`.
4. In your terminal or editor, use Maven to to install dependencies and compile the project code--for example:
@ -978,7 +975,6 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and an `infl
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END JAVA CONTENT ------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
### Query results

63
content/influxdb/cloud-dedicated/get-started/write.md
View File

@ -186,7 +186,7 @@ and then write it to {{< cloud-name >}}.
files = ["home.lp"]
```
- **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]` section, replace the default values with the following configuration for your InfluxDB Cloud Dedicated cluster:
- **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]` section, replace the default values with the following configuration for your {{% cloud-name %}} database:
```toml
[[outputs.influxdb_v2]]
@ -459,12 +459,11 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
"fmt"
"log"
"github.com/InfluxCommunity/influxdb3-go/influx"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
// Write line protocol data to InfluxDB
func WriteLineProtocol() error {
url := "https://cluster-id.influxdb.io"
// INFLUX_TOKEN is an environment variable you assigned to your
// database WRITE token value.
token := os.Getenv("INFLUX_TOKEN")
@ -472,17 +471,18 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
// 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},
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://{{< influxdb/host >}}",
Token: token,
Database: database,
WriteOptions: &influxdb3.WriteOptions{Precision: lineprotocol.Second},
})
// Close the client when the function returns.
defer func (client *influx.Client) {
defer func(client *influxdb3.Client) {
err := client.Close()
if err != nil {
panic(err)
panic(err)
}
}(client)
@ -522,7 +522,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
// Iterate over the lines array and write each line
// separately to InfluxDB
for _, record := range lines {
err = client.Write(context.Background(), database, []byte(record))
err = client.Write(context.Background(), []byte(record))
if err != nil {
log.Fatalf("Error writing line protocol: %v", err)
}
@ -543,11 +543,12 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
2. Defines a `WriteLineProtocol()` function that does the following:
1. To instantiate the client, calls the `influx.New(influx.Configs)` function and passes the following:
- **`HostURL`**: the {{% cloud-name %}} cluster URL
- **`AuthToken`**: an InfluxDB [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database.
1. To instantiate the client, calls the `influxdb3.New(influxdb3.ClientConfig)` function and passes the following:
- **`Host`**: the {{% cloud-name %}} cluster URL
- **`Database`**: The name of your {{% cloud-name %}} database
- **`Token`**: an InfluxDB [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`WriteParams`**: `influx.WriteParams` options for writing to InfluxDB.
- **`WriteOptions`**: `influxdb3.WriteOptions` options for writing to InfluxDB.
**Because the timestamps in the sample line protocol are in second
precision, the example passes the `Precision: lineprotocol.Second` option
@ -780,19 +781,19 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
public static async Task WriteLines()
{
// Set InfluxDB credentials
const string hostUrl = "https://cluster-id.influxdb.io";
const string host = "https://{{< influxdb/host >}}";
string? database = "get-started";
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* database WRITE token value.
*/
string? authToken = System.Environment
string? token = System.Environment
.GetEnvironmentVariable("INFLUX_TOKEN");
// Instantiate the InfluxDB client with credentials.
using var client = new InfluxDBClient(
hostUrl, authToken: authToken, database: database);
host, token: token, database: database);
/**
* Define an array of line protocol strings to write.
@ -847,9 +848,9 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
1. Calls the `new InfluxDBClient()` constructor to instantiate a client configured
with InfluxDB credentials.
- **`hostUrl`**: your {{% cloud-name %}} cluster URL
- **`host`**: your {{% cloud-name %}} cluster URL
- **`database`**: the name of the {{% cloud-name %}} database to write to
- **`authToken`**: an [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified bucket.
- **`token`**: an [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
_Instantiating the client with the `using` statement ensures that the client is disposed of when it's no longer needed._
@ -884,11 +885,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
and defines a `Main()` function that calls `Write.WriteLineProtocol()`.
The `dotnet` CLI recognizes `Program.Main()` as the entry point for your program.
7. To build and execute the program and write the line protocol to your {{% cloud-name %}} database, enter the following commands in your terminal:
```sh
dotnet build
```
7. To build and execute the program and write the line protocol to your {{% cloud-name %}} database, enter the following command in your terminal:
```sh
dotnet run
@ -913,7 +910,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
-Dversion="1.0"
```
The example command creates the `<artifactId>` directory (`./influxdb_java_client`) that
Maven creates the `<artifactId>` directory (`./influxdb_java_client`) that
contains a `pom.xml` and scaffolding for your `com.influxdbv3.influxdb_java_client` Java application.
3. In your terminal or editor, change into the `./influxdb_java_client` directory--for example:
@ -950,7 +947,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
import java.util.List;
import com.influxdb.v3.client.InfluxDBClient;
import com.influxdb.v3.client.write.WriteParameters;
import com.influxdb.v3.client.write.WriteOptions;
import com.influxdb.v3.client.write.WritePrecision;
/**
@ -971,19 +968,19 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
public static void writeLineProtocol() throws Exception {
// Set InfluxDB credentials
final String hostUrl = "https://cluster-id.influxdb.io";
final String host = "https://{{< influxdb/host >}}";
final String database = "get-started";
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* database WRITE token value.
*/
final char[] authToken = (System.getenv("INFLUX_TOKEN")).
final char[] token = (System.getenv("INFLUX_TOKEN")).
toCharArray();
// Instantiate the InfluxDB client.
try (InfluxDBClient client = InfluxDBClient.getInstance(hostUrl,
authToken, database)) {
try (InfluxDBClient client = InfluxDBClient.getInstance(host,
token, database)) {
// Create a list of line protocol records.
final List<String> records = List.of(
"home,room=Living\\ Room temp=21.1,hum=35.9,co=0i 1641024000",
@ -1020,7 +1017,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
* If no error occurs, print a success message.
* */
for (String record : records) {
client.writeRecord(record, new WriteParameters(null, null,
client.writeRecord(record, new WriteOptions(null, null,
WritePrecision.S));
System.out.printf("Data has been written successfully:
%s%n", record);
@ -1042,9 +1039,9 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
2. Calls `InfluxDBClient.getInstance()` to instantiate a client configured
with InfluxDB credentials.
- **`hostUrl`**: your {{% cloud-name %}} cluster URL
- **`host`**: your {{% cloud-name %}} cluster URL
- **`database`**: the name of the {{% cloud-name %}} database to write to
- **`authToken`**: an [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database.
- **`token`**: an [database token](/influxdb/cloud-dedicated/admin/tokens/) with _write_ access to the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
2. Defines a list of line protocol strings where each string represents a data record.

43
content/influxdb/cloud-dedicated/process-data/tools/pandas.md
View File

@ -15,23 +15,20 @@ influxdb/cloud-dedicated/tags: [analysis, pandas, pyarrow, python]
aliases:
- /influxdb/cloud-dedicated/visualize-data/pandas/
related:
- /influxdb/cloud-dedicated/query-data/sql/execute-queries/python/
- /influxdb/cloud-dedicated/query-data/execute-queries/client-libraries/python/
- /influxdb/cloud-dedicated/process-data/tools/pyarrow/
list_code_example: |
```py
...
dataframe = reader.read_pandas()
dataframe = dataframe.set_index('time')
print(dataframe.index)
resample = dataframe.resample("1H")
resample['temp'].mean()
```
```py
...
dataframe = reader.read_pandas()
dataframe = dataframe.set_index('time')
resample = dataframe.resample("1H")
resample['temp'].mean()
```
---
Use [pandas](https://pandas.pydata.org/), the Python data analysis library, to process, analyze, and visualize data
stored in InfluxDB.
stored in an {{% cloud-name %}} database.
> **pandas** is an open source, BSD-licensed library providing high-performance,
> easy-to-use data structures and data analysis tools for the Python programming language.
@ -52,7 +49,7 @@ stored in InfluxDB.
## Install prerequisites
The examples in this guide assume using a Python virtual environment and the InfluxDB v3 [`influxdb3-python` Python client library](/influxdb/cloud-dedicated/reference/client-libraries/v3/python/).
For more information, see how to [get started using Python to query InfluxDB](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/python/).
For more information, see how to [get started using Python to query InfluxDB](/influxdb/cloud-dedicated/query-data/execute-queries/client-libraries/python/).
Installing `influxdb3-python` also installs the [`pyarrow`](https://arrow.apache.org/docs/python/index.html) library that provides Python bindings for Apache Arrow.
@ -60,7 +57,7 @@ Installing `influxdb3-python` also installs the [`pyarrow`](https://arrow.apache
To use pandas, you need to install and import the `pandas` library.
In your terminal, use `pip` to install `pandas` in your active [Python virtual environment](/influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/python/#venv-install):
In your terminal, use `pip` to install `pandas` in your active [Python virtual environment](/influxdb/cloud-dedicated/query-data/execute-queries/python/#create-a-project-virtual-environment):
```sh
pip install pandas
@ -70,7 +67,7 @@ pip install pandas
The following steps use Python, `influxdb3-python`, and `pyarrow` to query InfluxDB and stream Arrow data to a pandas `DataFrame`.
1. In your editor, copy and paste the following code to a new file--for example, `pandas-example.py`:
1. In your editor, copy and paste the following code to a new file--for example, `pandas-example.py`:
{{% tabs-wrapper %}}
{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}
@ -105,12 +102,12 @@ print(dataframe)
{{% /code-placeholders %}}
{{% /tabs-wrapper %}}
2. Replace the following configuration values:
2. Replace the following configuration values:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: An InfluxDB [token](/influxdb/cloud-dedicated/admin/tokens/) with read permissions on the databases you want to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: The name of the InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/) to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/) to query
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: an InfluxDB [token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ permission on the specified database
3. In your terminal, use the Python interpreter to run the file:
3. In your terminal, use the Python interpreter to run the file:
```sh
python pandas-example.py
@ -213,8 +210,8 @@ print(dataframe.to_markdown())
Replace the following configuration values:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: An InfluxDB [token](/influxdb/cloud-dedicated/admin/tokens/) with read permissions on the databases you want to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: The name of the InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/) to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: The name of the InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/) to query.
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: An InfluxDB [token](/influxdb/cloud-dedicated/admin/tokens/) with read permission on the specified database.
### Downsample time series
@ -244,7 +241,7 @@ print(resample['temp'].mean())
{{< expand-wrapper >}}
{{% expand "View example results" %}}
```sh
time
time
2023-07-16 22:00:00 NaN
2023-07-16 23:00:00 22.600000
2023-07-17 00:00:00 22.513889

24
content/influxdb/cloud-dedicated/query-data/execute-queries/_index.md Normal file
View File

@ -0,0 +1,24 @@
---
title: Execute queries
description: >
Use tools and libraries to query data stored in InfluxDB Cloud Dedicated.
weight: 201
menu:
influxdb_cloud_dedicated:
name: Execute queries
parent: Query data
influxdb/cloud-dedicated/tags: [query, sql, influxql]
aliases:
- /influxdb/cloud-dedicated/query-data/tools/
- /influxdb/cloud-dedicated/query-data/sql/execute-queries/
- /influxdb/cloud-dedicated/query-data/influxql/execute-queries/
---
Use tools and libraries to query data stored in an {{% cloud-name %}} bucket.
InfluxDB client libraries and Flight clients can use the Flight+gRPC protocol to query with SQL or InfluxQL and retrieve data in the [Arrow in-memory format](https://arrow.apache.org/docs/format/Columnar.html).
HTTP clients can use the InfluxDB v1 `/query` REST API to query with InfluxQL and retrieve data in formatted as JSON.
Learn how to connect to InfluxDB and query your data using the following tools:
{{< children readmore=true hr=true hlevel="h2" >}}

22
content/influxdb/cloud-dedicated/query-data/execute-queries/client-libraries/_index.md Normal file
View File

@ -0,0 +1,22 @@
---
title: Use InfluxDB client libraries and SQL or InfluxQL to query data
list_title: Use client libraries
description: >
Use the InfluxDB v3 client libraries with SQL or InfluxQL to query data stored in InfluxDB.
InfluxDB v3 client libraries are language-specific packages that integrate with your application.
Execute queries and retrieve data and metadata over the Flight+gRPC protocol, and then process data using tools in the language of your choice.
weight: 30
menu:
influxdb_cloud_dedicated:
name: Use client libraries
parent: Execute queries
influxdb/cloud-dedicated/tags: [client libraries, SQL, InfluxQL, API, Flight, developer tools]
related:
- /influxdb/cloud-dedicated/reference/client-libraries/v3/
---
Use the InfluxDB v3 client libraries with SQL or InfluxQL to query data stored in InfluxDB.
InfluxDB v3 client libraries are language-specific packages that integrate with your application.
Execute queries and retrieve data and metadata over the Flight+gRPC protocol, and then process data using tools in the language of your choice.
{{< children depth="999" description="true" >}}

345
content/influxdb/cloud-dedicated/query-data/execute-queries/client-libraries/go.md Normal file
View File

@ -0,0 +1,345 @@
---
title: Use Go to query data
seotitle: Use Go and SQL or InfluxQL to query data
list_title: Use Go
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.
weight: 401
menu:
influxdb_cloud_dedicated:
parent: Use client libraries
name: Use Go
identifier: query-with-go
metadata: [InfluxQL, SQL]
influxdb/cloud-dedicated/tags: [query, flight, go, sql, influxql]
related:
- /influxdb/cloud-dedicated/reference/client-libraries/v3/go/
- /influxdb/cloud-dedicated/reference/sql/
- /influxdb/cloud-dedicated/reference/client-libraries/flight/
list_code_example: |
```go
import (
"context"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
func Query() error {
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://cluster-id.influxdb.io",
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'`
iterator, err := client.Query(context.Background(), query)
...
}
```
---
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.
<!-- TOC -->
- [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)
<!-- /TOC -->
## 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 {{% cloud-name %}} 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
```
- [`influxdb3-go`](https://github.com/InfluxCommunity/influxdb3-go) {{< req text="\* " color="magenta" >}}: 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](/influxdb/cloud-dedicated/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:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/) to query
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: an InfluxDB [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ permission on the specified database
{{% tabs-wrapper %}}
{{% tabs %}}
[SQL](#)
[InfluxQL](#)
{{% /tabs %}}
{{% tab-content %}}
<!---- BEGIN SQL EXAMPLE --->
{{% influxdb/custom-timestamps %}}
#### Query using SQL
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```go
// query.go
package main
import (
"context"
"fmt"
"io"
"os"
"text/tabwriter"
"time"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
"github.com/apache/arrow/go/v12/arrow"
)
func Query() error {
// Instantiate the client.
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://{{< influxdb/host >}}",
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 arrow and time packages to format unix timestamp
// as a time with timezone layout (RFC3339)
time := (row["time"].(arrow.Timestamp)).
ToTime(arrow.TimeUnit(arrow.Nanosecond)).
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()
}
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
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.
<!---- END SQL EXAMPLE ---->
{{% /tab-content %}}
{{% tab-content %}}
<!---- BEGIN INFLUXQL EXAMPLE ---->
{{% influxdb/custom-timestamps %}}
#### Query using InfluxQL
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```go
// query.go
package main
import (
"context"
"fmt"
"io"
"os"
"text/tabwriter"
"time"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
"github.com/apache/arrow/go/v12/arrow"
)
func InfluxQL() error {
// Instantiate the client.
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://{{< influxdb/host >}}",
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 arrow and time packages to format unix timestamp
// as a time with timezone layout (RFC3339)
time := (row["time"].(arrow.Timestamp)).
ToTime(arrow.TimeUnit(arrow.Nanosecond)).
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()
}
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
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 INFLUXQL EXAMPLE ---->
{{% /tab-content %}}
{{% /tabs-wrapper %}}
### 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.

151
content/influxdb/cloud-dedicated/query-data/sql/execute-queries/python.md → content/influxdb/cloud-dedicated/query-data/execute-queries/client-libraries/python.md
View File

@ -1,23 +1,31 @@
---
title: Use Python to query data with SQL
title: Use Python to query data
seotitle: Use Python and SQL or InfluxQL to query data
list_title: Use Python
description: >
Use the `influxdb_client_3` Python module and SQL to query data stored in InfluxDB.
Use the `influxdb_client_3` Python module 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 Python tools.
weight: 401
menu:
influxdb_cloud_dedicated:
parent: sql-execute-queries
parent: Use client libraries
name: Use Python
identifier: query-with-python-sql
influxdb/cloud-dedicated/tags: [query, flightsql, python, sql]
influxdb/cloud-dedicated/tags: [query, flight, python, sql, influxql]
aliases:
- /influxdb/cloud-dedicated/query-data/execute-queries/flight-sql/python/
- /influxdb/cloud-dedicated/query-data/execute-queries/influxql/python/
- /influxdb/cloud-dedicated/query-data/execute-queries/sql/python/
- /influxdb/cloud-dedicated/query-data/tools/python/
related:
- /influxdb/cloud-dedicated/reference/client-libraries/v3/python/
- /influxdb/cloud-dedicated/process-data/tools/pandas/
- /influxdb/cloud-dedicated/process-data/tools/pyarrow/
- /influxdb/cloud-dedicated/query-data/influxql/
- /influxdb/cloud-dedicated/query-data/sql/
- /influxdb/cloud-dedicated/reference/influxql/
- /influxdb/cloud-dedicated/reference/sql/
list_code_example: |
```py
from influxdb_client_3 import InfluxDBClient3
@ -40,8 +48,8 @@ list_code_example: |
```
---
Use the InfluxDB `influxdb_client_3` Python client library module and SQL to query data stored in InfluxDB.
Execute queries and retrieve data over the Flight protocol, and then process data using common Python tools.
Use the InfluxDB `influxdb_client_3` Python client library module 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 Python tools.
- [Get started using Python to query InfluxDB](#get-started-using-python-to-query-influxdb)
- [Create a Python virtual environment](#create-a-python-virtual-environment)
@ -55,12 +63,18 @@ Execute queries and retrieve data over the Flight protocol, and then process dat
## Get started using Python to query InfluxDB
This guide follows the recommended practice of using Python _virtual environments_.
If you don't want to use virtual environments and you have Python installed,
continue to [Query InfluxDB](#query-influxdb).
This guide assumes the following prerequisites:
- an {{% cloud-name %}} [database](/influxdb/cloud-dedicated/admin/databases/) with data to query
- a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the database
To learn how to set up InfluxDB and write data, see the [Setup instructions](/influxdb/cloud-dedicated/get-started/setup/) in the Get Started tutorial.
## Create a Python virtual environment
This guide follows the recommended practice of using Python _virtual environments_.
If you don't want to use virtual environments and you have Python installed,
continue to [Query InfluxDB](#query-influxdb).
Python [virtual environments](https://docs.python.org/3/library/venv.html) keep
the Python interpreter and dependencies for your project self-contained and isolated from other projects.
@ -122,7 +136,7 @@ to install a recent version of the Python programming language for your system.
`venv` creates the new virtual environment directory in your project.
3. To activate the new virtual environment in your terminal, run the `source` command and pass the file path of the virtual environment `activate` script:
3. To activate the new virtual environment in your terminal, run the `source` command and pass the path of the virtual environment `activate` script:
```sh
source envs/VIRTUAL_ENVIRONMENT_NAME/bin/activate
@ -190,14 +204,9 @@ When a virtual environment is activated, the name displays at the beginning of y
The `influxdb3-python` package provides the `influxdb_client_3` module for integrating {{% cloud-name %}} with your Python code.
The module supports writing data to InfluxDB and querying data using SQL or InfluxQL.
{{% note %}}
_To query data with **InfluxQL** and Python, see
[Use InfluxQL with Python](/influxdb/cloud-dedicated/query-data/influxql/execute-queries/python/)._
{{% /note %}}
Install the following dependencies:
{{< req type="key" text="Already installed in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" >}}
{{% req type="key" text="Already installed in the [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" %}}
- `influxdb3-python` {{< req text="\* " color="magenta" >}}: Provides the `influxdb_client_3` module and also installs the [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries.
- `pandas`: Provides [pandas modules](https://pandas.pydata.org/) for analyzing and manipulating data.
@ -215,7 +224,7 @@ analyze data stored in an InfluxDB database.
### Create an InfluxDB client
The following example shows how to use Python with the `influxdb_client_3`
module to instantiate a client configured for an {{% cloud-name %}} bucket.
module to instantiate a client configured for an {{% cloud-name %}} database.
In your editor, copy and paste the following sample code to a new file--for
example, `query-example.py`:
@ -225,7 +234,6 @@ example, `query-example.py`:
# query-example.py
from influxdb_client_3 import InfluxDBClient3
import pandas
# Instantiate an InfluxDBClient3 client configured for your database
client = InfluxDBClient3(
@ -247,12 +255,11 @@ If using a non-POSIX-compliant operating system (such as Windows), specify the r
pip install certifi
```
2. In your Python code, import `certifi` and call the `certifi.where()` method to retrieve the root certificate path.
2. In your Python code, import `certifi` and call the `certifi.where()` method to retrieve the certificate path.
3. When instantiating the client, pass the `flight_client_options.tls_root_certs=<ROOT_CERT_PATH>` option with the certificate path.
The following example shows how to use the Python `certifi` package and client library options to pass the certificate path:
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
{{< code-callout "flight_client_options|tls_root_certs|(cert\b)" >}}
```py
@ -281,23 +288,33 @@ For more information, see [`influxdb_client_3` query exceptions](/influxdb/cloud
Replace the following configuration values:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Your InfluxDB token with read permissions on the databases you want to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
The name of your {{% cloud-name %}} database.
- **`database`**: the name of the [{{% cloud-name %}} database](/influxdb/cloud-dedicated/admin/buckets/) to query
- **`token`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
### Execute a query
To execute an SQL query, call the client's [`query(query,language)` method](/influxdb/cloud-dedicated/reference/client-libraries/v3/python/#influxdbclient3query) and
specify the following arguments:
To execute a query, call the following client method:
- **query**: SQL query string to execute.
- **language**: `sql`
[`query(query,language)` method](/influxdb/cloud-dedicated/reference/client-libraries/v3/python/#influxdbclient3query)
and specify the following arguments:
- **query**: A string. The SQL or InfluxQL query to execute.
- **language**: A string (`"sql"` or `"influxql"`). The `query` language.
#### Example {#execute-query-example}
The following example shows how to use SQL to select all fields in a measurement, and then output the results formatted as a Markdown table.
The following examples shows how to use SQL or InfluxQL to select all fields in a measurement, and then output the results formatted as a Markdown table.
{{% code-tabs-wrapper %}}
{{% code-tabs %}}
[SQL](#)
[InfluxQL](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!---- BEGIN SQL EXAMPLE --->
{{% influxdb/custom-timestamps %}}
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```py
# query-example.py
@ -316,10 +333,82 @@ table = client.query(
language="sql"
)
# Return query results as a markdown table
print(table.to_pandas().to_markdown())
print("\n#### View Schema information\n")
print(table.schema)
print(table.schema.names)
print(table.schema.types)
print(table.field('room').type)
print(table.schema.field('time').metadata)
print("\n#### View column types (timestamp, tag, and field) and data types\n")
print(table.schema.field('time').metadata[b'iox::column::type'])
print(table.schema.field('room').metadata[b'iox::column::type'])
print(table.schema.field('temp').metadata[b'iox::column::type'])
print("\n#### Use PyArrow to read the specified columns\n")
print(table.column('temp'))
print(table.select(['room', 'temp']))
print(table.select(['time', 'room', 'temp']))
print("\n#### Use PyArrow compute functions to aggregate data\n")
print(table.group_by('hum').aggregate([]))
print(table.group_by('room').aggregate([('temp', 'mean')]))
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
<!---- END SQL EXAMPLE ---->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!---- BEGIN INFLUXQL EXAMPLE ---->
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```py
# query-example.py
from influxdb_client_3 import InfluxDBClient3
client = InfluxDBClient3(
host='{{< influxdb/host >}}',
token='DATABASE_TOKEN',
database='DATABASE_NAME'
)
# Execute the query and return an Arrow table
table = client.query(
query="SELECT * FROM home",
language="influxql"
)
print("\n#### View Schema information\n")
print(table.schema)
print(table.schema.names)
print(table.schema.types)
print(table.field('room').type)
print(table.schema.field('time').metadata)
print("\n#### View column types (timestamp, tag, and field) and data types\n")
print(table.schema.field('time').metadata[b'iox::column::type'])
print(table.schema.field('room').metadata[b'iox::column::type'])
print(table.schema.field('temp').metadata[b'iox::column::type'])
print("\n#### Use PyArrow to read the specified columns\n")
print(table.column('temp'))
print(table.select(['room', 'temp']))
print(table.select(['time', 'room', 'temp']))
print("\n#### Use PyArrow compute functions to aggregate data\n")
print(table.group_by('hum').aggregate([]))
print(table.group_by('room').aggregate([('temp', 'mean')]))
```
{{% /code-placeholders %}}
<!---- END INFLUXQL EXAMPLE ---->
{{% /code-tab-content %}}
{{% /code-tabs-wrapper %}}
Replace the following configuration values:
- **`database`**: the name of the [{{% cloud-name %}} database](/influxdb/cloud-dedicated/admin/buckets/) to query
- **`token`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
Next, learn how to use Python tools to work with time series data:

33
content/influxdb/cloud-dedicated/query-data/influxql/execute-queries/influxdb-v1-api.md → content/influxdb/cloud-dedicated/query-data/execute-queries/influxdb-v1-api.md
View File

@ -1,15 +1,21 @@
---
title: Use the InfluxDB v1 HTTP query API to query with InfluxQL
title: Use the InfluxDB v1 HTTP query API and InfluxQL to query data
seotitle: Use InfluxQL and InfluxDB v1 HTTP query API
list_title: Use the v1 query API and InfluxQL
description: >
Use the InfluxDB v1 HTTP query API to query data in InfluxDB Cloud Dedicated
with InfluxQL.
weight: 401
menu:
influxdb_cloud_dedicated:
parent: influxql-execute-queries
parent: Execute queries
name: Use the v1 query API
influxdb/cloud-dedicated/tags: [query, influxql, python]
metadata: [InfluxQL]
related:
- /influxdb/cloud-dedicated/api-compatibility/v1/
aliases:
- /influxdb/cloud-dedicated/query-data/influxql/execute-queries/influxdb-v1-api/
list_code_example: |
```sh
curl --get https://cluster-id.influxdb.io/query \
@ -43,25 +49,25 @@ Provide the following with your request:
- **Headers:**
- **Authorization:** `Bearer DATABASE_TOKEN`
- **Query parameters:**
- **db**: Database to query
- **rp**: _(Optional)_ Retention policy to query
- **db**: the database to query
- **rp**: Optional: the retention policy to query
- **q**: URL-encoded InfluxQL query
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```sh
curl --get https://cluster-id.influxdb.io/query \
--header "Authorization: Token DATABASE_TOKEN" \
curl --get https://{{< influxdb/host >}}/query \
--header "Authorization: Bearer DATABASE_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}
Replace the following:
Replace the following configuration values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
Name of the database to query
the name of the [database](/influxdb/cloud-dedicated/admin/databases/) to query.
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database.
{{% note %}}
#### Authenticate with username and password
@ -69,9 +75,8 @@ Replace the following:
If using basic authentication or query string authentication (username and password)
to interact with the v1 HTTP query API, provide the following credentials:
- **username**: Arbitrary string _({{< cloud-name >}} ignores the username)_
- **password**: [Database token](/influxdb/cloud-dedicated/admin/tokens/) with read permission
on the database you want to query
- **username**: an arbitrary string _({{< cloud-name >}} ignores the username)_
- **password**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database.
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
@ -120,7 +125,3 @@ curl --get https://cluster-id.influxdb.io/query \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}
<!--
TO-DO: Explain how DBRP mappings work with bucket names
-->

47
content/influxdb/cloud-dedicated/query-data/execute-queries/visualization-tools.md Normal file
View File

@ -0,0 +1,47 @@
---
title: Use visualization tools to query data
list_title: Use visualization tools
description: >
Use visualization tools and SQL or InfluxQL to query data stored in InfluxDB.
weight: 401
menu:
influxdb_cloud_dedicated:
parent: Execute queries
name: Use visualization tools
identifier: query-with-visualization-tools
influxdb/cloud-dedicated/tags: [query, sql, influxql]
metadata: [SQL, InfluxQL]
aliases:
- /influxdb/cloud-dedicated/query-data/influxql/execute-queries/visualization-tools/
- /influxdb/cloud-dedicated/query-data/sql/execute-queries/visualization-tools/
related:
- /influxdb/cloud-dedicated/process-data/visualize/grafana/
- /influxdb/cloud-dedicated/process-data/visualize/superset/
- /influxdb/cloud-dedicated/process-data/visualize/tableau/
---
Use visualization tools to query data stored in {{% cloud-name %}} with SQL.
## Query using SQL
The following visualization tools support querying InfluxDB with SQL:
- [Grafana](/influxdb/cloud-dedicated/process-data/visualize/grafana/)
- [Superset](/influxdb/cloud-dedicated/process-data/visualize/superset/)
- [Tableau](/influxdb/cloud-dedicated/process-data/visualize/tableau/)
## Query using InfluxQL
The following visualization tools support querying InfluxDB with InfluxQL:
- [Grafana](/influxdb/cloud-dedicated/process-data/visualize/grafana/?t=InfluxQL)
- [Chronograf](/influxdb/cloud-dedicated/process-data/visualize/chronograf/)
{{% warn %}}
#### InfluxQL feature support
InfluxQL is being rearchitected to work with the InfluxDB IOx storage engine.
This process is ongoing and some InfluxQL features are still being implemented.
For information about the current implementation status of InfluxQL features,
see [InfluxQL feature support](/influxdb/cloud-dedicated/reference/influxql/feature-support/).
{{% /warn %}}

18
content/influxdb/cloud-dedicated/query-data/influxql/execute-queries/_index.md
View File

@ -1,18 +0,0 @@
---
title: Execute InfluxQL queries
description: >
Use tools and libraries to query data with InfluxQL stored in InfluxDB Cloud Dedicated.
weight: 201
menu:
influxdb_cloud_dedicated:
name: Execute InfluxQL queries
parent: Query with InfluxQL
identifier: influxql-execute-queries
influxdb/cloud-dedicated/tags: [query, influxql]
---
Choose from the following options for executing InfluxQL queries with {{< cloud-name >}}:
{{< children type="anchored-list" >}}
{{< children readmore=true hr=true >}}

285
content/influxdb/cloud-dedicated/query-data/influxql/execute-queries/python.md
View File

@ -1,285 +0,0 @@
---
title: Use Python to query data with InfluxQL
description: >
Use Python and the `influxdb3-python` library to query data stored in InfluxDB
with InfluxQL.
weight: 401
menu:
influxdb_cloud_dedicated:
parent: influxql-execute-queries
name: Use Python
identifier: query-with-python-influxql
influxdb/cloud-dedicated/tags: [query, influxql, python]
related:
- /influxdb/cloud-dedicated/process-data/tools/pandas/
- /influxdb/cloud-dedicated/process-data/tools/pyarrow/
- /influxdb/cloud-dedicated/reference/influxql/
list_code_example: |
```py
from influxdb_client_3 import InfluxDBClient3
# Instantiate an InfluxDB client
client = InfluxDBClient3(
host='cluster-id.influxdb.io',
token='DATABASE_TOKEN',
database='DATABASE_NAME'
)
# Execute the query and return an Arrow table
table = client.query(
query="SELECT * FROM home",
language="influxql"
)
# Return query results as a markdown table
print(table.to_pandas().to_markdown())
```
---
Use the `influxdb3-python` client library to query data stored in InfluxDB with InfluxQL.
The `influxdb3-client` uses InfluxDB v3's Flight RPC protocol to query data from InfluxDB and return
results in Apache Arrow format.
- [Get started using Python to query InfluxDB](#get-started-using-python-to-query-influxdb)
- [Create a Python virtual environment](#create-a-python-virtual-environment)
- [Install Python](#install-python)
- [Create a project virtual environment](#venv-install)
- [Install Anaconda](?t=Anaconda#conda-install)
- [Query InfluxDB](#query-influxdb)
- [Install the influxdb3-python library](#install-the-influxdb3-python-library)
- [Create an InfluxDB client](#create-an-influxdb-client)
- [Execute a query](#execute-a-query)
{{% warn %}}
#### InfluxQL feature support
InfluxQL is being rearchitected to work with the InfluxDB IOx storage engine.
This process is ongoing and some InfluxQL features are still being implemented.
For information about the current implementation status of InfluxQL features,
see [InfluxQL feature support](/influxdb/cloud-dedicated/reference/influxql/feature-support/).
{{% /warn %}}
## Get started using Python to query InfluxDB
This guide follows the recommended practice of using Python _virtual environments_.
If you don't want to use virtual environments and you have Python installed,
continue to [Query InfluxDB](#query-influxdb).
## Create a Python virtual environment
Python [virtual environments](https://docs.python.org/3/library/venv.html) keep
the Python interpreter and dependencies for your project self-contained and isolated from other projects.
To install Python and create a virtual environment, choose one of the following options:
- [Python venv](?t=venv#venv-install): The [`venv` module](https://docs.python.org/3/library/venv.html) comes standard in Python as of version 3.5.
- [Anaconda® Distribution](?t=Anaconda#conda-install): A Python/R data science distribution that provides Python and the **conda** package and environment manager.
{{< tabs-wrapper >}}
{{% tabs "small" %}}
[venv]()
[Anaconda]()
{{% /tabs %}}
{{% tab-content %}}
<!--------------------------------- Begin venv -------------------------------->
### Install Python
1. Follow the [Python installation instructions](https://wiki.python.org/moin/BeginnersGuide/Download)
to install a recent version of the Python programming language for your system.
2. Check that you can run `python` and `pip` commands.
`pip` is a package manager included in most Python distributions.
In your terminal, enter the following commands:
```sh
python --version
```
```sh
pip --version
```
Depending on your system, you may need to use version-specific commands--for example.
```sh
python3 --version
```
```sh
pip3 --version
```
If neither `pip` nor `pip<PYTHON_VERSION>` works, follow one of the [Pypa.io Pip installation](https://pip.pypa.io/en/stable/installation/) methods for your system.
### Create a project virtual environment {#venv-install}
1. Create a directory for your Python project and change to the new directory--for example:
```sh
mkdir ./PROJECT_DIRECTORY && cd $_
```
2. Use the Python `venv` module to create a virtual environment--for example:
```sh
python -m venv envs/virtualenv-1
```
`venv` creates the new virtual environment directory in your project.
3. To activate the new virtual environment in your terminal, run the `source` command and pass the file path of the virtual environment `activate` script:
```sh
source envs/VIRTUAL_ENVIRONMENT_NAME/bin/activate
```
For example:
```sh
source envs/virtualenv-1/bin/activate
```
<!---------------------------------- End venv --------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!-------------------------------- Begin conda -------------------------------->
### Install Anaconda {#conda-install}
1. Follow the [Anaconda installation instructions](https://docs.continuum.io/anaconda/install/) for your system.
2. Check that you can run the `conda` command:
```sh
conda
```
3. Use `conda` to create a virtual environment--for example:
```sh
conda create --prefix envs/virtualenv-1
```
`conda` creates a virtual environment in a directory named `./envs/virtualenv-1`.
4. To activate the new virtual environment, use the `conda activate` command and pass the directory path of the virtual environment:
```sh
conda activate envs/VIRTUAL_ENVIRONMENT_NAME
```
For example:
```sh
conda activate ./envs/virtualenv-1
```
<!--------------------------------- END conda --------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
When a virtual environment is activated, the name displays at the beginning of your terminal command line--for example:
{{% code-callout "(virtualenv-1)"%}}
```sh
(virtualenv-1) $ PROJECT_DIRECTORY
```
{{% /code-callout %}}
## Query InfluxDB
1. [Install the influxdb3-python library](#install-the-influxdb3-python-library)
2. [Create an InfluxDB client](#create-an-influxdb-client)
3. [Execute a query](#execute-a-query)
### Install the influxdb3-python library
The `influxdb_client_3` module provides a simple and convenient way to interact
with {{< cloud-name >}} using Python. This module supports both writing data to
InfluxDB and querying data using SQL or InfluxQL queries.
Installing `inflxudb3-python` also installs the
[`pyarrow`](https://arrow.apache.org/docs/python/index.html) library that you'll
use for working with Arrow data returned from queries.
In your terminal, use `pip` to install `influxdb3-python`:
```sh
pip install influxdb3-python
```
With `influxdb3-python` and `pyarrow` installed, you're ready to query and
analyze data stored in an InfluxDB database.
### Create an InfluxDB client
The following example shows how to use Python with `influxdb3-python`
and to instantiate a client configured for an InfluxDB database.
In your editor, copy and paste the following sample code to a new file--for
example, `query-example.py`:
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```py
# query-example.py
from influxdb_client_3 import InfluxDBClient3
# Instantiate an InfluxDBClient3 client configured for your database
client = InfluxDBClient3(
host='cluster-id.influxdb.io',
token='DATABASE_TOKEN',
database='DATABASE_NAME'
)
```
{{% /code-placeholders %}}
Replace the following configuration values:
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}:
Your InfluxDB token with read permissions on the databases you want to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
The name of your InfluxDB database.
### Execute a query
To execute an InfluxQL query, call the client's `query(query,language)` method
and specify the following arguments:
- **query**: InfluxQL query string to execute.
- **language**: `influxql`
#### Syntax {#execute-query-syntax}
```py
query(query: str, language: str)
```
#### Example {#execute-query-example}
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```py
# query-example.py
from influxdb_client_3 import InfluxDBClient3
client = InfluxDBClient3(
host='cluster-id.influxdb.io',
token='DATABASE_TOKEN',
database='DATABASE_NAME'
)
# Execute the query and return an Arrow table
table = client.query(
query="SELECT * FROM home",
language="influxql"
)
# Return query results as a markdown table
print(table.to_pandas().to_markdown())
```
{{% /code-placeholders %}}
Next, learn how to use Python tools to work with time series data:
- [Use PyArrow](/influxdb/cloud-dedicated/process-data/tools/pyarrow/)
- [Use pandas](/influxdb/cloud-dedicated/process-data/tools/pandas/)

28
content/influxdb/cloud-dedicated/query-data/influxql/execute-queries/visualization-tools.md
View File

@ -1,28 +0,0 @@
---
title: Use visualization tools query data with InfluxQLQL
list_title: Use visualization tools
description: >
Use visualization tools and InfluxQL to query data stored in InfluxDB.
weight: 403
menu:
influxdb_cloud_dedicated:
parent: influxql-execute-queries
name: Use visualization tools
identifier: query-with-visualization-tools-influxql
influxdb/cloud-dedicated/tags: [query, influxql]
---
Use visualization tools to query data stored in {{% cloud-name %}} with InfluxQL.
The following visualization tools support querying InfluxDB with InfluxQL:
- [Grafana](/influxdb/cloud-dedicated/process-data/visualize/grafana/?t=InfluxQL)
- [Chronograf](/influxdb/cloud-dedicated/process-data/visualize/chronograf/)
{{% warn %}}
#### InfluxQL feature support
InfluxQL is being rearchitected to work with the InfluxDB IOx storage engine.
This process is ongoing and some InfluxQL features are still being implemented.
For information about the current implementation status of InfluxQL features,
see [InfluxQL feature support](/influxdb/cloud-dedicated/reference/influxql/feature-support/).
{{% /warn %}}

31
content/influxdb/cloud-dedicated/query-data/sql/execute-queries/_index.md
View File

@ -1,31 +0,0 @@
---
title: Execute SQL queries
description: >
Use tools and libraries to query data with SQL stored in InfluxDB Cloud Dedicated.
weight: 201
menu:
influxdb_cloud_dedicated:
name: Execute SQL queries
parent: Query with SQL
identifier: sql-execute-queries
influxdb/cloud-dedicated/tags: [query, sql]
aliases:
- /influxdb/cloud-dedicated/query-data/execute-queries/
- /influxdb/cloud-dedicated/query-data/tools/
---
The InfluxDB SQL implementation uses [Arrow DataFusion](https://arrow.apache.org/datafusion/)
and the [Apache Arrow Flight SQL](https://arrow.apache.org/) protocol to query
data stored in an InfluxDB database.
> Arrow Flight SQL is a protocol for interacting with SQL databases using the
> [Arrow in-memory format](https://arrow.apache.org/docs/format/Columnar.html)
> and the [Flight RPC](https://arrow.apache.org/docs/format/Flight.html) framework.
>
> {{% caption %}}[Apache Arrow Flight SQL documentation](https://arrow.apache.org/docs/format/FlightSql.html){{% /caption %}}
Data platforms and clients that support the Flight SQL protocol can query data
stored in an InfluxDB database.
Learn how to connect to InfluxDB and query your data using the following tools:
{{< children readmore=true hr=true hlevel="h2" >}}

24
content/influxdb/cloud-dedicated/query-data/sql/execute-queries/visualization-tools.md
View File

@ -1,24 +0,0 @@
---
title: Use visualization tools query data with SQL
list_title: Use visualization tools
description: >
Use visualization tools and SQL to query data stored in InfluxDB.
weight: 401
menu:
influxdb_cloud_dedicated:
parent: sql-execute-queries
name: Use visualization tools
identifier: query-with-visualization-tools-sql
influxdb/cloud-dedicated/tags: [query, sql]
related:
- /influxdb/cloud-dedicated/process-data/visualize/grafana/
- /influxdb/cloud-dedicated/process-data/visualize/superset/
- /influxdb/cloud-dedicated/process-data/visualize/tableau/
---
Use visualization tools to query data stored in {{% cloud-name %}} with SQL.
The following visualization tools support querying InfluxDB with SQL:
- [Grafana](/influxdb/cloud-dedicated/process-data/visualize/grafana/)
- [Superset](/influxdb/cloud-dedicated/process-data/visualize/superset/)
- [Tableau](/influxdb/cloud-dedicated/process-data/visualize/tableau/)

4
content/influxdb/cloud-dedicated/reference/client-libraries/flight/_index.md
View File

@ -19,11 +19,11 @@ Flight RPC and Flight SQL clients are language-specific drivers that interact wi
Apache Arrow Flight RPC and Flight SQL protocols define APIs for servers and clients.
{{% note %}}
#### InfluxDB v3 client libraries
#### Use InfluxDB v3 client libraries
We recommend using [InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) for integrating InfluxDB v3 with your application code.
Client libraries wrap Apache Arrow Flight clients
and provide convenient methods for writing, querying, and processing data stored in {{% cloud-name %}}.
and provide convenient methods for [writing](/influxdb/cloud-dedicated/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-dedicated/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
{{% /note %}}
**Flight RPC clients** can use SQL or InfluxQL to query data stored in an {{% cloud-name %}} database.

13
content/influxdb/cloud-dedicated/reference/client-libraries/flight/csharp-flight.md
View File

@ -1,13 +1,10 @@
---
title: C# .NET Flight client
description: The C# .NET Flight client integrates with C# .NET scripts and applications to query data stored in InfluxDB.
external_url: https://github.com/apache/arrow/tree/main/csharp/examples/FlightClientExample
menu:
influxdb_cloud_dedicated:
name: C# .NET
parent: Arrow Flight clients
params:
url: https://github.com/apache/arrow/tree/main/csharp/examples/FlightClientExample
identifier: csharp-flight-client
influxdb/cloud-dedicated/tags: [C#, gRPC, SQL, Flight SQL, client libraries]
aliases:
@ -18,3 +15,13 @@ weight: 201
[Apache Arrow for C# .NET](https://github.com/apache/arrow/blob/main/csharp/README.md) integrates with C# .NET scripts and applications to query data stored in InfluxDB.
For more information, see the [C# client example on GitHub](https://github.com/apache/arrow/tree/main/csharp/examples/FlightClientExample).
{{% note %}}
#### Use InfluxDB v3 client libraries
We recommend using the [`influxdb3-csharp` C# client library](/influxdb/cloud-dedicated/reference/client-libraries/v3/csharp/) for integrating InfluxDB v3 with your C# application code.
[InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) wrap Apache Arrow Flight clients
and provide convenient methods for [writing](/influxdb/cloud-dedicated/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-dedicated/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
Client libraries can query using SQL or InfluxQL.
{{% /note %}}

17
content/influxdb/cloud-dedicated/reference/client-libraries/flight/go-flight.md
View File

@ -7,6 +7,8 @@ menu:
parent: Arrow Flight clients
identifier: go-flight-client
influxdb/cloud-dedicated/tags: [Go, gRPC, SQL, Flight SQL, client libraries]
related:
- /influxdb/cloud-dedicated/reference/client-libraries/v3/go/
aliases:
- /influxdb/cloud-dedicated/reference/client-libraries/flight-sql/go-flightsql/
weight: 201
@ -14,6 +16,16 @@ weight: 201
[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.
{{% note %}}
#### Use InfluxDB v3 client libraries
We recommend using the [`influxdb3-go` Go client library](/influxdb/cloud-dedicated/reference/client-libraries/v3/go/) for integrating InfluxDB v3 with your Go application code.
[InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) wrap Apache Arrow Flight clients
and provide convenient methods for [writing](/influxdb/cloud-dedicated/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-dedicated/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
Client libraries can query using SQL or InfluxQL.
{{% /note %}}
## Flight SQL client
### Example query using Flight SQL
@ -127,10 +139,11 @@ The following example shows how to use the Arrow Flight SQL client for Go to que
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.
- **`database`**: the name of the {{% cloud-name %}} database to query
- **`token`**: a [database token](/influxdb/cloud-dedicated/get-started/setup/#create-an-all-access-api-token) with read permission on 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 InfluxDB over the _gRPC+TLS_ protocol.

497
content/influxdb/cloud-dedicated/reference/client-libraries/flight/java-flightsql.md
View File

@ -1,20 +1,507 @@
---
title: Java Flight SQL package
description: The Java Flight SQL client integrates with Java applications to query and retrieve data from Flight database servers using RPC and SQL.
external_url: https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/sql/package-summary.html
menu:
influxdb_cloud_dedicated:
name: Java Flight SQL
parent: Arrow Flight clients
identifier: java-flightsql-client
params:
url: https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/sql/package-summary.html
influxdb/cloud-dedicated/tags: [Java, gRPC, SQL, Flight SQL, client libraries]
influxdb/cloud-dedicated/tags: [Java, gRPC, SQL, Flight SQL]
weight: 201
related:
- /influxdb/cloud-dedicated/reference/client-libraries/v3/java/
aliases:
- /influxdb/cloud-dedicated/reference/client-libraries/flight-sql/java-flightsql/
list_code_example: |
```java
public class Query {
public static void main(String[] args) {
String query = "SELECT * FROM home";
Location location = Location.forGrpcTls(HOST, 443);
CredentialCallOption auth = new CredentialCallOption(new BearerCredentialWriter(TOKEN));
BufferAllocator allocator = new RootAllocator(Long.MAX_VALUE);
FlightClientMiddleware.Factory f = info -> new FlightClientMiddleware() {
@Override
public void onBeforeSendingHeaders(CallHeaders outgoingHeaders) {
outgoingHeaders.insert(DATABASE_FIELD, DATABASE_NAME);
}
};
FlightClient client = FlightClient.builder(allocator, location)
.intercept(f)
.build();
FlightSqlClient sqlClient = new FlightSqlClient(client);
FlightInfo flightInfo = sqlClient.execute(query, auth);
}
}
---
[Apache Arrow Flight SQL for Java](https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/sql/package-summary.html) integrates with Java applications to query and retrieve data from Flight database servers using RPC and SQL.
<a href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/sql/package-summary.html" target="_blank" class="btn github">Java Flight SQL package</a>
{{% note %}}
#### Use InfluxDB v3 client libraries
We recommend using the [`influxdb3-java` Go client library](/influxdb/cloud-dedicated/reference/client-libraries/v3/java/) for integrating InfluxDB v3 with your Java application code.
[InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) client libraries wrap Apache Arrow Flight clients
and provide convenient methods for [writing](/influxdb/cloud-dedicated/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-dedicated/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
Client libraries can query using SQL or InfluxQL.
{{% /note %}}
<!-- TOC -->
- [Get started using the Java Flight SQL client to query InfluxDB](#get-started-using-the-java-flight-sql-client-to-query-influxdb)
- [Set up InfluxDB](#set-up-influxdb)
- [Install prerequisites](#install-prerequisites)
- [Create the FlightQuery class](#create-the-flightquery-class)
- [Create a query client](#create-a-query-client)
- [Execute a query](#execute-a-query)
- [Retrieve and process Arrow data](#retrieve-and-process-arrow-data)
- [Run the application](#run-the-application)
- [Troubleshoot Arrow Flight requests](#troubleshoot-arrow-flight-requests)
## Get started using the Java Flight SQL client to query InfluxDB
Write a Java class for a Flight SQL client that connects to {{% cloud-name %}},
executes an SQL query, and retrieves data stored in an {{% cloud-name %}} database.
The example uses the [Apache Arrow Java implementation (`org.apache.arrow`)](https://arrow.apache.org/docs/java/index.html) for interacting with Flight database servers like InfluxDB v3.
- **`org.apache.arrow`**: Provides classes and methods for integrating Java applications with Apache Arrow data and protocols.
- **`org.apache.arrow.flight.sql`**: Provides classes and methods for
interacting with Flight database servers using Arrow Flight RPC and Flight SQL.
1. [Set up InfluxDB](#set-up-influxdb)
2. [Install prerequisites](#install-prerequisites)
3. [Create the FlightQuery class](#create-the-flightquery-class)
4. [Create a query client](#create-a-query-client)
5. [Execute a query](#execute-a-query)
6. [Retrieve and process Arrow data](#retrieve-and-process-arrow-data)
To clone or download the example application that you can run with Docker, see the [InfluxCommunity/ArrowFlightClient_Query_Examples repository](https://github.com/InfluxCommunity/ArrowFlightClient_Query_Examples) on GitHub.
### Set up InfluxDB
To configure the application for querying {{% cloud-name %}}, you'll need the following InfluxDB resources:
- {{% cloud-name %}} **database**
- {{% cloud-name %}} **database token** with _read_ permission to the database
If you don't already have a database token and a database, see how to [set up InfluxDB](/influxdb/cloud-dedicated/get-started/setup/).
If you don't already have data to query, see how to
[write data](/influxdb/cloud-dedicated/get-started/write/) to a database.
### Install prerequisites
The following uses Docker and Maven to build and run the Java application and avoid platform-specific dependency problems.
The example `Dockerfile` installs compatible versions of Maven
and Java JDK in the Docker container, and then runs the Maven commands to download dependencies and compile the application.
Follow the instructions to download and install Docker for your system:
- **macOS**: [Install Docker for macOS](https://docs.docker.com/desktop/install/mac-install/)
- **Linux**: [Install Docker for Linux](https://docs.docker.com/desktop/install/linux-install/)
{{< expand-wrapper >}}
{{% expand "View the Dockerfile" %}}
```dockerfile
# Use the official Maven image as the base image
FROM maven:3.8.3-openjdk-11 AS build
# Set the working directory
WORKDIR /app
# Copy the pom.xml file into the container
COPY pom.xml .
# Download and cache dependencies
RUN mvn dependency:go-offline
# Copy the rest of the source code into the container
COPY src/ ./src/
# Compile the source code and copy dependencies
RUN mvn compile dependency:copy-dependencies
# Use the official OpenJDK image as the runtime base image
FROM openjdk:11-jre-slim
# Set the working directory
WORKDIR /app
# Copy the compiled classes and dependencies from the build stage
COPY --from=build /app/target/classes ./classes
COPY --from=build /app/target/dependency ./dependency
# Set ARGs for --build-arg options passed in the build command
ARG DATABASE_FIELD
ARG DATABASE_NAME
ARG HOST
ARG TOKEN
# Set run-time ENVs from ARGs
ENV DATABASE_FIELD=${DATABASE_FIELD}
ENV DATABASE_NAME=${DATABASE_NAME}
ENV HOST=${HOST}
ENV TOKEN=${TOKEN}
# Set the entrypoint to run your Java application
ENTRYPOINT ["java", "-cp", "classes:dependency/*", "com.influxdb.examples.FlightExamples"]
```
{{% /expand %}}
{{% expand "View the Maven pom.xml" %}}
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.influxdb</groupId>
<artifactId>examples</artifactId>
<version>1.0-SNAPSHOT</version>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.2.0</version>
<configuration>
<archive>
<manifest>
<addClasspath>true</addClasspath>
<classpathPrefix>lib/</classpathPrefix>
<mainClass>com.influxdb.examples.FlightExamples</mainClass>
</manifest>
</archive>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-help-plugin</artifactId>
<version>3.2.0</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.4.1</version>
<executions>
<execution>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<shadedArtifactAttached>true</shadedArtifactAttached>
</configuration>
</execution>
</executions>
<configuration>
<minimizeJar>false</minimizeJar>
<filters>
<filter>
<artifact>*:*</artifact>
<excludes>
<exclude>META-INF/*.SF</exclude>
<exclude>META-INF/*.DSA</exclude>
<exclude>META-INF/*.RSA</exclude>
</excludes>
</filter>
</filters>
</configuration>
</plugin>
</plugins>
</build>
<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.arrow</groupId>
<artifactId>flight-sql</artifactId>
<version>11.0.0</version>
</dependency>
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-all</artifactId>
<version>4.1.74.Final</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>1.7.30</version>
</dependency>
</dependencies>
</project>
```
{{% /expand %}}
{{< /expand-wrapper >}}
### Create the FlightQuery class
{{< expand-wrapper >}}
{{% expand "View FlightQuery.java" %}}
```java
package com.influxdb.examples;
import org.apache.arrow.flight.auth2.BearerCredentialWriter;
import org.apache.arrow.flight.CallHeaders;
import org.apache.arrow.flight.CallStatus;
import org.apache.arrow.flight.grpc.CredentialCallOption;
import org.apache.arrow.flight.Location;
import org.apache.arrow.flight.FlightClient;
import org.apache.arrow.flight.FlightClientMiddleware;
import org.apache.arrow.flight.FlightInfo;
import org.apache.arrow.flight.FlightStream;
import org.apache.arrow.flight.sql.FlightSqlClient;
import org.apache.arrow.flight.Ticket;
import org.apache.arrow.memory.BufferAllocator;
import org.apache.arrow.memory.RootAllocator;
import org.apache.arrow.vector.VectorSchemaRoot;
public class FlightQuery {
/* Get server credentials from environment variables */
public static final String DATABASE_NAME = System.getenv("DATABASE_NAME");
public static final String HOST = System.getenv("HOST");
public static final String TOKEN = System.getenv("TOKEN");
public static void main() {
System.out.println("Query InfluxDB with the Java Flight SQL Client");
// Create an interceptor that injects header metadata (database name) in every request.
FlightClientMiddleware.Factory f = info -> new FlightClientMiddleware() {
@Override
public void onBeforeSendingHeaders(CallHeaders outgoingHeaders) {
outgoingHeaders.insert("database", DATABASE_NAME);
}
@Override
public void onHeadersReceived(CallHeaders incomingHeaders) {
}
@Override
public void onCallCompleted(CallStatus status) {
}
};
// Create a gRPC+TLS channel URI with HOST and port 443.
Location location = Location.forGrpcTls(HOST, 443);
// Set the allowed memory.
BufferAllocator allocator = new RootAllocator(Long.MAX_VALUE);
// Create a client with the allocator and gRPC channel.
FlightClient client = FlightClient.builder(allocator, location)
.intercept(f)
.build();
System.out.println("client" + client);
FlightSqlClient sqlClient = new FlightSqlClient(client);
System.out.println("sqlClient: " + sqlClient);
// Define the SQL query to execute.
String query = "SELECT * FROM home";
/* Construct a bearer credential using TOKEN.
Construct a credentials option using the bearer credential.
*/
CredentialCallOption auth = new CredentialCallOption(new BearerCredentialWriter(TOKEN));
/* Execute the query.
If successful, execute returns a FlightInfo object that contains metadata
and an endpoints list.
Each endpoint contains the following:
- A list of addresses where you can retrieve the data.
- A `ticket` value that identifies the data to retrieve.
*/
FlightInfo flightInfo = sqlClient.execute(query, auth);
// Extract the Flight ticket from the response.
Ticket ticket = flightInfo.getEndpoints().get(0).getTicket();
// Pass the ticket to request the Arrow stream data from the endpoint.
final FlightStream stream = sqlClient.getStream(ticket, auth);
// Process all the Arrow stream data.
while (stream.next()) {
try {
// Get the current vector data from the stream.
final VectorSchemaRoot root = stream.getRoot();
System.out.println(root.contentToTSVString());
} catch (Exception e) {
// Handle exceptions.
System.out.println("Error executing FlightSqlClient: " + e.getMessage());
}
}
try {
// Close the stream and release resources.
stream.close();
} catch (Exception e) {
// Handle exceptions.
System.out.println("Error closing stream: " + e.getMessage());
}
try {
// Close the client
sqlClient.close();
} catch (Exception e) {
// Handle exceptions.
System.out.println("Error closing client: " + e.getMessage());
}
}
}
```
{{% /expand %}}
{{< /expand-wrapper >}}
1. In your `<PROJECT_ROOT>/src/main/java` directory, create the `com/influxdb/examples` subdirectories for the `com.influxdb.examples` package.
2. In the `examples` directory from the preceding step, create the `FlightQuery.java` class file.
You should have the following directory structure:
<!-- Can't make filesystem-diagram shortcode indent properly -->
```
PROJECT_ROOT
└──src
└──main
└──java
└──com
└──influxdb
└──examples
└──FlightQuery.java
```
3. In `FlightQuery.java`:
1. Add the package name:
```java
package com.influxdb.examples;
```
2. Add `import` statements for the following packages. You'll use classes and methods
from these packages in the remaining steps:
- `org.apache.arrow.flight.auth2.BearerCredentialWriter`
- `org.apache.arrow.flight.CallHeaders`
- `org.apache.arrow.flight.CallStatus`
- `org.apache.arrow.flight.grpc.CredentialCallOption`
- `org.apache.arrow.flight.Location`
- `org.apache.arrow.flight.FlightClient`
- `org.apache.arrow.flight.FlightClientMiddleware`
- `org.apache.arrow.flight.FlightInfo`
- `org.apache.arrow.flight.FlightStream`
- `org.apache.arrow.flight.sql.FlightSqlClient`
- `org.apache.arrow.flight.Ticket`
- `org.apache.arrow.memory.BufferAllocator`
- `org.apache.arrow.memory.RootAllocator`
- `org.apache.arrow.vector.VectorSchemaRoot`
3. Create a `FlightQuery` class.
4. In the `FlightQuery` class:
1. Define constants for server credentials.
- `DATABASE_NAME`
- `HOST`
- `TOKEN`
_The example `Dockerfile` defines environment variables for
these credentials._
2. Create a `main()` method.
### Create a query client
In the `FlightQuery.main()` method, do the following to create an SQL client that can connect to `HOST` and `DATABASE_NAME`:
1. Construct a _gRPC+TLS_ channel URI with `HOST` and port `443` for communicating with a [gRPC server over TLS](https://grpc.io/docs/guides/auth/#with-server-authentication-ssltls-4).
2. Instantiate `FlightClientMiddleware` and define an event callback
that inserts the following Flight request metadata header property:
```json
"database": "DATABASE_NAME"
```
3. Instantiate a `BufferAllocator` that sets the memory allowed for the client.
4. Create a `FlightClient` with the allocator and gRPC channel.
5. Instantiate a `FlightSqlClient` that wraps the `FlightClient` instance.
### Execute a query
In the `FlightQuery.main` method:
1. Instantiate a `CredentialCallOption` with `TOKEN` as a _bearer_ credential.
The result is a credential object that you'll pass in each request to the server.
2. Define a string that contains the SQL query to execute--for example:
```java
String query = "SELECT * FROM home";
```
3. Call the `FlightSqlClient.execute` method with the SQL query and the `CredentialCallOption`.
4. If successful, the `FlightSqlClient.execute` method responds with a `FlightInfo` object that contains metadata and an `endpoints: [...]` list.
Each endpoint contains the following:
- A list of addresses where you can retrieve the data.
- A `ticket` value that identifies the data to retrieve.
5. Extract the ticket from the response.
### Retrieve and process Arrow data
In the `FlightQuery.main()` method, do the following to retrieve the data stream described in the `FlightInfo` response:
1. Call the `FlightSqlClient.getStream` method with the _ticket_ and the `CredentialCallOption` to fetch the [Arrow stream](https://arrow.apache.org/docs/format/CStreamInterface.html).
2. Call the `FlightStream.getRoot` method to get the current vector data from the stream.
3. Process the data and handle exceptions. The example converts the vector data into tab-separated values and prints the result to `System.out`.
For more examples using Java to work with Arrow data, see the [Apache Arrow Java Cookbook](https://arrow.apache.org/cookbook/java/).
4. Finally, close the stream and client.
### Run the application
Follow these steps to build and run the application using Docker:
1. Copy the `Dockerfile` and `pom.xml` to your project root directory.
2. Open a terminal in your project root directory.
3. In your terminal, run the `docker build` command and pass `--build-arg` flags for the server credentials:
- **`DATABASE_NAME`**: your [{{% cloud-name %}} database](/influxdb/cloud-dedicated/admin/databases/)
- **`HOST`**: your [{{% cloud-name %}} region](/influxdb/cloud-dedicated/reference/regions/) hostname (URL without the "https://")
- **`TOKEN`**: your [{{% cloud-name %}} database token](/influxdb/cloud-dedicated/get-started/setup/) with _read_ permission to the database
```sh
docker build \
--build-arg DATABASE_NAME=INFLUX_DATABASE \
--build-arg HOST=cluster-id.influxdb.io \
--build-arg TOKEN=INFLUX_TOKEN \
-t javaflight .
```
The command builds a Docker image named `javaflight`.
4. To run the application in a new Docker container, enter the following command:
```sh
docker run javaflight
```
The output is the query data in TSV-format.
## Troubleshoot Arrow Flight requests
For the list of Arrow Flight error response codes, see the [Arrow Flight RPC documentation](https://arrow.apache.org/docs/format/Flight.html#error-handling).

10
content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flight.md
View File

@ -49,6 +49,16 @@ list_code_example: |
[Apache Arrow Python bindings](https://arrow.apache.org/docs/python/index.html) integrate with Python scripts and applications to query data stored in InfluxDB.
{{% note %}}
#### Use InfluxDB v3 client libraries
We recommend using the [`influxdb3-python` Python client library](/influxdb/cloud-dedicated/reference/client-libraries/v3/python/) for integrating InfluxDB v3 with your Python application code.
[InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) wrap Apache Arrow Flight clients
and provide convenient methods for [writing](/influxdb/cloud-dedicated/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-dedicated/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
Client libraries can query using SQL or InfluxQL.
{{% /note %}}
The following examples show how to use the `pyarrow.flight` and `pandas` Python modules to query and format data stored in an {{% cloud-name %}} database:
{{% code-tabs-wrapper %}}

8
content/influxdb/cloud-dedicated/reference/client-libraries/flight/python-flightsql-dbapi.md
View File

@ -15,13 +15,13 @@ aliases:
The [Python `flightsql-dbapi` Flight SQL DBAPI library](https://github.com/influxdata/flightsql-dbapi) integrates with Python applications using SQL to query data stored in an {{% cloud-name %}} database. The `flightsql-dbapi` library uses the [Flight SQL protocol](https://arrow.apache.org/docs/format/FlightSql.html) to query and retrieve data.
{{% note %}}
#### InfluxDB v3 client libraries
#### Use InfluxDB v3 client libraries
We recommend using the [`influxdb3-python` Python client library](/influxdb/cloud-dedicated/reference/client-libraries/v3/python/) for integrating InfluxDB v3 with your Python application code.
[InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) client libraries wrap Apache Arrow Flight clients
and provide convenient methods for writing, querying, and processing data stored in {{% cloud-name %}}.
Client libraries can query using [SQL](/influxdb/cloud-dedicated/query-data/sql/execute-queries/python/) or [InfluxQL](/influxdb/cloud-dedicated/query-data/influxql/execute-queries/python/).
[InfluxDB v3 client libraries](/influxdb/cloud-dedicated/reference/client-libraries/v3/) wrap Apache Arrow Flight clients
and provide convenient methods for [writing](/influxdb/cloud-dedicated/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-dedicated/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
Client libraries can query using SQL or InfluxQL.
{{% /note %}}
## Installation

7
content/influxdb/cloud-dedicated/reference/client-libraries/v3/_index.md
View File

@ -15,6 +15,11 @@ influxdb/cloud-dedicated/tags: [client libraries, API, developer tools]
InfluxDB v3 client libraries are language-specific packages that work with
and integrate with your application to write to and query data in {{% cloud-name %}}.
InfluxData and the user community maintain client libraries for developers who want to take advantage of:
- Idioms for InfluxDB requests, responses, and errors.
- Common patterns in a familiar programming language.
- Faster development and less boilerplate code.
InfluxDB client libraries provide configurable batch writing of data to InfluxDB HTTP APIs.
They can be used to construct line protocol data and transform data from other formats
@ -24,7 +29,7 @@ InfluxDB v3 client libraries can query InfluxDB v3 using InfluxDB v3's IOx-speci
Client libraries use Flight clients to execute SQL and InfluxQL queries, request
database information, and retrieve data stored in {{% cloud-name %}}.
Additional functionality may vary among client libraries and some may not be feature-complete.
Additional features may vary among client libraries.
For specifics about a client library, see the library's GitHub repository.
InfluxDB v3 client libraries are part of the [Influx Community](https://github.com/InfluxCommunity).

166
content/influxdb/cloud-dedicated/reference/client-libraries/v3/go.md
View File

@ -1,15 +1,13 @@
---
title: Go client library for InfluxDB v3
list_title: Go
description: >
The InfluxDB v3 `influxdb3-go` Go client library integrates with Go scripts and applications to write and query data stored in an InfluxDB Cloud Dedicated database.
external_url: https://github.com/InfluxCommunity/influxdb3-go
description: The InfluxDB v3 `influxdb3-go` Go client library integrates with Go scripts and applications to write and query data stored in an {{% cloud-name %}} database.
menu:
influxdb_cloud_dedicated:
name: Go
parent: v3 client libraries
identifier: influxdb3-go
influxdb/cloud-dedicated/tags: [go, gRPC, SQL, Flight SQL, client libraries]
influxdb/cloud-dedicated/tags: [go, InfluxQL, SQL, Flight, client libraries]
weight: 201
aliases:
- /influxdb/cloud-dedicated/reference/api/client-libraries/go/
@ -19,6 +17,162 @@ aliases:
The InfluxDB v3 [`influxdb3-go` Go client library](https://github.com/InfluxCommunity/influxdb3-go) integrates with Go scripts and applications
to write and query data stored in an {{% cloud-name %}} database.
The documentation for this client library is available on GitHub.
## Installation
<a href="https://github.com/InfluxCommunity/influxdb3-go" target="_blank" class="btn github">InfluxDB v3 Go client library</a>
```sh
go get github.com/InfluxCommunity/influxdb3-go
```
## Importing the package
The `influxdb3-go` client library module provides the `influxdb3` package.
Import the package:
```go
import (
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
```
## API reference
<!-- The `influxdb_client_3` module includes the following functions: -->
### Function `New`
Create a client to interact with InfluxDB.
#### Syntax
```go
New(config ClientConfig)
```
Initializes and returns a `influxdb3.Client` instance with the following:
- Configuration and functions for writing to the database.
- A `*flight.Client` and functions for querying the database.
#### Parameters
- **`config`**: A `ClientConfig` struct with the following configuration properties:
- **`Host`** (string): the {{% cloud-name %}} server URL
- **`Token`** (string): a database token string
- **`Database`** (string): the database to use for writing and querying.
- **`Organization`** (string): _Optional_. The organization name or ID.
- **`HTTPClient`** (`*http.Client`): _Optional_. Specifies a custom HTTP client, TLS configuration, or timeout to use.
- **`WriteOptions`** (`*WriteOptions`): _Optional_. Options passed to the write client for writing to the database.
- **`Headers`** (`http.Header`): _Optional_. Headers to include in all requests.
#### Examples
##### Create an InfluxDB client
{{% code-placeholders "DATABASE_(NAME|TOKEN)" %}}
```go
package main
import (
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
func main() {
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://{{< influxdb/host >}}",
Token: "DATABASE_TOKEN",
Database: "DATABASE_NAME",
})
defer func(client *influxdb3.Client) {
err := client.Close()
if err != nil {
panic(err)
}
}(client)
if(err != nil) {
panic(err)
}
}
```
{{% /code-placeholders %}}
Replace the following configuration values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the InfluxDB [database](/influxdb/cloud-dedicated/admin/databases/) to query
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: an InfluxDB [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ permission on the specified database
## Class influxdb3.Client
### Function `Client.Query()`
Query data from InfluxDB IOx using SQL.
#### Syntax
```go
client.Query(ctx context.Context, query string)
```
Sends a Flight query request with SQL to InfluxDB.
Returns the following:
- A custom iterator (*QueryIterator) for accessing query result data and metadata.
- An error, if any.
#### Parameters
- **`ctx`** (`context.Context`): the context to use for the request
- **`query`** (string): the SQL query to execute.
#### Examples
##### Query using SQL
```go
query := `SELECT *
FROM home
WHERE time >= '2022-01-02T08:00:00Z'
AND time <= '2022-01-02T20:00:00Z'`
iterator, err := client.Query(context.Background(), query)
```
### Function `Client.QueryWithOptions()`
Query data from InfluxDB IOx with query options such as **query type** for querying with InfluxQL.
#### Syntax
```go
client.QueryWithOptions(ctx context.Context, options *QueryOptions, query string)
```
Sends a query request with the specified query options to InfluxDB.
Returns the following:
- A custom iterator (*QueryIterator) for accessing query result data and metadata.
- An error, if any.
#### Parameters
- **`ctx`** (`context.Context`): the context to use for the request
- **`options`**: query options (query type, optional database)
- **`query`** (string): the SQL or InfluxQL query to execute.
#### Examples
##### Query using InfluxQL
```go
query := `SELECT *
FROM home
WHERE time >= 1641124000s
AND time <= 1641124000s + 8h`
queryOptions := influxdb3.QueryOptions{QueryType: influxdb3.InfluxQL}
iterator, err := client.QueryWithOptions(context.Background(), &queryOptions, query)
```

4
content/influxdb/cloud-dedicated/reference/glossary.md
View File

@ -103,7 +103,7 @@ By convention, you can express `true` as the integer `1` and false as the intege
### bucket
"Bucket" is the term used in InfluxDB 2.x and _InfluxDB Cloud Serverless_ to refer
to named location where time series data is stored.
to a named location where time series data is stored.
Bucket is synonymous with "database" when using InfluxDB Cloud Dedicated.
Related entries:
@ -1018,7 +1018,7 @@ Related entries:
The InfluxDB v1 and v2 data storage format that allows greater compaction and
higher write and read throughput than B+ or LSM tree implementations.
The TSM storage engine has been replace by [IOx](#iox).
The TSM storage engine has been replaced by [IOx](#iox).
Related entries:
[IOx](#iox)

2
content/influxdb/cloud-dedicated/reference/sql/subqueries.md
View File

@ -39,7 +39,7 @@ Query examples on this page use the following sample data sets:
- [Get started home sensor sample data](/influxdb/cloud-dedicated/reference/sample-data/#get-started-home-sensor-data)
- [Home sensor actions sample data](/influxdb/cloud-dedicated/reference/sample-data/#home-sensor-actions-data)
- [NOAA Bay Area weather sample data](/influxdb/cloud-serverless/reference/sample-data/#noaa-bay-area-weather-data)
- [NOAA Bay Area weather sample data](/influxdb/cloud-dedicated/reference/sample-data/#noaa-bay-area-weather-data)
{{% /note %}}

7
content/influxdb/cloud-serverless/api-compatibility/v1/_index.md
View File

@ -1,6 +1,5 @@
---
title: Use the InfluxDB v1 API with InfluxDB Cloud Serverless
list_title: Use the InfluxDB v1 API
title: Use the InfluxDB v1 API
description: >
Use InfluxDB v1 API authentication, endpoints, and tools when bringing existing 1.x workloads to InfluxDB Cloud Serverless.
weight: 3
@ -61,7 +60,7 @@ Learn how to authenticate requests, adjust request parameters for existing v1 wo
## Authenticate API requests
InfluxDB requires each API request to be authenticated with a
{{% cloud-name %}} requires each API request to be authenticated with an
[API token](/influxdb/cloud-serverless/admin/tokens/).
With the InfluxDB v1 API, you can use API tokens in InfluxDB 1.x username and password
schemes or in the InfluxDB v2 `Authorization: Token` scheme.
@ -421,7 +420,7 @@ Replace the following:
- [Flight clients](/influxdb/cloud-serverless/reference/client-libraries/flight-sql/)
- [Superset](/influxdb/cloud-serverless/query-data/sql/execute-queries/superset/)
- [Grafana](/influxdb/cloud-serverless/query-data/sql/execute-queries/grafana/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/query-data/influxql/execute-queries/influxdb-v1-api/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/query-data/execute-queries/influxdb-v1-api/)
- [Chronograf](/{{< latest "Chronograf" >}}/)
{{% /note %}}

75
content/influxdb/cloud-serverless/get-started/query.md
View File

@ -50,7 +50,7 @@ The examples in this section of the tutorial query the [**get-started** bucket](
- [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/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/query-data/influxql/execute-queries/influxdb-v1-api/)
- [InfluxQL with InfluxDB v1 HTTP API](/influxdb/cloud-serverless/query-data/execute-queries/influxdb-v1-api/)
- [Chronograf](/{{< latest "chronograf" >}}/)
## SQL query basics
@ -373,8 +373,10 @@ _If your project's virtual environment is already running, skip to step 3._
{{< expand-wrapper >}}
{{% expand "<span class='req'>Important</span>: If using **Windows**, specify the **Windows** certificate path" %}}
If using a non-POSIX-compliant operating system (such as Windows), specify the root certificate path when instantiating the client.
The following example shows how to use the Python `certifi` package and client library options to pass the certificate path:
When instantiating the client, Python looks for SSL/TLS certificate authority (CA) certificates for verifying the server's authenticity.
If using a non-POSIX-compliant operating system (such as Windows), you need to specify a certificate bundle path that Python can access on your system.
The following example shows how to use the [Python `certifi` package](https://certifiio.readthedocs.io/en/latest/) and client library options to provide a bundle of trusted certificates to the Python Flight client:
1. In your terminal, install the Python `certifi` package.
@ -417,9 +419,9 @@ _If your project's virtual environment is already running, skip to step 3._
2. Calls the `InfluxDBClient3()` constructor method with credentials to instantiate an InfluxDB `client` with the following credentials:
- **`host`**: {{% cloud-name %}} region hostname (URL without protocol or trailing slash)
- **`database`**: the name of the [{{% cloud-name %}} bucket](/influxdb/cloud-serverless/admin/buckets/) to query
- **`token`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`database`**: the name of the {{% cloud-name %}} bucket to query
3. Defines the SQL query to execute and assigns it to a `query` variable.
@ -502,7 +504,7 @@ _If your project's virtual environment is already running, skip to step 3._
"text/tabwriter"
"github.com/apache/arrow/go/v12/arrow"
"github.com/InfluxCommunity/influxdb3-go/influx"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
func Query() error {
@ -510,19 +512,19 @@ _If your project's virtual environment is already running, skip to step 3._
// INFLUX_TOKEN is an environment variable you created
// for your API read token.
token := os.Getenv("INFLUX_TOKEN")
database := "get-started"
// Instantiate the client.
client, err := influx.New(influx.Configs{
HostURL: "https://cloud2.influxdata.com",
AuthToken: token,
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://{{< influxdb/host >}}",
Token: token,
Database: "get-started",
})
// Close the client when the function returns.
defer func (client *influx.Client) {
defer func(client *influxdb3.Client) {
err := client.Close()
if err != nil {
panic(err)
panic(err)
}
}(client)
@ -533,7 +535,7 @@ _If your project's virtual environment is already running, skip to step 3._
AND time <= '2022-01-01T20:00:00Z'`
// Execute the query.
iterator, err := client.Query(context.Background(), database, query)
iterator, err := client.Query(context.Background(), query)
if err != nil {
panic(err)
@ -570,20 +572,22 @@ _If your project's virtual environment is already running, skip to step 3._
- `os`
- `text/tabwriter`
- `github.com/apache/arrow/go/v12/arrow`
- `github.com/InfluxCommunity/influxdb3-go/influx`
- `github.com/InfluxCommunity/influxdb3-go/influxdb3`
2. Defines a `Query()` function that does the following:
1. Instantiates `influx.Client` with InfluxDB credentials.
- **`HostURL`**: your {{% cloud-name %}} region URL
- **`AuthToken`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket.
- **`Host`**: your {{% cloud-name %}} region URL
- **`Database`**: The name of your {{% cloud-name %}} bucket
- **`Token`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with read permission on the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
2. Defines a deferred function to close the client after execution.
3. Defines a string variable for the SQL query.
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.
4. Calls the `influxdb3.Client.Query(sql string)` method and passes the SQL string to query InfluxDB.
`Query(sql string)` method returns an `iterator` for data in the response stream.
5. Iterates over rows, formats the timestamp as an [RFC3339 timestamp](/influxdb/cloud-serverless/reference/glossary/#rfc3339-timestamp), and prints the data in table format to stdout.
3. In your editor, open the `main.go` file you created in the
@ -752,21 +756,17 @@ _This tutorial assumes you installed Node.js and npm, and created an `influxdb_j
**/
public static async Task QuerySQL()
{
/** Set InfluxDB credentials **/
const string hostUrl = "https://cloud2.influxdata.com";
string? database = "get-started";
/** INFLUX_TOKEN is an environment variable you assigned to your
* API READ token value.
**/
string? authToken = System.Environment
string? token = System.Environment
.GetEnvironmentVariable("INFLUX_TOKEN");
/**
* Instantiate the InfluxDB client with credentials.
**/
using var client = new InfluxDBClient(
hostUrl, authToken: authToken, database: database);
"https://{{< influxdb/host >}}", token: token, database: database);
const string sql = @"
SELECT time, room, temp, hum, co
@ -808,12 +808,13 @@ _This tutorial assumes you installed Node.js and npm, and created an `influxdb_j
1. Calls the `new InfluxDBClient()` constructor to instantiate a client configured
with InfluxDB credentials.
- **`hostURL`**: your {{% cloud-name %}} region URL.
- **`authToken`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket.
- **`host`**: your {{% cloud-name %}} region URL.
- **`token`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with read permission on the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`database`**: the name of the {{% cloud-name %}} bucket to query
2. Defines a string variable for the SQL query.
3. Calls the `InfluxDBClient.Query()` method to send the query request with the SQL string. `Query()` returns batches of rows from the response stream as a two-dimensional array--an array of rows in which each row is an array of values.
3. Calls the `InfluxDBClient.Query()` method to send the query request with the SQL string.
`Query()` returns batches of rows from the response stream as a two-dimensional array--an array of rows in which each row is an array of values.
4. Iterates over rows and prints the data in table format to stdout.
3. In your editor, open the `Program.cs` file you created in the
[Write data section](/influxdb/cloud-serverless/get-started/write/?t=C%23#write-line-protocol-to-influxdb) and insert code to call the `Query()` function--for example:
@ -836,13 +837,9 @@ _This tutorial assumes you installed Node.js and npm, and created an `influxdb_j
}
```
4. To execute the program and query {{% cloud-name %}},
4. To build and execute the program and query {{% cloud-name %}},
enter the following commands in your terminal:
```sh
dotnet build
```
```sh
dotnet run
```
@ -853,7 +850,7 @@ _This tutorial assumes you installed Node.js and npm, and created an `influxdb_j
<!------------------------------ BEGIN JAVA CONTENT ------------------------------->
{{% influxdb/custom-timestamps %}}
_This tutorial assumes using Maven version 3.9, Java version >= 15, and a `influxdb_java_client` Maven project created in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Java)._
_This tutorial assumes using Maven version 3.9, Java version >= 15, and an `influxdb_java_client` Maven project created in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Java)._
1. In your terminal or editor, change to the `influxdb_java_client` directory you created in the
[Write data section](/influxdb/cloud-serverless/get-started/write/?t=Java).
@ -886,17 +883,17 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and a `influ
*/
/** Set InfluxDB credentials. **/
final String hostUrl = "https://cloud2.influxdata.com";
final String host = "https://{{< influxdb/host >}}";
final String database = "get-started";
/** INFLUX_TOKEN is an environment variable you assigned to your
* API READ token value.
**/
final char[] authToken = (System.getenv("INFLUX_TOKEN")).
final char[] token = (System.getenv("INFLUX_TOKEN")).
toCharArray();
try (InfluxDBClient client = InfluxDBClient.getInstance(hostUrl,
authToken, database)) {
try (InfluxDBClient client = InfluxDBClient.getInstance(host,
token, database)) {
String sql =
"""
SELECT time, room, temp, hum, co
@ -937,9 +934,9 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and a `influ
1. Calls `InfluxDBClient.getInstance()` to instantiate a client configured
with InfluxDB credentials.
- **`hostUrl`**: your {{% cloud-name %}} region URL
- **`host`**: your {{% cloud-name %}} region URL
- **`database`**: the name of the {{% cloud-name %}} bucket to write to
- **`authToken`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket.
- **`token`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
2. Defines a string variable (`sql`) for the SQL query.
3. Defines a Markdown table format layout for headings and data rows.
@ -973,7 +970,7 @@ _This tutorial assumes using Maven version 3.9, Java version >= 15, and a `influ
}
```
- The `App`, `Write`, and `Query` classes are part of the same `com.influxdbv3` package (your project **groupId**).
- The `App`, `Write`, and `Query` classes belong to the `com.influxdbv3` package (your project **groupId**).
- `App` defines a `main()` function that calls `Write.writeLineProtocol()` and `Query.querySQL()`.
4. In your terminal or editor, use Maven to to install dependencies and compile the project code--for example:

58
content/influxdb/cloud-serverless/get-started/write.md
View File

@ -269,7 +269,7 @@ and then write it to {{< cloud-name >}}.
```
- **`output-influxdb_v2` output plugin**: In the `[[outputs.influxdb_v2]]` section, replace the default values with the following configuration for your InfluxDB Cloud Serverless bucket:
p
```toml
[[outputs.influxdb_v2]]
# InfluxDB Cloud Serverless region URL
@ -535,12 +535,11 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
"fmt"
"log"
"github.com/InfluxCommunity/influxdb3-go/influx"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
// Write line protocol data to InfluxDB
func WriteLineProtocol() error {
url := "https://cloud2.influxdata.com"
// INFLUX_TOKEN is an environment variable you assigned to your
// API WRITE token value.
token := os.Getenv("INFLUX_TOKEN")
@ -548,17 +547,18 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
// 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},
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://{{< influxdb/host >}}",
Token: token,
Database: database,
WriteOptions: &influxdb3.WriteOptions{Precision: lineprotocol.Second},
})
// Close the client when the function returns.
defer func (client *influx.Client) {
defer func(client *influxdb3.Client) {
err := client.Close()
if err != nil {
panic(err)
panic(err)
}
}(client)
@ -598,7 +598,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
// Iterate over the lines array and write each line
// separately to InfluxDB
for _, record := range lines {
err = client.Write(context.Background(), database, []byte(record))
err = client.Write(context.Background(), []byte(record))
if err != nil {
log.Fatalf("Error writing line protocol: %v", err)
}
@ -619,11 +619,11 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
2. Defines a `WriteLineProtocol()` function that does the following:
1. To instantiate the client, calls the `influx.New(influx.Configs)` function and passes the following:
- **`HostURL`**: the {{% cloud-name %}} region URL
- **`AuthToken`**: an InfluxDB [API token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket.
1. To instantiate the client, calls the `influxdb3.New(influxdb3.ClientConfig)` function and passes the following:
- **`Host`**: your {{% cloud-name %}} region URL
- **`Token`**: an InfluxDB [API](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`WriteParams`**: `influx.WriteParams` options for writing to InfluxDB.
- **`WriteOptions`**: `influxdb3.WriteOptions` options for writing to InfluxDB.
**Because the timestamps in the sample line protocol are in second
precision, the example passes the `Precision: lineprotocol.Second` option
@ -856,19 +856,19 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
public static async Task WriteLines()
{
// Set InfluxDB credentials
const string hostUrl = "https://cloud2.influxdata.com";
const string host = "https://{{< influxdb/host >}}";
string? database = "get-started";
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* API WRITE token value.
*/
string? authToken = System.Environment
string? token = System.Environment
.GetEnvironmentVariable("INFLUX_TOKEN");
// Instantiate the InfluxDB client with credentials.
using var client = new InfluxDBClient(
hostUrl, authToken: authToken, database: database);
host, token: token, database: database);
/**
* Define an array of line protocol strings to write.
@ -923,9 +923,9 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
1. Calls the `new InfluxDBClient()` constructor to instantiate a client configured
with InfluxDB credentials.
- **hostUrl**: your {{% cloud-name %}} region URL
- **host**: your {{% cloud-name %}} region URL
- **database**: the name of the {{% cloud-name %}} bucket to write to
- **authToken**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket.
- **token**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
_Instantiating the client with the `using` statement ensures that the client is disposed of when it's no longer needed._
@ -977,6 +977,7 @@ InfluxDB v3 [influxdb3-go client library package](https://github.com/InfluxCommu
<!---------------------------- BEGIN JAVA CONTENT --------------------------->
_The tutorial assumes using Maven version 3.9 and Java version >= 15._
1. If you haven't already, follow the instructions to download and install the [Java JDK](https://www.oracle.com/java/technologies/downloads/) and [Maven](https://maven.apache.org/download.cgi) for your system.
2. In your terminal or editor, use Maven to generate a project--for example:
@ -988,7 +989,8 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
-Dversion="1.0"
```
The example command creates the `<artifactId>` directory (`./influxdb_java_client`) that contains a `pom.xml` and scaffolding for your `com.influxdbv3.influxdb_java_client` Java application.
Maven creates the `<artifactId>` directory (`./influxdb_java_client`) that
contains a `pom.xml` and scaffolding for your `com.influxdbv3.influxdb_java_client` Java application.
3. In your terminal or editor, change into the `./influxdb_java_client` directory--for example:
@ -1024,7 +1026,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
import java.util.List;
import com.influxdb.v3.client.InfluxDBClient;
import com.influxdb.v3.client.write.WriteParameters;
import com.influxdb.v3.client.write.WriteOptions;
import com.influxdb.v3.client.write.WritePrecision;
/**
@ -1045,19 +1047,19 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
public static void writeLineProtocol() throws Exception {
// Set InfluxDB credentials
final String hostUrl = "https://cloud2.influxdata.com";
final String host = "https://{{< influxdb/host >}}";
final String database = "get-started";
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* API WRITE token value.
*/
final char[] authToken = (System.getenv("INFLUX_TOKEN")).
final char[] token = (System.getenv("INFLUX_TOKEN")).
toCharArray();
// Instantiate the InfluxDB client.
try (InfluxDBClient client = InfluxDBClient.getInstance(hostUrl,
authToken, database)) {
try (InfluxDBClient client = InfluxDBClient.getInstance(host,
token, database)) {
// Create a list of line protocol records.
final List<String> records = List.of(
"home,room=Living\\ Room temp=21.1,hum=35.9,co=0i 1641024000",
@ -1094,7 +1096,7 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
* If no error occurs, print a success message.
* */
for (String record : records) {
client.writeRecord(record, new WriteParameters(null, null,
client.writeRecord(record, new WriteOptions(null, null,
WritePrecision.S));
System.out.printf("Data has been written successfully:
%s%n", record);
@ -1116,9 +1118,9 @@ _The tutorial assumes using Maven version 3.9 and Java version >= 15._
2. Calls `InfluxDBClient.getInstance()` to instantiate a client configured
with InfluxDB credentials.
- **`hostUrl`**: the {{% cloud-name %}} region URL
- **`host`**: your {{% cloud-name %}} region URL
- **`database`**: the name of the {{% cloud-name %}} bucket to write to
- **`authToken`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket.
- **`token`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
2. Defines a list of line protocol strings where each string represents a data record.

27
content/influxdb/cloud-serverless/process-data/tools/pandas.md
View File

@ -16,6 +16,7 @@ aliases:
- /influxdb/cloud-serverless/visualize-data/pandas/
- /influxdb/cloud-serverless/visualize-data/python/
related:
- /influxdb/cloud-serverless/query-data/execute-queries/client-libraries/python/
- /influxdb/cloud-serverless/process-data/tools/pyarrow/
- /influxdb/cloud-serverless/query-data/sql/
list_code_example: |
@ -23,17 +24,13 @@ list_code_example: |
...
dataframe = reader.read_pandas()
dataframe = dataframe.set_index('time')
print(dataframe.index)
resample = dataframe.resample("1H")
resample['temp'].mean()
```
---
Use [pandas](https://pandas.pydata.org/), the Python data analysis library, to process, analyze, and visualize data
stored in an InfluxDB Cloud Serverless bucket.
stored in an {{% cloud-name %}} bucket.
> **pandas** is an open source, BSD-licensed library providing high-performance,
> easy-to-use data structures and data analysis tools for the Python programming language.
@ -54,7 +51,7 @@ stored in an InfluxDB Cloud Serverless bucket.
## Install prerequisites
The examples in this guide assume using a Python virtual environment and the InfluxDB v3 [`influxdb3-python` Python client library](/influxdb/cloud-serverless/reference/client-libraries/v3/python/).
For more information, see how to [get started using Python to query InfluxDB](/influxdb/cloud-serverless/query-data/execute-queries/flight-sql/python/).
For more information, see how to [get started using Python to query InfluxDB](/influxdb/cloud-serverless/query-data/execute-queries/client-libraries/python/).
Installing `influxdb3-python` also installs the [`pyarrow`](https://arrow.apache.org/docs/python/index.html) library that provides Python bindings for Apache Arrow.
@ -62,7 +59,7 @@ Installing `influxdb3-python` also installs the [`pyarrow`](https://arrow.apache
To use pandas, you need to install and import the `pandas` library.
In your terminal, use `pip` to install `pandas` in your active [Python virtual environment](/influxdb/cloud-serverless/query-data/sql/execute-queries/python/#create-a-project-virtual-environment):
In your terminal, use `pip` to install `pandas` in your active [Python virtual environment](/influxdb/cloud-serverless/query-data/execute-queries/python/#create-a-project-virtual-environment):
```sh
pip install pandas
@ -72,7 +69,7 @@ pip install pandas
The following steps use Python, `influxdb3-python`, and `pyarrow` to query InfluxDB and stream Arrow data to a pandas `DataFrame`.
1. In your editor, copy and paste the following code to a new file--for example, `pandas-example.py`:
1. In your editor, copy and paste the following code to a new file--for example, `pandas-example.py`:
{{% tabs-wrapper %}}
{{% code-placeholders "BUCKET_NAME|API_TOKEN" %}}
@ -107,12 +104,12 @@ print(dataframe)
{{% /code-placeholders %}}
{{% /tabs-wrapper %}}
2. Replace the following configuration values:
2. Replace the following configuration values:
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: An InfluxDB [token](/influxdb/cloud-serverless/admin/tokens/) with read permissions on the buckets you want to query.
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: The name of the InfluxDB [bucket](/influxdb/cloud-serverless/admin/buckets/) to query.
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: the name of the InfluxDB [bucket](/influxdb/cloud-serverless/admin/buckets/) to query
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: an InfluxDB [token](/influxdb/cloud-serverless/admin/tokens/) with _read_ permission on the specified bucket
3. In your terminal, use the Python interpreter to run the file:
3. In your terminal, use the Python interpreter to run the file:
```sh
python pandas-example.py
@ -215,8 +212,8 @@ print(dataframe.to_markdown())
Replace the following configuration values:
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: An InfluxDB [token](/influxdb/cloud-serverless/admin/tokens/) with read permissions on the buckets you want to query.
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: The name of the InfluxDB [bucket](/influxdb/cloud-serverless/admin/buckets/) to query.
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: the name of the InfluxDB [bucket](/influxdb/cloud-serverless/admin/buckets/) to query
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: An InfluxDB [token](/influxdb/cloud-serverless/admin/tokens/) with read permission on the specified bucket.
### Downsample time series
@ -246,7 +243,7 @@ print(resample['temp'].mean())
{{< expand-wrapper >}}
{{% expand "View example results" %}}
```sh
time
time
2023-07-16 22:00:00 NaN
2023-07-16 23:00:00 22.600000
2023-07-17 00:00:00 22.513889

32
content/influxdb/cloud-serverless/query-data/execute-queries/_index.md Normal file
View File

@ -0,0 +1,32 @@
---
title: Execute queries
description: >
Use tools and libraries to query data stored in InfluxDB Cloud Serverless.
weight: 201
menu:
influxdb_cloud_serverless:
name: Execute queries
parent: Query data
influxdb/cloud-serverless/tags: [query, sql, influxql]
aliases:
- /influxdb/cloud-serverless/query-data/tools/
- /influxdb/cloud-serverless/query-data/sql/execute-queries/
- /influxdb/cloud-serverless/query-data/influxql/execute-queries/
---
Use tools and libraries to query data stored in an {{% cloud-name %}} bucket.
InfluxDB client libraries and Flight clients can use the Flight+gRPC protocol to query with SQL or InfluxQL and retrieve data in the [Arrow in-memory format](https://arrow.apache.org/docs/format/Columnar.html).
HTTP clients can use the InfluxDB v1 `/query` REST API to query with InfluxQL and retrieve data in formatted as JSON.
{{% note %}}
#### Map databases and retention policies to buckets
Before using InfluxQL, make sure database and retention policy (DBRP)
combinations are mapped to buckets. For more information, see
[Map databases and retention policies to buckets](/influxdb/cloud-serverless/query-data/influxql/dbrp/).
{{% /note %}}
Learn how to connect to InfluxDB and query your data using the following tools:
{{< children readmore=true hr=true hlevel="h2" >}}

23
content/influxdb/cloud-serverless/query-data/execute-queries/client-libraries/_index.md Normal file
View File

@ -0,0 +1,23 @@
---
title: Use InfluxDB client libraries to query data
seotitle: Use InfluxDB client libraries and SQL or InfluxQL to query data
list_title: Use client libraries
description: >
Use the InfluxDB v3 client libraries with SQL or InfluxQL to query data stored in InfluxDB.
InfluxDB v3 client libraries are language-specific packages that integrate with your application.
Execute queries and retrieve data and metadata over the Flight+gRPC protocol, and then process data using tools in the language of your choice.
weight: 30
menu:
influxdb_cloud_serverless:
name: Use client libraries
parent: Execute queries
influxdb/cloud-serverless/tags: [client libraries, SQL, InfluxQL, API, Flight, developer tools]
related:
- /influxdb/cloud-serverless/reference/client-libraries/v3/
---
Use the InfluxDB v3 client libraries with SQL or InfluxQL to query data stored in InfluxDB.
InfluxDB v3 client libraries are language-specific packages that integrate with your application.
Execute queries and retrieve data and metadata over the Flight+gRPC protocol, and then process data using tools in the language of your choice.
{{< children depth="999" description="true" >}}

347
content/influxdb/cloud-serverless/query-data/execute-queries/client-libraries/go.md Normal file
View File

@ -0,0 +1,347 @@
---
title: Use Go to query data
seotitle: Use Go and SQL or InfluxQL to query data
list_title: Use Go
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.
weight: 401
menu:
influxdb_cloud_serverless:
parent: Use client libraries
name: Use Go
identifier: query-with-go
metadata: [InfluxQL, SQL]
influxdb/cloud-serverless/tags: [query, flight, go, sql, influxql]
related:
- /influxdb/cloud-serverless/reference/client-libraries/v3/go/
- /influxdb/cloud-serverless/reference/sql/
- /influxdb/cloud-serverless/reference/client-libraries/flight/
list_code_example: |
```go
import (
"context"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
func Query() error {
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://cloud2.influxdata.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'`
iterator, err := client.Query(context.Background(), query)
...
}
```
---
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.
<!-- TOC -->
- [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)
<!-- /TOC -->
## 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 {{% cloud-name %}} 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
```
- [`influxdb3-go`](https://github.com/InfluxCommunity/influxdb3-go) {{< req text="\* " color="magenta" >}}: 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](/influxdb/cloud-serverless/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:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: the name of the InfluxDB [bucket](/influxdb/cloud-serverless/admin/buckets/) to query
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: an InfluxDB [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ permission on the specified bucket
{{% tabs-wrapper %}}
{{% tabs %}}
[SQL](#)
[InfluxQL](#)
{{% /tabs %}}
{{% tab-content %}}
<!---- BEGIN SQL EXAMPLE --->
{{% influxdb/custom-timestamps %}}
#### Query using SQL
{{% code-placeholders "BUCKET_NAME|API_TOKEN" %}}
```go
// query.go
package main
import (
"context"
"fmt"
"io"
"os"
"text/tabwriter"
"time"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
"github.com/apache/arrow/go/v12/arrow"
)
func Query() error {
// Instantiate the client.
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://{{< influxdb/host >}}",
Token: "API_TOKEN",
Database: "BUCKET_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 arrow and time packages to format unix timestamp
// as a time with timezone layout (RFC3339)
time := (row["time"].(arrow.Timestamp)).
ToTime(arrow.TimeUnit(arrow.Nanosecond)).
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()
}
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
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.
<!---- END SQL EXAMPLE ---->
{{% /tab-content %}}
{{% tab-content %}}
<!---- BEGIN INFLUXQL EXAMPLE ---->
{{% influxdb/custom-timestamps %}}
#### Query using InfluxQL
{{% code-placeholders "BUCKET_NAME|API_TOKEN" %}}
```go
// query.go
package main
import (
"context"
"fmt"
"io"
"os"
"text/tabwriter"
"time"
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
"github.com/apache/arrow/go/v12/arrow"
)
func InfluxQL() error {
// Instantiate the client.
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://{{< influxdb/host >}}",
Token: "API_TOKEN",
Database: "BUCKET_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 arrow and time packages to format unix timestamp
// as a time with timezone layout (RFC3339)
time := (row["time"].(arrow.Timestamp)).
ToTime(arrow.TimeUnit(arrow.Nanosecond)).
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()
}
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
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 INFLUXQL EXAMPLE ---->
{{% /tab-content %}}
{{% /tabs-wrapper %}}
### 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.

166
content/influxdb/cloud-serverless/query-data/sql/execute-queries/python.md → content/influxdb/cloud-serverless/query-data/execute-queries/client-libraries/python.md
View File

@ -1,22 +1,32 @@
---
title: Use Python to query data with SQL
title: Use Python to query data
seotitle: Use Python and SQL or InfluxQL to query data
list_title: Use Python
description: >
Use the `influxdb_client_3` Python module and SQL to query data stored in InfluxDB.
weight: 101
Use the `influxdb_client_3` Python module 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 Python tools.
weight: 401
menu:
influxdb_cloud_serverless:
parent: Execute SQL queries
parent: Use client libraries
name: Use Python
identifier: query-with-python-sql
influxdb/cloud-serverless/tags: [query, flightsql, python, sql]
influxdb/cloud-serverless/tags: [query, flight, python, sql, influxql]
metadata: [SQL, InfluxQL]
aliases:
- /influxdb/cloud-serverless/query-data/execute-queries/flight-sql/python/
- /influxdb/cloud-serverless/query-data/execute-queries/influxql/python/
- /influxdb/cloud-serverless/query-data/execute-queries/sql/python/
- /influxdb/cloud-serverless/query-data/tools/python/
related:
- /influxdb/cloud-serverless/reference/client-libraries/v3/python/
- /influxdb/cloud-serverless/process-data/tools/pandas/
- /influxdb/cloud-serverless/process-data/tools/pyarrow/
- /influxdb/cloud-serverless/query-data/influxql/
- /influxdb/cloud-serverless/query-data/sql/
- /influxdb/cloud-serverless/reference/influxql/
- /influxdb/cloud-serverless/reference/sql/
list_code_example: |
```py
from influxdb_client_3 import InfluxDBClient3
@ -24,7 +34,6 @@ list_code_example: |
# Instantiate an InfluxDB client
client = InfluxDBClient3(
host='cloud2.influxdata.com',
org='ORG_NAME',
token='DATABASE_TOKEN',
database='DATABASE_NAME'
)
@ -40,8 +49,8 @@ list_code_example: |
```
---
Use the InfluxDB `influxdb_client_3` Python client library module and SQL to query data stored in InfluxDB.
Execute queries and retrieve data over the Flight protocol, and then process data using common Python tools.
Use the InfluxDB `influxdb_client_3` Python client library module 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 Python tools.
- [Get started using Python to query InfluxDB](#get-started-using-python-to-query-influxdb)
- [Create a Python virtual environment](#create-a-python-virtual-environment)
@ -55,12 +64,18 @@ Execute queries and retrieve data over the Flight protocol, and then process dat
## Get started using Python to query InfluxDB
This guide follows the recommended practice of using Python _virtual environments_.
If you don't want to use virtual environments and you have Python installed,
continue to [Query InfluxDB](#query-influxdb).
This guide assumes the following prerequisites:
- an {{% cloud-name %}} [bucket](/influxdb/cloud-serverless/admin/buckets/) with data to query
- an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the database
To learn how to set up InfluxDB and write data, see the [Setup instructions](/influxdb/cloud-serverless/get-started/setup/) in the Get Started tutorial.
## Create a Python virtual environment
This guide follows the recommended practice of using Python _virtual environments_.
If you don't want to use virtual environments and you have Python installed,
continue to [Query InfluxDB](#query-influxdb).
Python [virtual environments](https://docs.python.org/3/library/venv.html) keep
the Python interpreter and dependencies for your project self-contained and isolated from other projects.
@ -122,7 +137,7 @@ to install a recent version of the Python programming language for your system.
`venv` creates the new virtual environment directory in your project.
3. To activate the new virtual environment in your terminal, run the `source` command and pass the file path of the virtual environment `activate` script:
3. To activate the new virtual environment in your terminal, run the `source` command and pass the path of the virtual environment `activate` script:
```sh
source envs/VIRTUAL_ENVIRONMENT_NAME/bin/activate
@ -190,14 +205,9 @@ When a virtual environment is activated, the name displays at the beginning of y
The `influxdb3-python` package provides the `influxdb_client_3` module for integrating {{% cloud-name %}} with your Python code.
The module supports writing data to InfluxDB and querying data using SQL or InfluxQL.
{{% note %}}
_To query data with **InfluxQL** and Python, see
[Use InfluxQL with Python](/influxdb/cloud-serverless/query-data/influxql/execute-queries/python/)._
{{% /note %}}
Install the following dependencies:
{{< req type="key" text="Already installed in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" >}}
{{% req type="key" text="Already installed in the [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Python#write-line-protocol-to-influxdb)" color="magenta" %}}
- `influxdb3-python` {{< req text="\* " color="magenta" >}}: Provides the `influxdb_client_3` module and also installs the [`pyarrow` package](https://arrow.apache.org/docs/python/index.html) for working with Arrow data returned from queries.
- `pandas`: Provides [pandas modules](https://pandas.pydata.org/) for analyzing and manipulating data.
@ -218,19 +228,17 @@ The following example shows how to use Python with the `influxdb_client_3`
module to instantiate a client configured for an {{% cloud-name %}} bucket.
In your editor, copy and paste the following sample code to a new file--for
example, `query-example.py`:
example, `query-example.py`.
{{% code-placeholders "(BUCKET|ORG|API)_(NAME|TOKEN)" %}}
```py
# query-example.py
from influxdb_client_3 import InfluxDBClient3
import pandas
# Instantiate an InfluxDBClient3 client configured for your bucket
client = InfluxDBClient3(
host='cloud2.influxdata.com',
org='ORG_NAME'
host='{{< influxdb/host >}}',
token='API_TOKEN',
database='BUCKET_NAME'
)
@ -251,8 +259,7 @@ If using a non-POSIX-compliant operating system (such as Windows), specify the r
2. In your Python code, import `certifi` and call the `certifi.where()` method to retrieve the certificate path.
3. When instantiating the client, pass the `flight_client_options.tls_root_certs=<ROOT_CERT_PATH>` option with the certificate path.
The following example shows how to use the Python `certifi` package and client library options to pass the certificate path:
The following code sample shows how to use the Python `certifi` package and client library options to pass the certificate path:
{{% code-placeholders "BUCKET_NAME|API_TOKEN" %}}
{{< code-callout "flight_client_options|tls_root_certs|(cert\b)" >}}
@ -282,34 +289,41 @@ For more information, see [`influxdb_client_3` query exceptions](/influxdb/cloud
Replace the following configuration values:
- {{% code-placeholder-key %}}`ORG_NAME`{{% /code-placeholder-key %}}:
Your InfluxDB organization name.
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}:
Your InfluxDB API token with read permissions on the bucket you want to query.
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}:
The name of your InfluxDB bucket.
- **`database`**: the name of the [{{% cloud-name %}} bucket](/influxdb/cloud-serverless/admin/buckets/) to query
- **`token`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
### Execute a query
To execute an SQL query, call the client's [`query(query,language)` method](/influxdb/cloud-serverless/reference/client-libraries/v3/python/#influxdbclient3query) and
specify the following arguments:
To execute a query, call the following client method:
- **query**: SQL query string to execute.
- **language**: `sql`
[`query(query,language)` method](/influxdb/cloud-serverless/reference/client-libraries/v3/python/#influxdbclient3query)
and specify the following arguments:
- **query**: A string. The SQL or InfluxQL query to execute.
- **language**: A string (`"sql"` or `"influxql"`). The `query` language.
#### Example {#execute-query-example}
The following example shows how to use SQL to select all fields in a measurement, and then output the results formatted as a Markdown table.
The following examples show how to use SQL or InfluxQL to select all fields in a measurement, and then output the results formatted as a Markdown table.
{{% code-placeholders "(BUCKET|ORG|API)_(NAME|TOKEN)" %}}
{{% code-tabs-wrapper %}}
{{% code-tabs %}}
[SQL](#)
[InfluxQL](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!---- BEGIN SQL EXAMPLE --->
{{% influxdb/custom-timestamps %}}
{{% code-placeholders "(BUCKET|API)_(NAME|TOKEN)" %}}
```py
# query-example.py
from influxdb_client_3 import InfluxDBClient3
client = InfluxDBClient3(
host='cloud2.influxdata.com',
org='ORG_NAME',
host='{{< influxdb/host >}}',
token='API_TOKEN',
database='BUCKET_NAME'
)
@ -320,10 +334,82 @@ table = client.query(
language="sql"
)
# Return query results as a markdown table
print(table.to_pandas().to_markdown())
print("\n#### View Schema information\n")
print(table.schema)
print(table.schema.names)
print(table.schema.types)
print(table.field('room').type)
print(table.schema.field('time').metadata)
print("\n#### View column types (timestamp, tag, and field) and data types\n")
print(table.schema.field('time').metadata[b'iox::column::type'])
print(table.schema.field('room').metadata[b'iox::column::type'])
print(table.schema.field('temp').metadata[b'iox::column::type'])
print("\n#### Use PyArrow to read the specified columns\n")
print(table.column('temp'))
print(table.select(['room', 'temp']))
print(table.select(['time', 'room', 'temp']))
print("\n#### Use PyArrow compute functions to aggregate data\n")
print(table.group_by('hum').aggregate([]))
print(table.group_by('room').aggregate([('temp', 'mean')]))
```
{{% /code-placeholders %}}
{{% /influxdb/custom-timestamps %}}
<!---- END SQL EXAMPLE ---->
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!---- BEGIN INFLUXQL EXAMPLE ---->
{{% code-placeholders "(BUCKET|API)_(NAME|TOKEN)" %}}
```py
# query-example.py
from influxdb_client_3 import InfluxDBClient3
client = InfluxDBClient3(
host='{{< influxdb/host >}}',
token='DATABASE_TOKEN',
database='DATABASE_NAME'
)
# Execute the query and return an Arrow table
table = client.query(
query="SELECT * FROM home",
language="influxql"
)
print("\n#### View Schema information\n")
print(table.schema)
print(table.schema.names)
print(table.schema.types)
print(table.field('room').type)
print(table.schema.field('time').metadata)
print("\n#### View column types (timestamp, tag, and field) and data types\n")
print(table.schema.field('time').metadata[b'iox::column::type'])
print(table.schema.field('room').metadata[b'iox::column::type'])
print(table.schema.field('temp').metadata[b'iox::column::type'])
print("\n#### Use PyArrow to read the specified columns\n")
print(table.column('temp'))
print(table.select(['room', 'temp']))
print(table.select(['time', 'room', 'temp']))
print("\n#### Use PyArrow compute functions to aggregate data\n")
print(table.group_by('hum').aggregate([]))
print(table.group_by('room').aggregate([('temp', 'mean')]))
```
{{% /code-placeholders %}}
<!---- END INFLUXQL EXAMPLE ---->
{{% /code-tab-content %}}
{{% /code-tabs-wrapper %}}
Replace the following configuration values:
- **`database`**: the name of the [{{% cloud-name %}} bucket](/influxdb/cloud-serverless/admin/buckets/) to query
- **`token`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
Next, learn how to use Python tools to work with time series data:

7
content/influxdb/cloud-serverless/query-data/sql/execute-queries/data-explorer.md → content/influxdb/cloud-serverless/query-data/execute-queries/data-explorer.md
View File

@ -6,16 +6,17 @@ weight: 201
menu:
influxdb_cloud_serverless:
name: Use the Data Explorer
parent: Execute SQL queries
parent: Execute queries
influxdb/cloud-serverless/tags: [query]
aliases:
- /influxdb/cloud-serverless/query-data/execute-queries/data-explorer/
- /influxdb/cloud-serverless/query-data/execute-queries/sql/data-explorer/
related:
- /influxdb/cloud-serverless/query-data/sql/
- /influxdb/cloud-serverless/query-data/flux-sql/
metadata: [SQL]
---
Build, execute, and visualize your queries in InfluxDB UI's **Data Explorer**.
Build, execute, and visualize SQL queries in the InfluxDB UI **Data Explorer**.
<!--Need a screenshot of the SQL builder with a pretty graph-->

32
content/influxdb/cloud-serverless/query-data/influxql/execute-queries/influxdb-v1-api.md → content/influxdb/cloud-serverless/query-data/execute-queries/influxdb-v1-api.md
View File

@ -1,15 +1,21 @@
---
title: Use the InfluxDB v1 HTTP query API to query with InfluxQL
title: Use the InfluxDB v1 HTTP query API and InfluxQL to query data
seotitle: Use InfluxQL and InfluxDB v1 HTTP query API
list_title: Use the v1 query API and InfluxQL
description: >
Use the InfluxDB v1 HTTP query API to query data in InfluxDB Cloud Serverless
with InfluxQL.
weight: 401
menu:
influxdb_cloud_serverless:
parent: influxql-execute-queries
parent: Execute queries
name: Use the v1 query API
influxdb/cloud-serverless/tags: [query, influxql, python]
metadata: [InfluxQL]
related:
- /influxdb/cloud-serverless/api-compatibility/v1/
aliases:
- /influxdb/cloud-serverless/query-data/influxql/execute-queries/influxdb-v1-api/
list_code_example: |
```sh
curl --get https://cloud2.influxdata.com/query \
@ -50,10 +56,11 @@ Use the v1 `/query` endpoint and the `GET` request method to query data with Inf
Provide the following with your request:
- **Headers:**
- **Authorization:** `Bearer API_TOKEN`
- **Authorization:** `Token API_TOKEN`
- **Query parameters:**
- **db**: Database to query
- **rp**: _(Optional)_ Retention policy to query
- **db**: the database (bucket) to query
- **rp**: the [retention policy](/influxdb/cloud-serverless/query-data/influxql/dbrp/) to query.
Required if you haven't configured a default retention policy for the bucket.
- **q**: URL-encoded InfluxQL query
{{% code-placeholders "DATABASE_NAME|API_TOKEN" %}}
@ -65,12 +72,12 @@ curl --get https://cloud2.influxdata.com/query \
```
{{% /code-placeholders %}}
Replace the following:
Replace the following configuration values:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
Name of the database to query
the name of the [database (bucket)](/influxdb/cloud-serverless/admin/buckets/) to query
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}:
InfluxDB token with read permissions on the databases you want to query.
an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified database.
{{% note %}}
#### Authenticate with username and password
@ -78,9 +85,8 @@ Replace the following:
If using basic authentication or query string authentication (username and password)
to interact with the v1 HTTP query API, provide the following credentials:
- **username**: Arbitrary string _({{< cloud-name >}} ignores the username)_
- **password**: [API token](/influxdb/cloud-serverless/admin/tokens/) with read permission
on the database you want to query
- **username**: an arbitrary string _({{< cloud-name >}} ignores the username)_
- **password**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified database.
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
@ -129,7 +135,3 @@ curl --get https://cloud2.influxdata.com/query \
--data-urlencode "q=SELECT * FROM home"
```
{{% /code-placeholders %}}
<!--
TO-DO: Explain how DBRP mappings work with bucket names
-->

47
content/influxdb/cloud-serverless/query-data/execute-queries/visualization-tools.md Normal file
View File

@ -0,0 +1,47 @@
---
title: Use visualization tools to query data
list_title: Use visualization tools
description: >
Use visualization tools and SQL or InfluxQL to query data stored in InfluxDB.
weight: 401
menu:
influxdb_cloud_serverless:
parent: Execute queries
name: Use visualization tools
identifier: query-with-visualization-tools
influxdb/cloud-serverless/tags: [query, sql, influxql]
metadata: [SQL, InfluxQL]
aliases:
- /influxdb/cloud-serverless/query-data/influxql/execute-queries/visualization-tools/
- /influxdb/cloud-serverless/query-data/sql/execute-queries/visualization-tools/
related:
- /influxdb/cloud-serverless/process-data/visualize/grafana/
- /influxdb/cloud-serverless/process-data/visualize/superset/
- /influxdb/cloud-serverless/process-data/visualize/tableau/
---
Use visualization tools to query data stored in {{% cloud-name %}}.
## Query using SQL
The following visualization tools support querying InfluxDB with SQL:
- [Grafana](/influxdb/cloud-serverless/process-data/visualize/grafana/)
- [Superset](/influxdb/cloud-serverless/process-data/visualize/superset/)
- [Tableau](/influxdb/cloud-serverless/process-data/visualize/tableau/)
## Query using InfluxQL
The following visualization tools support querying InfluxDB with InfluxQL:
- [Grafana](/influxdb/cloud-serverless/process-data/visualize/grafana/?t=InfluxQL)
- [Chronograf](/influxdb/cloud-serverless/process-data/visualize/chronograf/)
{{% warn %}}
#### InfluxQL feature support
InfluxQL is being rearchitected to work with the InfluxDB IOx storage engine.
This process is ongoing and some InfluxQL features are still being implemented.
For information about the current implementation status of InfluxQL features,
see [InfluxQL feature support](/influxdb/cloud-serverless/reference/influxql/feature-support/).
{{% /warn %}}

29
content/influxdb/cloud-serverless/query-data/influxql/execute-queries/_index.md
View File

@ -1,29 +0,0 @@
---
title: Execute InfluxQL queries
description: >
Use tools and libraries to query data with InfluxQL stored in InfluxDB Cloud Serverless.
weight: 201
menu:
influxdb_cloud_serverless:
name: Execute InfluxQL queries
parent: Query with InfluxQL
identifier: influxql-execute-queries
influxdb/cloud-serverless/tags: [query, influxql]
---
Choose from the following options for executing InfluxQL queries with {{< cloud-name >}}:
:
{{< children type="anchored-list" >}}
{{% note %}}
#### Map databases and retention policies to buckets
Before using InfluxQL, make sure database and retention policy (DBRP)
combinations are mapped to buckets. For more information, see
[Map databases and retention policies to buckets](/influxdb/cloud-serverless/query-data/influxql/dbrp/).
{{% /note %}}
---
{{< children readmore=true hr=true >}}

297
content/influxdb/cloud-serverless/query-data/influxql/execute-queries/python.md
View File

@ -1,297 +0,0 @@
---
title: Use Python to query data with InfluxQL
description: >
Use Python and the `influxdb3-python` library to query data stored in InfluxDB
with InfluxQL.
weight: 401
menu:
influxdb_cloud_serverless:
parent: influxql-execute-queries
name: Use Python
identifier: query-with-python-influxql
influxdb/cloud-serverless/tags: [query, influxql, python]
related:
- /influxdb/cloud-serverless/process-data/tools/pandas/
- /influxdb/cloud-serverless/process-data/tools/pyarrow/
- /influxdb/cloud-serverless/reference/influxql/
list_code_example: |
```py
from influxdb_client_3 import InfluxDBClient3
# Instantiate an InfluxDB client
client = InfluxDBClient3(
host='cloud2.influxdata.com',
org='ORG_NAME',
token='API_TOKEN',
database='DATABASE_NAME'
)
# Execute the query and return an Arrow table
table = client.query(
query="SELECT * FROM home",
language="influxql"
)
# Return query results as a markdown table
print(table.to_pandas().to_markdown())
```
---
Use the `influxdb3-python` client library to query data stored in InfluxDB with InfluxQL.
The `influxdb3-client` uses InfluxDB v3's Flight RPC protocol to query data from InfluxDB and return
results in Apache Arrow Table format.
- [Get started using Python to query InfluxDB](#get-started-using-python-to-query-influxdb)
- [Create a Python virtual environment](#create-a-python-virtual-environment)
- [Install Python](#install-python)
- [Create a project virtual environment](#venv-install)
- [Install Anaconda](?t=Anaconda#conda-install)
- [Query InfluxDB](#query-influxdb)
- [Install the influxdb3-python library](#install-the-influxdb3-python-library)
- [Create an InfluxDB client](#create-an-influxdb-client)
- [Execute a query](#execute-a-query)
{{% note %}}
#### Databases and retention policies map to InfluxDB buckets
InfluxQL **databases** and **retention policies** are used to route queries to
an InfluxDB **bucket** based on database and retention policy (DBRP) mappings.
For more information, see
[Map databases and retention policies to buckets](/influxdb/cloud-serverless/query-data/influxql/dbrp/).
{{% /note %}}
{{% warn %}}
#### InfluxQL feature support
InfluxQL is being rearchitected to work with the InfluxDB IOx storage engine.
This process is ongoing and some InfluxQL features are still being implemented.
For information about the current implementation status of InfluxQL features,
see [InfluxQL feature support](/influxdb/cloud-serverless/reference/influxql/feature-support/).
{{% /warn %}}
## Get started using Python to query InfluxDB
This guide follows the recommended practice of using Python _virtual environments_.
If you don't want to use virtual environments and you have Python installed,
continue to [Query InfluxDB](#query-influxdb).
## Create a Python virtual environment
Python [virtual environments](https://docs.python.org/3/library/venv.html) keep
the Python interpreter and dependencies for your project self-contained and isolated from other projects.
To install Python and create a virtual environment, choose one of the following options:
- [Python venv](?t=venv#venv-install): The [`venv` module](https://docs.python.org/3/library/venv.html) comes standard in Python as of version 3.5.
- [Anaconda® Distribution](?t=Anaconda#conda-install): A Python/R data science distribution that provides Python and the **conda** package and environment manager.
{{< tabs-wrapper >}}
{{% tabs "small" %}}
[venv]()
[Anaconda]()
{{% /tabs %}}
{{% tab-content %}}
<!--------------------------------- Begin venv -------------------------------->
### Install Python
1. Follow the [Python installation instructions](https://wiki.python.org/moin/BeginnersGuide/Download)
to install a recent version of the Python programming language for your system.
2. Check that you can run `python` and `pip` commands.
`pip` is a package manager included in most Python distributions.
In your terminal, enter the following commands:
```sh
python --version
```
```sh
pip --version
```
Depending on your system, you may need to use version-specific commands--for example.
```sh
python3 --version
```
```sh
pip3 --version
```
If neither `pip` nor `pip<PYTHON_VERSION>` works, follow one of the [Pypa.io Pip installation](https://pip.pypa.io/en/stable/installation/) methods for your system.
### Create a project virtual environment {#venv-install}
1. Create a directory for your Python project and change to the new directory--for example:
```sh
mkdir ./PROJECT_DIRECTORY && cd $_
```
2. Use the Python `venv` module to create a virtual environment--for example:
```sh
python -m venv envs/virtualenv-1
```
`venv` creates the new virtual environment directory in your project.
3. To activate the new virtual environment in your terminal, run the `source` command and pass the file path of the virtual environment `activate` script:
```sh
source envs/VIRTUAL_ENVIRONMENT_NAME/bin/activate
```
For example:
```sh
source envs/virtualenv-1/bin/activate
```
<!---------------------------------- End venv --------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!-------------------------------- Begin conda -------------------------------->
### Install Anaconda {#conda-install}
1. Follow the [Anaconda installation instructions](https://docs.continuum.io/anaconda/install/) for your system.
2. Check that you can run the `conda` command:
```sh
conda
```
3. Use `conda` to create a virtual environment--for example:
```sh
conda create --prefix envs/virtualenv-1
```
`conda` creates a virtual environment in a directory named `./envs/virtualenv-1`.
4. To activate the new virtual environment, use the `conda activate` command and pass the directory path of the virtual environment:
```sh
conda activate envs/VIRTUAL_ENVIRONMENT_NAME
```
For example:
```sh
conda activate ./envs/virtualenv-1
```
<!--------------------------------- END conda --------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
When a virtual environment is activated, the name displays at the beginning of your terminal command line--for example:
{{% code-callout "(virtualenv-1)"%}}
```sh
(virtualenv-1) $ PROJECT_DIRECTORY
```
{{% /code-callout %}}
## Query InfluxDB
1. [Install the influxdb3-python library](#install-the-influxdb3-python-library)
2. [Create an InfluxDB client](#create-an-influxdb-client)
3. [Execute a query](#execute-a-query)
### Install the influxdb3-python library
The `influxdb_client_3` module provides a simple and convenient way to interact
with {{< cloud-name >}} using Python. This module supports both writing data to
InfluxDB and querying data using SQL or InfluxQL queries.
Installing `inflxudb3-python` also installs the
[`pyarrow`](https://arrow.apache.org/docs/python/index.html) library that you'll
use for working with Arrow data returned from queries.
In your terminal, use `pip` to install `influxdb3-python`:
```sh
pip install influxdb3-python
```
With `influxdb3-python` and `pyarrow` installed, you're ready to query and
analyze data stored in an InfluxDB database.
### Create an InfluxDB client
The following example shows how to use Python with `influxdb3-python`
and to instantiate a client configured for an InfluxDB database.
In your editor, copy and paste the following sample code to a new file--for
example, `query-example.py`:
{{% code-placeholders "(DATABASE|ORG|API)_(NAME|TOKEN)" %}}
```py
# query-example.py
from influxdb_client_3 import InfluxDBClient3
# Instantiate an InfluxDBClient3 client configured for your database
client = InfluxDBClient3(
host='cloud2.influxdata.com',
org='ORG_NAME',
token='API_TOKEN',
database='DATABASE_NAME'
)
```
{{% /code-placeholders %}}
Replace the following configuration values:
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}:
Your InfluxDB [token](/influxdb/cloud-serverless/admin/tokens/) with read permissions on the databases you want to query.
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
The name of your InfluxDB database.
### Execute a query
To execute an InfluxQL query, call the client's `query(query,language)` method
and specify the following arguments:
- **query**: InfluxQL query string to execute.
- **language**: `influxql`
#### Syntax {#execute-query-syntax}
```py
query(query: str, language: str)
```
#### Example {#execute-query-example}
{{% code-placeholders "(DATABASE|ORG|API)_(NAME|TOKEN)" %}}
```py
# query-example.py
from influxdb_client_3 import InfluxDBClient3
client = InfluxDBClient3(
host='cloud2.influxdata.com',
org='ORG_NAME',
token='API_TOKEN',
database='DATABASE_NAME'
)
# Execute the query and return an Arrow table
table = client.query(
query="SELECT * FROM home",
language="influxql"
)
# Return query results as a markdown table
print(table.to_pandas().to_markdown())
```
{{% /code-placeholders %}}
Next, learn how to use Python tools to work with time series data:
- [Use PyArrow](/influxdb/cloud-serverless/process-data/tools/pyarrow/)
- [Use pandas](/influxdb/cloud-serverless/process-data/tools/pandas/)

31
content/influxdb/cloud-serverless/query-data/influxql/execute-queries/visualization-tools.md
View File

@ -1,31 +0,0 @@
---
title: Use visualization tools to query data with InfluxQL
list_title: Use visualization tools
description: >
Use visualization tools and InfluxQL to query data stored in InfluxDB.
weight: 403
menu:
influxdb_cloud_serverless:
parent: influxql-execute-queries
name: Use visualization tools
identifier: query-with-visualization-tools-influxql
influxdb/cloud-serverless/tags: [query, influxql]
related:
- /influxdb/cloud-serverless/process-data/visualize/grafana/
- /influxdb/cloud-serverless/process-data/visualize/chronograf/
---
Use visualization tools to query data stored in {{% cloud-name %}} with InfluxQL.
The following visualization tools support querying InfluxDB with InfluxQL:
- [Grafana](/influxdb/cloud-serverless/process-data/visualize/grafana/?t=InfluxQL)
- [Chronograf](/influxdb/cloud-serverless/process-data/visualize/chronograf/)
{{% warn %}}
#### InfluxQL feature support
InfluxQL is being rearchitected to work with the InfluxDB IOx storage engine.
This process is ongoing and some InfluxQL features are still being implemented.
For information about the current implementation status of InfluxQL features,
see [InfluxQL feature support](/influxdb/cloud-serverless/reference/influxql/feature-support/).
{{% /warn %}}

33
content/influxdb/cloud-serverless/query-data/sql/execute-queries/_index.md
View File

@ -1,33 +0,0 @@
---
title: Execute SQL queries
seotitle: Execute SQL queries for data in InfluxDB Cloud Serverless
description: >
Use tools and libraries to query data with SQL stored in InfluxDB Cloud Serverless.
weight: 103
menu:
influxdb_cloud_serverless:
name: Execute SQL queries
parent: Query with SQL
influxdb/cloud-serverless/tags: [query]
aliases:
- /influxdb/cloud-serverless/query-data/execute-queries/
- /influxdb/cloud-serverless/query-data/tools/
---
The InfluxDB SQL implementation uses [Arrow DataFusion](https://arrow.apache.org/datafusion/)
and the [Apache Arrow Flight SQL](https://arrow.apache.org/) protocol to query
data stored in an InfluxDB database.
> Arrow Flight SQL is a protocol for interacting with SQL databases using the
> [Arrow in-memory format](https://arrow.apache.org/docs/format/Columnar.html)
> and the [Flight RPC](https://arrow.apache.org/docs/format/Flight.html) framework.
>
> {{% caption %}}[Apache Arrow Flight SQL documentation](https://arrow.apache.org/docs/format/FlightSql.html){{% /caption %}}
Data platforms and clients that support the Flight SQL protocol can query data
stored in an InfluxDB database.
Learn how to connect to InfluxDB and query your data using the following tools:
---
{{< children readmore=true hr=true hlevel="h2" >}}

502
content/influxdb/cloud-serverless/query-data/sql/execute-queries/java.md
View File

@ -1,502 +0,0 @@
---
title: Use Java and the Flight SQL package to query data
description: >
Use Java and the `org.apache.arrow.flight.sql` Flight SQL package to query data
stored in an InfluxDB Cloud Serverless bucket.
weight: 101
menu:
influxdb_cloud_serverless:
parent: Execute SQL queries
name: Use Java
identifier: query_with_java
influxdb/cloud-serverless/tags: [query, flightsql, java]
aliases:
- /influxdb/cloud-serverless/query-data/tools/java/
related:
- /influxdb/cloud-serverless/query-data/sql/
list_code_example: |
```java
public class Query {
public static void main(String[] args) {
String query = "SELECT * FROM home";
Location location = Location.forGrpcTls(HOST, 443);
CredentialCallOption auth = new CredentialCallOption(new BearerCredentialWriter(TOKEN));
BufferAllocator allocator = new RootAllocator(Long.MAX_VALUE);
FlightClientMiddleware.Factory f = info -> new FlightClientMiddleware() {
@Override
public void onBeforeSendingHeaders(CallHeaders outgoingHeaders) {
outgoingHeaders.insert(DATABASE_FIELD, DATABASE_NAME);
}
};
FlightClient client = FlightClient.builder(allocator, location)
.intercept(f)
.build();
FlightSqlClient sqlClient = new FlightSqlClient(client);
FlightInfo flightInfo = sqlClient.execute(query, auth);
}
}
```
---
Use Java and the Flight SQL package to query data stored in an InfluxDB Cloud
Serverless bucket.
<!-- TOC -->
- [Get started using Java to query InfluxDB](#get-started-using-java-to-query-influxdb)
- [Set up InfluxDB](#set-up-influxdb)
- [Install prerequisites](#install-prerequisites)
- [Create the FlightQuery class](#create-the-flightquery-class)
- [Create a query client](#create-a-query-client)
- [Execute a query](#execute-a-query)
- [Retrieve and process Arrow data](#retrieve-and-process-arrow-data)
- [Run the application](#run-the-application)
- [Troubleshoot Arrow Flight requests](#troubleshoot-arrow-flight-requests)
<!-- /TOC -->
## Get started using Java to query InfluxDB
Write a Java class for a Flight SQL client that connects to InfluxDB Cloud Serverless,
executes an SQL query, and retrieves data stored in an InfluxDB Cloud Serverless bucket.
The example uses the [Apache Arrow Java implementation (`org.apache.arrow`)](https://arrow.apache.org/docs/java/index.html) for interacting with Flight database servers like InfluxDB v3.
- **`org.apache.arrow`**: Provides classes and methods for integrating Java applications with Apache Arrow data and protocols.
- **`org.apache.arrow.flight.sql`**: Provides classes and methods for
interacting with Flight database servers using Arrow Flight RPC and Flight SQL.
1. [Set up InfluxDB](#set-up-influxdb)
2. [Install prerequisites](#install-prerequisites)
3. [Create the FlightQuery class](#create-the-flightquery-class)
4. [Create a query client](#create-a-query-client)
5. [Execute a query](#execute-a-query)
6. [Retrieve and process Arrow data](#retrieve-and-process-arrow-data)
To clone or download the example application that you can run with Docker, see the [InfluxCommunity/ArrowFlightClient_Query_Examples repo](https://github.com/InfluxCommunity/ArrowFlightClient_Query_Examples) on GitHub.
### Set up InfluxDB
To configure the application for querying InfluxDB Cloud Serverless, you'll need the following InfluxDB resources:
- InfluxDB Cloud Serverless **bucket**
- InfluxDB Cloud Serverless **API token** with _read_ permission to the bucket
If you don't already have an API token and a bucket, see how to [set up InfluxDB](/influxdb/cloud-serverless/get-started/setup/).
If you don't already have data to query, see how to
[write data](/influxdb/cloud-serverless/get-started/write/) to a bucket.
### Install prerequisites
We recommend using Docker and Maven for building and running the Java application and avoiding platform-specific dependency problems.
The example `Dockerfile` installs compatible versions of Maven
and Java JDK in the Docker container, and then runs the Maven commands to download dependencies and compile the application.
Follow the instructions to download and install Docker for your system:
- **macOS**: [Install Docker for macOS](https://docs.docker.com/desktop/install/mac-install/)
- **Linux**: [Install Docker for Linux](https://docs.docker.com/desktop/install/linux-install/)
{{< expand-wrapper >}}
{{% expand "View the Dockerfile" %}}
```dockerfile
# Use the official Maven image as the base image
FROM maven:3.8.3-openjdk-11 AS build
# Set the working directory
WORKDIR /app
# Copy the pom.xml file into the container
COPY pom.xml .
# Download and cache dependencies
RUN mvn dependency:go-offline
# Copy the rest of the source code into the container
COPY src/ ./src/
# Compile the source code and copy dependencies
RUN mvn compile dependency:copy-dependencies
# Use the official OpenJDK image as the runtime base image
FROM openjdk:11-jre-slim
# Set the working directory
WORKDIR /app
# Copy the compiled classes and dependencies from the build stage
COPY --from=build /app/target/classes ./classes
COPY --from=build /app/target/dependency ./dependency
# Set ARGs for --build-arg options passed in the build command
ARG DATABASE_FIELD
ARG DATABASE_NAME
ARG HOST
ARG TOKEN
# Set run-time ENVs from ARGs
ENV DATABASE_FIELD=${DATABASE_FIELD}
ENV DATABASE_NAME=${DATABASE_NAME}
ENV HOST=${HOST}
ENV TOKEN=${TOKEN}
# Set the entrypoint to run your Java application
ENTRYPOINT ["java", "-cp", "classes:dependency/*", "com.influxdb.examples.FlightExamples"]
```
{{% /expand %}}
{{% expand "View the Maven pom.xml" %}}
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.influxdb</groupId>
<artifactId>examples</artifactId>
<version>1.0-SNAPSHOT</version>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.2.0</version>
<configuration>
<archive>
<manifest>
<addClasspath>true</addClasspath>
<classpathPrefix>lib/</classpathPrefix>
<mainClass>com.influxdb.examples.FlightExamples</mainClass>
</manifest>
</archive>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-help-plugin</artifactId>
<version>3.2.0</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.4.1</version>
<executions>
<execution>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<shadedArtifactAttached>true</shadedArtifactAttached>
</configuration>
</execution>
</executions>
<configuration>
<minimizeJar>false</minimizeJar>
<filters>
<filter>
<artifact>*:*</artifact>
<excludes>
<exclude>META-INF/*.SF</exclude>
<exclude>META-INF/*.DSA</exclude>
<exclude>META-INF/*.RSA</exclude>
</excludes>
</filter>
</filters>
</configuration>
</plugin>
</plugins>
</build>
<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.arrow</groupId>
<artifactId>flight-sql</artifactId>
<version>11.0.0</version>
</dependency>
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-all</artifactId>
<version>4.1.74.Final</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>1.7.30</version>
</dependency>
</dependencies>
</project>
```
{{% /expand %}}
{{< /expand-wrapper >}}
### Create the FlightQuery class
{{< expand-wrapper >}}
{{% expand "View FlightQuery.java" %}}
```java
package com.influxdb.examples;
import org.apache.arrow.flight.auth2.BearerCredentialWriter;
import org.apache.arrow.flight.CallHeaders;
import org.apache.arrow.flight.CallStatus;
import org.apache.arrow.flight.grpc.CredentialCallOption;
import org.apache.arrow.flight.Location;
import org.apache.arrow.flight.FlightClient;
import org.apache.arrow.flight.FlightClientMiddleware;
import org.apache.arrow.flight.FlightInfo;
import org.apache.arrow.flight.FlightStream;
import org.apache.arrow.flight.sql.FlightSqlClient;
import org.apache.arrow.flight.Ticket;
import org.apache.arrow.memory.BufferAllocator;
import org.apache.arrow.memory.RootAllocator;
import org.apache.arrow.vector.VectorSchemaRoot;
public class FlightQuery {
/* Get server credentials from environment variables */
public static final String DATABASE_NAME = System.getenv("DATABASE_NAME");
public static final String HOST = System.getenv("HOST");
public static final String TOKEN = System.getenv("TOKEN");
public static void main() {
System.out.println("Query InfluxDB with the Java Flight SQL Client");
// Create an interceptor that injects header metadata (database name) in every request.
FlightClientMiddleware.Factory f = info -> new FlightClientMiddleware() {
@Override
public void onBeforeSendingHeaders(CallHeaders outgoingHeaders) {
outgoingHeaders.insert("database", DATABASE_NAME);
}
@Override
public void onHeadersReceived(CallHeaders incomingHeaders) {
}
@Override
public void onCallCompleted(CallStatus status) {
}
};
// Create a gRPC+TLS channel URI with HOST and port 443.
Location location = Location.forGrpcTls(HOST, 443);
// Set the allowed memory.
BufferAllocator allocator = new RootAllocator(Long.MAX_VALUE);
// Create a client with the allocator and gRPC channel.
FlightClient client = FlightClient.builder(allocator, location)
.intercept(f)
.build();
System.out.println("client" + client);
FlightSqlClient sqlClient = new FlightSqlClient(client);
System.out.println("sqlClient: " + sqlClient);
// Define the SQL query to execute.
String query = "SELECT * FROM home";
/* Construct a bearer credential using TOKEN.
Construct a credentials option using the bearer credential.
*/
CredentialCallOption auth = new CredentialCallOption(new BearerCredentialWriter(TOKEN));
/* Execute the query.
If successful, execute returns a FlightInfo object that contains metadata
and an endpoints list.
Each endpoint contains the following:
- A list of addresses where you can retrieve the data.
- A `ticket` value that identifies the data to retrieve.
*/
FlightInfo flightInfo = sqlClient.execute(query, auth);
// Extract the Flight ticket from the response.
Ticket ticket = flightInfo.getEndpoints().get(0).getTicket();
// Pass the ticket to request the Arrow stream data from the endpoint.
final FlightStream stream = sqlClient.getStream(ticket, auth);
// Process all the Arrow stream data.
while (stream.next()) {
try {
// Get the current vector data from the stream.
final VectorSchemaRoot root = stream.getRoot();
System.out.println(root.contentToTSVString());
} catch (Exception e) {
// Handle exceptions.
System.out.println("Error executing FlightSqlClient: " + e.getMessage());
}
}
try {
// Close the stream and release resources.
stream.close();
} catch (Exception e) {
// Handle exceptions.
System.out.println("Error closing stream: " + e.getMessage());
}
try {
// Close the client
sqlClient.close();
} catch (Exception e) {
// Handle exceptions.
System.out.println("Error closing client: " + e.getMessage());
}
}
}
```
{{% /expand %}}
{{< /expand-wrapper >}}
1. In your `<PROJECT_ROOT>/src/main/java` directory, create the `com/influxdb/examples` subdirectories for the `com.influxdb.examples` package.
2. In the `examples` directory from the preceding step, create the `FlightQuery.java` class file.
You should have the following directory structure:
<!-- Can't make filesystem-diagram shortcode indent properly -->
```
PROJECT_ROOT
└──src
└──main
└──java
└──com
└──influxdb
└──examples
└──FlightQuery.java
```
3. In `FlightQuery.java`:
1. Add the package name:
```java
package com.influxdb.examples;
```
2. Add `import` statements for the following packages. You'll use classes and methods
from these packages in the remaining steps:
- `org.apache.arrow.flight.auth2.BearerCredentialWriter`
- `org.apache.arrow.flight.CallHeaders`
- `org.apache.arrow.flight.CallStatus`
- `org.apache.arrow.flight.grpc.CredentialCallOption`
- `org.apache.arrow.flight.Location`
- `org.apache.arrow.flight.FlightClient`
- `org.apache.arrow.flight.FlightClientMiddleware`
- `org.apache.arrow.flight.FlightInfo`
- `org.apache.arrow.flight.FlightStream`
- `org.apache.arrow.flight.sql.FlightSqlClient`
- `org.apache.arrow.flight.Ticket`
- `org.apache.arrow.memory.BufferAllocator`
- `org.apache.arrow.memory.RootAllocator`
- `org.apache.arrow.vector.VectorSchemaRoot`
3. Create a `FlightQuery` class.
4. In the `FlightQuery` class:
1. Define constants for server credentials.
- `DATABASE_NAME`
- `HOST`
- `TOKEN`
_The example `Dockerfile` defines environment variables for
these credentials._
2. Create a `main()` method.
### Create a query client
In the `FlightQuery.main()` method, do the following to create an SQL client that can connect to `HOST` and `DATABASE_NAME`:
1. Construct a _gRPC+TLS_ channel URI with `HOST` and port `443` for communicating with a [gRPC server over TLS](https://grpc.io/docs/guides/auth/#with-server-authentication-ssltls-4).
2. Instantiate `FlightClientMiddleware` and define an event callback
that inserts the following Flight request metadata header property:
```json
"database": "DATABASE_NAME"
```
3. Instantiate a `BufferAllocator` that sets the memory allowed for the client.
4. Create a `FlightClient` with the allocator and gRPC channel.
5. Instantiate a `FlightSqlClient` that wraps the `FlightClient` instance.
### Execute a query
In the `FlightQuery.main` method:
1. Instantiate a `CredentialCallOption` with `TOKEN` as a _bearer_ credential.
The result is a credential object that you'll pass in each request to the server.
2. Define a string that contains the SQL query to execute--for example:
```java
String query = "SELECT * FROM home";
```
3. Call the `FlightSqlClient.execute` method with the SQL query and the `CredentialCallOption`.
4. If successful, the `FlightSqlClient.execute` method responds with a `FlightInfo` object that contains metadata and an `endpoints: [...]` list.
Each endpoint contains the following:
- A list of addresses where you can retrieve the data.
- A `ticket` value that identifies the data to retrieve.
5. Extract the ticket from the response.
### Retrieve and process Arrow data
In the `FlightQuery.main()` method, do the following to retrieve the data stream described in the `FlightInfo` response:
1. Call the `FlightSqlClient.getStream` method with the _ticket_ and the `CredentialCallOption` to fetch the [Arrow stream](https://arrow.apache.org/docs/format/CStreamInterface.html).
2. Call the `FlightStream.getRoot` method to get the current vector data from the stream.
3. Process the data and handle exceptions. The example converts the vector data into tab-separated values and prints the result to `System.out`.
For more examples using Java to work with Arrow data, see the [Apache Arrow Java Cookbook](https://arrow.apache.org/cookbook/java/).
4. Finally, close the stream and client.
### Run the application
Follow these steps to build and run the application using Docker:
1. Copy the `Dockerfile` and `pom.xml` to your project root directory.
2. Open a terminal in your project root directory.
3. In your terminal, run the `docker build` command and pass `--build-arg` flags for the server credentials:
- **`DATABASE_NAME`**: your [InfluxDB Cloud Serverless bucket](/influxdb/cloud-serverless/admin/buckets/)
- **`HOST`**: your [InfluxDB Cloud Serverless region](/influxdb/cloud-serverless/reference/regions/) hostname (URL without the "https://")
- **`TOKEN`**: your [InfluxDB Cloud Serverless API token](/influxdb/cloud-serverless/get-started/setup/) with _read_ permission to the bucket
```sh
docker build \
--build-arg DATABASE_NAME=INFLUX_BUCKET \
--build-arg HOST=cloud2.influxdata.com \
--build-arg TOKEN=INFLUX_TOKEN \
-t javaflight .
```
The command builds a Docker image named `javaflight`.
4. To run the application in a new Docker container, enter the following command:
```sh
docker run javaflight
```
The output is the query data in TSV-format.
## Troubleshoot Arrow Flight requests
For the list of Arrow Flight error response codes, see the [Arrow Flight RPC documentation](https://arrow.apache.org/docs/format/Flight.html#error-handling).

24
content/influxdb/cloud-serverless/query-data/sql/execute-queries/visualization-tools.md
View File

@ -1,24 +0,0 @@
---
title: Use visualization tools query data with SQL
list_title: Use visualization tools
description: >
Use visualization tools and SQL to query data stored in InfluxDB.
weight: 401
menu:
influxdb_cloud_serverless:
parent: Execute SQL queries
name: Use visualization tools
identifier: query-with-visualization-tools-sql
influxdb/cloud-serverless/tags: [query, sql]
related:
- /influxdb/cloud-serverless/process-data/visualize/grafana/
- /influxdb/cloud-serverless/process-data/visualize/superset/
- /influxdb/cloud-serverless/process-data/visualize/tableau/
---
Use visualization tools to query data stored in {{% cloud-name %}} with SQL.
The following visualization tools support querying InfluxDB with SQL:
- [Grafana](/influxdb/cloud-serverless/process-data/visualize/grafana/)
- [Superset](/influxdb/cloud-serverless/process-data/visualize/superset/)
- [Tableau](/influxdb/cloud-serverless/process-data/visualize/tableau/)

4
content/influxdb/cloud-serverless/reference/client-libraries/flight/_index.md
View File

@ -19,11 +19,11 @@ Flight RPC and Flight SQL clients are language-specific drivers that interact wi
Apache Arrow Flight RPC and Flight SQL protocols define APIs for servers and clients.
{{% note %}}
#### InfluxDB v3 client libraries
#### Use InfluxDB v3 client libraries
We recommend using [InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) for integrating InfluxDB v3 with your application code.
Client libraries wrap Apache Arrow Flight clients
and provide convenient methods for writing, querying, and processing data stored in {{% cloud-name %}}.
and provide convenient methods for [writing](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-serverless/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
{{% /note %}}
**Flight RPC clients** can use SQL or InfluxQL to query data stored in an {{% cloud-name %}} bucket.

13
content/influxdb/cloud-serverless/reference/client-libraries/flight/csharp-flight.md
View File

@ -1,13 +1,10 @@
---
title: C# .NET Flight client
description: The C# .NET Flight client integrates with C# .NET scripts and applications to query data stored in InfluxDB.
external_url: https://github.com/apache/arrow/tree/main/csharp/examples/FlightClientExample
menu:
influxdb_cloud_serverless:
name: C# .NET
parent: Arrow Flight clients
params:
url: https://github.com/apache/arrow/tree/main/csharp/examples/FlightClientExample
identifier: csharp-flight-client
influxdb/cloud-serverless/tags: [C#, gRPC, SQL, Flight SQL, client libraries]
aliases:
@ -18,3 +15,13 @@ weight: 201
[Apache Arrow for C# .NET](https://github.com/apache/arrow/blob/main/csharp/README.md) integrates with C# .NET scripts and applications to query data stored in InfluxDB.
For more information, see the [C# client example on GitHub](https://github.com/apache/arrow/tree/main/csharp/examples/FlightClientExample).
{{% note %}}
#### Use InfluxDB v3 client libraries
We recommend using the [`influxdb3-csharp` C# client library](/influxdb/cloud-serverless/reference/client-libraries/v3/csharp/) for integrating InfluxDB v3 with your C# application code.
[InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) wrap Apache Arrow Flight clients
and provide convenient methods for [writing](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-serverless/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
Client libraries can query using SQL or InfluxQL.
{{% /note %}}

20
content/influxdb/cloud-serverless/reference/client-libraries/flight/go-flight.md
View File

@ -1,12 +1,14 @@
---
title: Go Flight client
description: The Go Flight client integrates with Go scripts and applications to query data stored in InfluxDB.
title: Go Arrow Flight client
description: The Go Arrow Flight client integrates with Go scripts and applications to query data stored in InfluxDB.
menu:
influxdb_cloud_serverless:
name: Go
parent: Arrow Flight clients
identifier: go-flight-client
influxdb/cloud-serverless/tags: [Golang, gRPC, SQL, Flight SQL, client libraries]
related:
- /influxdb/cloud-serverless/reference/client-libraries/v3/go/
aliases:
- /influxdb/cloud-serverless/reference/client-libraries/flight-sql/go-flightsql/
weight: 201
@ -14,6 +16,16 @@ weight: 201
[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.
{{% note %}}
#### Use InfluxDB v3 client libraries
We recommend using the [`influxdb3-go` Go client library](/influxdb/cloud-serverless/reference/client-libraries/v3/go/) for integrating InfluxDB v3 with your Go application code.
[InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) wrap Apache Arrow Flight clients
and provide convenient methods for [writing](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-serverless/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
Client libraries can query using SQL or InfluxQL.
{{% /note %}}
## Flight SQL client
### Example query using Flight SQL
@ -127,10 +139,10 @@ The following example shows how to use the Arrow Flight SQL client for Go to que
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.
- **`database`**: the name of the {{% cloud-name %}} bucket to query
- **`token`**: an [API token](/influxdb/cloud-serverless/get-started/setup/#create-an-all-access-api-token) with read permission on 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.

499
content/influxdb/cloud-serverless/reference/client-libraries/flight/java-flightsql.md
View File

@ -1,20 +1,507 @@
---
title: Java Flight SQL package
description: The Java Flight SQL clients integrates with Java applications to query and retrieve data from Flight database servers using RPC and SQL.
external_url: https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/sql/package-summary.html
description: The Java Flight SQL client integrates with Java applications to query and retrieve data from Flight database servers using RPC and SQL.
menu:
influxdb_cloud_serverless:
name: Java Flight SQL
parent: Arrow Flight clients
identifier: java-flightsql-client
params:
url: https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/sql/package-summary.html
influxdb/cloud-serverless/tags: [Java, gRPC, SQL, Flight SQL, client libraries]
influxdb/cloud-serverless/tags: [Java, gRPC, SQL, Flight SQL]
weight: 201
related:
- /influxdb/cloud-serverless/reference/client-libraries/v3/java/
aliases:
- /influxdb/cloud-serverless/reference/client-libraries/flight-sql/java-flightsql/
list_code_example: |
```java
public class Query {
public static void main(String[] args) {
String query = "SELECT * FROM home";
Location location = Location.forGrpcTls(HOST, 443);
CredentialCallOption auth = new CredentialCallOption(new BearerCredentialWriter(TOKEN));
BufferAllocator allocator = new RootAllocator(Long.MAX_VALUE);
FlightClientMiddleware.Factory f = info -> new FlightClientMiddleware() {
@Override
public void onBeforeSendingHeaders(CallHeaders outgoingHeaders) {
outgoingHeaders.insert(DATABASE_FIELD, DATABASE_NAME);
}
};
FlightClient client = FlightClient.builder(allocator, location)
.intercept(f)
.build();
FlightSqlClient sqlClient = new FlightSqlClient(client);
FlightInfo flightInfo = sqlClient.execute(query, auth);
}
}
---
[Apache Arrow Flight SQL for Java](https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/sql/package-summary.html) integrates with Java applications to query and retrieve data from Flight database servers using RPC and SQL.
<a href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/sql/package-summary.html" target="_blank" class="btn github">Java Flight SQL package</a>
{{% note %}}
#### Use InfluxDB v3 client libraries
We recommend using the [`influxdb3-java` Java client library](/influxdb/cloud-serverless/reference/client-libraries/v3/java/) for integrating InfluxDB v3 with your Java application code.
[InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) wrap Apache Arrow Flight clients
and provide convenient methods for [writing](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-serverless/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
Client libraries can query using SQL or InfluxQL.
{{% /note %}}
<!-- TOC -->
- [Get started using the Java Flight SQL client to query InfluxDB](#get-started-using-the-java-flight-sql-client-to-query-influxdb)
- [Set up InfluxDB](#set-up-influxdb)
- [Install prerequisites](#install-prerequisites)
- [Create the FlightQuery class](#create-the-flightquery-class)
- [Create a query client](#create-a-query-client)
- [Execute a query](#execute-a-query)
- [Retrieve and process Arrow data](#retrieve-and-process-arrow-data)
- [Run the application](#run-the-application)
- [Troubleshoot Arrow Flight requests](#troubleshoot-arrow-flight-requests)
## Get started using the Java Flight SQL client to query InfluxDB
Write a Java class for a Flight SQL client that connects to {{% cloud-name %}},
executes an SQL query, and retrieves data stored in an {{% cloud-name %}} bucket.
The example uses the [Apache Arrow Java implementation (`org.apache.arrow`)](https://arrow.apache.org/docs/java/index.html) for interacting with Flight database servers like InfluxDB v3.
- **`org.apache.arrow`**: Provides classes and methods for integrating Java applications with Apache Arrow data and protocols.
- **`org.apache.arrow.flight.sql`**: Provides classes and methods for
interacting with Flight database servers using Arrow Flight RPC and Flight SQL.
1. [Set up InfluxDB](#set-up-influxdb)
2. [Install prerequisites](#install-prerequisites)
3. [Create the FlightQuery class](#create-the-flightquery-class)
4. [Create a query client](#create-a-query-client)
5. [Execute a query](#execute-a-query)
6. [Retrieve and process Arrow data](#retrieve-and-process-arrow-data)
To clone or download the example application that you can run with Docker, see the [InfluxCommunity/ArrowFlightClient_Query_Examples repository](https://github.com/InfluxCommunity/ArrowFlightClient_Query_Examples) on GitHub.
### Set up InfluxDB
To configure the application for querying {{% cloud-name %}}, you'll need the following InfluxDB resources:
- {{% cloud-name %}} **bucket**
- {{% cloud-name %}} **API token** with _read_ permission to the bucket
If you don't already have an API token and a bucket, see how to [set up InfluxDB](/influxdb/cloud-serverless/get-started/setup/).
If you don't already have data to query, see how to
[write data](/influxdb/cloud-serverless/get-started/write/) to a bucket.
### Install prerequisites
The following uses Docker and Maven to build and run the Java application and avoid platform-specific dependency problems.
The example `Dockerfile` installs compatible versions of Maven
and Java JDK in the Docker container, and then runs the Maven commands to download dependencies and compile the application.
Follow the instructions to download and install Docker for your system:
- **macOS**: [Install Docker for macOS](https://docs.docker.com/desktop/install/mac-install/)
- **Linux**: [Install Docker for Linux](https://docs.docker.com/desktop/install/linux-install/)
{{< expand-wrapper >}}
{{% expand "View the Dockerfile" %}}
```dockerfile
# Use the official Maven image as the base image
FROM maven:3.8.3-openjdk-11 AS build
# Set the working directory
WORKDIR /app
# Copy the pom.xml file into the container
COPY pom.xml .
# Download and cache dependencies
RUN mvn dependency:go-offline
# Copy the rest of the source code into the container
COPY src/ ./src/
# Compile the source code and copy dependencies
RUN mvn compile dependency:copy-dependencies
# Use the official OpenJDK image as the runtime base image
FROM openjdk:11-jre-slim
# Set the working directory
WORKDIR /app
# Copy the compiled classes and dependencies from the build stage
COPY --from=build /app/target/classes ./classes
COPY --from=build /app/target/dependency ./dependency
# Set ARGs for --build-arg options passed in the build command
ARG DATABASE_FIELD
ARG DATABASE_NAME
ARG HOST
ARG TOKEN
# Set run-time ENVs from ARGs
ENV DATABASE_FIELD=${DATABASE_FIELD}
ENV DATABASE_NAME=${DATABASE_NAME}
ENV HOST=${HOST}
ENV TOKEN=${TOKEN}
# Set the entrypoint to run your Java application
ENTRYPOINT ["java", "-cp", "classes:dependency/*", "com.influxdb.examples.FlightExamples"]
```
{{% /expand %}}
{{% expand "View the Maven pom.xml" %}}
```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.influxdb</groupId>
<artifactId>examples</artifactId>
<version>1.0-SNAPSHOT</version>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.2.0</version>
<configuration>
<archive>
<manifest>
<addClasspath>true</addClasspath>
<classpathPrefix>lib/</classpathPrefix>
<mainClass>com.influxdb.examples.FlightExamples</mainClass>
</manifest>
</archive>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-help-plugin</artifactId>
<version>3.2.0</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.4.1</version>
<executions>
<execution>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<shadedArtifactAttached>true</shadedArtifactAttached>
</configuration>
</execution>
</executions>
<configuration>
<minimizeJar>false</minimizeJar>
<filters>
<filter>
<artifact>*:*</artifact>
<excludes>
<exclude>META-INF/*.SF</exclude>
<exclude>META-INF/*.DSA</exclude>
<exclude>META-INF/*.RSA</exclude>
</excludes>
</filter>
</filters>
</configuration>
</plugin>
</plugins>
</build>
<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.arrow</groupId>
<artifactId>flight-sql</artifactId>
<version>11.0.0</version>
</dependency>
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-all</artifactId>
<version>4.1.74.Final</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>1.7.30</version>
</dependency>
</dependencies>
</project>
```
{{% /expand %}}
{{< /expand-wrapper >}}
### Create the FlightQuery class
{{< expand-wrapper >}}
{{% expand "View FlightQuery.java" %}}
```java
package com.influxdb.examples;
import org.apache.arrow.flight.auth2.BearerCredentialWriter;
import org.apache.arrow.flight.CallHeaders;
import org.apache.arrow.flight.CallStatus;
import org.apache.arrow.flight.grpc.CredentialCallOption;
import org.apache.arrow.flight.Location;
import org.apache.arrow.flight.FlightClient;
import org.apache.arrow.flight.FlightClientMiddleware;
import org.apache.arrow.flight.FlightInfo;
import org.apache.arrow.flight.FlightStream;
import org.apache.arrow.flight.sql.FlightSqlClient;
import org.apache.arrow.flight.Ticket;
import org.apache.arrow.memory.BufferAllocator;
import org.apache.arrow.memory.RootAllocator;
import org.apache.arrow.vector.VectorSchemaRoot;
public class FlightQuery {
/* Get server credentials from environment variables */
public static final String DATABASE_NAME = System.getenv("DATABASE_NAME");
public static final String HOST = System.getenv("HOST");
public static final String TOKEN = System.getenv("TOKEN");
public static void main() {
System.out.println("Query InfluxDB with the Java Flight SQL Client");
// Create an interceptor that injects header metadata (database name) in every request.
FlightClientMiddleware.Factory f = info -> new FlightClientMiddleware() {
@Override
public void onBeforeSendingHeaders(CallHeaders outgoingHeaders) {
outgoingHeaders.insert("database", DATABASE_NAME);
}
@Override
public void onHeadersReceived(CallHeaders incomingHeaders) {
}
@Override
public void onCallCompleted(CallStatus status) {
}
};
// Create a gRPC+TLS channel URI with HOST and port 443.
Location location = Location.forGrpcTls(HOST, 443);
// Set the allowed memory.
BufferAllocator allocator = new RootAllocator(Long.MAX_VALUE);
// Create a client with the allocator and gRPC channel.
FlightClient client = FlightClient.builder(allocator, location)
.intercept(f)
.build();
System.out.println("client" + client);
FlightSqlClient sqlClient = new FlightSqlClient(client);
System.out.println("sqlClient: " + sqlClient);
// Define the SQL query to execute.
String query = "SELECT * FROM home";
/* Construct a bearer credential using TOKEN.
Construct a credentials option using the bearer credential.
*/
CredentialCallOption auth = new CredentialCallOption(new BearerCredentialWriter(TOKEN));
/* Execute the query.
If successful, execute returns a FlightInfo object that contains metadata
and an endpoints list.
Each endpoint contains the following:
- A list of addresses where you can retrieve the data.
- A `ticket` value that identifies the data to retrieve.
*/
FlightInfo flightInfo = sqlClient.execute(query, auth);
// Extract the Flight ticket from the response.
Ticket ticket = flightInfo.getEndpoints().get(0).getTicket();
// Pass the ticket to request the Arrow stream data from the endpoint.
final FlightStream stream = sqlClient.getStream(ticket, auth);
// Process all the Arrow stream data.
while (stream.next()) {
try {
// Get the current vector data from the stream.
final VectorSchemaRoot root = stream.getRoot();
System.out.println(root.contentToTSVString());
} catch (Exception e) {
// Handle exceptions.
System.out.println("Error executing FlightSqlClient: " + e.getMessage());
}
}
try {
// Close the stream and release resources.
stream.close();
} catch (Exception e) {
// Handle exceptions.
System.out.println("Error closing stream: " + e.getMessage());
}
try {
// Close the client
sqlClient.close();
} catch (Exception e) {
// Handle exceptions.
System.out.println("Error closing client: " + e.getMessage());
}
}
}
```
{{% /expand %}}
{{< /expand-wrapper >}}
1. In your `<PROJECT_ROOT>/src/main/java` directory, create the `com/influxdb/examples` subdirectories for the `com.influxdb.examples` package.
2. In the `examples` directory from the preceding step, create the `FlightQuery.java` class file.
You should have the following directory structure:
<!-- Can't make filesystem-diagram shortcode indent properly -->
```
PROJECT_ROOT
└──src
└──main
└──java
└──com
└──influxdb
└──examples
└──FlightQuery.java
```
3. In `FlightQuery.java`:
1. Add the package name:
```java
package com.influxdb.examples;
```
2. Add `import` statements for the following packages. You'll use classes and methods
from these packages in the remaining steps:
- `org.apache.arrow.flight.auth2.BearerCredentialWriter`
- `org.apache.arrow.flight.CallHeaders`
- `org.apache.arrow.flight.CallStatus`
- `org.apache.arrow.flight.grpc.CredentialCallOption`
- `org.apache.arrow.flight.Location`
- `org.apache.arrow.flight.FlightClient`
- `org.apache.arrow.flight.FlightClientMiddleware`
- `org.apache.arrow.flight.FlightInfo`
- `org.apache.arrow.flight.FlightStream`
- `org.apache.arrow.flight.sql.FlightSqlClient`
- `org.apache.arrow.flight.Ticket`
- `org.apache.arrow.memory.BufferAllocator`
- `org.apache.arrow.memory.RootAllocator`
- `org.apache.arrow.vector.VectorSchemaRoot`
3. Create a `FlightQuery` class.
4. In the `FlightQuery` class:
1. Define constants for server credentials.
- `DATABASE_NAME`
- `HOST`
- `TOKEN`
_The example `Dockerfile` defines environment variables for
these credentials._
2. Create a `main()` method.
### Create a query client
In the `FlightQuery.main()` method, do the following to create an SQL client that can connect to `HOST` and `DATABASE_NAME`:
1. Construct a _gRPC+TLS_ channel URI with `HOST` and port `443` for communicating with a [gRPC server over TLS](https://grpc.io/docs/guides/auth/#with-server-authentication-ssltls-4).
2. Instantiate `FlightClientMiddleware` and define an event callback
that inserts the following Flight request metadata header property:
```json
"database": "DATABASE_NAME"
```
3. Instantiate a `BufferAllocator` that sets the memory allowed for the client.
4. Create a `FlightClient` with the allocator and gRPC channel.
5. Instantiate a `FlightSqlClient` that wraps the `FlightClient` instance.
### Execute a query
In the `FlightQuery.main` method:
1. Instantiate a `CredentialCallOption` with `TOKEN` as a _bearer_ credential.
The result is a credential object that you'll pass in each request to the server.
2. Define a string that contains the SQL query to execute--for example:
```java
String query = "SELECT * FROM home";
```
3. Call the `FlightSqlClient.execute` method with the SQL query and the `CredentialCallOption`.
4. If successful, the `FlightSqlClient.execute` method responds with a `FlightInfo` object that contains metadata and an `endpoints: [...]` list.
Each endpoint contains the following:
- A list of addresses where you can retrieve the data.
- A `ticket` value that identifies the data to retrieve.
5. Extract the ticket from the response.
### Retrieve and process Arrow data
In the `FlightQuery.main()` method, do the following to retrieve the data stream described in the `FlightInfo` response:
1. Call the `FlightSqlClient.getStream` method with the _ticket_ and the `CredentialCallOption` to fetch the [Arrow stream](https://arrow.apache.org/docs/format/CStreamInterface.html).
2. Call the `FlightStream.getRoot` method to get the current vector data from the stream.
3. Process the data and handle exceptions. The example converts the vector data into tab-separated values and prints the result to `System.out`.
For more examples using Java to work with Arrow data, see the [Apache Arrow Java Cookbook](https://arrow.apache.org/cookbook/java/).
4. Finally, close the stream and client.
### Run the application
Follow these steps to build and run the application using Docker:
1. Copy the `Dockerfile` and `pom.xml` to your project root directory.
2. Open a terminal in your project root directory.
3. In your terminal, run the `docker build` command and pass `--build-arg` flags for the server credentials:
- **`DATABASE_NAME`**: your [{{% cloud-name %}} bucket](/influxdb/cloud-serverless/admin/buckets/)
- **`HOST`**: your [{{% cloud-name %}} region](/influxdb/cloud-serverless/reference/regions/) hostname (URL without the "https://")
- **`TOKEN`**: your [{{% cloud-name %}} API token](/influxdb/cloud-serverless/get-started/setup/) with _read_ permission to the bucket
```sh
docker build \
--build-arg DATABASE_NAME=INFLUX_BUCKET \
--build-arg HOST=cloud2.influxdata.com \
--build-arg TOKEN=INFLUX_TOKEN \
-t javaflight .
```
The command builds a Docker image named `javaflight`.
4. To run the application in a new Docker container, enter the following command:
```sh
docker run javaflight
```
The output is the query data in TSV-format.
## Troubleshoot Arrow Flight requests
For the list of Arrow Flight error response codes, see the [Arrow Flight RPC documentation](https://arrow.apache.org/docs/format/Flight.html#error-handling).

10
content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flight.md
View File

@ -49,6 +49,16 @@ list_code_example: |
[Apache Arrow Python bindings](https://arrow.apache.org/docs/python/index.html) integrate with Python scripts and applications to query data stored in InfluxDB.
{{% note %}}
#### Use InfluxDB v3 client libraries
We recommend using the [`influxdb3-python` Python client library](/influxdb/cloud-serverless/reference/client-libraries/v3/python/) for integrating InfluxDB v3 with your Python application code.
[InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) wrap Apache Arrow Flight clients
and provide convenient methods for [writing](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-serverless/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
Client libraries can query using SQL or InfluxQL.
{{% /note %}}
The following examples show how to use the `pyarrow.flight` and `pandas` Python modules to query and format data stored in an {{% cloud-name %}} bucket:
{{% code-tabs-wrapper %}}

8
content/influxdb/cloud-serverless/reference/client-libraries/flight/python-flightsql-dbapi.md
View File

@ -13,13 +13,13 @@ weight: 201
The [Python `flightsql-dbapi` Flight SQL DBAPI library](https://github.com/influxdata/flightsql-dbapi) integrates with Python applications using SQL to query data stored in an {{% cloud-name %}} bucket. The `flightsql-dbapi` library uses the [Flight SQL protocol](https://arrow.apache.org/docs/format/FlightSql.html) to query and retrieve data.
{{% note %}}
#### InfluxDB v3 client libraries
#### Use InfluxDB v3 client libraries
We recommend using the [`influxdb3-python` Python client library](/influxdb/cloud-serverless/reference/client-libraries/v3/python/) for integrating InfluxDB v3 with your Python application code.
[InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) client libraries wrap Apache Arrow Flight clients
and provide convenient methods for writing, querying, and processing data stored in {{% cloud-name %}}.
Client libraries can query using [SQL](/influxdb/cloud-serverless/query-data/sql/execute-queries/python/) or [InfluxQL](/influxdb/cloud-serverless/query-data/influxql/execute-queries/python/).
[InfluxDB v3 client libraries](/influxdb/cloud-serverless/reference/client-libraries/v3/) wrap Apache Arrow Flight clients
and provide convenient methods for [writing](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb), [querying](/influxdb/cloud-serverless/get-started/query/#execute-an-sql-query), and processing data stored in {{% cloud-name %}}.
Client libraries can query using SQL or InfluxQL.
{{% /note %}}
## Installation

7
content/influxdb/cloud-serverless/reference/client-libraries/v3/_index.md
View File

@ -15,6 +15,11 @@ influxdb/cloud-serverless/tags: [client libraries, API, developer tools]
InfluxDB v3 client libraries are language-specific packages that work with
and integrate with your application to write to and query data in {{% cloud-name %}}.
InfluxData and the user community maintain client libraries for developers who want to take advantage of:
- Idioms for InfluxDB requests, responses, and errors.
- Common patterns in a familiar programming language.
- Faster development and less boilerplate code.
InfluxDB client libraries provide configurable batch writing of data to InfluxDB HTTP APIs.
They can be used to construct line protocol data and transform data from other formats
@ -24,7 +29,7 @@ InfluxDB v3 client libraries can query InfluxDB v3 using InfluxDB v3's IOx-speci
Client libraries use Flight clients to execute SQL and InfluxQL queries, request
database information, and retrieve data stored in {{% cloud-name %}}.
Additional functionality may vary among client libraries and some may not be feature-complete.
Additional features may vary among client libraries.
For specifics about a client library, see the library's GitHub repository.
InfluxDB v3 client libraries are part of the [Influx Community](https://github.com/InfluxCommunity).

164
content/influxdb/cloud-serverless/reference/client-libraries/v3/go.md
View File

@ -2,13 +2,12 @@
title: Go client library for InfluxDB v3
list_title: Go
description: The InfluxDB v3 `influxdb3-go` Go client library integrates with Go scripts and applications to write and query data stored in an {{% cloud-name %}} bucket.
external_url: https://github.com/InfluxCommunity/influxdb3-go
menu:
influxdb_cloud_serverless:
name: Go
parent: v3 client libraries
identifier: influxdb3-go
influxdb/cloud-serverless/tags: [go, gRPC, SQL, Flight SQL, client libraries]
influxdb/cloud-serverless/tags: [go, InfluxQL, SQL, Flight, client libraries]
weight: 201
aliases:
- /influxdb/cloud-serverless/reference/api/client-libraries/go/
@ -18,6 +17,163 @@ aliases:
The InfluxDB v3 [`influxdb3-go` Go client library](https://github.com/InfluxCommunity/influxdb3-go) integrates with Go scripts and applications
to write and query data stored in an {{% cloud-name %}} bucket.
The documentation for this client library is available on GitHub.
## Installation
<a href="https://github.com/InfluxCommunity/influxdb3-go" target="_blank" class="btn github">InfluxDB v3 Go client library</a>
```sh
go get github.com/InfluxCommunity/influxdb3-go
```
## Importing the package
The `influxdb3-go` client library module provides the `influxdb3` package.
Import the package:
```go
import (
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
```
## API reference
<!-- The `influxdb_client_3` module includes the following functions: -->
### Function `New`
Create a client to interact with InfluxDB.
#### Syntax
```go
New(config ClientConfig)
```
Initializes and returns a `influxdb3.Client` instance with the following:
- Configuration and functions for writing to the database.
- A `*flight.Client` and functions for querying the database.
#### Parameters
- **`config`**: A `ClientConfig` struct with the following configuration properties:
- **`Host`** (string): the {{% cloud-name %}} server URL
- **`Token`** (string): a database token string
- **`Database`** (string): the database to use for writing and querying.
- **`Organization`** (string): _Optional_. The organization name or ID.
- **`HTTPClient`** (`*http.Client`): _Optional_. Specifies a custom HTTP client, TLS configuration, or timeout to use.
- **`WriteOptions`** (`*WriteOptions`): _Optional_. Options passed to the write client for writing to the bucket.
- **`Headers`** (`http.Header`): _Optional_. Headers to include in all requests.
#### Examples
##### Create an InfluxDB client
{{% code-placeholders "(BUCKET|API)_(NAME|TOKEN)" %}}
```go
package main
import (
"github.com/InfluxCommunity/influxdb3-go/influxdb3"
)
func Query() error {
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "https://{{< influxdb/host >}}",
Token: "API_TOKEN",
Database: "BUCKET_NAME",
})
defer func(client *influxdb3.Client) {
err := client.Close()
if err != nil {
panic(err)
}
}(client)
if(err != nil) {
panic(err)
}
}
```
{{% /code-placeholders %}}
Replace the following configuration values:
- {{% code-placeholder-key %}}`BUCKET_NAME`{{% /code-placeholder-key %}}: the name of the InfluxDB [bucket](/influxdb/cloud-serverless/admin/buckets/) to query
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: an InfluxDB [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ permission on the specified bucket
## Class influxdb3.Client
### Function `Client.Query()`
Query data from InfluxDB IOx using SQL.
#### Syntax
```go
client.Query(ctx context.Context, query string)
```
Sends a Flight query request with SQL to InfluxDB.
Returns the following:
- A custom iterator (*QueryIterator) for accessing query result data and metadata.
- An error, if any.
#### Parameters
- **`ctx`** (`context.Context`): the context to use for the request
- **`query`** (string): the SQL query to execute.
#### Examples
##### Query using SQL
```go
query := `SELECT *
FROM home
WHERE time >= '2022-01-02T08:00:00Z'
AND time <= '2022-01-02T20:00:00Z'`
iterator, err := client.Query(context.Background(), query)
```
### Function `Client.QueryWithOptions()`
Query data from InfluxDB IOx with query options such as **query type** for querying with InfluxQL.
#### Syntax
```go
client.QueryWithOptions(ctx context.Context, options *QueryOptions, query string)
```
Sends a query request with the specified query options to InfluxDB.
Returns the following:
- A custom iterator (*QueryIterator) for accessing query result data and metadata.
- An error, if any.
#### Parameters
- **`ctx`** (`context.Context`): the context to use for the request
- **`options`**: query options (query type, optional database)
- **`query`** (string): the SQL or InfluxQL query to execute.
#### Examples
##### Query using InfluxQL
```go
query := `SELECT *
FROM home
WHERE time >= 1641124000s
AND time <= 1641124000s + 8h`
queryOptions := influxdb3.QueryOptions{QueryType: influxdb3.InfluxQL}
iterator, err := client.QueryWithOptions(context.Background(), &queryOptions, query)
```

2
content/influxdb/cloud-serverless/reference/client-libraries/v3/java.md
View File

@ -11,6 +11,8 @@ menu:
identifier: influxdb3-java
influxdb/cloud-serverless/tags: [Java, gRPC, SQL, Flight SQL, client libraries]
weight: 201
aliases:
- /cloud-serverless/query-data/sql/execute-queries/java/
---
The InfluxDB v3 [`influxdb3-java` Java client library](https://github.com/InfluxCommunity/influxdb3-java) integrates with Java application code

4
content/influxdb/cloud-serverless/reference/glossary.md
View File

@ -105,7 +105,7 @@ By convention, you can express `true` as the integer `1` and false as the intege
### bucket
"Bucket" is the term used in InfluxDB 2.x and _InfluxDB Cloud Serverless_ to refer
to named location where time series data is stored.
to a named location where time series data is stored.
Bucket is synonymous with "database" when using InfluxDB Cloud Dedicated.
Related entries:
@ -1024,7 +1024,7 @@ Related entries:
The InfluxDB v1 and v2 data storage format that allows greater compaction and
higher write and read throughput than B+ or LSM tree implementations.
The TSM storage engine has been replace by [IOx](#iox).
The TSM storage engine has been replaced by [IOx](#iox).
Related entries:
[IOx](#iox)