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](#) [Python](#)
[Go](#) [Go](#)
[C#](#) [C#](#)
[Java](#)
{{% /tabs %}} {{% /tabs %}}
{{% tab-content %}} {{% tab-content %}}
<!--------------------------- BEGIN influx3 CONTENT ---------------------------> <!--------------------------- BEGIN influx3 CONTENT --------------------------->
@ -452,6 +453,7 @@ _If your project's virtual environment is already running, skip to step 3._
{{% tab-content %}} {{% tab-content %}}
<!----------------------------- BEGIN GO CONTENT ------------------------------> <!----------------------------- BEGIN GO CONTENT ------------------------------>
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
1. In the `influxdb_go_client` directory you created in the 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), [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=Go#write-line-protocol-to-influxdb),
create a new file named `query.go`. 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. // Define the query.
query := `SELECT * query := `SELECT *
FROM home FROM home
WHERE time >= '2022-01-02T08:00:00Z' WHERE time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-02T20:00:00Z'` AND time <= '2022-01-01T20:00:00Z'`
// Execute the query. // Execute the query.
iterator, err := client.Query(context.Background(), database, 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. 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 `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 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: [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 %}} {{% tab-content %}}
<!------------------------------ BEGIN C# CONTENT -----------------------------> <!------------------------------ BEGIN C# CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
1. In the `influxdb_csharp_client` directory you created in the 1. In the `influxdb_csharp_client` directory you created in the
[Write data section](/influxdb/cloud-dedicated/get-started/write/?t=C%23), [Write data section](/influxdb/cloud-dedicated/get-started/write/?t=C%23),
create a new file named `Query.cs`. 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"; string? database = "get-started";
/** INFLUX_TOKEN is an environment variable you assigned to your /** INFLUX_TOKEN is an environment variable you assigned to your
* API token value. * database token value.
**/ **/
string? authToken = System.Environment string? authToken = System.Environment
.GetEnvironmentVariable("INFLUX_TOKEN"); .GetEnvironmentVariable("INFLUX_TOKEN");
@ -623,8 +626,8 @@ _If your project's virtual environment is already running, skip to step 3._
const string sql = @" const string sql = @"
SELECT time, room, temp, hum, co SELECT time, room, temp, hum, co
FROM home FROM home
WHERE time >= '2022-01-02T08:00:00Z' WHERE time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-02T20:00:00Z' AND time <= '2022-01-01T20:00:00Z'
"; ";
Console.WriteLine("{0,-30}{1,-15}{2,-15}{3,-15}{4,-15}", 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. - **`hostURL`**: your {{% cloud-name %}} cluster URL.
- **`authToken`**: a [database token](/influxdb/cloud-dedicated/admin/tokens/) with _read_ access to the specified database. - **`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 - **`database`**: the name of the {{% cloud-name %}} database to query
2. Defines a string variable for the SQL 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.
@ -698,10 +701,167 @@ _If your project's virtual environment is already running, skip to step 3._
```sh ```sh
dotnet run dotnet run
``` ```
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
<!------------------------------ END C# CONTENT -------------------------------> <!------------------------------ END C# CONTENT ------------------------------->
{{% /tab-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 >}} {{< /tabs-wrapper >}}
### Query results ### 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 %}} {{% note %}}
Some examples in this getting started tutorial assume your InfluxDB 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). [environment variables](/influxdb/cloud-dedicated/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials).
{{% /note %}} {{% /note %}}
@ -154,6 +154,7 @@ credentials (**url**, **organization**, and **token**) are provided by
[Go](#) [Go](#)
[Node.js](#) [Node.js](#)
[C#](#) [C#](#)
[Java](#)
{{% /tabs %}} {{% /tabs %}}
{{% tab-content %}} {{% tab-content %}}
<!------------------------------- BEGIN TELEGRAF 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: 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. - `--once`: Runs a single Telegraf collection cycle for the configured inputs and outputs, and then exits.
Enter the following command in your terminal: Enter the following command in your terminal:
@ -249,7 +250,7 @@ Include the following with your request:
- **Accept**: application/json - **Accept**: application/json
- **Query parameters**: - **Query parameters**:
- **bucket**: InfluxDB database name - **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 - **Request body**: Line protocol as plain text
{{% note %}} {{% note %}}
@ -398,17 +399,18 @@ dependencies to your current project.
2. Calls the `InfluxDBClient3()` constructor to instantiate an InfluxDB client 2. Calls the `InfluxDBClient3()` constructor to instantiate an InfluxDB client
configured with the following credentials: configured with the following credentials:
- **host**: {{% cloud-name %}} cluster hostname (URL without protocol or trailing slash) - **`host`**: {{% cloud-name %}} cluster hostname (URL without protocol or trailing slash)
- **org**: an empty or arbitrary string (InfluxDB ignores this parameter) - **`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 - **`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 _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. 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. 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 **Because the timestamps in the sample line protocol are in second
precision, the example passes the `write_precision='s'` option 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 %}} 6. To execute the module and write line protocol to your {{% cloud-name %}}
database, enter the following command in your terminal: 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: 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, 1. To instantiate the client, calls the `influx.New(influx.Configs)` function and passes the following:
database token, and [timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) for writing data to {{% cloud-name %}}. - **`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. 2. Defines a deferred function that closes the client when the function returns.
3. Defines an array of line protocol strings where each string 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 **Because the timestamps in the sample line protocol are in second
precision, the example passes `'s'` for the `precision` option in order 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 6. Calls the write client's `writeRecords()` method with the line protocol array
to write the records in batches to InfluxDB. 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() public static async Task WriteLines()
{ {
// Set InfluxDB credentials // Set InfluxDB credentials
const string hostUrl = "https://cloud2.influxdata.com"; const string hostUrl = "https://cluster-id.influxdb.io";
string? database = "get-started"; 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 1. Calls the `new InfluxDBClient()` constructor to instantiate a client configured
with InfluxDB credentials. with InfluxDB credentials.
- **hostUrl**: your {{% cloud-name %}} cluster URL - **`hostUrl`**: your {{% cloud-name %}} cluster URL
- **database**: the name of the {{% cloud-name %}} database to write to - **`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. - **`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._ _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._ _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 **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) 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: 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 ---------------------------> <!---------------------------- END C# CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
{{% /tab-content %}} {{% /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 >}} {{< /tabs-wrapper >}}
If successful, the output is the success message; otherwise, error details and the failure message. 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](#) [Python](#)
[Go](#) [Go](#)
[C#](#) [C#](#)
[Java](#)
{{% /tabs %}} {{% /tabs %}}
{{% tab-content %}} {{% tab-content %}}
@ -481,6 +482,7 @@ _If your project's virtual environment is already running, skip to step 3._
{{% tab-content %}} {{% tab-content %}}
<!----------------------------- BEGIN GO CONTENT ------------------------------> <!----------------------------- BEGIN GO CONTENT ------------------------------>
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
1. In the `influxdb_go_client` directory you created in the 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), [Write data section](/influxdb/cloud-serverless/get-started/write/?t=Go#write-line-protocol-to-influxdb),
create a new file named `query.go`. 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. // Define the query.
query := `SELECT * query := `SELECT *
FROM home FROM home
WHERE time >= '2022-01-02T08:00:00Z' WHERE time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-02T20:00:00Z'` AND time <= '2022-01-01T20:00:00Z'`
// Execute the query. // Execute the query.
iterator, err := client.Query(context.Background(), database, 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)). time := (row["time"].(arrow.Timestamp)).
ToTime(arrow.TimeUnit(arrow.Nanosecond)). ToTime(arrow.TimeUnit(arrow.Nanosecond)).
Format(time.RFC3339) 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"]) 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. 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 `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 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: [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 %}} {{% tab-content %}}
<!------------------------------ BEGIN C# CONTENT -----------------------------> <!------------------------------ BEGIN C# CONTENT ----------------------------->
{{% influxdb/custom-timestamps %}} {{% influxdb/custom-timestamps %}}
1. In the `influxdb_csharp_client` directory you created in the 1. In the `influxdb_csharp_client` directory you created in the
[Write data section](/influxdb/cloud-serverless/get-started/write/?t=C%23), [Write data section](/influxdb/cloud-serverless/get-started/write/?t=C%23),
create a new file named `Query.cs`. 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 = @" const string sql = @"
SELECT time, room, temp, hum, co SELECT time, room, temp, hum, co
FROM home FROM home
WHERE time >= '2022-01-02T08:00:00Z' WHERE time >= '2022-01-01T08:00:00Z'
AND time <= '2022-01-02T20:00:00Z' AND time <= '2022-01-01T20:00:00Z'
"; ";
Console.WriteLine("{0,-30}{1,-15}{2,-15}{3,-15}{4,-15}", 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. - **`hostURL`**: your {{% cloud-name %}} region URL.
- **`authToken`**: an [API token](/influxdb/cloud-serverless/admin/tokens/) with _read_ access to the specified bucket. - **`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 - **`database`**: the name of the {{% cloud-name %}} bucket to query
2. Defines a string variable for the SQL 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.
@ -730,6 +733,164 @@ _If your project's virtual environment is already running, skip to step 3._
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
<!------------------------------ END C# CONTENT -------------------------------> <!------------------------------ END C# CONTENT ------------------------------->
{{% /tab-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 >}} {{< /tabs-wrapper >}}
### Query results ### 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 %}} {{% note %}}
Some examples in this getting started tutorial assume your InfluxDB 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). [environment variables](/influxdb/cloud-serverless/get-started/setup/?t=InfluxDB+API#configure-authentication-credentials).
{{% /note %}} {{% /note %}}
@ -158,6 +158,7 @@ credentials (**url**, **organization**, and **token**) are provided by
[Go](#) [Go](#)
[Node.js](#) [Node.js](#)
[C#](#) [C#](#)
[Java](#)
{{% /tabs %}} {{% /tabs %}}
{{% tab-content %}} {{% tab-content %}}
<!------------------------------ BEGIN UI CONTENT -----------------------------> <!------------------------------ BEGIN UI CONTENT ----------------------------->
@ -195,7 +196,7 @@ The UI will confirm that the data has been written successfully.
**Provide the following**: **Provide the following**:
- `-b, --bucket` or `--bucket-id` flag with the bucket name or ID to write do. - `-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. - String-encoded line protocol.
- [Connection and authentication credentials](/influxdb/cloud-serverless/get-started/setup/?t=influx+CLI#configure-authentication-credentials) - [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"] 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 ```toml
[[outputs.influxdb_v2]] [[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: 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. - `--once`: Runs a single Telegraf collection cycle for the configured inputs and outputs, and then exits.
Enter the following command in your terminal: 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 %}} {{% tab-content %}}
<!----------------------------- BEGIN cURL 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. 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" >}} {{< 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 - **Accept**: application/json
- **Query parameters**: - **Query parameters**:
- **bucket**: InfluxDB bucket name - **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 - **Request body**: Line protocol as plain text
The following example uses cURL and the InfluxDB v2 API to write line protocol 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 2. Calls the `InfluxDBClient3()` constructor to instantiate an InfluxDB client
configured with the following credentials: configured with the following credentials:
- **host**: {{% cloud-name %}} region hostname (URL without protocol or trailing slash) - **`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. - **`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._ _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 - **`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. 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. 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 **Because the timestamps in the sample line protocol are in second
precision, the example passes the `write_precision='s'` option 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 %}} 6. To execute the module and write line protocol to your {{% cloud-name %}}
bucket, enter the following command in your terminal: 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: 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, 1. To instantiate the client, calls the `influx.New(influx.Configs)` function and passes the following:
database token, and [timestamp precision](/influxdb/cloud-dedicated/reference/glossary/#timestamp-precision) for writing data to {{% cloud-name %}}. - **`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. 2. Defines a deferred function that closes the client when the function returns.
3. Defines an array of line protocol strings where each string 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 **Because the timestamps in the sample line protocol are in second
precision, the example passes `'s'` for the `precision` option in order 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 6. Calls the write client's `writeRecords()` method with the line protocol array
to write the records in batches to InfluxDB. 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 - **hostUrl**: your {{% cloud-name %}} region URL
- **database**: the name of the {{% cloud-name %}} bucket to write to - **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. - **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._ _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 **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) 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: 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 ---------------------------> <!---------------------------- END C# CONTENT --------------------------->
{{% /influxdb/custom-timestamps %}} {{% /influxdb/custom-timestamps %}}
{{% /tab-content %}} {{% /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 >}} {{< /tabs-wrapper >}}
If successful, the output is the success message; otherwise, error details and the failure message. If successful, the output is the success message; otherwise, error details and the failure message.