docs(examples): make the pooled QuestDB facade the first-class API

Convert the QWP query examples from the low-level QwpQueryClient to the
pooled QuestDB facade (db.query()/db.executeSql()), and add ws-pooled
ingest and facade examples so the recommended entry point is what the
examples lead with. Keep one low-level QwpQueryClient example and the ILP
Sender examples as the legacy-transport reference.

New:
- root: QuestDBExample (ingest+query round-trip), QuestDBSeparateConfigExample,
  ConnectionErrorExample, BinaryColumnExample
- sender (ws): WsExample, WsConcurrentIngestExample, WsColumnTypesExample,
  WsArrayExample, WsAuthTlsExample, WsAdvancedExample, WsStoreAndForwardExample,
  WsFailoverExample, SenderErrorHandlingExample (low-level)
- query: QwpQueryClientExample (low-level), ArrayResultExample,
  MultiInFlightQueryExample, QueryCancellationExample, QueryFailoverExample

Wire qwp-pool/qwp-ingest/qwp-query into examples.manifest.yaml (mirroring the
Go client) while keeping the ilp* entries.

Verified by running every example against a live QuestDB; fixes from that:
- BindAllTypesExample: ::GEOHASH(60b) is invalid (cast(.. as GEOHASH) works);
  ::FLOAT is widened to DOUBLE, so read c_float as a double
- WsArrayExample: only double arrays are supported for ingest
- ErrorHandlingExample: COPY isn't rejected on egress; use an invalid column
- ConnectionErrorExample: connect() eagerly warms the sender pool, so bad
  hosts surface as LineSenderException

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kafka1991

examples.manifest.yaml

