chroma-core / chroma-core/chroma

[DOC] `Collection.add` / `query` docstrings list ValueErrors the client never raises

Open Beginner friendly
#7,735 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.