Skip to content

Validate required fields in SearchBuilder and CreateCollectionBuilder - #93

Merged
gansheer merged 2 commits into
quarkiverse:mainfrom
inamdarmihir:feat/builder-input-validation
Oct 27, 2026
Merged

gansheer merged 2 commits into
quarkiverse:mainfrom
inamdarmihir:feat/builder-input-validation

Conversation

@inamdarmihir

@inamdarmihir inamdarmihir commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

What

SearchBuilder.execute() and CreateCollectionBuilder.execute() now throw a QdrantException with a clear message before the REST call, matching DeleteBuilder:

  • Search requires a collection name and a non-empty query vector.
  • Create collection requires a collection name, a vector size greater than zero, and a distance metric.

Why

A missing required field produced a confusing server-side error, or for search a silently empty result. See #61.

Optional fields (limit, filter, score threshold) and the set of valid distance values are deliberately not validated, so new Qdrant metrics keep working.

How was it tested

Added ErrorHandlingTest cases in deployment, which already covers DeleteBuilder: 3 for search validation, 4 for create-collection validation, plus a happy path for each builder. The search happy path is self-contained (creates its own collection, upserts a point with a UUID id, asserts it is returned).

Added DocumentResourceTest#testCreateCollectionWithInvalidVectorSizeReturnsBadRequest in integration-tests/default: PUT /admin/collections/{name}?vectorSize=0 returns 400. Without the AdminResource change below it fails.

  • Without the runtime change: mvn -pl deployment -am test -Dtest=ErrorHandlingTest gives 25 run, 7 failures. The 7 failures are exactly the missing-field tests.
  • With the change: mvn -B -pl runtime,deployment,integration-tests/default -am verify gives BUILD SUCCESS on JDK 21, with 37 tests passing in deployment and 9 in integration-tests/default. The formatter and impsort leave no diff.
  • Not run: JDK 17/25 or the native build.

Notes for the reviewer

  • QdrantException is the parent of QdrantApiException, so validation errors would have escaped the integration-test AdminResource.createCollection as HTTP 500. It now maps QdrantException to 400 after the QdrantApiException catch. Today QdrantException is only thrown by these builder validations, so 400 is accurate; if it later wraps non-client errors, that mapping needs revisiting.
  • Behaviour change: a search with no query vector (filter-only) now throws instead of calling the server. The builder had no other way to express a query, and Add input validation to SearchBuilder and CreateCollectionBuilder #61 asks for this validation.
  • I removed searchWithoutQueryReturnsEmptyResults, since it pinned the behaviour this PR changes.

Fixes #61

Authored by Mihir Inamdar.

Throw a QdrantException with a clear message before the REST call when
the collection name or the query vector is missing on search, or when the
collection name, vector size or distance is missing on create collection,
the same way DeleteBuilder does.

Fixes quarkiverse#61
@inamdarmihir
inamdarmihir requested a review from a team as a code owner October 26, 2026 05:13

@gansheer gansheer left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi!
Thanks for the contribution!

On general nitpick on the test. If I understand correctely validation errors now escape AdminResource as HTTP 500. The new client-side QdrantException is the parent of QdrantApiException, and AdminResource.createCollection catches only the subclass, so PUT /admin/collections/foo?vectorSize=0 now returns 500 (unhandled exception) where it used to return a mapped 4xx. The fix belongs in AdminResource even though this PR doesn't touch it, because the regression is caused by it:

  } catch (QdrantApiException e) {
      return Response.status(e.getStatusCode()).entity(e.getMessage()).build();
  } catch (QdrantException e) {
      return Response.status(Response.Status.BAD_REQUEST).entity(e.getMessage()).build();
  }

An IT asserting PUT with vectorSize=0 W -> 400 would lock the mapping in, nothing in the suite currently exercises the validation path through HTTP.

}

@Test
void searchWithVectorSucceeds() {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see one issue in this test. The PR is not entirely at fault here but if it can be fixed I would appreciate it.
searchWithVectorSucceeds asserts an accident of the suite. .isEmpty() only holds because nothing ever successfully upserts into test_col; it's carried over from the deleted searchWithoutQueryReturnsEmptyResults, where emptiness was the behavior under test. Any future test that seeds test_col breaks this with a misleading "search returned results" failure. Either we assert only what the name promises (assertThat(results).isNotNull()), or make it self-contained:

  @Test
  void searchWithVectorSucceeds() {
      String id = UUID.randomUUID().toString();
      client.createCollection("search_test_col").vectorSize(4).distance("Cosine").execute();
      try {
          client.upsert("search_test_col")
                  .point(new PointStruct(id, List.of(1.0f, 2.0f, 3.0f, 4.0f), Map.of()))
                  .execute();
          assertThat(client.search("search_test_col").vector(new float[] { 1.0f, 2.0f, 3.0f, 4.0f }).execute())
                  .extracting(ScoredPoint::getId).contains(id);
      } finally {
          client.deleteCollection("search_test_col");
      }
  }

WDYT ?
Note the UUID: current Qdrant (verified on 1.19.2) rejects non-UUID string IDs with 400 "value ... is not a valid point ID". I will create a follow up on that.

@inamdarmihir

Copy link
Copy Markdown
Contributor Author

Thanks @gansheer, both points addressed in the latest push.

  • AdminResource: createCollection now also catches QdrantException and returns 400 with the message, after the existing QdrantApiException catch. Added DocumentResourceTest#testCreateCollectionWithInvalidVectorSizeReturnsBadRequest (PUT /admin/collections/invalid-size-test?vectorSize=0 -> 400). Without the AdminResource change that test fails; with it, it passes.
  • searchWithVectorSucceeds: now self-contained, as suggested. It creates search_test_col, upserts one point with a UUID id, asserts the search result contains that id, and deletes the collection in finally.

mvn -B -pl runtime,deployment,integration-tests/default -am verify on JDK 21: BUILD SUCCESS (deployment 37 tests, integration-tests 9 tests).

Could you take another look when you have a moment?

@gansheer
gansheer merged commit 487ecc9 into quarkiverse:main Oct 27, 2026
6 checks passed
@zbendhiba

Copy link
Copy Markdown
Contributor

thanks @inamdarmihir for your contribution !

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add input validation to SearchBuilder and CreateCollectionBuilder

3 participants