@@ -1,3 +1,21 @@
+- name: qwp-pool
+  lang: java
+  path: examples/src/main/java/com/example/QuestDBExample.java
+  header: |-
+    QuestDB Java client [docs](https://questdb.io/docs/connect/clients/java/)
+    and [Maven artifact](https://central.sonatype.com/artifact/org.questdb/questdb-client).
+- name: qwp-ingest
+  lang: java
+  path: examples/src/main/java/com/example/sender/WsExample.java
+  header: |-
+    QuestDB Java client [docs](https://questdb.io/docs/connect/clients/java/)
+    and [Maven artifact](https://central.sonatype.com/artifact/org.questdb/questdb-client).
+- name: qwp-query
+  lang: java
+  path: examples/src/main/java/com/example/query/BasicQueryExample.java
+  header: |-
+    QuestDB Java client [docs](https://questdb.io/docs/connect/clients/java/)
+    and [Maven artifact](https://central.sonatype.com/artifact/org.questdb/questdb-client).
 - name: ilp-http
   lang: java
   path: examples/src/main/java/com/example/sender/HttpExample.java

examples/src/main/java/com/example/BinaryColumnExample.java

@@ -0,0 +1,63 @@
+package com.example;
+
+import io.questdb.client.QueryException;
+import io.questdb.client.QuestDB;
+import io.questdb.client.Sender;
+import io.questdb.client.cutlass.qwp.client.QwpColumnBatch;
+import io.questdb.client.cutlass.qwp.client.QwpColumnBatchHandler;
+
+import java.util.Arrays;
+
+/**
+ * BINARY column round-trip: ingest a {@code byte[]} and read it back.
+ * <p>
+ * Ingest with {@code binaryColumn(name, byte[])} (overloads also take a native
+ * {@code (ptr, len)} pair or a {@code DirectByteSlice} for zero-copy paths).
+ * On egress, {@link QwpColumnBatch#getBinary(int, int)} returns a heap
+ * {@code byte[]}; {@code getBinaryA}/{@code getBinaryB} give reusable native
+ * views for allocation-free reads.
+ */
+public class BinaryColumnExample {
+
+    public static void main(String[] args) throws InterruptedException {
+        byte[] payload = {0x00, 0x01, 0x02, (byte) 0xFF};
+
+        try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
+
+            try (Sender sender = db.borrowSender()) {
+                sender.table("blobs")
+                        .symbol("kind", "thumbnail")
+                        .binaryColumn("payload", payload)
+                        .atNow();
+            }
+
+            try {
+                db.executeSql(
+                        "SELECT kind, payload FROM blobs LIMIT 10",
+                        new QwpColumnBatchHandler() {
+                            @Override
+                            public void onBatch(QwpColumnBatch batch) {
+                                for (int row = 0; row < batch.getRowCount(); row++) {
+                                    String kind = batch.getSymbol(0, row);
+                                    byte[] bytes = batch.isNull(1, row) ? null : batch.getBinary(1, row);
+                                    System.out.println("kind=" + kind + " payload=" + Arrays.toString(bytes));
+                                }
+                            }
+
+                            @Override
+                            public void onEnd(long totalRows) {
+                                System.out.println("done: " + totalRows + " rows");
+                            }
+
+                            @Override
+                            public void onError(byte status, String message) {
+                                System.err.printf("error: 0x%02X %s%n", status & 0xFF, message);
+                            }
+                        }
+                ).await();
+            } catch (QueryException e) {
+                System.err.printf("query failed: status=0x%02X %s%n", e.getStatus() & 0xFF, e.getMessage());
+            }
+        }
+    }
+}

examples/src/main/java/com/example/ConnectionErrorExample.java

@@ -0,0 +1,74 @@
+package com.example;
+
+import io.questdb.client.QueryException;
+import io.questdb.client.QuestDB;
+import io.questdb.client.Sender;
+import io.questdb.client.cutlass.http.client.HttpClientException;
+import io.questdb.client.cutlass.line.LineSenderException;
+import io.questdb.client.cutlass.qwp.client.QwpColumnBatch;
+import io.questdb.client.cutlass.qwp.client.QwpColumnBatchHandler;
+import io.questdb.client.cutlass.qwp.client.QwpRoleMismatchException;
+
+/**
+ * Connection-level failures on the pooled facade.
+ * <p>
+ * Some failures happen when the pool opens a WebSocket, before any row or query
+ * is exchanged. The pool warms up its minimum connections at {@code connect()}
+ * and opens more on demand, so a connect-level error can surface either from
+ * {@link QuestDB#connect} or from the first {@link QuestDB#borrowSender()} /
+ * query -- wrap both.
+ * <ul>
+ *   <li><b>Authentication failure</b> (401/403 on the upgrade) is terminal
+ *       across all endpoints and surfaces as {@link LineSenderException} on the
+ *       ingest side.</li>
+ *   <li><b>Role mismatch</b>: when every listed endpoint reports a role that
+ *       doesn't match the query-side {@code target=} filter, the client raises
+ *       {@link QwpRoleMismatchException}.</li>
+ *   <li><b>Unreachable / unresolvable host</b>: a generic connect failure
+ *       surfaces as {@link LineSenderException} on the ingest side and as
+ *       {@link HttpClientException} (the {@code QwpRoleMismatchException}
+ *       supertype) on the query side.</li>
+ * </ul>
+ */
+public class ConnectionErrorExample {
+
+    public static void main(String[] args) throws InterruptedException {
+
+        // 1. Bad credentials -> auth failure on the ingest connection.
+        try (QuestDB db = QuestDB.connect(
+                "wss::addr=db.example.com:9000;token=INVALID_TOKEN;")) {
+            try (Sender sender = db.borrowSender()) {
+                sender.table("trades").doubleColumn("price", 1.0).atNow();
+            }
+        } catch (LineSenderException | HttpClientException e) {
+            System.err.println("ingest connection failed (auth/unreachable?): " + e.getMessage());
+        }
+
+        // 2. target=replica but no listed endpoint is a replica -> role mismatch.
+        try (QuestDB db = QuestDB.connect(
+                "wss::addr=db-primary:9000;token=YOUR_TOKEN;target=replica;")) {
+            try {
+                db.executeSql("SELECT 1", new QwpColumnBatchHandler() {
+                    @Override
+                    public void onBatch(QwpColumnBatch batch) {
+                    }
+
+                    @Override
+                    public void onEnd(long totalRows) {
+                    }
+
+                    @Override
+                    public void onError(byte status, String message) {
+                        System.err.printf("error: 0x%02X %s%n", status & 0xFF, message);
+                    }
+                }).await();
+            } catch (QueryException e) {
+                System.err.printf("query failed: status=0x%02X %s%n", e.getStatus() & 0xFF, e.getMessage());
+            }
+        } catch (QwpRoleMismatchException e) {
+            System.err.println("no endpoint matched target=replica: " + e.getMessage());
+        } catch (LineSenderException | HttpClientException e) {
+            System.err.println("connection failed: " + e.getMessage());
+        }
+    }
+}

examples/src/main/java/com/example/QuestDBExample.java

@@ -0,0 +1,95 @@
+package com.example;
+
+import io.questdb.client.Completion;
+import io.questdb.client.QueryException;
+import io.questdb.client.QuestDB;
+import io.questdb.client.Sender;
+import io.questdb.client.cutlass.qwp.client.QwpColumnBatch;
+import io.questdb.client.cutlass.qwp.client.QwpColumnBatchHandler;
+
+/**
+ * The recommended entry point: the pooled {@link QuestDB} handle.
+ * <p>
+ * {@code QuestDB.connect(...)} owns connection pools for <b>both</b> directions
+ * over QWP (the QuestDB WebSocket protocol): a {@link Sender} pool for ingest
+ * and a query-client pool for egress. One {@code ws}/{@code wss} connect string
+ * configures both -- each side reads the keys it owns and ignores the rest.
+ * <p>
+ * Construct one {@code QuestDB} per deployment, share it across threads, and
+ * close it at shutdown. This example does the whole round trip on one thread:
+ * borrow a {@link Sender} to ingest a couple of rows, then run a {@code SELECT}
+ * to read them back.
+ * <p>
+ * For ingest-only and query-only variants, see
+ * {@code com.example.sender.WsExample} and
+ * {@code com.example.query.BasicQueryExample}.
+ */
+public class QuestDBExample {
+
+    public static void main(String[] args) throws InterruptedException {
+        // One handle for the whole deployment. close() (try-with-resources)
+        // shuts the pools down and disconnects every underlying client.
+        try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
+
+            // Ingest: borrow a Sender, write rows, close() flushes it and
+            // returns it to the pool. The WebSocket is NOT torn down here --
+            // a real disconnect only happens at db.close().
+            try (Sender sender = db.borrowSender()) {
+                sender.table("trades")
+                        .symbol("symbol", "ETH-USD")
+                        .symbol("side", "sell")
+                        .doubleColumn("price", 2615.54)
+                        .doubleColumn("amount", 0.00044)
+                        .atNow();
+                sender.table("trades")
+                        .symbol("symbol", "BTC-USD")
+                        .symbol("side", "sell")
+                        .doubleColumn("price", 39269.98)
+                        .doubleColumn("amount", 0.001)
+                        .atNow();
+            }
+
+            // Query: one-shot SELECT. executeSql(...) borrows a query client
+            // from the egress pool, runs the SQL, and returns a Completion.
+            // (Freshly ingested rows land in the WAL asynchronously, so an
+            // immediate read-back may not see them yet -- that is expected.)
+            Completion c = db.executeSql(
+                    "SELECT symbol, side, price, amount FROM trades "
+                            + "WHERE symbol = 'ETH-USD' LIMIT 10",
+                    new PrintingHandler());
+            try {
+                c.await(); // blocks until onEnd / onError has run
+            } catch (QueryException e) {
+                // Server reported an error (parse failure, schema mismatch, ...).
+                System.err.printf("query failed: status=0x%02X %s%n",
+                        e.getStatus() & 0xFF, e.getMessage());
+            }
+        }
+    }
+
+    /**
+     * Prints each row. The {@code QwpColumnBatch} is valid only during the
+     * {@code onBatch} callback -- copy values out if you need them later.
+     */
+    private static final class PrintingHandler implements QwpColumnBatchHandler {
+        @Override
+        public void onBatch(QwpColumnBatch batch) {
+            batch.forEachRow(row -> System.out.printf(
+                    "symbol=%s side=%s price=%.4f amount=%.5f%n",
+                    row.getSymbol(0),
+                    row.getSymbol(1),
+                    row.getDoubleValue(2),
+                    row.getDoubleValue(3)));
+        }
+
+        @Override
+        public void onEnd(long totalRows) {
+            System.out.println("done: " + totalRows + " rows");
+        }
+
+        @Override
+        public void onError(byte status, String message) {
+            System.err.printf("error: 0x%02X %s%n", status & 0xFF, message);
+        }
+    }
+}

examples/src/main/java/com/example/QuestDBSeparateConfigExample.java

@@ -0,0 +1,64 @@
+package com.example;
+
+import io.questdb.client.QueryException;
+import io.questdb.client.QuestDB;
+import io.questdb.client.Sender;
+import io.questdb.client.cutlass.qwp.client.QwpColumnBatch;
+import io.questdb.client.cutlass.qwp.client.QwpColumnBatchHandler;
+
+/**
+ * Pointing ingest and query at different endpoints.
+ * <p>
+ * The single-string {@link QuestDB#connect(CharSequence)} configures both
+ * directions from one {@code ws}/{@code wss} string -- the common case. When
+ * ingest and egress differ (ingest goes to the primary while reads target a
+ * read-replica or a separate load balancer), pass two strings to
+ * {@link QuestDB#connect(CharSequence, CharSequence)}, or use the builder's
+ * {@code ingestConfig(...)} / {@code queryConfig(...)}. Each string still
+ * accepts keys owned by the other direction; the split just lets the two sides
+ * point at different hosts or carry different tuning.
+ */
+public class QuestDBSeparateConfigExample {
+
+    public static void main(String[] args) throws InterruptedException {
+        // First string is the ingest (Sender) config, second is the query
+        // (egress) config. Both must use the ws/wss schema.
+        try (QuestDB db = QuestDB.connect(
+                "ws::addr=ingest.cluster:9000;",
+                "wss::addr=read-replica.cluster:9000;token=YOUR_TOKEN;")) {
+
+            try (Sender sender = db.borrowSender()) {
+                sender.table("trades")
+                        .symbol("symbol", "ETH-USD")
+                        .doubleColumn("price", 2615.54)
+                        .atNow();
+            }
+
+            try {
+                db.executeSql("SELECT count() FROM trades", new QwpColumnBatchHandler() {
+                    @Override
+                    public void onBatch(QwpColumnBatch batch) {
+                        batch.forEachRow(row -> System.out.println("count = " + row.getLongValue(0)));
+                    }
+
+                    @Override
+                    public void onEnd(long totalRows) {
+                    }
+
+                    @Override
+                    public void onError(byte status, String message) {
+                        System.err.printf("error: 0x%02X %s%n", status & 0xFF, message);
+                    }
+                }).await();
+            } catch (QueryException e) {
+                System.err.printf("query failed: status=0x%02X %s%n", e.getStatus() & 0xFF, e.getMessage());
+            }
+        }
+
+        // The connect string can also come from the QDB_CLIENT_CONF environment
+        // variable (export QDB_CLIENT_CONF="wss::addr=db:9000;token=...;"):
+        //
+        //   String cfg = System.getenv("QDB_CLIENT_CONF");
+        //   try (QuestDB db = QuestDB.connect(cfg)) { ... }
+    }
+}

examples/src/main/java/com/example/query/ArrayResultExample.java

@@ -0,0 +1,66 @@
+package com.example.query;
+
+import io.questdb.client.QueryException;
+import io.questdb.client.QuestDB;
+import io.questdb.client.cutlass.qwp.client.QwpColumnBatch;
+import io.questdb.client.cutlass.qwp.client.QwpColumnBatchHandler;
+
+import java.util.Arrays;
+
+/**
+ * Reading array columns from a result set.
+ * <p>
+ * {@link QwpColumnBatch#getDoubleArrayElements(int, int)} returns a flattened
+ * {@code double[]} in row-major order; {@link QwpColumnBatch#getArrayNDims(int, int)}
+ * reports the dimensionality so you can interpret that flat layout. This is the
+ * egress counterpart to {@link com.example.sender.WsArrayExample} (ingest).
+ * <p>
+ * Alternatively, extract individual elements in SQL (e.g. {@code SELECT
+ * bids[1][1] FROM market_data}) and read them as scalar doubles.
+ * <p>
+ * Assumes a table with a {@code DOUBLE[]} column, e.g. the one
+ * {@code WsArrayExample} writes:
+ * <pre>
+ *   CREATE TABLE book (levels DOUBLE[], ts TIMESTAMP)
+ *       TIMESTAMP(ts) PARTITION BY DAY WAL;
+ * </pre>
+ */
+public class ArrayResultExample {
+
+    public static void main(String[] args) throws InterruptedException {
+        try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
+            try {
+                db.executeSql(
+                        "SELECT levels FROM book LIMIT 10",
+                        new QwpColumnBatchHandler() {
+                            @Override
+                            public void onBatch(QwpColumnBatch batch) {
+                                for (int row = 0; row < batch.getRowCount(); row++) {
+                                    if (batch.isNull(0, row)) {
+                                        System.out.println("levels: null");
+                                        continue;
+                                    }
+                                    int nDims = batch.getArrayNDims(0, row);
+                                    double[] flat = batch.getDoubleArrayElements(0, row);
+                                    System.out.printf("levels: nDims=%d values=%s%n",
+                                            nDims, Arrays.toString(flat));
+                                }
+                            }
+
+                            @Override
+                            public void onEnd(long totalRows) {
+                                System.out.println("done: " + totalRows + " rows");
+                            }
+
+                            @Override
+                            public void onError(byte status, String message) {
+                                System.err.printf("error: 0x%02X %s%n", status & 0xFF, message);
+                            }
+                        }
+                ).await();
+            } catch (QueryException e) {
+                System.err.printf("query failed: status=0x%02X %s%n", e.getStatus() & 0xFF, e.getMessage());
+            }
+        }
+    }
+}