Files
qdrant/tests/openapi/test_optional_vectors.py
Andrey Vasnetsov 8a7325ad5d Remove deprecated search endpoints from OpenAPI, deprecate them in gRPC (#9982)
* Remove deprecated search/recommend/discover endpoints from OpenAPI

Remove deprecated REST API endpoint definitions from the OpenAPI
generator. These endpoints were deprecated in v1.13.3 (`f4ced2567`,
#5907, 2025-01-30) in favor of the universal `/points/query` endpoint:

- POST /points/search
- POST /points/search/batch
- POST /points/search/groups
- POST /points/recommend
- POST /points/recommend/batch
- POST /points/recommend/groups
- POST /points/discover
- POST /points/discover/batch

Also removes the corresponding request types from the schema generator
and updates the expected API count in the consistency check.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Migrate OpenAPI integration tests to /points/query

The deprecated /points/search, /points/recommend and /points/discover
endpoints (along with their /batch and /groups variants) were removed
from the OpenAPI spec, which caused validation failures in the Python
integration test harness.

This commit migrates the affected tests to the universal /points/query
endpoint:

- Delete tests dedicated to the deprecated endpoints:
  test_recommend.py, test_discover.py, test_multicollection_reco.py,
  test_recommendation_multivector.py
- Refactor remaining tests to call /points/query (and /query/batch,
  /query/groups), translating request bodies (vector -> query / using,
  positive/negative -> query.recommend, target/context -> query.discover)
  and unwrapping the new result.points response shape.
- Drop equivalence assertions against the now-removed legacy endpoints.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Relax non-empty assertions in migrated recommend/discover tests

The previous migration added `len(...) > 0` assertions to tests that
previously only checked equivalence between the deprecated and new
API. These assertions are too strict because the parametrized
`query_filter` cases legitimately produce empty result sets.

Drop the `> 0` assertion and rely on `request_with_validation` to
verify the response is well-formed and HTTP OK.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Migrate remaining OpenAPI tests off deprecated search endpoints

Tests added to dev after the original migration was written still call
/points/search and /points/recommend/groups through
`request_with_validation`, which resolves the endpoint against the
OpenAPI spec and therefore breaks once the endpoint is not in the spec:

- test_turbo4_storage.py, test_sparse_idf_corpus.py, test_validation.py:
  translate /points/search to /points/query (vector{name,vector} ->
  query + using, result -> result.points).
- test_group.py: drop the /points/recommend/groups half of the
  lookup_from validation test in favour of the query equivalent.

test_sparse_idf_corpus.py's test_query_api_supports_idf_corpus goes
away: with the helper on /points/query every test in the file now
exercises what it asserted.

Also record why test_recommend_group cannot assert on its groups: it
uses every point in the collection as a recommend example, so all of
them are excluded and the result is legitimately empty.

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

* Regenerate openapi.json without the deprecated search endpoints

Drops the 8 deprecated paths and the request schemas that only they
referenced: Search/Recommend/Discover request (+Batch, +Groups) types
and their exclusive dependencies (NamedVector, NamedSparseVector,
NamedVectorStruct, UsingVector, RecommendExample, ContextExamplePair).

Regenerated output is a strict subset of the previous spec, and every
remaining $ref still resolves.

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

* Deprecate the search/recommend/discover RPCs in gRPC

The REST counterparts have carried `deprecated: true` since v1.13.3 and
are now gone from the OpenAPI spec, while the gRPC RPCs never got any
deprecation annotation at all. Mark all 8 with `option deprecated = true`
so generated clients warn, and point each doc comment at its `Query`
replacement.

tonic puts `#[deprecated]` on the generated client methods only; the
server trait gets the doc comment alone, so our own `impl` is unaffected.
The RPCs keep serving traffic — this is annotation only.

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

* Restore the deleted recommend/discover suites on /points/query

The earlier migration deleted these four files outright, but the
query-side tests it left behind are all shallow smoke tests
(`len(result) > 0`, `"points" in result[0]`). The deleted ones carried
invariants with no query-API equivalent anywhere, so deleting them was a
real loss of coverage rather than de-duplication:

- test_recommend.py: default strategy equals average_vector; batch
  results identical to sequential singles across six request shapes;
  best_score with only negatives yields all-negative scores; best_score
  with a single positive orders identically to a nearest query; raw
  vectors as examples equal ids as examples.
- test_discover.py: context-only scores are all <= 0; target-only orders
  identically to a nearest query but scores differently; with a fixed
  context the integer part of the score is stable while the decimal part
  moves, and vice versa with a fixed target; batch equals singles;
  lookup_from by id equals by vector.
- test_multicollection_reco.py: cross-collection lookup_from, plus
  wrong-vector-size, unknown-collection and unknown-vector rejections.
- test_recommendation_multivector.py: the same recommend invariants over
  a max_sim multivector collection, which the query suite never covered.

Only test_recommend_missing_lookup_from_collection_with_raw_vector is
dropped as genuinely redundant — test_query.py's
test_query_missing_lookup_from_collection covers query, query/batch and
prefetch.

Two request-shape differences the translation had to absorb:

- Giving no examples at all is 422 (a RecommendInput validation rule),
  where the legacy API reported 400 from the query itself. A malformed
  example, such as an empty vector, is still 400.
- DiscoverInput requires the `context` key and accepts only an explicit
  null to mean "no context", so target-only discover must spell it out.
  The legacy API let it be omitted.

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

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 18:09:43 +02:00

666 lines
20 KiB
Python

import pytest
from .helpers.collection_setup import drop_collection, multivec_collection_setup
from .helpers.helpers import request_with_validation
@pytest.fixture(autouse=True)
def setup(on_disk_vectors, on_disk_payload, collection_name):
multivec_collection_setup(collection_name=collection_name, on_disk_vectors=on_disk_vectors, on_disk_payload=on_disk_payload, distance='Dot')
yield
drop_collection(collection_name=collection_name)
def compare_vectors(v1, v2):
if len(v1) != len(v2):
return False
for i in range(len(v1)):
if abs(v1[i] - v2[i]) > 1e-5:
return False
return True
def test_delete_and_search(collection_name):
response = request_with_validation(
api='/collections/{collection_name}/points/vectors/delete',
method="POST",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [2, 3],
"vector": ["text"]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/query',
method="POST",
path_params={'collection_name': collection_name},
body={
"query": [0.0, 0.0, 1.0, 1.0],
"using": "image",
"limit": 10,
"with_payload": True,
"with_vector": ["text"],
}
)
assert response.ok
def test_retrieve_deleted_vector(collection_name):
# Delete vector
response = request_with_validation(
api='/collections/{collection_name}/points/vectors/delete',
method="POST",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [1, 3],
"vector": ["text"]
}
)
assert response.ok
# Retrieve deleted vector
response = request_with_validation(
api='/collections/{collection_name}/points',
method="POST",
path_params={'collection_name': collection_name},
body={
"ids": [1, 2, 3, 4],
"with_vectors": ["text", "image"],
"with_payload": True,
}
)
assert response.ok
result = response.json()["result"]
assert len(result) == 4
id_to_result = {r["id"]: r for r in result}
assert id_to_result[1]["vector"].get("image") is not None
assert id_to_result[1]["vector"].get("text") is None
assert id_to_result[2]["vector"].get("image") is not None
assert id_to_result[2]["vector"].get("text") is not None
assert id_to_result[3]["vector"].get("image") is not None
assert id_to_result[3]["vector"].get("text") is None
assert id_to_result[4]["vector"].get("image") is not None
assert id_to_result[4]["vector"].get("text") is not None
def test_upsert_partial_vectors(collection_name):
response = request_with_validation(
api='/collections/{collection_name}/points',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": 101,
"vector": {
"text": [0.05, 0.61, 0.76, 0.74, 0.05, 0.61, 0.76, 0.74],
},
"payload": {"city": "Berlin"}
},
{
"id": 102,
"vector": {
"image": [0.19, 0.81, 0.75, 0.11],
},
"payload": {"city": ["Berlin", "London"]}
},
{
"id": 103,
"vector": {},
"payload": {"city": ["Berlin", "Moscow"]}
},
]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': 101},
)
assert response.ok
result = response.json()["result"]
assert result["id"] == 101
assert "image" not in result["vector"]
assert "text" in result["vector"]
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': 102},
)
assert response.ok
result = response.json()["result"]
assert result["id"] == 102
assert "image" in result["vector"]
assert "text" not in result["vector"]
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': 103},
)
assert response.ok
result = response.json()["result"]
assert result["id"] == 103
assert "image" not in result["vector"]
assert "text" not in result["vector"]
def test_update_vectors(collection_name):
POINT_ID = 1000
# Put empty vector first
response = request_with_validation(
api='/collections/{collection_name}/points',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": POINT_ID,
"vector": {},
"payload": {"city": "Berlin"}
}
]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': POINT_ID},
)
assert response.ok
result = response.json()["result"]
assert result["vector"].get("text") is None
text_vector = [
0.34035879, 0.344099,
0.3478392, 0.35157941,
0.35531961, 0.35905982,
0.36280003, 0.36654023
]
response = request_with_validation(
api='/collections/{collection_name}/points/vectors',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": POINT_ID,
"vector": {
"text": text_vector,
}
}
]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': POINT_ID},
)
assert response.ok
result = response.json()["result"]
assert compare_vectors(result["vector"]["text"], text_vector)
assert result["payload"]["city"] == "Berlin"
text_vector = [
0.07902951, 0.22391693,
0.36880436, 0.51369179,
0.59272129, 0.07902951,
0.22391693, 0.36880436
]
image_vector = [0.19, 0.28, 0.37, 0.46]
response = request_with_validation(
api='/collections/{collection_name}/points/vectors',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": POINT_ID,
"vector": {
"text": text_vector,
"image": image_vector,
}
}
]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': POINT_ID},
)
assert response.ok
result = response.json()["result"]
assert compare_vectors(result["vector"]["image"], image_vector)
assert compare_vectors(result["vector"]["text"], text_vector)
image_vector = [0.00, 0.01, 0.00, 0.01]
response = request_with_validation(
api='/collections/{collection_name}/points/vectors',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": POINT_ID,
"vector": {
"image": image_vector,
}
}
]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': POINT_ID},
)
assert response.ok
result = response.json()["result"]
assert compare_vectors(result["vector"]["image"], image_vector)
assert compare_vectors(result["vector"]["text"], text_vector)
def test_update_empty_vectors(collection_name):
"""
Remove all named vectors for a point. Then add named vectors and test
against it.
"""
response = request_with_validation(
api='/collections/{collection_name}/points/vectors/delete',
method="POST",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [1],
"vector": ["image", "text"]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': 1},
)
assert response.ok
result = response.json()["result"]
assert "text" not in result["vector"]
assert "image" not in result["vector"]
text_vector = [
0.34035879, 0.344099,
0.3478392, 0.35157941,
0.35531961, 0.35905982,
0.36280003, 0.36654023
]
response = request_with_validation(
api='/collections/{collection_name}/points/vectors',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": 1,
"vector": {
"text": text_vector,
}
}
]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': 1},
)
assert response.ok
result = response.json()["result"]
assert compare_vectors(result["vector"]["text"], text_vector)
assert "image" not in result["vector"]
image_vector = [0.19, 0.28, 0.37, 0.46]
response = request_with_validation(
api='/collections/{collection_name}/points/vectors',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": 1,
"vector": {
"image": image_vector,
}
}
]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': 1},
)
assert response.ok
result = response.json()["result"]
assert compare_vectors(result["vector"]["image"], image_vector)
assert compare_vectors(result["vector"]["text"], text_vector)
def test_update_vectors_unknown_point(collection_name):
response = request_with_validation(
api='/collections/{collection_name}/points/vectors',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": 1,
"vector": {
"text": [0.05, 0.61, 0.76, 0.74, 0.05, 0.61, 0.76, 0.74],
},
"payload": {"city": "Berlin"}
},
{
"id": 424242424242424242,
"vector": {
"image": [0.19, 0.81, 0.75, 0.11],
},
"payload": {"city": ["Berlin", "London"]}
}
]
}
)
assert not response.ok
assert response.status_code == 404
error = response.json()["status"]["error"]
assert error == "Not found: No point with id 424242424242424242 found"
def test_update_vectors_same_point_in_batch(collection_name):
POINT_ID = 1000
response = request_with_validation(
api='/collections/{collection_name}/points',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": POINT_ID,
"vector": {
"text": [0.1, 0.3, 0.2, 0.9, 0.9, 0.1, 0.4, 0.9],
"image": [0.8, 0.6, 0.3, 0.0],
},
}
]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': POINT_ID},
)
assert response.ok
result = response.json()["result"]
assert result["vector"].get("text") == [0.1, 0.3, 0.2, 0.9, 0.9, 0.1, 0.4, 0.9]
assert result["vector"].get("image") == [0.8, 0.6, 0.3, 0.0]
# Update both vectors in separate batch items
# Matches bug report: <https://github.com/qdrant/qdrant/issues/3376>
response = request_with_validation(
api='/collections/{collection_name}/points/vectors',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": POINT_ID,
"vector": {
"text": [0.8, 0.8, 0.9, 0.2, 0.7, 0.5, 0.2, 0.6],
}
},
{
"id": POINT_ID,
"vector": {
"image": [0.3, 0.6, 0.4, 0.4],
}
}
]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': POINT_ID},
)
assert response.ok
result = response.json()["result"]
assert result["vector"].get("text") == [0.8, 0.8, 0.9, 0.2, 0.7, 0.5, 0.2, 0.6]
assert result["vector"].get("image") == [0.3, 0.6, 0.4, 0.4]
# Update the same vector twice
response = request_with_validation(
api='/collections/{collection_name}/points/vectors',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": POINT_ID,
"vector": {
"text": [0.2, 0.0, 0.1, 0.3, 0.1, 0.0, 0.0, 0.5],
}
},
{
"id": POINT_ID,
"vector": {
"image": [0.7, 0.5, 0.0, 0.5],
"text": [0.9, 0.2, 0.5, 0.6, 0.4, 0.1, 0.6, 0.7],
}
},
{
"id": 1,
"vector": {
"image": [0.4, 0.4, 0.0, 0.9],
"text": [0.8, 0.6, 0.9, 0.2, 0.3, 0.9, 0.5, 0.9],
}
},
{
"id": 2,
"vector": {
"text": [0.5, 0.8, 0.9, 0.8, 0.3, 0.2, 0.1, 0.1],
}
},
{
"id": 3,
"vector": {
"image": [0.1, 0.1, 0.3, 0.7],
}
},
{
"id": POINT_ID,
"vector": {
"image": [0.9, 0.9, 0.7, 0.5],
}
},
{
"id": POINT_ID,
"vector": {
"image": [0.4, 0.5, 0.6, 0.2],
}
},
]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': POINT_ID},
)
assert response.ok
result = response.json()["result"]
assert result["vector"].get("text") == [0.9, 0.2, 0.5, 0.6, 0.4, 0.1, 0.6, 0.7]
assert result["vector"].get("image") == [0.4, 0.5, 0.6, 0.2]
def test_no_vectors(collection_name):
response = request_with_validation(
api='/collections/{collection_name}/points/vectors',
method="PUT",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [
{
"id": 1,
"vector": {},
}
]
}
)
assert not response.ok
assert response.status_code == 422
error = response.json()["status"]["error"]
assert error.__contains__(
"Validation error in JSON body: [points[0].vector: must specify vectors to update for point]")
def test_delete_vectors(collection_name):
delete_vectors(collection_name)
# Deleting a second time should work fine
delete_vectors(collection_name)
def delete_vectors(collection_name):
response = request_with_validation(
api='/collections/{collection_name}/points/vectors/delete',
method="POST",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [1, 2],
"vector": ["image"]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/vectors/delete',
method="POST",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [2, 3],
"vector": ["text"]
}
)
assert response.ok
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': 1},
)
assert response.ok
result = response.json()["result"]
assert "image" not in result["vector"]
assert "text" in result["vector"]
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': 2},
)
assert response.ok
result = response.json()["result"]
assert "image" not in result["vector"]
assert "text" not in result["vector"]
response = request_with_validation(
api='/collections/{collection_name}/points/{id}',
method="GET",
path_params={'collection_name': collection_name, 'id': 3},
)
assert response.ok
result = response.json()["result"]
assert "image" in result["vector"]
assert "text" not in result["vector"]
def test_delete_all_vectors(collection_name):
response = request_with_validation(
api='/collections/{collection_name}/points/vectors/delete',
method="POST",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"filter": {},
"vector": ["image", "text"]
}
)
assert response.ok
def test_delete_unknown_vectors(collection_name):
response = request_with_validation(
api='/collections/{collection_name}/points/vectors/delete',
method="POST",
path_params={'collection_name': collection_name},
query_params={'wait': 'true'},
body={
"points": [1, 2],
"vector": ["a"]
}
)
assert not response.ok
assert response.status_code == 400
error = response.json()["status"]["error"]
assert error.__contains__("Wrong input: Not existing vector name error: a")