docs(qwp): make the pooled facade first-class and add more ws ingest/query examples#61
Open
kafka1991 wants to merge 3 commits into
Open
docs(qwp): make the pooled facade first-class and add more ws ingest/query examples#61kafka1991 wants to merge 3 commits into
kafka1991 wants to merge 3 commits into
Conversation
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>
kafka1991
changed the title
kafka1991
changed the title
kafka1991
changed the title
kafka1991
changed the title
kafka1991
changed the title
kafka1991
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
The
examples/module had drifted fromjava.md, which calls the pooledQuestDBhandle "the recommended entry point." The examples instead led with the low-level primitives —QwpQueryClientfor queries andSender.fromConfig(...)over legacy ILP (tcp/http) for ingest.This PR reworks the examples so the pooled QWP (WebSocket) facade is the first-class API for both ingest and query, adds a broad set of new
wsexamples, and keeps the low-level primitives and the ILP transports as a clearly-labeled reference.Changes
Query examples → pooled facade. Every QWP query example now uses
db.query()/db.executeSql()instead ofQwpQueryClient— binds, cancellation, DDL/DML, compression, flow-control, streaming, column reads, and error handling.BasicQueryExample(the docs-embeddedqwp-query) queries the sametradesschema the ingest examples write, so the ingest and query snippets on the docs page compose.New
wsingest & facade examplesQuestDBExample(ingest+query round-trip),QuestDBSeparateConfigExample,ConnectionErrorExamplesender/(ws) —WsExample,WsConcurrentIngestExample,WsColumnTypesExample,WsArrayExample,WsAuthTlsExample,WsAdvancedExample,WsStoreAndForwardExample,WsFailoverExamplequery/—ArrayResultExample,BinaryResultExample,ConcurrentQueryExample,MultiInFlightQueryExample,QueryCancellationExample,QueryFailoverExampleKept as low-level / legacy reference
query/QwpQueryClientExample— the low-levelQwpQueryClientprimitivesender/SenderErrorHandlingExample— low-levelSender+SenderErrorHandler(the facade doesn't expose this callback)sender/examples (tcp / http / TLS / ECDSA);BasicExampleis renamedTcpExampleto match its transport-named siblingsManifest. Added
qwp-pool/qwp-ingest/qwp-queryentries toexamples.manifest.yaml(mirroring the Go client'sgo.md) sojava.mdcan embed them via<RemoteRepoExample>; theilp*entries keep their names, with theilp/ilp-from-confpaths following theTcpExamplerename.Every example compiles in CI (root reactor, JDK 8 + JDK 25) and was run against a live QuestDB while preparing this PR — the resulting doc-vs-server fixes are in the commit messages.
Follow-ups (not in this PR)
documentationrepo: add<RemoteRepoExample name="qwp-*" lang="java">tags tojava.md. The docs plugin fetchesexamples.manifest.yamlfrom the client's default branch, so this can only land after merge.questdbrepo: bump the submodule pointer in a separate commit once this merges.