chroma-core / chroma-core/chroma
[DOC] `Collection.add` / `query` docstrings list ValueErrors the client never raises
- Dominant language
- Rust
- Stars
- 29.3k
- Forks
- 2.5k
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 38
Description
The `Raises:` sections of `Collection.add` and `Collection.query` (and the same text in `AsyncCollection`) describe three errors that chromadb 1.5.9 does not raise. The generated reference page `reference/python/collection.mdx` repeats them, and in two of the three cases the user guide already says the opposite.
| Docstring says | What happens (1.5.9) | Guide says |
|---|---|---|
| `add`: "ValueError: If an ID already exists." | No error. The existing record is kept and the new one is dropped. | `add-data.mdx:182`: "it will be ignored without throwing an error" |
| `add`: "ValueError: If embeddings and documents are both provided." | Accepted, both stored. `types.py` explicitly allows documents alongside embeddings. | `add-data.mdx:57`, `:60`: pass both, stored as-is |
| `query`: "ValueError: If multiple query input types are provided." | No error. With `query_embeddings` and `query_texts` both given, the embeddings are used and the texts are ignored. | — |
All three reproduce with `EphemeralClient` and with `HttpClient` against `chroma run`. The existing-ID `add` and the `query` case also reproduce with `AsyncHttpClient`.
## Reproduction
```python
import chromadb
col = chromadb.EphemeralClient().create_collection("repro", embedding_function=None)
e = [[0.1, 0.2, 0.3]]
col.add(ids=["a"], embeddings=e, documents=["first"])
col.add(ids=["a"], embeddings=[[0.9, 0.9, 0.9]], documents=["second"]) # documented to raise
print(col.get(ids=["a"])["documents"]) # ['first']
col.add(ids=["b"], embeddings=e, documents=["doc"]) # documented to raise; accepted
print(col.query(query_embeddings=e, query_texts=["unrelated"], n_results=1)["ids"]) # documented to raise; texts ignored
```
## Where
- `chromadb/api/models/Collection.py`: `add` Raises (lines 122, 124 on `main`), `query` Raises (268)
- `chromadb/api/models/AsyncCollection.py`: `add` Raises (84-85), `query` Raises (249-251)
- `docs/mintlify/reference/python/collection.mdx`: generated from the above by `docs/scripts/generate_python_reference.py`
## Versions
chromadb 1.5.9 (latest on PyPI), Python 3.11.6, Windows 11. Line numbers are from `main` at a7920e9.
## Proposed fix
For `add`, the behaviour matches the guide, so only the docstrings are wrong: drop the two lines, and state that an existing ID is ignored, pointing at `upsert`/`update`. Then regenerate `collection.mdx`.
`query` is less clear-cut. Silently ignoring `query_texts` when embeddings are also passed is easy to miss, so it could be either a docstring fix or a real check. Raising now would break callers that pass both today. Which would you prefer?
I can open a PR for the docstring changes.
Contributor guide
No contributing guide indexed for this repository
Research direction
Read the Raises sections in chromadb/api/models/Collection.py and chromadb/api/models/AsyncCollection.py, then run the EphemeralClient reproduction from the issue to confirm the documented behavior. Update the relevant docstrings and regenerate docs/mintlify/reference/python/collection.mdx with docs/scripts/generate_python_reference.py; done means the reference matches the supported behavior and the unresolved query case has an explicit decision.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 76/100