ZVEC Compatibility (Vector)

This page tracks hlquery compatibility for zvec-style vector query features.

Implemented

• vector_query / vectorQuery / vector / embedding
  • Supports dense arrays and sparse map payloads ({"12": 0.9, "91": 0.4})
• field_name / fieldName / field
• topk / top_k / topK / k / limit / per_page
• vector_queries / vectorQueries (multi-query)
• Per-query metrics: cosine, dot, l2, l1
• Per-query controls: weight, threshold, normalize
• Fusion: weighted_sum, max, average, rrf
• Filtering: filter_by / filterBy / filter
• Output controls: output_fields / outputFields, include_vector / includeVector
• Distance constraints:
  • radius / max_distance / maxDistance
  • range_filter / min_distance / minDistance
• Distance output: include_distance / includeDistance (returns _vector_distance)
• Query tuning hints:
  • query_params / queryParams / params
  • ef / ef_search / hnsw_ef_search
  • nprobe / ivf_nprobe
  • is_linear
  • is_using_refiner
• Endpoint methods: GET and POST on /collections/{name}/vector_search

Not Implemented Yet

• Native ANN index lifecycle APIs equivalent to zvec index management classes
• Binary vector datatypes and quantization controls as dedicated schema/index modes

Zvec Collection API parity checklist

Zvec exposes an in-process Collection interface with DDL/DML/vector query helpers. The table below shows how HLQuery’s HTTP APIs already cover some of those routines and highlights gaps we still need to implement to reach parity.

Zvec method	HLQuery equivalent	Status
CreateAndOpen(path, schema, option)	POST /collections	Implemented via the Collections API and schema creation docs (see Collections API).
Open(path, option)	GET /collections/{name}	Implemented (collection info/summary) even though we do not expose filesystem path.
Destroy()	DELETE /collections/{name}	Implemented.
Flush()	POST /collections/flush	Implemented (global flush resets all collections).
Path()	Not exposed	Missing – HLQuery does not publish internal storage paths via the HTTP API.
Stats()	GET /collections/{name} / metadata	Partially implemented: num_documents, disk_size, and collection metadata are returned, but we can expand with richer stats later (see Get Collection).
Schema()	POST /collections / GET /collections/{name}	Implemented for creation and listing of schema fields.
Options()	Not exposed	Missing – HLQuery currently lacks an options/collection settings endpoint.
CreateIndex(column, params, options)	—	Missing – no HTTP endpoint yet to build vector or inverted indexes on top of a collection.
DropIndex(column)	—	Missing – index lifecycle is not part of the API today.
Optimize(options)	—	Missing – there is no direct optimize call for collection segments/indexes.
AddColumn(schema, expression, option)	POST /collections/{name}/update (fields only)	Partial – we can append new fields but expressions/options and expression-based population (zvec style) are not yet supported.
DropColumn(column)	—	Missing – we do not allow removing columns once created.
AlterColumn(old_name, new_name, schema, option)	—	Missing – renaming or schema mutation of existing fields is not supported.
Insert(docs)	POST /collections/{name}/documents	Implemented via Documents API.
Upsert(docs)	PUT /collections/{name}/documents/{id} (implicit upsert)	Implemented: PUT updates or creates documents.
Update(docs)	PUT /collections/{name}/documents/{id}	Implemented as partial updates.
Delete(pks)	DELETE /collections/{name}/documents/{id}	Implemented per-document deletion; bulk delete exists via the delete_by_filter endpoint.
DeleteByFilter(filter)	DELETE /collections/{name}/documents?filter=...	Implemented via bulk deletion helpers (see Documents API).
Query(VectorQuery)	POST /collections/{name}/vector_search	Implemented (vector search endpoint exposes multi-query, metrics, etc).
GroupByQuery(GroupByVectorQuery)	—	Missing – HLQuery does not yet support grouped vector aggregation.
Fetch(pks)	GET /collections/{name}/documents/{id}	Implemented (document retrieval).

Missing entries above (index lifecycle, column alteration, options, path, group-by) represent concrete gaps we can track under vector-zvec-compat.md until we implement the API parity.

Notes

hlquery currently executes vector search via linear scan over candidate documents. ANN-style params (ef, nprobe, etc.) are accepted as query-time hints and influence candidate sizing behavior.