chroma_query_documents
Search and retrieve documents from a Chroma collection using text queries, metadata filters, and advanced content operators for precise results.
Instructions
Query documents from a Chroma collection with advanced filtering.
Args:
collection_name: Name of the collection to query
query_texts: List of query texts to search for
n_results: Number of results to return per query
where: Optional metadata filters using Chroma's query operators
Examples:
- Simple equality: {"metadata_field": "value"}
- Comparison: {"metadata_field": {"$gt": 5}}
- Logical AND: {"$and": [{"field1": {"$eq": "value1"}}, {"field2": {"$gt": 5}}]}
- Logical OR: {"$or": [{"field1": {"$eq": "value1"}}, {"field1": {"$eq": "value2"}}]}
where_document: Optional document content filters
Examples:
- Contains: {"$contains": "value"}
- Not contains: {"$not_contains": "value"}
- Regex: {"$regex": "[a-z]+"}
- Not regex: {"$not_regex": "[a-z]+"}
- Logical AND: {"$and": [{"$contains": "value1"}, {"$not_regex": "[a-z]+"}]}
- Logical OR: {"$or": [{"$regex": "[a-z]+"}, {"$not_contains": "value2"}]}
include: List of what to include in response. By default, this will include documents, metadatas, and distances.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection_name | Yes | ||
| include | No | ||
| n_results | No | ||
| query_texts | Yes | ||
| where | No | ||
| where_document | No |
Implementation Reference
- src/chroma_mcp/server.py:395-441 (handler)The main handler function for the 'chroma_query_documents' tool. Decorated with @mcp.tool(), which handles both registration and schema definition (from type hints and docstring). Implements querying Chroma collection using query_texts with optional filters and includes.@mcp.tool() async def chroma_query_documents( collection_name: str, query_texts: List[str], n_results: int = 5, where: Dict | None = None, where_document: Dict | None = None, include: List[str] = ["documents", "metadatas", "distances"] ) -> Dict: """Query documents from a Chroma collection with advanced filtering. Args: collection_name: Name of the collection to query query_texts: List of query texts to search for n_results: Number of results to return per query where: Optional metadata filters using Chroma's query operators Examples: - Simple equality: {"metadata_field": "value"} - Comparison: {"metadata_field": {"$gt": 5}} - Logical AND: {"$and": [{"field1": {"$eq": "value1"}}, {"field2": {"$gt": 5}}]} - Logical OR: {"$or": [{"field1": {"$eq": "value1"}}, {"field1": {"$eq": "value2"}}]} where_document: Optional document content filters Examples: - Contains: {"$contains": "value"} - Not contains: {"$not_contains": "value"} - Regex: {"$regex": "[a-z]+"} - Not regex: {"$not_regex": "[a-z]+"} - Logical AND: {"$and": [{"$contains": "value1"}, {"$not_regex": "[a-z]+"}]} - Logical OR: {"$or": [{"$regex": "[a-z]+"}, {"$not_contains": "value2"}]} include: List of what to include in response. By default, this will include documents, metadatas, and distances. """ if not query_texts: raise ValueError("The 'query_texts' list cannot be empty.") client = get_chroma_client() try: collection = client.get_collection(collection_name) return collection.query( query_texts=query_texts, n_results=n_results, where=where, where_document=where_document, include=include ) except Exception as e: raise Exception(f"Failed to query documents from collection '{collection_name}': {str(e)}") from e
- src/chroma_mcp/server.py:395-441 (registration)The @mcp.tool() decorator registers the function as an MCP tool.@mcp.tool() async def chroma_query_documents( collection_name: str, query_texts: List[str], n_results: int = 5, where: Dict | None = None, where_document: Dict | None = None, include: List[str] = ["documents", "metadatas", "distances"] ) -> Dict: """Query documents from a Chroma collection with advanced filtering. Args: collection_name: Name of the collection to query query_texts: List of query texts to search for n_results: Number of results to return per query where: Optional metadata filters using Chroma's query operators Examples: - Simple equality: {"metadata_field": "value"} - Comparison: {"metadata_field": {"$gt": 5}} - Logical AND: {"$and": [{"field1": {"$eq": "value1"}}, {"field2": {"$gt": 5}}]} - Logical OR: {"$or": [{"field1": {"$eq": "value1"}}, {"field1": {"$eq": "value2"}}]} where_document: Optional document content filters Examples: - Contains: {"$contains": "value"} - Not contains: {"$not_contains": "value"} - Regex: {"$regex": "[a-z]+"} - Not regex: {"$not_regex": "[a-z]+"} - Logical AND: {"$and": [{"$contains": "value1"}, {"$not_regex": "[a-z]+"}]} - Logical OR: {"$or": [{"$regex": "[a-z]+"}, {"$not_contains": "value2"}]} include: List of what to include in response. By default, this will include documents, metadatas, and distances. """ if not query_texts: raise ValueError("The 'query_texts' list cannot be empty.") client = get_chroma_client() try: collection = client.get_collection(collection_name) return collection.query( query_texts=query_texts, n_results=n_results, where=where, where_document=where_document, include=include ) except Exception as e: raise Exception(f"Failed to query documents from collection '{collection_name}': {str(e)}") from e