#7753·chroma

[Bug]: Text KNN queries fail in dictionary searches

Author: HaokaiDingCreated Sep 16, 2026Updated Sep 16, 2026

What happened?

The documented dictionary form of a text KNN search raises TypeError during construction, while the equivalent Knn expression works.

python
from chromadb import Knn, Search

expected = Search(rank=Knn(query="quantum mechanics"))
actual = Search(rank={"$knn": {"query": "quantum mechanics"}})
assert actual.to_dict() == expected.to_dict()

The second construction fails before any collection, embedding function or database is involved. This is the same dictionary pattern shown in the Search Basics mixed-types example.

Rank.from_dict(Knn(query="hello world").to_dict()) and nested arithmetic expressions containing text KNN queries fail for the same reason. Rank.from_dict handles dense and sparse query values but rejects strings, despite Knn.query supporting them and the collection already having a string-query embedding path.

Expected: preserve the string in the Knn expression so dictionary and object construction behave consistently and the existing embedding path can process it later.

Versions

  • Current main Python source, reporting Chroma 1.5.9.
  • Python 3.12.13, NumPy 2.5.3, macOS 26.6.2 ARM64.
  • Reproduced locally without starting a database, loading a model or calling an embedding service.

Relevant log output

TypeError: $knn query must be a list, numpy array, or SparseVector dict, got str