Skip to content

Commit 5a9c5f3

Browse files
jstirnamanjstirnaman
authored
Merge branch 'master' into 5448-serverless-missing-delete-predicate
2 parents 8888e51 + 5a95f2e commit 5a9c5f3

File tree

4 files changed

+775
-46
lines changed

4 files changed

+775
-46
lines changed

‎content/influxdb/cloud-dedicated/reference/client-libraries/v3/java.md

Lines changed: 345 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@ title: Java client library for InfluxDB v3
33
list_title: Java
44
description: >
55
The InfluxDB v3 `influxdb3-java` Java client library integrates with application code to write and query data stored in an InfluxDB Cloud Dedicated database.
6-
external_url: https://github.com/InfluxCommunity/influxdb3-java
76
menu:
87
influxdb_cloud_dedicated:
98
name: Java
@@ -13,9 +12,350 @@ influxdb/cloud-dedicated/tags: [Flight client, Java, gRPC, SQL, Flight SQL, clie
1312
weight: 201
1413
---
1514

16-
The InfluxDB v3 [`influxdb3-java` Java client library](https://github.com/InfluxCommunity/influxdb3-java) integrates with Java application code
17-
to write and query data stored in an {{% product-name %}} database.
15+
The InfluxDB v3 [`influxdb3-java` Java client library](https://github.com/InfluxCommunity/influxdb3-java) integrates
16+
with Java application code to write and query data stored in {{% product-name %}}.
1817

19-
The documentation for this client library is available on GitHub.
18+
InfluxDB client libraries provide configurable batch writing of data to {{% product-name %}}.
19+
Use client libraries to construct line protocol data, transform data from other formats
20+
to line protocol, and batch write line protocol data to InfluxDB HTTP APIs.
2021

21-
<a href="https://github.com/InfluxCommunity/influxdb3-java" target="_blank" class="btn github">InfluxDB v3 Java client library</a>
22+
InfluxDB v3 client libraries can query {{% product-name %}} using SQL or InfluxQL.
23+
The `influxdb3-java` Java client library wraps the Apache Arrow `org.apache.arrow.flight.FlightClient`
24+
in a convenient InfluxDB v3 interface for executing SQL and InfluxQL queries, requesting
25+
server metadata, and retrieving data from {{% product-name %}} using the Flight protocol with gRPC.
26+
27+
- [Installation](#installation)
28+
- [Using Maven](#using-maven)
29+
- [Using Gradle](#using-gradle)
30+
- [Importing the client](#importing-the-client)
31+
- [API reference](#api-reference)
32+
- [Classes](#classes)
33+
- [InfluxDBClient interface](#influxdbclient-interface)
34+
- [Initialize with credential parameters](#initialize-with-credential-parameters)
35+
- [InfluxDBClient instance methods](#influxdbclient-instance-methods)
36+
- [InfluxDBClient.writePoint](#influxdbclientwritepoint)
37+
- [InfluxDBClient.query](#influxdbclientquery)
38+
39+
40+
#### Example: write and query data
41+
42+
The following example shows how to use `influxdb3-java` to write and query data stored in {{% product-name %}}.
43+
44+
{{% code-placeholders "DATABASE_NAME | DATABASE_TOKEN" %}}
45+
46+
```java
47+
package com.influxdata.demo;
48+
49+
import com.influxdb.v3.client.InfluxDBClient;
50+
import com.influxdb.v3.client.Point;
51+
import com.influxdb.v3.client.query.QueryOptions;
52+
import com.influxdb.v3.client.query.QueryType;
53+
54+
import java.time.Instant;
55+
import java.util.stream.Stream;
56+
57+
public class HelloInfluxDB {
58+
private static final String HOST_URL = "https://{{< influxdb/host >}}"; // your cluster URL
59+
private static final String DATABASE = "DATABASE_NAME"; // your InfluxDB database name
60+
private static final char[] TOKEN = System.getenv("DATABASE_TOKEN"); // a local environment variable that stores your database token
61+
62+
// Create a client instance that writes and queries data in your database.
63+
public static void main(String[] args) {
64+
// Instantiate the client with your InfluxDB credentials
65+
try (InfluxDBClient client = InfluxDBClient.getInstance(HOST_URL, TOKEN, DATABASE)) {
66+
writeData(client);
67+
queryData(client);
68+
}
69+
catch (Exception e) {
70+
System.err.println("An error occurred while connecting to InfluxDB!");
71+
e.printStackTrace();
72+
}
73+
}
74+
75+
// Use the Point class to construct time series data.
76+
private static void writeData(InfluxDBClient client) {
77+
Point point = Point.measurement("temperature")
78+
.setTag("location", "London")
79+
.setField("value", 30.01)
80+
.setTimestamp(Instant.now().minusSeconds(10));
81+
try {
82+
client.writePoint(point);
83+
System.out.println("Data is written to the database.");
84+
}
85+
catch (Exception e) {
86+
System.err.println("Failed to write data to the database.");
87+
e.printStackTrace();
88+
}
89+
}
90+
91+
// Use SQL to query the most recent 10 measurements
92+
private static void queryData(InfluxDBClient client) {
93+
System.out.printf("--------------------------------------------------------%n");
94+
System.out.printf("| %-8s | %-8s | %-30s |%n", "location", "value", "time");
95+
System.out.printf("--------------------------------------------------------%n");
96+
97+
String sql = "select time,location,value from temperature order by time desc limit 10";
98+
try (Stream<Object[]> stream = client.query(sql)) {
99+
stream.forEach(row -> System.out.printf("| %-8s | %-8s | %-30s |%n", row[1], row[2], row[0]));
100+
}
101+
catch (Exception e) {
102+
System.err.println("Failed to query data from the database.");
103+
e.printStackTrace();
104+
}
105+
}
106+
}
107+
```
108+
109+
{{% cite %}}Source: [suyashcjoshi/SimpleJavaInfluxDB](https://github.com/suyashcjoshi/SimpleJavaInfluxDB/) on GitHub{{% /cite %}}
110+
111+
{{% /code-placeholders %}}
112+
113+
Replace the following:
114+
115+
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
116+
the name of your {{% product-name %}}
117+
[database](/influxdb/cloud-dedicated/admin/databases/) to read and write data to
118+
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a
119+
local environment variable that stores your
120+
[token](/influxdb/cloud-dedicated/admin/tokens/database/)--the token must have
121+
read and write permissions on the specified database.
122+
123+
### Run the example to write and query data
124+
125+
1. Build an executable JAR for the project--for example, using Maven:
126+
127+
<!--pytest.mark.skip-->
128+
129+
```bash
130+
mvn package
131+
```
132+
133+
2. In your terminal, run the `java` command to write and query data in your database:
134+
135+
<!--pytest.mark.skip-->
136+
137+
```bash
138+
java \
139+
--add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED \
140+
-jar target/PROJECT_NAME.jar
141+
```
142+
143+
Include the following in your command:
144+
145+
- [`--add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED`](https://arrow.apache.org/docs/java/install.html#id3): with Java version 9 or later and Apache Arrow version 16 or later, exposes JDK internals for Arrow.
146+
For more options, see the [Apache Arrow Java install documentation](https://arrow.apache.org/docs/java/install.html).
147+
- `-jar target/PROJECT_NAME.jar`: your `.jar` file to run.
148+
149+
The output is the newly written data from your {{< product-name >}} database.
150+
151+
## Installation
152+
153+
Include `com.influxdb.influxdb3-java` in your project dependencies.
154+
155+
{{< code-tabs-wrapper >}}
156+
{{% code-tabs %}}
157+
[Maven pom.xml](#)
158+
[Gradle dependency script](#)
159+
{{% /code-tabs %}}
160+
{{% code-tab-content %}}
161+
```xml
162+
<dependency>
163+
<groupId>com.influxdb</groupId>
164+
<artifactId>influxdb3-java</artifactId>
165+
<version>RELEASE</version>
166+
</dependency>
167+
```
168+
{{% /code-tab-content %}}
169+
{{% code-tab-content %}}
170+
<!--pytest.mark.skip-->
171+
```groovy
172+
dependencies {
173+
174+
implementation group: 'com.influxdb', name: 'influxdb3-java', version: 'latest.release'
175+
176+
}
177+
```
178+
{{% /code-tab-content %}}
179+
{{< /code-tabs-wrapper >}}
180+
181+
## Importing the client
182+
183+
The `influxdb3-java` client library package provides
184+
`com.influxdb.v3.client` classes for constructing, writing, and querying data
185+
stored in {{< product-name >}}.
186+
187+
## API reference
188+
189+
- [Interface InfluxDBClient](#interface-influxdbclient)
190+
- [Initialize with credential parameters](#initialize-with-credential-parameters)
191+
- [InfluxDBClient instance methods](#influxdbclient-instance-methods)
192+
- [InfluxDBClient.writePoint](#influxdbclientwritepoint)
193+
- [InfluxDBClient.query](#influxdbclientquery)
194+
195+
196+
## InfluxDBClient interface
197+
198+
`InfluxDBClient` provides an interface for interacting with InfluxDB APIs for writing and querying data.
199+
200+
The `InfluxDBClient.getInstance` constructor initializes and returns a client instance with the following:
201+
202+
- A _write client_ configured for writing to the database.
203+
- An Arrow _Flight client_ configured for querying the database.
204+
205+
To initialize a client, call `getInstance` and pass your credentials as one of
206+
the following types:
207+
208+
- [parameters](#initialize-with-credential-parameters)
209+
- a [`ClientConfig`](https://github.com/InfluxCommunity/influxdb3-java/blob/main/src/main/java/com/influxdb/v3/client/config/ClientConfig.java)
210+
- a [database connection string](#initialize-using-a-database-connection-string)
211+
212+
### Initialize with credential parameters
213+
214+
{{% code-placeholders "host | database | token" %}}
215+
216+
```java
217+
static InfluxDBClient getInstance(@Nonnull final String host,
218+
@Nullable final char[] token,
219+
@Nullable final String database)
220+
```
221+
222+
{{% /code-placeholders %}}
223+
224+
- {{% code-placeholder-key %}}`host`{{% /code-placeholder-key %}} (string): The host URL of the InfluxDB instance.
225+
- {{% code-placeholder-key %}}`database`{{% /code-placeholder-key %}} (string): The [database](/influxdb/cloud-dedicated/admin/databases/) to use for writing and querying.
226+
- {{% code-placeholder-key %}}`token`{{% /code-placeholder-key %}} (char array): A [database token](/influxdb/cloud-dedicated/admin/tokens/database/) with read/write permissions.
227+
228+
#### Example: initialize with credential parameters
229+
230+
{{% code-placeholders "DATABASE_NAME | DATABASE_TOKEN" %}}
231+
232+
```java
233+
package com.influxdata.demo;
234+
235+
import com.influxdb.v3.client.InfluxDBClient;
236+
import com.influxdb.v3.client.Point;
237+
import com.influxdb.v3.client.query.QueryOptions;
238+
import com.influxdb.v3.client.query.QueryType;
239+
240+
import java.time.Instant;
241+
import java.util.stream.Stream;
242+
243+
public class HelloInfluxDB {
244+
private static final String HOST_URL = "https://{{< influxdb/host >}}";
245+
private static final String DATABASE = "DATABASE_NAME";
246+
private static final char[] TOKEN = System.getenv("DATABASE_TOKEN");
247+
248+
// Create a client instance, and then write and query data in InfluxDB.
249+
public static void main(String[] args) {
250+
try (InfluxDBClient client = InfluxDBClient.getInstance(HOST_URL, DATABASE_TOKEN, DATABASE)) {
251+
writeData(client);
252+
queryData(client);
253+
}
254+
catch (Exception e) {
255+
System.err.println("An error occurred while connecting to InfluxDB!");
256+
e.printStackTrace();
257+
}
258+
}
259+
}
260+
```
261+
262+
{{% /code-placeholders %}}
263+
264+
Replace the following:
265+
266+
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
267+
your {{% product-name %}} [database](/influxdb/cloud-dedicated/admin/databases/)
268+
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a
269+
[database token](/influxdb/cloud-dedicated/admin/tokens/database/) that has
270+
the necessary permissions on the specified database.
271+
272+
#### Default tags
273+
274+
To include default [tags](/influxdb/cloud-dedicated/reference/glossary/#tag) in
275+
all written data, pass a `Map` of tag keys and values.
276+
277+
```java
278+
InfluxDBClient getInstance(@Nonnull final String host,
279+
@Nullable final char[] token,
280+
@Nullable final String database,
281+
@Nullable Map<String, String> defaultTags)
282+
```
283+
284+
### Initialize using a database connection string
285+
286+
{{% code-placeholders "DATABASE_NAME | API_TOKEN" %}}
287+
288+
```java
289+
"https://{{< influxdb/host >}}"
290+
+ "?token=DATABASE_TOKEN&amp;database=DATABASE_NAME"
291+
```
292+
293+
{{% /code-placeholders %}}
294+
295+
Replace the following:
296+
297+
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}:
298+
your {{% product-name %}} [database](/influxdb/cloud-dedicated/admin/databases/)
299+
- {{% code-placeholder-key %}}`DATABASE_TOKEN`{{% /code-placeholder-key %}}: a
300+
[database token](/influxdb/cloud-dedicated/admin/tokens/database/) that has
301+
the necessary permissions on the specified database.
302+
303+
### InfluxDBClient instance methods
304+
305+
#### InfluxDBClient.writePoint
306+
307+
To write points as line protocol to a database:
308+
309+
1. [Initialize the `client`](#initialize-with-credential-parameters)--your
310+
token must have write permission on the specified database.
311+
2. Use the `com.influxdb.v3.client.Point` class to create time series data.
312+
3. Call the `client.writePoint()` method to write points as line protocol in your
313+
database.
314+
315+
```java
316+
// Use the Point class to construct time series data.
317+
// Call client.writePoint to write the point in your database.
318+
private static void writeData(InfluxDBClient client) {
319+
Point point = Point.measurement("temperature")
320+
.setTag("location", "London")
321+
.setField("value", 30.01)
322+
.setTimestamp(Instant.now().minusSeconds(10));
323+
try {
324+
client.writePoint(point);
325+
System.out.println("Data written to the database.");
326+
}
327+
catch (Exception e) {
328+
System.err.println("Failed to write data to the database.");
329+
e.printStackTrace();
330+
}
331+
}
332+
```
333+
334+
#### InfluxDBClient.query
335+
336+
To query data and process the results:
337+
338+
1. [Initialize the `client`](#initialize-with-credential-parameters)--the
339+
token must have read permission on the database you want to query.
340+
2. Call `client.query()` and provide your SQL query as a string.
341+
3. Use the result stream's built-in iterator to process row data.
342+
343+
```java
344+
// Query the latest 10 measurements using SQL
345+
private static void queryData(InfluxDBClient client) {
346+
System.out.printf("--------------------------------------------------------%n");
347+
System.out.printf("| %-8s | %-8s | %-30s |%n", "location", "value", "time");
348+
System.out.printf("--------------------------------------------------------%n");
349+
350+
String sql = "select time,location,value from temperature order by time desc limit 10";
351+
try (Stream<Object[]> stream = client.query(sql)) {
352+
stream.forEach(row -> System.out.printf("| %-8s | %-8s | %-30s |%n", row[1], row[2], row[0]));
353+
}
354+
catch (Exception e) {
355+
System.err.println("Failed to query data from the database.");
356+
e.printStackTrace();
357+
}
358+
}
359+
```
360+
361+
<a class="btn" href="https://github.com/InfluxCommunity/influxdb3-java/" target="\_blank">View the InfluxDB v3 Java client library</a>

0 commit comments

Comments
 (0)