The documentation or JavaDoc of InfluxDBClient should document the existence of NanosecondConverter

[linghengqian]

Specifications

• Client Version: 1.0.0
• InfluxDB Version: Docker Image quay.io/influxdb/influxdb3-core:911ba92ab4133e75fe2a420e16ed9cb4cf32196f
• Platform: InfluxDB 3 Core

Code sample to reproduce problem

• The documentation or JavaDoc of com.influxdb.v3.client.InfluxDBClient should document the existence of com.influxdb.v3.client.internal.NanosecondConverter.
• This does require the introduction of a unit test explanation. I created a minimal reproducible unit test at https://github.com/linghengqian/influxdb-3-core-jdbc-test/blob/master/src/test/java/io/github/linghengqian/influxdb3java/SqlTest.java .
• Verified unit test under Ubuntu 22.04.5 LTS with SDKMAN! and Docker CE.

sdk install java 21.0.6-ms
git clone [email protected]:linghengqian/influxdb-3-core-jdbc-test.git
cd ./influxdb-3-core-jdbc-test/
sdk use java 21.0.6-ms
./mvnw -T 1C clean test

@Testcontainers
public class SqlTest {
    private final Instant magicTime = Instant.now().minusSeconds(10);
    @Container
    private final GenericContainer<?> container = new GenericContainer<>("quay.io/influxdb/influxdb3-core:911ba92ab4133e75fe2a420e16ed9cb4cf32196f")
            .withCommand("serve --node-id local01 --object-store file --data-dir /home/influxdb3/.influxdb3")
            .withExposedPorts(8181);
    @Test
    void test() throws Exception {
        try (InfluxDBClient client = InfluxDBClient.getInstance(
                "http://" + container.getHost() + ":" + container.getMappedPort(8181),
                null,
                "mydb")) {
            writeData(client);
            queryData(client);
        }
    }
    private void writeData(InfluxDBClient client) {
        Point point = Point.measurement("home")
                .setTag("location", "London")
                .setField("value", 30.01)
                .setTimestamp(magicTime);
        client.writePoint(point);
    }
    private void queryData(InfluxDBClient client) {
        try (Stream<Object[]> stream = client.query("select time,location,value from home order by time desc limit 10")) {
            List<Object[]> list = stream.toList();
            assertThat(list.size(), is(1));
            Object[] row = list.getFirst();
            assertThat(row[0], is(NanosecondConverter.convert(magicTime, WritePrecision.NS)));
            assertThat(row[1], is("London"));
            assertThat(row[2], is(30.01));
        }
    }
}

• The interesting thing here is that inserting data into influxdb 3 core always requires providing a java.time.Instant. Because the documentation requires using com.influxdb.v3.client.Point#setTimestamp(java.time.Instant).
• Internally, com.influxdb.v3.client.PointValues#setTimestamp(java.time.Instant) converts the java.time.Instant to a java.math.BigInteger which the user does not know in advance via com.influxdb.v3.client.internal.NanosecondConverter.convert(time, WritePrecision.NS).
• After writing the data, when querying the influxdb 3 core through SQL like select time,location,value from home order by time desc limit 10, the user gets a string like 1738913940774821921 instead of a java.time.Instant class instance. This makes it difficult to design hamcrest assertions in unit tests without using com.influxdb.v3.client.internal.NanosecondConverter.
• It might be better if there was documentation or JavaDoc examples documenting com.influxdb.v3.client.internal.NanosecondConverter .

Expected behavior

• The documentation or JavaDoc of com.influxdb.v3.client.InfluxDBClient should document the existence of com.influxdb.v3.client.internal.NanosecondConverter.

Actual behavior

• The existence of com.influxdb.v3.client.internal.NanosecondConverter is not documented in the documentation or the JavaDoc of com.influxdb.v3.client.InfluxDBClient.

Additional info

• Early investigations came from the unit tests on the https://github.com/linghengqian/influxdb-3-core-jdbc-test side.

[bednar]

Hi @linghengqian,

com.influxdb.v3.client.Point#setTimestamp(java.time.Instant) is provided as a helper method to simplify setting timestamps. In our API design, we represent timestamps as the number of nanoseconds since the Unix epoch.

We’ll clarify the expected return type for timestamps in our query methods.

Best Regards