Skip to content

fix(qdrant-java): trace async universal queries through completion - #418

Open
nik13 wants to merge 2 commits into
devfrom
fix/qdrant-java-async-query
Open

nik13 wants to merge 2 commits into
devfrom
fix/qdrant-java-async-query

Conversation

@nik13

@nik13 nik13 commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Keep the Qdrant Java package: its semantic retrieval/vector spans remain useful. Repair the blocking-only wrapper rather than retire it.

  • Add universal queryAsync, queryBatchAsync, and queryGroupsAsync, with SDK timeout and read-consistency options passed through unchanged.
  • Add asynchronous counterparts for the six existing operation families. Keep every existing blocking entry point and unwrap() working.
  • Return a ListenableFuture that preserves results, failure causes, cancellation acceptance/interrupt flags and caller-selected listener executors. End one semantic span before exposing completion, including cancellation and synchronous SDK failures. This also prevents blocking callers from shutting down tracing before the completion callback ends its span.
  • Capture the caller's parent context, scope the SDK invocation and completion callback without retaining a thread-local scope while waiting, and continue using the core error-privacy policy.
  • Record only operation metadata/counts; do not export vector values, payloads, group keys or query bodies.
  • Add compatibility CI for Qdrant 1.16.2 (declared floor) and 1.20.0 (current).

Verification

  • Reproduced against dev d6a9966: exposesNonBlockingUniversalQuery fails with NoSuchMethodException before the fix.
  • After the fix: 43 tests pass with each of Qdrant 1.16.2 and 1.20.0, including clean recompilation, nine operation families across delayed success/failure/cancellation/synchronous failure, blocking compatibility, context restoration, argument identity and result counts.
  • An additional adversarial regression first reproduced the race between get() and span completion. It now verifies that the returned future does not expose the outcome before the span ends. Rejected cancellation and caller-selected listener executors are also covered.
  • Real Qdrant SDK gRPC requests are exercised against a loopback synthetic service. A loopback OTLP/HTTP receiver decodes protobuf and checks parentage, completion-time spans, results count, and absence of private response/error sentinels.
  • Local runs use Maven offline under an outbound-network-denied sandbox with loopback permitted; no vendor/backend calls or credentials. On macOS the fixture uses -Djava.net.preferIPv4Stack=true for sandbox-compatible sockets.

Re-run for each client version:

mvn -B -ntp -f java/pom.xml -pl traceai-java-qdrant -am \
  -Dqdrant.version=1.16.2 \
  -Dtest=TracedQdrantClientTest,TracedQdrantWireTest \
  -Dsurefire.failIfNoSpecifiedTests=false clean test

Scope and release

No version or changelog bump. Release-please owns publishing. No merges, tags or releases performed.
The package still does not promise coverage of every Qdrant API; operations on unwrap() bypass this wrapper. As with the SDK itself, applications propagate context for their own future listeners.

Existing Maven Central 1.0.0 installation guidance is corrected in future-agi/docs#1062; documentation for the new async surface must wait for a registry release. A javap -public comparison against the published 1.0.0 JAR confirms all 10 released public constructor/method signatures remain present (18 additions).

E2E coverage

Not applicable (no product e2e/ harness). The package has synthetic gRPC-to-OTLP integration coverage.

Generated with Claude Code

Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant