client refactoring

Author: bluestreak01

core/src/main/java/io/questdb/client/cutlass/qwp/client/QwpColumnBatch.java

@@ -30,15 +30,21 @@
  * Invoked by {@link QwpQueryClient#execute(String, QwpColumnBatchHandler)}:
  * once per {@code RESULT_BATCH} frame via {@link #onBatch(QwpColumnBatch)},
  * then exactly once via either {@link #onEnd(long)} or
- * {@link #onError(byte, String)}.
+ * {@link #onError(byte, String)} (or {@link #onExecDone} for non-SELECT queries).
  * <p>
  * The {@link QwpColumnBatch} passed to {@link #onBatch} is valid only for the
- * duration of the callback. Copy any values you need to retain.
+ * duration of that call. Copy any values you need to retain.
+ * <p>
+ * <strong>Exception contract:</strong> if any callback method throws, the
+ * exception propagates out of the {@link QwpQueryClient#execute} call on the
+ * caller's thread and no further callbacks fire for that query. The connection
+ * remains usable for subsequent queries.
  */
 public interface QwpColumnBatchHandler {
 
     /**
-     * Invoked for each {@code RESULT_BATCH} received.
+     * Invoked for each {@code RESULT_BATCH} received. Throwing from here aborts
+     * the query (see the class-level exception contract).
      *
      * @param batch column-major view over the batch; valid until {@code onBatch} returns
      */
@@ -52,7 +58,8 @@ public interface QwpColumnBatchHandler {
     void onEnd(long totalRows);
 
     /**
-     * Invoked exactly once if the query fails at any point.
+     * Invoked exactly once if the query fails at any point, instead of
+     * {@link #onEnd} / {@link #onExecDone}.
      *
      * @param status  one of the QWP status codes (e.g., {@code STATUS_PARSE_ERROR})
      * @param message server-supplied error message (may be empty)
@@ -64,14 +71,16 @@ public interface QwpColumnBatchHandler {
      * a non-SELECT (DDL, INSERT, UPDATE, etc.). No batches are delivered for
      * such queries -- the server executes the statement and replies with a
      * single {@code EXEC_DONE}.
+     * <p>
+     * Override this method in any handler that may see non-SELECT SQL (e.g. a
+     * generic query runner or a test harness that issues {@code CREATE TABLE}
+     * before querying). SELECT-only handlers can rely on the default no-op and
+     * will only ever see {@link #onBatch} + {@link #onEnd} / {@link #onError}.
      *
      * @param opType       matches one of {@code CompiledQuery.SELECT} / {@code INSERT} /
      *                     {@code UPDATE} / {@code CREATE_TABLE} / etc. (server-side constants)
      * @param rowsAffected rows inserted / updated / deleted; 0 for pure DDL
      */
     default void onExecDone(short opType, long rowsAffected) {
-        // Default no-op lets existing SELECT-only implementations stay source-
-        // compatible. A handler that ever sees a non-SELECT query should
-        // override this method.
     }
 }

core/src/main/java/io/questdb/client/cutlass/qwp/client/QwpColumnBatchHandler.java

@@ -25,6 +25,7 @@
 package io.questdb.client.cutlass.qwp.client;
 
 import io.questdb.client.std.MemoryTag;
+import io.questdb.client.std.ObjList;
 import io.questdb.client.std.QuietCloseable;
 import io.questdb.client.std.Unsafe;
 
@@ -92,6 +93,14 @@ public class QwpColumnLayout implements QuietCloseable {
      * left with stale values -- use {@link #nonNullIdx}/null-check first.
      */
     int[] symbolRowIds;
+    /**
+     * SYMBOL: lazy String cache indexed by dict ID. Populated on first
+     * {@code getSymbol}/{@code getSymbolForId}/{@code getString}(SYMBOL) call
+     * so a query over 10M rows with N distinct symbols materialises only N
+     * Strings per batch instead of one per row. Cleared (size reset to 0) in
+     * {@link #clear()} because a reused layout may be rebound to a different dict.
+     */
+    final ObjList<String> symbolStringCache = new ObjList<>();
     /**
      * Absolute payload address where this column's non-null values start. For
      * fixed-width types this is the dense values array. For strings/varchars
@@ -141,6 +150,7 @@ public void clear() {
         symbolDictHeapAddr = 0;
         symbolDictEntriesAddr = 0;
         symbolDictSize = 0;
+        symbolStringCache.clear();
         nextAddr = 0;
     }
 

core/src/main/java/io/questdb/client/cutlass/qwp/client/QwpColumnLayout.java

@@ -26,17 +26,21 @@
 
 /**
  * Per-column metadata recorded when a schema is registered on a client connection.
+ * Internal to the QWP client; callers read column attributes through the forwarder
+ * methods on {@link QwpColumnBatch} (for example {@link QwpColumnBatch#getColumnName}).
  */
-public class QwpEgressColumnInfo {
-    public String name;
-    public int precisionBits; // valid only for GEOHASH
-    public int scale;         // valid only for DECIMAL*
-    public byte wireType;
+class QwpEgressColumnInfo {
+    String name;
+    int precisionBits; // valid only for GEOHASH; set per-batch by QwpResultBatchDecoder.parseColumn
+    int scale;         // valid only for DECIMAL*;  set per-batch by QwpResultBatchDecoder.parseColumn
+    byte wireType;
 
-    public void of(String name, byte wireType, int scale, int precisionBits) {
+    void of(String name, byte wireType) {
         this.name = name;
         this.wireType = wireType;
-        this.scale = scale;
-        this.precisionBits = precisionBits;
+        // scale / precisionBits come from the per-batch column data section, not the schema.
+        // Reset here in case a schema slot is reused for a different schema.
+        this.scale = 0;
+        this.precisionBits = 0;
     }
 }

core/src/main/java/io/questdb/client/cutlass/qwp/client/QwpEgressColumnInfo.java

@@ -370,7 +370,12 @@ public static QwpQueryClient fromConfig(CharSequence configurationString) {
     }
 
     /**
-     * Creates a plain-text (non-TLS) QWP query client.
+     * Creates a plain-text (non-TLS) QWP query client against {@code host:port}
+     * with all other settings at their defaults. For TLS, authentication,
+     * custom paths, compression, or buffer pool sizing use
+     * {@link #fromConfig(CharSequence)} with a connection string instead.
+     *
+     * @see #fromConfig(CharSequence)
      */
     public static QwpQueryClient newPlainText(CharSequence host, int port) {
         return new QwpQueryClient(host, port);

core/src/main/java/io/questdb/client/cutlass/qwp/client/QwpQueryClient.java

@@ -405,7 +405,7 @@ private void decodePayload(QwpBatchBuffer buffer, long payload, int payloadLen)
                 String colName = readUtf8(p, colNameLen);
                 p += colNameLen;
                 byte wireType = Unsafe.getUnsafe().getByte(p++);
-                columns.getQuick(i).of(colName, wireType, 0, 0);
+                columns.getQuick(i).of(colName, wireType);
             }
         } else if (schemaMode == QwpConstants.SCHEMA_MODE_REFERENCE) {
             if (schemaId >= schemaRegistry.size() || schemaRegistry.getQuick(schemaId) == null) {

core/src/main/java/io/questdb/client/cutlass/qwp/client/QwpResultBatchDecoder.java

@@ -25,9 +25,18 @@
 package io.questdb.client.std;
 
 /**
- * A 256-bit hash with string representation up to 64 hex digits following a prefix '0x'.
- * (e.g. 0xaba86bf575ba7fde98b6673bb7d85bf489fd71a619cddaecba5de0378e3d22ed)
+ * A 256-bit value split into four 64-bit words, least-significant first.
+ * Also used for QuestDB's DECIMAL256 unscaled value (same wire layout).
+ * Pair with {@link Long256Impl} as a reusable sink.
  */
 public interface Long256 {
     int BYTES = 32;
-}
+
+    long getLong0();
+
+    long getLong1();
+
+    long getLong2();
+
+    long getLong3();
+}

core/src/main/java/io/questdb/client/std/Long256.java

@@ -0,0 +1,65 @@
+/*+*****************************************************************************
+ *     ___                  _   ____  ____
+ *    / _ \ _   _  ___  ___| |_|  _ \| __ )
+ *   | | | | | | |/ _ \/ __| __| | | |  _ \
+ *   | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+ *    \__\_\\__,_|\___||___/\__|____/|____/
+ *
+ *  Copyright (c) 2014-2019 Appsicle
+ *  Copyright (c) 2019-2026 QuestDB
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ ******************************************************************************/
+
+package io.questdb.client.std;
+
+/**
+ * Mutable concrete {@link Long256} backed by four {@code long} fields. Intended
+ * as a reusable sink: hand the same instance to a series of producers (e.g.
+ * QWP batch accessors) to avoid per-row allocation.
+ */
+public class Long256Impl implements Long256, Long256Sink {
+    private long l0;
+    private long l1;
+    private long l2;
+    private long l3;
+
+    @Override
+    public long getLong0() {
+        return l0;
+    }
+
+    @Override
+    public long getLong1() {
+        return l1;
+    }
+
+    @Override
+    public long getLong2() {
+        return l2;
+    }
+
+    @Override
+    public long getLong3() {
+        return l3;
+    }
+
+    @Override
+    public void setAll(long l0, long l1, long l2, long l3) {
+        this.l0 = l0;
+        this.l1 = l1;
+        this.l2 = l2;
+        this.l3 = l3;
+    }
+}

core/src/main/java/io/questdb/client/std/Long256Impl.java

@@ -0,0 +1,53 @@
+/*+*****************************************************************************
+ *     ___                  _   ____  ____
+ *    / _ \ _   _  ___  ___| |_|  _ \| __ )
+ *   | | | | | | |/ _ \/ __| __| | | |  _ \
+ *   | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+ *    \__\_\\__,_|\___||___/\__|____/|____/
+ *
+ *  Copyright (c) 2014-2019 Appsicle
+ *  Copyright (c) 2019-2026 QuestDB
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ ******************************************************************************/
+
+package io.questdb.client.std;
+
+/**
+ * Write-side of a 256-bit value split into four 64-bit words. Implementations
+ * accept a full value in a single call, so producers can ship all four words
+ * with one virtual dispatch instead of one per word.
+ */
+public interface Long256Sink {
+
+    /**
+     * Copies four little-endian 64-bit words starting at {@code address} into
+     * this sink. Default implementation issues four native 64-bit loads and
+     * delegates to {@link #setAll}.
+     */
+    default void fromAddress(long address) {
+        setAll(
+                Unsafe.getUnsafe().getLong(address),
+                Unsafe.getUnsafe().getLong(address + 8L),
+                Unsafe.getUnsafe().getLong(address + 16L),
+                Unsafe.getUnsafe().getLong(address + 24L)
+        );
+    }
+
+    /**
+     * Sets all four 64-bit words of this value. {@code l0} is the least
+     * significant word; {@code l3} the most significant.
+     */
+    void setAll(long l0, long l1, long l2, long l3);
+}

core/src/main/java/io/questdb/client/std/Long256Sink.java

@@ -0,0 +1,64 @@
+/*+*****************************************************************************
+ *     ___                  _   ____  ____
+ *    / _ \ _   _  ___  ___| |_|  _ \| __ )
+ *   | | | | | | |/ _ \/ __| __| | | |  _ \
+ *   | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+ *    \__\_\\__,_|\___||___/\__|____/|____/
+ *
+ *  Copyright (c) 2014-2019 Appsicle
+ *  Copyright (c) 2019-2026 QuestDB
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ ******************************************************************************/
+
+package io.questdb.client.std;
+
+/**
+ * Mutable 128-bit UUID value split into two 64-bit words. Intended as a
+ * reusable sink: hand the same instance to a series of producers (e.g. QWP
+ * batch accessors) and read {@link #getLo} / {@link #getHi} after each
+ * {@link #setAll} call.
+ */
+public class Uuid {
+    public static final int BYTES = 16;
+    private long hi;
+    private long lo;
+
+    /**
+     * Loads the two 64-bit words from {@code address} (little-endian, low word first).
+     */
+    public void fromAddress(long address) {
+        setAll(
+                Unsafe.getUnsafe().getLong(address),
+                Unsafe.getUnsafe().getLong(address + 8L)
+        );
+    }
+
+    public long getHi() {
+        return hi;
+    }
+
+    public long getLo() {
+        return lo;
+    }
+
+    /**
+     * Sets both 64-bit words. {@code lo} is the least significant; {@code hi}
+     * the most significant.
+     */
+    public void setAll(long lo, long hi) {
+        this.lo = lo;
+        this.hi = hi;
+    }
+}