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

feature(v3): Write and query data using the Java client library: (#5076) 

* feature(v3): Write and query data using the Java client library:

- Closes #5048
- Part of #5050
- Fixes csharp example.
- Fixes wrong time placeholder values in query samples.
- Misc. cleanup and fixes.

* fix(v3): whitespace

* Apply suggestions from code review

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

---------

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>
pull/5081/head
Jason Stirnaman 2023-08-10 09:44:12 -05:00 committed by GitHub
parent 4b6494969b
commit d3be011e3d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 766 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -202,6 +202,7 @@ credentials (**URL**, **organization**, and **token**) are provided by
[Python](#)
[Go](#)
[C#](#)
[Java](#)
{{% /tabs %}}
{{% tab-content %}}
<!--------------------------- BEGIN influx3 CONTENT --------------------------->
@ -452,6 +453,7 @@ _If your project's virtual environment is already running, skip to step 3._
{{% tab-content %}}
<!----------------------------- BEGIN GO CONTENT ------------------------------>
{{% influxdb/custom-timestamps %}}
1. In the `influxdb_go_client` directory you created in the
[Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Go#write-line-protocol-to-influxdb),
create a new file named `query.go`.
@ -497,8 +499,8 @@ _If your project's virtual environment is already running, skip to step 3._
// Define the query.
query := `SELECT *
FROM home
WHERE time >= '2022-01-02T08:00:00Z'
AND time <= '2022-01-02T20:00:00Z'`
WHERE time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-01T20:00:00Z'`
// Execute the query.
iterator, err := client.Query(context.Background(), database, query)
@ -552,7 +554,7 @@ _If your project's virtual environment is already running, skip to step 3._
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.
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.
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
[Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Go#write-line-protocol-to-influxdb) and insert code to call the `Query()` function--for example:
@ -580,6 +582,7 @@ _If your project's virtual environment is already running, skip to step 3._
{{% tab-content %}}
<!------------------------------ BEGIN C# CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}}
1. In the `influxdb_csharp_client` directory you created in the
[Write data section](/influxdb/cloud-dedicated/get-started/write/?t=C%23),
create a new file named `Query.cs`.
@ -609,7 +612,7 @@ _If your project's virtual environment is already running, skip to step 3._
string? database = "get-started";
/** INFLUX_TOKEN is an environment variable you assigned to your
* API token value.
* database token value.
**/
string? authToken = System.Environment
.GetEnvironmentVariable("INFLUX_TOKEN");
@ -623,8 +626,8 @@ _If your project's virtual environment is already running, skip to step 3._
const string sql = @"
SELECT time, room, temp, hum, co
FROM home
WHERE time >= '2022-01-02T08:00:00Z'
AND time <= '2022-01-02T20:00:00Z'
WHERE time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-01T20:00:00Z'
";
Console.WriteLine("{0,-30}{1,-15}{2,-15}{3,-15}{4,-15}",
@ -662,7 +665,7 @@ _If your project's virtual environment is already running, skip to step 3._
- **`hostURL`**: your {{% cloud-name %}} cluster URL.
- **`authToken`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database.
_For security reasons, we recommend setting this as an environment variable rather than including the raw token string._
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`database`**: the name of the {{% cloud-name %}} database 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.
@ -698,10 +701,167 @@ _If your project's virtual environment is already running, skip to step 3._
```sh
dotnet run
```
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END C# CONTENT ------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------ 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-dedicated/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-dedicated/get-started/write/?t=Java).
2. Inside of the `src/main/java/com/influxdbv3` directory, create a new file named `Query.java`.
3. In `Query.java`, enter the following sample code:
```java
// Query.java
package com.influxdbv3;
import com.influxdb.v3.client.InfluxDBClient;
import java.util.stream.Stream;
/**
* Queries an InfluxDB database using the Java client
* library.
**/
public final class Query {
private Query() {
//not called
}
/**
* @throws Exception
*/
public static void querySQL() throws Exception {
/**
* Query using SQL.
*/
/** Set InfluxDB credentials. **/
final String hostUrl = "https://cluster-id.influxdb.io";
final String database = "get-started";
/** INFLUX_TOKEN is an environment variable you assigned to your
* database token value.
**/
final char[] authToken = (System.getenv("INFLUX_TOKEN")).
toCharArray();
try (InfluxDBClient client = InfluxDBClient.getInstance(hostUrl,
authToken, database)) {
String sql =
"""
SELECT time, room, temp, hum, co
FROM home
WHERE time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-01T20:00:00Z'""";
String layoutHead = "| %-16s | %-12s | %-6s | %-6s | %-6s |%n";
System.out.printf(
"--------------------------------------------------------%n");
System.out.printf(layoutHead,
"time", "room", "co", "hum", "temp");
System.out.printf(
"--------------------------------------------------------%n");
String layout = "| %-16s | %-12s | %-6s | %.1f | %.1f |%n";
try (Stream<Object[]> stream = client.query(sql)) {
stream.forEach(row ->
System.out.printf(layout,
row[0], row[1], row[4], row[3], row[2])
);
}
}
}
}
```
The sample code does the following:
1. Assigns the `com.influxdbv3` package name (the Maven **groupId**).
2. Imports the following classes:
- `com.influxdb.v3.client.InfluxDBClient`
- `java.util.stream.Stream`
3. Defines a `Query` class with a `querySQL()` method that does the following:
1. Calls `InfluxDBClient.getInstance()` to instantiate a client configured
with InfluxDB credentials.
- **`hostUrl`**: 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.
_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.
4. Calls the `InfluxDBClient.query()` method to send the query request with the SQL string.
`query()` returns a stream of rows.
5. Iterates over rows and prints the data in the specified layout to stdout.
4. In your editor, open the `src/main/java/com/influxdbv3/App.java` file and replace its contents with the following sample code:
```java
// App.java
package com.influxdbv3;
/**
* Execute the client functions.
*
*/
public class App {
/**
* @param args
* @throws Exception
*/
public static void main(final String[] args) throws Exception {
// Write data to InfluxDB v3.
Write.writeLineProtocol();
// Run the SQL query.
Query.querySQL();
}
}
```
- The `App`, `Write`, and `Query` classes are part of the same `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:
```sh
mvn compile
```
5. Set the `--add-opens=java.base/java.nio=ALL-UNNAMED` Java option for your environment.
The Apache Arrow Flight library requires this setting for access to the [java.nio API package](https://docs.oracle.com/en/java/javase/20/docs/api/java.base/java/nio/package-summary.html).
For example, enter the following command in your terminal:
**Linux/MacOS**
```sh
export MAVEN_OPTS="--add-opens=java.base/java.nio=ALL-UNNAMED"
```
**Windows PowerShell**
```powershell
$env:MAVEN_OPTS="--add-opens=java.base/java.nio=ALL-UNNAMED"
```
6. To run the app to write to and query {{% cloud-name %}}, execute `App.main()`--for example, using Maven:
```sh
mvn exec:java -Dexec.mainClass="com.influxdbv3.App"
```
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END JAVA CONTENT ------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
### Query results

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

@ -142,7 +142,7 @@ To learn more about available tools and options, see [Write data](/influxdb/clou
{{% note %}}
Some examples in this getting started tutorial assume your InfluxDB
credentials (**url**, **organization**, and **token**) are provided by
credentials (**URL**, **organization**, and **token**) are provided by
[environment variables](/influxdb/cloud-dedicated/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials).
{{% /note %}}
@ -154,6 +154,7 @@ credentials (**url**, **organization**, and **token**) are provided by
[Go](#)
[Node.js](#)
[C#](#)
[Java](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------- BEGIN TELEGRAF CONTENT ------------------------------>
@ -211,7 +212,7 @@ and then write it to {{< cloud-name >}}.
5. To write the data, start the `telegraf` daemon with the following options:
- `--config`: Specifies the filepath of the configuration file.
- `--config`: Specifies the path of the configuration file.
- `--once`: Runs a single Telegraf collection cycle for the configured inputs and outputs, and then exits.
Enter the following command in your terminal:
@ -249,7 +250,7 @@ Include the following with your request:
- **Accept**: application/json
- **Query parameters**:
- **bucket**: InfluxDB database name
- **precision**: Timestamp precision (default is `ns`)
- **precision**:[timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) (default is `ns`)
- **Request body**: Line protocol as plain text
{{% note %}}
@ -398,17 +399,18 @@ dependencies to your current project.
2. Calls the `InfluxDBClient3()` constructor to instantiate an InfluxDB client
configured with the following credentials:
- **host**: {{% cloud-name %}} cluster hostname (URL without protocol or trailing slash)
- **org**: an empty or arbitrary string (InfluxDB ignores this parameter)
- **token**: an InfluxDB [database token](/influxdb/cloud-dedicated/admin/tokens/) with write access to the target database
- **database**: the name of the {{% cloud-name %}} database to write to
- **`host`**: {{% cloud-name %}} cluster hostname (URL without protocol or trailing slash)
- **`org`**: an empty or arbitrary string (InfluxDB ignores this parameter)
- **`token`**: an InfluxDB [database token](/influxdb/cloud-dedicated/admin/tokens/) with write access to the target database.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`database`**: the name of the {{% cloud-name %}} database to write to
3. Defines a list of line protocol strings where each string represents a data record.
4. Calls the `client.write()` method with the line protocol record list and write options.
**Because the timestamps in the sample line protocol are in second
precision, the example passes the `write_precision='s'` option
to set the timestamp precision to seconds.**
to set the[timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds.**
6. To execute the module and write line protocol to your {{% cloud-name %}}
database, enter the following command in your terminal:
@ -541,9 +543,16 @@ 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 InfluxDB URL,
database token, and [timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) for writing data to {{% cloud-name %}}.
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.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`WriteParams`**: `influx.WriteParams` 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
to set the [timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds.**
2. Defines a deferred function that closes the client when the function returns.
3. Defines an array of line protocol strings where each string
@ -687,7 +696,7 @@ To write data to {{% cloud-name %}} using Node.js, use the
**Because the timestamps in the sample line protocol are in second
precision, the example passes `'s'` for the `precision` option in order
to set the timestamp precision to seconds**.
to set the[timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds**.
6. Calls the write client's `writeRecords()` method with the line protocol array
to write the records in batches to InfluxDB.
@ -748,7 +757,7 @@ To write data to {{% cloud-name %}} using Node.js, use the
public static async Task WriteLines()
{
// Set InfluxDB credentials
const string hostUrl = "https://cloud2.influxdata.com";
const string hostUrl = "https://cluster-id.influxdb.io";
string? database = "get-started";
/**
@ -815,10 +824,10 @@ To write data to {{% cloud-name %}} using Node.js, use the
1. Calls the `new InfluxDBClient()` constructor to instantiate a client configured
with InfluxDB credentials.
- **hostUrl**: 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.
_For security reasons, we recommend setting this as an environment variable rather than including the raw token string._
- **`hostUrl`**: 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.
_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._
@ -827,7 +836,7 @@ To write data to {{% cloud-name %}} using Node.js, use the
**Because the timestamps in the sample line protocol are in second
precision, the example passes the [`WritePrecision.S` enum value](https://github.com/InfluxCommunity/influxdb3-csharp/blob/main/Client/Write/WritePrecision.cs)
to the `precision:` option in order to set the timestamp precision to seconds.**
to the `precision:` option to set the[timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds.**
6. In your editor, open the `Program.cs` file and replace its contents with the following:
@ -864,6 +873,197 @@ To write data to {{% cloud-name %}} using Node.js, use the
<!---------------------------- END C# CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}}
{{% /tab-content %}}
{{% tab-content %}}
{{% influxdb/custom-timestamps %}}
<!---------------------------- 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:
```sh
mvn org.apache.maven.plugins:maven-archetype-plugin:3.1.2:generate \
-DarchetypeArtifactId="maven-archetype-quickstart" \
-DarchetypeGroupId="org.apache.maven.archetypes" -DarchetypeVersion="1.4" \
-DgroupId="com.influxdbv3" -DartifactId="influxdb_java_client"
-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.
3. In your terminal or editor, change into the `./influxdb_java_client` directory--for example:
```sh
cd ./influxdb_java_client
```
4. In your editor, open the `pom.xml` Maven configuration file and add the `com.influxdb.influxdb3-java` client library into `dependencies`.
```pom
...
<dependencies>
...
<dependency>
<groupId>com.influxdb</groupId>
<artifactId>influxdb3-java</artifactId>
<version>0.1.0</version>
</dependency>
...
</dependencies>
```
5. To check your `pom.xml` for errors, run Maven's `validate` command--for example, enter the following in your terminal:
```sh
mvn validate
```
6. In your editor, navigate to the `./influxdb_java_client/src/main/java/com/influxdbv3` directory and create a `Write.java` file.
7. In `Write.java`, enter the following sample code:
```java
// Write.java
package com.influxdbv3;
import java.util.List;
import com.influxdb.v3.client.InfluxDBClient;
import com.influxdb.v3.client.write.WriteParameters;
import com.influxdb.v3.client.write.WritePrecision;
/**
* Writes line protocol to InfluxDB using the Java client
* library.
*/
public final class Write {
/**
* Write data to InfluxDB v3.
*/
private Write() {
//not called
}
/**
* @throws Exception
*/
public static void writeLineProtocol() throws Exception {
// Set InfluxDB credentials
final String hostUrl = "https://cluster-id.influxdb.io";
final String database = "get-started";
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* database token value.
*/
final char[] authToken = (System.getenv("INFLUX_TOKEN")).
toCharArray();
// Instantiate the InfluxDB client.
try (InfluxDBClient client = InfluxDBClient.getInstance(hostUrl,
authToken, 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",
"home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000",
"home,room=Living\\ Room temp=21.4,hum=35.9,co=0i 1641027600",
"home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600",
"home,room=Living\\ Room temp=21.8,hum=36.0,co=0i 1641031200",
"home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200",
"home,room=Living\\ Room temp=22.2,hum=36.0,co=0i 1641034800",
"home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800",
"home,room=Living\\ Room temp=22.2,hum=35.9,co=0i 1641038400",
"home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400",
"home,room=Living\\ Room temp=22.4,hum=36.0,co=0i 1641042000",
"home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000",
"home,room=Living\\ Room temp=22.3,hum=36.1,co=0i 1641045600",
"home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600",
"home,room=Living\\ Room temp=22.3,hum=36.1,co=1i 1641049200",
"home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200",
"home,room=Living\\ Room temp=22.4,hum=36.0,co=4i 1641052800",
"home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800",
"home,room=Living\\ Room temp=22.6,hum=35.9,co=5i 1641056400",
"home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400",
"home,room=Living\\ Room temp=22.8,hum=36.2,co=9i 1641060000",
"home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000",
"home,room=Living\\ Room temp=22.5,hum=36.3,co=14i 1641063600",
"home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600",
"home,room=Living\\ Room temp=22.2,hum=36.4,co=17i 1641067200",
"home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200"
);
/**
* Write each record separately to InfluxDB with timestamp
* precision in seconds.
* If no error occurs, print a success message.
* */
for (String record : records) {
client.writeRecord(record, new WriteParameters(null, null,
WritePrecision.S));
System.out.printf("Data has been written successfully:
%s%n", record);
}
}
}
}
```
The sample code does the following:
1. Calls `InfluxDBClient.getInstance()` to instantiate a client configured
with InfluxDB credentials.
- **`hostUrl`**: 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.
_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.
3. Calls the client's `writeRecord()` method to write each record separately to InfluxDB.
**Because the timestamps in the sample line protocol are in second
precision, the example passes the [`WritePrecision.S` enum value](https://github.com/InfluxCommunity/influxdb3-java/blob/main/src/main/java/com/influxdb/v3/client/write/WritePrecision.java)
as the `precision` argument to set the write[timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) to seconds.**
8. In your editor, open the `App.java` file (created by Maven) and replace its contents with the following sample code:
```java
// App.java
package com.influxdbv3;
/**
* Execute the client functions.
*
*/
public class App {
/**
* @param args
* @throws Exception
*/
public static void main(final String[] args) throws Exception {
// Write data to InfluxDB v3.
Write.writeLineProtocol();
}
}
```
- The `App` class and `Write` class are part of the same `com.influxdbv3` package (your project **groupId**).
- `App` defines a `main()` function that calls `Write.writeLineProtocol()`.
9. In your terminal or editor, use Maven to to install dependencies and compile the project code--for example:
```sh
mvn compile
```
10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for example, using Maven:
```sh
mvn exec:java -Dexec.mainClass="com.influxdbv3.App"
```
<!---------------------------- END JAVA CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}}
{{% /tab-content %}}
{{< /tabs-wrapper >}}
If successful, the output is the success message; otherwise, error details and the failure message.

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

@ -205,6 +205,7 @@ credentials (**URL**, **organization**, and **token**) are provided by
[Python](#)
[Go](#)
[C#](#)
[Java](#)
{{% /tabs %}}
{{% tab-content %}}
@ -481,6 +482,7 @@ _If your project's virtual environment is already running, skip to step 3._
{{% tab-content %}}
<!----------------------------- BEGIN GO CONTENT ------------------------------>
{{% influxdb/custom-timestamps %}}
1. In the `influxdb_go_client` directory you created in the
[Write data section](/influxdb/cloud-serverless/get-started/write/?t=Go#write-line-protocol-to-influxdb),
create a new file named `query.go`.
@ -526,8 +528,8 @@ _If your project's virtual environment is already running, skip to step 3._
// Define the query.
query := `SELECT *
FROM home
WHERE time >= '2022-01-02T08:00:00Z'
AND time <= '2022-01-02T20:00:00Z'`
WHERE time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-01T20:00:00Z'`
// Execute the query.
iterator, err := client.Query(context.Background(), database, query)
@ -548,7 +550,7 @@ _If your project's virtual environment is already running, skip to step 3._
time := (row["time"].(arrow.Timestamp)).
ToTime(arrow.TimeUnit(arrow.Nanosecond)).
Format(time.RFC3339)
fmt.Fprintf(w, "%s\t%s\t%d\t%.2f\t%.2f\n",
fmt.Fprintf(w, "%s\t%s\t%d\t%.1f\t%.1f\n",
time, row["room"], row["co"], row["hum"], row["temp"])
}
@ -581,7 +583,7 @@ _If your project's virtual environment is already running, skip to step 3._
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.
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.
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
[Write data section](/influxdb/cloud-serverless/get-started/write/?t=Go#write-line-protocol-to-influxdb) and insert code to call the `Query()` function--for example:
@ -609,6 +611,7 @@ _If your project's virtual environment is already running, skip to step 3._
{{% tab-content %}}
<!------------------------------ BEGIN C# CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}}
1. In the `influxdb_csharp_client` directory you created in the
[Write data section](/influxdb/cloud-serverless/get-started/write/?t=C%23),
create a new file named `Query.cs`.
@ -652,8 +655,8 @@ _If your project's virtual environment is already running, skip to step 3._
const string sql = @"
SELECT time, room, temp, hum, co
FROM home
WHERE time >= '2022-01-02T08:00:00Z'
AND time <= '2022-01-02T20:00:00Z'
WHERE time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-01T20:00:00Z'
";
Console.WriteLine("{0,-30}{1,-15}{2,-15}{3,-15}{4,-15}",
@ -691,7 +694,7 @@ _If your project's virtual environment is already running, skip to step 3._
- **`hostURL`**: your {{% cloud-name %}} region URL.
- **`authToken`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket.
_For security reasons, we recommend setting this as an environment variable rather than including the raw token string._
_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.
@ -730,6 +733,164 @@ _If your project's virtual environment is already running, skip to step 3._
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END C# CONTENT ------------------------------->
{{% /tab-content %}}
{{% tab-content %}}
<!------------------------------ 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)._
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).
2. Inside of the `src/main/java/com/influxdbv3` directory, create a new file named `Query.java`.
3. In `Query.java`, enter the following sample code:
```java
// Query.java
package com.influxdbv3;
import com.influxdb.v3.client.InfluxDBClient;
import java.util.stream.Stream;
/**
* Queries an InfluxDB database (bucket) using the Java client
* library.
**/
public final class Query {
private Query() {
//not called
}
/**
* @throws Exception
*/
public static void querySQL() throws Exception {
/**
* Query using SQL.
*/
/** Set InfluxDB credentials. **/
final String hostUrl = "https://cloud2.influxdata.com";
final String database = "get-started";
/** INFLUX_TOKEN is an environment variable you assigned to your
* API token value.
**/
final char[] authToken = (System.getenv("INFLUX_TOKEN")).
toCharArray();
try (InfluxDBClient client = InfluxDBClient.getInstance(hostUrl,
authToken, database)) {
String sql =
"""
SELECT time, room, temp, hum, co
FROM home
WHERE time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-01T20:00:00Z'""";
String layoutHead = "| %-16s | %-12s | %-6s | %-6s | %-6s |%n";
System.out.printf(
"--------------------------------------------------------%n");
System.out.printf(layoutHead,
"time", "room", "co", "hum", "temp");
System.out.printf(
"--------------------------------------------------------%n");
String layout = "| %-16s | %-12s | %-6s | %.1f | %.1f |%n";
try (Stream<Object[]> stream = client.query(sql)) {
stream.forEach(row ->
System.out.printf(layout,
row[0], row[1], row[4], row[3], row[2])
);
}
}
}
}
```
The sample code does the following:
1. Assigns the `com.influxdbv3` package name (the Maven **groupId**).
2. Imports the following classes:
- `com.influxdb.v3.client.InfluxDBClient`
- `java.util.stream.Stream`
3. Defines a `Query` class with a `querySQL()` method that does the following:
1. Calls `InfluxDBClient.getInstance()` to instantiate a client configured
with InfluxDB credentials.
- **`hostUrl`**: your {{% cloud-name %}} cluster 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.
_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.
4. Calls the `InfluxDBClient.query()` method to send the query request with the SQL string.
`query()` returns a stream of rows.
5. Iterates over rows and prints the data in the specified layout to stdout.
4. In your editor, open the `src/main/java/com/influxdbv3/App.java` file and replace its contents with the following sample code:
```java
// App.java
package com.influxdbv3;
/**
* Execute the client functions.
*
*/
public class App {
/**
* @param args
* @throws Exception
*/
public static void main(final String[] args) throws Exception {
// Write data to InfluxDB v3.
Write.writeLineProtocol();
// Run the SQL query.
Query.querySQL();
}
}
```
- The `App`, `Write`, and `Query` classes are part of the same `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:
```sh
mvn compile
```
5. Set the `--add-opens=java.base/java.nio=ALL-UNNAMED` Java option for your environment.
The Apache Arrow Flight library requires this setting for access to the [java.nio API package](https://docs.oracle.com/en/java/javase/20/docs/api/java.base/java/nio/package-summary.html).
For example, enter the following command in your terminal:
**Linux/MacOS**
```sh
export MAVEN_OPTS="--add-opens=java.base/java.nio=ALL-UNNAMED"
```
**Windows PowerShell**
```powershell
$env:MAVEN_OPTS="--add-opens=java.base/java.nio=ALL-UNNAMED"
```
6. To run the app to write to and query {{% cloud-name %}}, execute `App.main()`--for example, using Maven:
```sh
mvn exec:java -Dexec.mainClass="com.influxdbv3.App"
```
{{% /influxdb/custom-timestamps %}}
<!------------------------------ END JAVA CONTENT ------------------------------->
{{% /tab-content %}}
{{< /tabs-wrapper >}}
### Query results

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

@ -144,7 +144,7 @@ To learn more about available tools and options, see [Write data](influxdb/cloud
{{% note %}}
Some examples in this getting started tutorial assume your InfluxDB
credentials (**url**, **organization**, and **token**) are provided by
credentials (**URL**, **organization**, and **token**) are provided by
[environment variables](/influxdb/cloud-serverless/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials).
{{% /note %}}
@ -158,6 +158,7 @@ credentials (**url**, **organization**, and **token**) are provided by
[Go](#)
[Node.js](#)
[C#](#)
[Java](#)
{{% /tabs %}}
{{% tab-content %}}
<!------------------------------ BEGIN UI CONTENT ----------------------------->
@ -195,7 +196,7 @@ The UI will confirm that the data has been written successfully.
**Provide the following**:
- `-b, --bucket` or `--bucket-id` flag with the bucket name or ID to write do.
- `-p, --precision` flag with the timestamp precision (`s`).
- `-p, --precision` flag with the [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) (`s`).
- String-encoded line protocol.
- [Connection and authentication credentials](/influxdb/cloud-serverless/get-started/setup/?t=influx+CLI#configure-authentication-credentials)
@ -267,7 +268,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 InfluxDB Cloud Serverless bucket:
```toml
[[outputs.influxdb_v2]]
@ -293,7 +294,7 @@ and then write it to {{< cloud-name >}}.
5. To write the data, start the `telegraf` daemon with the following options:
- `--config`: Specifies the filepath of the configuration file.
- `--config`: Specifies the path of the configuration file.
- `--once`: Runs a single Telegraf collection cycle for the configured inputs and outputs, and then exits.
Enter the following command in your terminal:
@ -318,7 +319,7 @@ To learn more, see how to [use Telegraf to write data](/influxdb/cloud-serverles
{{% tab-content %}}
<!----------------------------- BEGIN cURL CONTENT ----------------------------->
To write data to InfluxDB using the InfluxDB HTTP API, send a request to
To write data to InfluxDB using the InfluxDB v2 HTTP API, send a request to
the InfluxDB API `/api/v2/write` endpoint using the `POST` request method.
{{< api-endpoint endpoint="https://cloud2.influxdata.com/api/v2/write" method="post" api-ref="/influxdb/cloud-serverless/api/#operation/PostWrite" >}}
@ -331,7 +332,7 @@ Include the following with your request:
- **Accept**: application/json
- **Query parameters**:
- **bucket**: InfluxDB bucket name
- **precision**: timestamp precision (default is `ns`)
- **precision**: [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) (default is `ns`)
- **Request body**: Line protocol as plain text
The following example uses cURL and the InfluxDB v2 API to write line protocol
@ -475,17 +476,17 @@ dependencies to your current project.
2. Calls the `InfluxDBClient3()` constructor to instantiate an InfluxDB client
configured with the following credentials:
- **host**: {{% cloud-name %}} region hostname (URL without protocol or trailing slash)
- **token**: an InfluxDB [API token](/influxdb/cloud-serverless/admin/tokens/) with _write_ access to the specified bucket.
_For security reasons, we recommend setting this as an environment variable rather than including the raw token string._
- **database**: the name of the {{% cloud-name %}} bucket to write to
- **`host`**: {{% cloud-name %}} region hostname (URL without protocol or trailing slash)
- **`token`**: an InfluxDB [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._
- **`database`**: the name of the {{% cloud-name %}} bucket to write to
3. Defines a list of line protocol strings where each string represents a data record.
4. Calls the `client.write()` method with the line protocol record list and write options.
**Because the timestamps in the sample line protocol are in second
precision, the example passes the `write_precision='s'` option
to set the timestamp precision to seconds.**
to set the [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.**
6. To execute the module and write line protocol to your {{% cloud-name %}}
bucket, enter the following command in your terminal:
@ -618,9 +619,16 @@ 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 InfluxDB URL,
database token, and [timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) for writing data to {{% cloud-name %}}.
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.
_Store this in a secret store or environment variable to avoid exposing the raw token string._
- **`WriteParams`**: `influx.WriteParams` 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
to set the [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.**
2. Defines a deferred function that closes the client when the function returns.
3. Defines an array of line protocol strings where each string
@ -764,7 +772,7 @@ To write data to {{% cloud-name %}} using Node.js, use the
**Because the timestamps in the sample line protocol are in second
precision, the example passes `'s'` for the `precision` option in order
to set the timestamp precision to seconds**.
to set the [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds**.
6. Calls the write client's `writeRecords()` method with the line protocol array
to write the records in batches to InfluxDB.
@ -895,7 +903,7 @@ To write data to {{% cloud-name %}} using Node.js, use the
- **hostUrl**: 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.
_For security reasons, we recommend setting this as an environment variable rather than including the raw token string._
_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._
@ -904,7 +912,7 @@ To write data to {{% cloud-name %}} using Node.js, use the
**Because the timestamps in the sample line protocol are in second
precision, the example passes the [`WritePrecision.S` enum value](https://github.com/InfluxCommunity/influxdb3-csharp/blob/main/Client/Write/WritePrecision.cs)
to the `precision:` option in order to set the timestamp precision to seconds.**
to the `precision:` option to set the [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.**
6. In your editor, open the `Program.cs` file and replace its contents with the following:
@ -941,6 +949,195 @@ To write data to {{% cloud-name %}} using Node.js, use the
<!---------------------------- END C# CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}}
{{% /tab-content %}}
{{% tab-content %}}
{{% influxdb/custom-timestamps %}}
<!---------------------------- 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:
```sh
mvn org.apache.maven.plugins:maven-archetype-plugin:3.1.2:generate \
-DarchetypeArtifactId="maven-archetype-quickstart" \
-DarchetypeGroupId="org.apache.maven.archetypes" -DarchetypeVersion="1.4" \
-DgroupId="com.influxdbv3" -DartifactId="influxdb_java_client"
-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.
3. In your terminal or editor, change into the `./influxdb_java_client` directory--for example:
```sh
cd ./influxdb_java_client
```
4. In your editor, open the `pom.xml` Maven configuration file and add the `com.influxdb.influxdb3-java` client library into `dependencies`.
```pom
...
<dependencies>
...
<dependency>
<groupId>com.influxdb</groupId>
<artifactId>influxdb3-java</artifactId>
<version>0.1.0</version>
</dependency>
...
</dependencies>
```
5. To check your `pom.xml` for errors, run Maven's `validate` command--for example, enter the following in your terminal:
```sh
mvn validate
```
6. In your editor, navigate to the `./influxdb_java_client/src/main/java/com/influxdbv3` directory and create a `Write.java` file.
7. In `Write.java`, enter the following sample code:
```java
// Write.java
package com.influxdbv3;
import java.util.List;
import com.influxdb.v3.client.InfluxDBClient;
import com.influxdb.v3.client.write.WriteParameters;
import com.influxdb.v3.client.write.WritePrecision;
/**
* Writes line protocol to InfluxDB using the Java client
* library.
*/
public final class Write {
/**
* Write data to InfluxDB v3.
*/
private Write() {
//not called
}
/**
* @throws Exception
*/
public static void writeLineProtocol() throws Exception {
// Set InfluxDB credentials
final String hostUrl = "https://cloud2.influxdata.com";
final String database = "get-started";
/**
* INFLUX_TOKEN is an environment variable you assigned to your
* database token value.
*/
final char[] authToken = (System.getenv("INFLUX_TOKEN")).
toCharArray();
// Instantiate the InfluxDB client.
try (InfluxDBClient client = InfluxDBClient.getInstance(hostUrl,
authToken, 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",
"home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000",
"home,room=Living\\ Room temp=21.4,hum=35.9,co=0i 1641027600",
"home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600",
"home,room=Living\\ Room temp=21.8,hum=36.0,co=0i 1641031200",
"home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200",
"home,room=Living\\ Room temp=22.2,hum=36.0,co=0i 1641034800",
"home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800",
"home,room=Living\\ Room temp=22.2,hum=35.9,co=0i 1641038400",
"home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400",
"home,room=Living\\ Room temp=22.4,hum=36.0,co=0i 1641042000",
"home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000",
"home,room=Living\\ Room temp=22.3,hum=36.1,co=0i 1641045600",
"home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600",
"home,room=Living\\ Room temp=22.3,hum=36.1,co=1i 1641049200",
"home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200",
"home,room=Living\\ Room temp=22.4,hum=36.0,co=4i 1641052800",
"home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800",
"home,room=Living\\ Room temp=22.6,hum=35.9,co=5i 1641056400",
"home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400",
"home,room=Living\\ Room temp=22.8,hum=36.2,co=9i 1641060000",
"home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000",
"home,room=Living\\ Room temp=22.5,hum=36.3,co=14i 1641063600",
"home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600",
"home,room=Living\\ Room temp=22.2,hum=36.4,co=17i 1641067200",
"home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200"
);
/**
* Write each record separately to InfluxDB with timestamp
* precision in seconds.
* If no error occurs, print a success message.
* */
for (String record : records) {
client.writeRecord(record, new WriteParameters(null, null,
WritePrecision.S));
System.out.printf("Data has been written successfully:
%s%n", record);
}
}
}
}
```
The sample code does the following:
1. Calls `InfluxDBClient.getInstance()` to instantiate a client configured
with InfluxDB credentials.
- **`hostUrl`**: the {{% 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.
_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.
3. Calls the client's `writeRecord()` method to write each record separately to InfluxDB.
**Because the timestamps in the sample line protocol are in second
precision, the example passes the [`WritePrecision.S` enum value](https://github.com/InfluxCommunity/influxdb3-java/blob/main/src/main/java/com/influxdb/v3/client/write/WritePrecision.java)
as the `precision` argument to set the write [timestamp precision](/influxdb/cloud-serverless/reference/glossary/#timestamp-precision) to seconds.**
8. In your editor, open the `App.java` file (created by Maven) and replace its contents with the following sample code:
```java
// App.java
package com.influxdbv3;
/**
* Execute the client functions.
*
*/
public class App {
/**
* @param args
* @throws Exception
*/
public static void main(final String[] args) throws Exception {
// Write data to InfluxDB v3.
Write.writeLineProtocol();
}
}
```
- The `App` class and `Write` class are part of the same `com.influxdbv3` package (your project **groupId**).
- `App` defines a `main()` function that calls `Write.writeLineProtocol()`.
9. In your terminal or editor, use Maven to to install dependencies and compile the project code--for example:
```sh
mvn compile
```
10. In your terminal or editor, execute `App.main()` to write to InfluxDB--for example, using Maven:
```sh
mvn exec:java -Dexec.mainClass="com.influxdbv3.App"
```
<!---------------------------- END JAVA CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}}
{{% /tab-content %}}
{{< /tabs-wrapper >}}
If successful, the output is the success message; otherwise, error details and the failure message.