feat: fast no-sync write support (#238)

Author: jansimonb

CHANGELOG.md

@@ -3,6 +3,16 @@
 ### Features
 
 1. [#209](https://github.com/InfluxCommunity/influxdb3-java/pull/209) Add query function returning row as map.
+1. [#238](https://github.com/InfluxCommunity/influxdb3-java/pull/238): Support fast writes without waiting for WAL
+   persistence:
+   - New write option (`WriteOptions.noSync`) added: `true` value means faster write but without the confirmation that
+     the data was persisted. Default value: `false`.
+   - **Supported by self-managed InfluxDB 3 Core and Enterprise servers only!**
+   - Also configurable via connection string query parameter (`writeNoSync`).
+   - Also configurable via environment variable (`INFLUX_WRITE_NO_SYNC`).
+   - Long precision string values added from v3 HTTP API: `"nanosecond"`, `"microsecond"`, `"millisecond"`,
+     `"second"` (
+     in addition to the existing `"ns"`, `"us"`, `"ms"`, `"s"`).
 
 ## 1.1.0 [2025-05-22]
 

src/main/java/com/influxdb/v3/client/InfluxDBClient.java

@@ -526,6 +526,7 @@ static InfluxDBClient getInstance(@Nonnull final ClientConfig config) {
      *   <li>database - database (bucket) name</li>
      *   <li>precision - timestamp precision when writing data</li>
      *   <li>gzipThreshold - payload size size for gzipping data</li>
+     *   <li>writeNoSync - skip waiting for WAL persistence on write</li>
      * </ul>
      *
      * @param connectionString connection string
@@ -558,6 +559,7 @@ static InfluxDBClient getInstance(@Nonnull final String connectionString) {
      *   <li>INFLUX_DATABASE - database (bucket) name</li>
      *   <li>INFLUX_PRECISION - timestamp precision when writing data</li>
      *   <li>INFLUX_GZIP_THRESHOLD - payload size size for gzipping data</li>
+     *   <li>INFLUX_WRITE_NO_SYNC - skip waiting for WAL persistence on write</li>
      * </ul>
      * Supported system properties:
      * <ul>
@@ -568,6 +570,7 @@ static InfluxDBClient getInstance(@Nonnull final String connectionString) {
      *   <li>influx.database - database (bucket) name</li>
      *   <li>influx.precision - timestamp precision when writing data</li>
      *   <li>influx.gzipThreshold - payload size size for gzipping data</li>
+     *   <li>influx.writeNoSync - skip waiting for WAL persistence on write</li>
      * </ul>
      *
      * @return instance of {@link InfluxDBClient}

src/main/java/com/influxdb/v3/client/config/ClientConfig.java

@@ -36,6 +36,7 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
+import com.influxdb.v3.client.write.WriteOptions;
 import com.influxdb.v3.client.write.WritePrecision;
 
 /**
@@ -52,6 +53,7 @@
  *     <li><code>writePrecision</code> - precision to use when writing points to InfluxDB</li>
  *     <li><code>defaultTags</code> - defaultTags added when writing points to InfluxDB</li>
  *     <li><code>gzipThreshold</code> - threshold when gzip compression is used for writing points to InfluxDB</li>
+ *     <li><code>writeNoSync</code> - skip waiting for WAL persistence on write</li>
  *     <li><code>responseTimeout</code> - timeout when connecting to InfluxDB</li>
  *     <li><code>allowHttpRedirects</code> - allow redirects for InfluxDB connections</li>
  *     <li><code>disableServerCertificateValidation</code> -
@@ -73,6 +75,7 @@
  *     .database("my-database")
  *     .writePrecision(WritePrecision.S)
  *     .gzipThreshold(4096)
+ *     .writeNoSync(true)
  *     .proxyUrl("http://localhost:10000")
  *     .build();
  *
@@ -94,6 +97,7 @@ public final class ClientConfig {
     private final String database;
     private final WritePrecision writePrecision;
     private final Integer gzipThreshold;
+    private final Boolean writeNoSync;
     private final Map<String, String> defaultTags;
     private final Duration timeout;
     private final Boolean allowHttpRedirects;
@@ -180,6 +184,16 @@ public Integer getGzipThreshold() {
         return gzipThreshold;
     }
 
+    /**
+     * Skip waiting for WAL persistence on write?
+     *
+     * @return skip waiting for WAL persistence on write
+     */
+    @Nonnull
+    public Boolean getWriteNoSync() {
+        return writeNoSync;
+    }
+
     /**
      * Gets default tags used when writing points.
      * @return default tags
@@ -295,6 +309,7 @@ public boolean equals(final Object o) {
                 && Objects.equals(database, that.database)
                 && writePrecision == that.writePrecision
                 && Objects.equals(gzipThreshold, that.gzipThreshold)
+                && Objects.equals(writeNoSync, that.writeNoSync)
                 && Objects.equals(defaultTags, that.defaultTags)
                 && Objects.equals(timeout, that.timeout)
                 && Objects.equals(allowHttpRedirects, that.allowHttpRedirects)
@@ -309,7 +324,7 @@ public boolean equals(final Object o) {
     @Override
     public int hashCode() {
         return Objects.hash(host, Arrays.hashCode(token), authScheme, organization,
-                database, writePrecision, gzipThreshold,
+                database, writePrecision, gzipThreshold, writeNoSync,
                 timeout, allowHttpRedirects, disableServerCertificateValidation,
                 proxy, proxyUrl, authenticator, headers,
                 defaultTags, sslRootsFilePath);
@@ -323,6 +338,7 @@ public String toString() {
                 .add("database='" + database + "'")
                 .add("writePrecision=" + writePrecision)
                 .add("gzipThreshold=" + gzipThreshold)
+                .add("writeNoSync=" + writeNoSync)
                 .add("timeout=" + timeout)
                 .add("allowHttpRedirects=" + allowHttpRedirects)
                 .add("disableServerCertificateValidation=" + disableServerCertificateValidation)
@@ -348,6 +364,7 @@ public static final class Builder {
         private String database;
         private WritePrecision writePrecision;
         private Integer gzipThreshold;
+        private Boolean writeNoSync;
         private Map<String, String> defaultTags;
         private Duration timeout;
         private Boolean allowHttpRedirects;
@@ -452,6 +469,19 @@ public Builder gzipThreshold(@Nullable final Integer gzipThreshold) {
             return this;
         }
 
+        /**
+         * Sets whether to skip waiting for WAL persistence on write.
+         *
+         * @param writeNoSync skip waiting for WAL persistence on write
+         * @return this
+         */
+        @Nonnull
+        public Builder writeNoSync(@Nullable final Boolean writeNoSync) {
+
+            this.writeNoSync = writeNoSync;
+            return this;
+        }
+
         /**
          * Sets default tags to be written with points.
          *
@@ -634,6 +664,9 @@ public ClientConfig build(@Nonnull final String connectionString) throws Malform
             if (parameters.containsKey("gzipThreshold")) {
                 this.gzipThreshold(Integer.parseInt(parameters.get("gzipThreshold")));
             }
+            if (parameters.containsKey("writeNoSync")) {
+                this.writeNoSync(Boolean.parseBoolean(parameters.get("writeNoSync")));
+            }
 
             return new ClientConfig(this);
         }
@@ -682,6 +715,10 @@ public ClientConfig build(@Nonnull final Map<String, String> env, final Properti
             if (gzipThreshold != null) {
                 this.gzipThreshold(Integer.parseInt(gzipThreshold));
             }
+            final String writeNoSync = get.apply("INFLUX_WRITE_NO_SYNC", "influx.writeNoSync");
+            if (writeNoSync != null) {
+                this.writeNoSync(Boolean.parseBoolean(writeNoSync));
+            }
 
             return new ClientConfig(this);
         }
@@ -690,15 +727,19 @@ private WritePrecision parsePrecision(@Nonnull final String precision) {
             WritePrecision writePrecision;
             switch (precision) {
                 case "ns":
+                case "nanosecond":
                     writePrecision = WritePrecision.NS;
                     break;
                 case "us":
+                case "microsecond":
                     writePrecision = WritePrecision.US;
                     break;
                 case "ms":
+                case "millisecond":
                     writePrecision = WritePrecision.MS;
                     break;
                 case "s":
+                case "second":
                     writePrecision = WritePrecision.S;
                     break;
                 default:
@@ -716,8 +757,9 @@ private ClientConfig(@Nonnull final Builder builder) {
         authScheme = builder.authScheme;
         organization = builder.organization;
         database = builder.database;
-        writePrecision = builder.writePrecision != null ? builder.writePrecision : WritePrecision.NS;
-        gzipThreshold = builder.gzipThreshold != null ? builder.gzipThreshold : 1000;
+        writePrecision = builder.writePrecision != null ? builder.writePrecision : WriteOptions.DEFAULT_WRITE_PRECISION;
+        gzipThreshold = builder.gzipThreshold != null ? builder.gzipThreshold : WriteOptions.DEFAULT_GZIP_THRESHOLD;
+        writeNoSync = builder.writeNoSync != null ? builder.writeNoSync : WriteOptions.DEFAULT_NO_SYNC;
         defaultTags = builder.defaultTags;
         timeout = builder.timeout != null ? builder.timeout : Duration.ofSeconds(10);
         allowHttpRedirects = builder.allowHttpRedirects != null ? builder.allowHttpRedirects : false;

src/main/java/com/influxdb/v3/client/internal/InfluxDBClientImpl.java

@@ -38,18 +38,21 @@
 import javax.annotation.Nullable;
 
 import io.netty.handler.codec.http.HttpMethod;
+import io.netty.handler.codec.http.HttpResponseStatus;
 import org.apache.arrow.flight.CallOption;
 import org.apache.arrow.vector.FieldVector;
 import org.apache.arrow.vector.VectorSchemaRoot;
 
 import com.influxdb.v3.client.InfluxDBApiException;
+import com.influxdb.v3.client.InfluxDBApiHttpException;
 import com.influxdb.v3.client.InfluxDBClient;
 import com.influxdb.v3.client.Point;
 import com.influxdb.v3.client.PointValues;
 import com.influxdb.v3.client.config.ClientConfig;
 import com.influxdb.v3.client.query.QueryOptions;
 import com.influxdb.v3.client.write.WriteOptions;
 import com.influxdb.v3.client.write.WritePrecision;
+import com.influxdb.v3.client.write.WritePrecisionConverter;
 
 /**
  * Implementation of the InfluxDBClient. It is thread-safe and can be safely shared between threads.
@@ -309,11 +312,27 @@ private <T> void writeData(@Nonnull final List<T> data, @Nonnull final WriteOpti
 
         WritePrecision precision = options.precisionSafe(config);
 
-        Map<String, String> queryParams = new HashMap<>() {{
-            put("bucket", database);
-            put("org", config.getOrganization());
-            put("precision", precision.name().toLowerCase());
-        }};
+        String path;
+        Map<String, String> queryParams;
+        boolean noSync = options.noSyncSafe(config);
+        if (noSync) {
+            // Setting no_sync=true is supported only in the v3 API.
+            path = "api/v3/write_lp";
+            queryParams = new HashMap<>() {{
+                put("org", config.getOrganization());
+                put("db", database);
+                put("precision", WritePrecisionConverter.toV3ApiString(precision));
+                put("no_sync", "true");
+            }};
+        } else {
+            // By default, use the v2 API.
+            path = "api/v2/write";
+            queryParams = new HashMap<>() {{
+                put("org", config.getOrganization());
+                put("bucket", database);
+                put("precision", WritePrecisionConverter.toV2ApiString(precision));
+            }};
+        }
 
         Map<String, String> defaultTags = options.defaultTagsSafe(config);
 
@@ -349,7 +368,16 @@ private <T> void writeData(@Nonnull final List<T> data, @Nonnull final WriteOpti
         }
         headers.putAll(options.headersSafe());
 
-        restClient.request("api/v2/write", HttpMethod.POST, body, queryParams, headers);
+        try {
+            restClient.request(path, HttpMethod.POST, body, queryParams, headers);
+        } catch (InfluxDBApiHttpException e) {
+            if (noSync && e.statusCode() == HttpResponseStatus.METHOD_NOT_ALLOWED.code()) {
+                // Server does not support the v3 write API, can't use the NoSync option.
+                throw new InfluxDBApiHttpException("Server doesn't support write with NoSync=true "
+                        + "(supported by InfluxDB 3 Core/Enterprise servers only).", e.headers(), e.statusCode());
+            }
+            throw e;
+        }
     }
 
     @Nonnull