Skip to content

Commit ca42746

Browse files
bluestreak01bluestreak01
committed
docs(examples): migrate examples to the pooled borrowQuery/borrowSender API
PR #60 made the QuestDB facade pooled-only, removing the convenience/ thread-affine methods the examples were written against: executeSql(sql, handler), query(), newQuery(), sender(), releaseSender() and the two-arg connect(ingest, query). After the merge of main the examples module no longer compiled, failing both the build-jdk8 and compile-jdk25 CI jobs. Rewrite every example against the surviving API: - executeSql(sql, handler).await() -> borrowQuery(); q.sql(sql).handler(h) .submit().await() - query()/newQuery() -> borrowQuery() (one handle per concurrent in-flight query; reuse a single handle for sequential queries) - sender() -> borrowSender() (try-with-resources) - refresh the surrounding javadoc/comments that referenced the removed methods. Remove QuestDBSeparateConfigExample: it demonstrated connect(ingest, query) / separate ingest+query configs, which no longer exist on the facade.
1 parent 5d2dfb4 commit ca42746

32 files changed

Lines changed: 230 additions & 278 deletions

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
package com.example;
22

3+
import io.questdb.client.Query;
34
import io.questdb.client.QueryException;
45
import io.questdb.client.QuestDB;
56
import io.questdb.client.Sender;
@@ -47,8 +48,8 @@ public static void main(String[] args) throws InterruptedException {
4748
// 2. target=replica but no listed endpoint is a replica -> role mismatch.
4849
try (QuestDB db = QuestDB.connect(
4950
"wss::addr=db-primary:9000;token=YOUR_TOKEN;target=replica;")) {
50-
try {
51-
db.executeSql("SELECT 1", new QwpColumnBatchHandler() {
51+
try (Query q = db.borrowQuery()) {
52+
q.sql("SELECT 1").handler(new QwpColumnBatchHandler() {
5253
@Override
5354
public void onBatch(QwpColumnBatch batch) {
5455
}
@@ -60,7 +61,7 @@ public void onEnd(long totalRows) {
6061
@Override
6162
public void onError(byte status, String message) {
6263
}
63-
}).await();
64+
}).submit().await();
6465
} catch (QueryException e) {
6566
System.err.printf("query failed: status=0x%02X %s%n", e.getStatus() & 0xFF, e.getMessage());
6667
}

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

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package com.example;
22

33
import io.questdb.client.Completion;
4+
import io.questdb.client.Query;
45
import io.questdb.client.QueryException;
56
import io.questdb.client.QuestDB;
67
import io.questdb.client.Sender;
@@ -29,7 +30,8 @@ public class QuestDBExample {
2930
public static void main(String[] args) throws InterruptedException {
3031
// One handle for the whole deployment. close() (try-with-resources)
3132
// shuts the pools down and disconnects every underlying client.
32-
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
33+
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;");
34+
Query q = db.borrowQuery()) {
3335

3436
// Ingest: borrow a Sender, write rows, close() flushes it and
3537
// returns it to the pool. The WebSocket is NOT torn down here --
@@ -49,14 +51,15 @@ public static void main(String[] args) throws InterruptedException {
4951
.atNow();
5052
}
5153

52-
// Query: one-shot SELECT. executeSql(...) borrows a query client
53-
// from the egress pool, runs the SQL, and returns a Completion.
54+
// Query: one-shot SELECT. Borrow a Query handle from the egress
55+
// pool, submit the SQL, and await the returned Completion.
5456
// (Freshly ingested rows land in the WAL asynchronously, so an
5557
// immediate read-back may not see them yet -- that is expected.)
56-
Completion c = db.executeSql(
58+
Completion c = q.sql(
5759
"SELECT symbol, side, price, amount FROM trades "
58-
+ "WHERE symbol = 'ETH-USD' LIMIT 10",
59-
new PrintingHandler());
60+
+ "WHERE symbol = 'ETH-USD' LIMIT 10")
61+
.handler(new PrintingHandler())
62+
.submit();
6063
try {
6164
c.await(); // blocks until onEnd / onError has run
6265
} catch (QueryException e) {

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

Lines changed: 0 additions & 63 deletions
This file was deleted.

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

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
package com.example.query;
22

3+
import io.questdb.client.Query;
34
import io.questdb.client.QueryException;
45
import io.questdb.client.QuestDB;
56
import io.questdb.client.cutlass.qwp.client.QwpColumnBatch;
@@ -29,10 +30,10 @@ public class ArrayResultExample {
2930

3031
public static void main(String[] args) throws InterruptedException {
3132
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
32-
try {
33-
db.executeSql(
34-
"SELECT levels FROM book LIMIT 10",
35-
new QwpColumnBatchHandler() {
33+
try (Query q = db.borrowQuery()) {
34+
q.sql(
35+
"SELECT levels FROM book LIMIT 10")
36+
.handler(new QwpColumnBatchHandler() {
3637
@Override
3738
public void onBatch(QwpColumnBatch batch) {
3839
for (int row = 0; row < batch.getRowCount(); row++) {
@@ -56,7 +57,7 @@ public void onEnd(long totalRows) {
5657
public void onError(byte status, String message) {
5758
}
5859
}
59-
).await();
60+
).submit().await();
6061
} catch (QueryException e) {
6162
System.err.printf("query failed: status=0x%02X %s%n", e.getStatus() & 0xFF, e.getMessage());
6263
}

‎examples/src/main/java/com/example/query/BasicQueryExample.java‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
package com.example.query;
22

3+
import io.questdb.client.Query;
34
import io.questdb.client.QueryException;
45
import io.questdb.client.QuestDB;
56
import io.questdb.client.cutlass.qwp.client.QwpColumnBatch;
@@ -8,8 +9,8 @@
89
/**
910
* Minimal QWP egress query example.
1011
* <p>
11-
* Opens a pooled {@link QuestDB} handle over QWP (WebSocket), runs a SELECT
12-
* through {@code db.executeSql(...)}, and prints each row as the batches
12+
* Opens a pooled {@link QuestDB} handle over QWP (WebSocket), borrows a
13+
* {@link Query} to run a SELECT, and prints each row as the batches
1314
* arrive. {@code Completion.await()} blocks until the query finishes and
1415
* rethrows any server error as a {@link QueryException}.
1516
* <p>
@@ -31,10 +32,10 @@ public class BasicQueryExample {
3132

3233
public static void main(String[] args) throws InterruptedException {
3334
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
34-
try {
35-
db.executeSql(
36-
"SELECT timestamp, symbol, side, price, amount FROM trades WHERE symbol = 'ETH-USD' LIMIT 1000",
37-
new QwpColumnBatchHandler() {
35+
try (Query q = db.borrowQuery()) {
36+
q.sql(
37+
"SELECT timestamp, symbol, side, price, amount FROM trades WHERE symbol = 'ETH-USD' LIMIT 1000")
38+
.handler(new QwpColumnBatchHandler() {
3839
@Override
3940
public void onBatch(QwpColumnBatch batch) {
4041
// The RowView handed to the lambda is reusable and pinned to the
@@ -63,7 +64,7 @@ public void onEnd(long totalRows) {
6364
public void onError(byte status, String message) {
6465
}
6566
}
66-
).await();
67+
).submit().await();
6768
} catch (QueryException e) {
6869
System.err.printf("query failed: status=0x%02X %s%n", e.getStatus() & 0xFF, e.getMessage());
6970
}

‎examples/src/main/java/com/example/query/BinaryResultExample.java‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
package com.example.query;
22

3+
import io.questdb.client.Query;
34
import io.questdb.client.QueryException;
45
import io.questdb.client.QuestDB;
56
import io.questdb.client.Sender;
@@ -31,10 +32,10 @@ public static void main(String[] args) throws InterruptedException {
3132
.atNow();
3233
}
3334

34-
try {
35-
db.executeSql(
36-
"SELECT kind, payload FROM blobs LIMIT 10",
37-
new QwpColumnBatchHandler() {
35+
try (Query q = db.borrowQuery()) {
36+
q.sql(
37+
"SELECT kind, payload FROM blobs LIMIT 10")
38+
.handler(new QwpColumnBatchHandler() {
3839
@Override
3940
public void onBatch(QwpColumnBatch batch) {
4041
for (int row = 0; row < batch.getRowCount(); row++) {
@@ -53,7 +54,7 @@ public void onEnd(long totalRows) {
5354
public void onError(byte status, String message) {
5455
}
5556
}
56-
).await();
57+
).submit().await();
5758
} catch (QueryException e) {
5859
System.err.printf("query failed: status=0x%02X %s%n", e.getStatus() & 0xFF, e.getMessage());
5960
}

‎examples/src/main/java/com/example/query/BindAllTypesExample.java‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
package com.example.query;
22

3+
import io.questdb.client.Query;
34
import io.questdb.client.QueryException;
45
import io.questdb.client.QuestDB;
56
import io.questdb.client.cutlass.qwp.client.QwpColumnBatch;
@@ -46,10 +47,10 @@ public static void main(String[] args) throws InterruptedException {
4647
+ "$18::DECIMAL(76, 10) AS c_dec256 "
4748
+ "FROM long_sequence(1)";
4849

49-
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
50+
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;");
51+
Query q = db.borrowQuery()) {
5052
try {
51-
db.query()
52-
.sql(sql)
53+
q.sql(sql)
5354
.binds(binds -> binds
5455
.setBoolean(0, true)
5556
.setByte(1, (byte) 42)

‎examples/src/main/java/com/example/query/BindDecimalExample.java‎

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
package com.example.query;
22

3+
import io.questdb.client.Query;
34
import io.questdb.client.QueryException;
45
import io.questdb.client.QuestDB;
56
import io.questdb.client.cutlass.qwp.client.QwpColumnBatch;
@@ -34,15 +35,15 @@
3435
public class BindDecimalExample {
3536

3637
public static void main(String[] args) throws InterruptedException {
37-
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
38+
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;");
39+
Query q = db.borrowQuery()) {
3840

3941
// --- Example 1: DECIMAL64 amount, unscaled literal.
4042
// Looking up invoices where the total is exactly $1999.99 --
4143
// unscaled = 199_999 at scale 2.
4244
System.out.println("lookup by DECIMAL64 amount = 1999.99");
4345
try {
44-
db.query()
45-
.sql("SELECT id FROM invoices WHERE amount = $1")
46+
q.sql("SELECT id FROM invoices WHERE amount = $1")
4647
.binds(binds -> binds.setDecimal64(0, 2, 199_999L))
4748
.handler(printIdHandler())
4849
.submit()
@@ -57,8 +58,7 @@ public static void main(String[] args) throws InterruptedException {
5758
// limb alone; high limb is zero.
5859
System.out.println("lookup by DECIMAL128 tax = 12.345678");
5960
try {
60-
db.query()
61-
.sql("SELECT id FROM invoices WHERE tax = $1")
61+
q.sql("SELECT id FROM invoices WHERE tax = $1")
6262
.binds(binds -> binds.setDecimal128(0, 6, 12_345_678L, 0L))
6363
.handler(printIdHandler())
6464
.submit()
@@ -73,8 +73,7 @@ public static void main(String[] args) throws InterruptedException {
7373
Decimal128 tax = Decimal128.fromLong(12_345_678L, 6);
7474
System.out.println("lookup by DECIMAL128 via Decimal128 convenience");
7575
try {
76-
db.query()
77-
.sql("SELECT id FROM invoices WHERE tax = $1")
76+
q.sql("SELECT id FROM invoices WHERE tax = $1")
7877
.binds(binds -> binds.setDecimal128(0, tax))
7978
.handler(printIdHandler())
8079
.submit()
@@ -88,8 +87,7 @@ public static void main(String[] args) throws InterruptedException {
8887
// only the lowest of the four limbs is set.
8988
System.out.println("project DECIMAL256 42.0 at scale 10");
9089
try {
91-
db.query()
92-
.sql("SELECT $1::DECIMAL(76, 10) AS v FROM long_sequence(1)")
90+
q.sql("SELECT $1::DECIMAL(76, 10) AS v FROM long_sequence(1)")
9391
.binds(binds -> binds.setDecimal256(0, 10, 420_000_000_000L, 0L, 0L, 0L))
9492
.handler(new QwpColumnBatchHandler() {
9593
@Override
@@ -115,8 +113,7 @@ public void onError(byte status, String message) {
115113
Decimal256 big = new Decimal256(0L, 0L, 0L, 420_000_000_000L, 10);
116114
System.out.println("project DECIMAL256 via Decimal256 convenience");
117115
try {
118-
db.query()
119-
.sql("SELECT $1::DECIMAL(76, 10) AS v FROM long_sequence(1)")
116+
q.sql("SELECT $1::DECIMAL(76, 10) AS v FROM long_sequence(1)")
120117
.binds(binds -> binds.setDecimal256(0, big))
121118
.handler(new QwpColumnBatchHandler() {
122119
@Override

‎examples/src/main/java/com/example/query/BindErrorHandlingExample.java‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@
2626
public class BindErrorHandlingExample {
2727

2828
public static void main(String[] args) throws InterruptedException {
29-
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
29+
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;");
30+
Query q = db.borrowQuery()) {
3031

3132
// 1. Scale out of range. Max scale is 76 for every DECIMAL form.
3233
System.out.println("bad: DECIMAL scale = 200");
@@ -63,8 +64,7 @@ public static void main(String[] args) throws InterruptedException {
6364
// 6. For comparison: a good call. The pool stays healthy after the
6465
// errors above, so this still works.
6566
System.out.println("good: valid DECIMAL64 bind");
66-
db.query()
67-
.sql("SELECT $1::DECIMAL(18, 4) AS v FROM long_sequence(1)")
67+
q.sql("SELECT $1::DECIMAL(18, 4) AS v FROM long_sequence(1)")
6868
.binds(binds -> binds.setDecimal64(0, 4, 123_456L))
6969
.handler(new QwpColumnBatchHandler() {
7070
@Override
@@ -88,8 +88,8 @@ public void onError(byte status, String message) {
8888

8989
private static void runExpectingBindError(QuestDB db, String sql, QwpBindSetter binds)
9090
throws InterruptedException {
91-
try {
92-
db.query().sql(sql).binds(binds).handler(printErrorHandler()).submit().await();
91+
try (Query q = db.borrowQuery()) {
92+
q.sql(sql).binds(binds).handler(printErrorHandler()).submit().await();
9393
} catch (QueryException e) {
9494
// await() rethrows the bind-encode failure the handler already
9595
// reported in onError; swallowed here so the demo continues.

‎examples/src/main/java/com/example/query/BindNullExample.java‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
package com.example.query;
22

3+
import io.questdb.client.Query;
34
import io.questdb.client.QueryException;
45
import io.questdb.client.QuestDB;
56
import io.questdb.client.cutlass.qwp.client.QwpColumnBatch;
@@ -36,16 +37,16 @@
3637
public class BindNullExample {
3738

3839
public static void main(String[] args) throws InterruptedException {
39-
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
40+
try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;");
41+
Query q = db.borrowQuery()) {
4042

4143
// --- Convenience: setVarchar(index, null).
4244
// Use IS NULL / IS NOT NULL predicates since SQL equality with
4345
// NULL always yields NULL. $1 still needs a typed NULL so the
4446
// server can infer the intended type; the bind drives that.
4547
System.out.println("rows where note IS NOT NULL and level < some-null-placeholder:");
4648
try {
47-
db.query()
48-
.sql("SELECT id, note FROM logs WHERE note IS NOT NULL AND level < COALESCE($1::INT, 100) LIMIT 10")
49+
q.sql("SELECT id, note FROM logs WHERE note IS NOT NULL AND level < COALESCE($1::INT, 100) LIMIT 10")
4950
.binds(binds -> binds.setNull(0, QwpConstants.TYPE_INT))
5051
.handler(printRowsHandler())
5152
.submit()
@@ -57,8 +58,7 @@ public static void main(String[] args) throws InterruptedException {
5758
// --- Convenience: setUuid(index, (UUID) null).
5859
System.out.println("projection: NULL VARCHAR");
5960
try {
60-
db.query()
61-
.sql("SELECT $1 AS v FROM long_sequence(1)")
61+
q.sql("SELECT $1 AS v FROM long_sequence(1)")
6262
.binds(binds -> binds.setVarchar(0, null))
6363
.handler(new QwpColumnBatchHandler() {
6464
@Override
@@ -84,8 +84,7 @@ public void onError(byte status, String message) {
8484
// don't have a value-type overload, e.g. TIMESTAMP_NANOS).
8585
System.out.println("projection: NULL TIMESTAMP_NANOS");
8686
try {
87-
db.query()
88-
.sql("SELECT CAST($1 AS TIMESTAMP_NS) AS ts FROM long_sequence(1)")
87+
q.sql("SELECT CAST($1 AS TIMESTAMP_NS) AS ts FROM long_sequence(1)")
8988
.binds(binds -> binds.setNull(0, QwpConstants.TYPE_TIMESTAMP_NANOS))
9089
.handler(new QwpColumnBatchHandler() {
9190
@Override

0 commit comments

Comments
 (0)