> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search API Overview

export const Callout = ({title, children}) => <div className="my-6">
    <div className="relative pr-1.5 pb-1.5">
      <div className="absolute top-1.5 left-1.5 right-0 bottom-0 bg-blue-500 dark:bg-blue-600" />
      <div className="relative border border-black dark:border-gray-500 px-5 py-4 bg-white dark:bg-neutral-900">
        {title && <p className="block mb-2"><strong>{title}</strong></p>}
        {children}
      </div>
    </div>
  </div>;

The Search API is a powerful, flexible interface for hybrid search operations in Chroma Cloud, combining vector similarity search with metadata filtering and custom ranking expressions.

<Callout>
  **Search API is available in Chroma Cloud only.** Future support on single-node Chroma is planned.
</Callout>

## What is the Search API?

The Search API provides a powerful, unified interface for all search operations in Chroma. Instead of using separate `query()` and `get()` methods with different parameters, the Search API offers:

* **Unified interface**: One consistent API replaces both `query()` and `get()` methods
* **Expression-based queries**: Use `K()` expressions for powerful filtering and field selection
* **Composable operations**: Chain methods to build complex queries naturally
* **Type safety**: Full type hints, IDE autocomplete, and clear error messages
* **Advanced capabilities**: Hybrid search with RRF, custom ranking expressions, and batch operations
* **Flexible result selection**: Choose exactly which fields to return, reducing payload size

## Quick Start

<CodeGroup>
  ```python Python theme={null}
  from chromadb import Search, K, Knn

  # Build the base search with filtering
  search = (
      Search()
      .where(K("category") == "science")
      .limit(10)
      .select(K.DOCUMENT, K.SCORE)
  )

  # Option 1: Pass pre-computed embeddings directly
  query_embedding = [0.25, -0.15, 0.33, ...]
  result = collection.search(search.rank(Knn(query=query_embedding)))

  # Option 2: Pass text query (embedding created using collection's schema configuration)
  query_text = "What are the latest advances in quantum computing?"
  result = collection.search(search.rank(Knn(query=query_text)))
  ```

  ```typescript TypeScript theme={null}
  import { Search, K, Knn } from 'chromadb';

  // Build the base search with filtering
  const search = new Search()
    .where(K("category").eq("science"))
    .limit(10)
    .select(K.DOCUMENT, K.SCORE);

  // Option 1: Pass pre-computed embeddings directly
  const queryEmbedding = [0.25, -0.15, 0.33, ...];
  const result = await collection.search(search.rank(Knn({ query: queryEmbedding })));

  // Option 2: Pass text query (embedding created using collection's schema configuration)
  const queryText = "What are the latest advances in quantum computing?";
  const result2 = await collection.search(search.rank(Knn({ query: queryText })));
  ```

  ```rust Rust theme={null}
  use chroma::types::{Key, QueryVector, RankExpr, SearchPayload};

  let search = SearchPayload::default()
      .r#where(Key::field("category").eq("science"))
      .limit(Some(10), 0)
      .select([Key::Document, Key::Score]);

  let result = collection
      .search(vec![search.rank(RankExpr::Knn {
          query: QueryVector::Dense(vec![0.25, -0.15, 0.33]),
          key: Key::Embedding,
          limit: 10,
          default: None,
          return_rank: false,
      })])
      .await?;
  ```
</CodeGroup>

<Callout>
  When passing text to `Knn()`, the embedding is automatically created using the collection's schema configuration. By default, `Knn` uses the `#embedding` key, which corresponds to the default vector index. You can specify a different key with the `key` parameter (e.g., `Knn(query=query_text, key="my_custom_embedding")`). If the specified key doesn't have an embedding configuration in the collection schema, an error will be thrown.
</Callout>

## Feature Comparison

| Feature                            | `query()`                | `get()`          | `search()` |
| ---------------------------------- | ------------------------ | ---------------- | ---------- |
| Vector similarity search           | Yes                      | No               | Yes        |
| Filtering (metadata, document, ID) | Yes                      | Yes              | Yes        |
| Custom ranking expressions         | No                       | No               | Yes        |
| Result grouping/deduplication      | No                       | No               | Yes        |
| Batch operations                   | Partial (Embedding only) | No               | Yes        |
| Field selection                    | Partial (Coarse)         | Partial (Coarse) | Yes        |
| Pagination                         | No                       | Yes              | Yes        |
| Type safety                        | Partial                  | Partial          | Yes        |

## Availability

The Search API is available for Chroma Cloud. Support for local Chroma deployments will be available in a future release.

## Required Setup

To use the Search API, you'll need to import the necessary components:

<CodeGroup>
  ```python Python theme={null}
  from chromadb import Search, K, Knn

  # Optional: For advanced features
  from chromadb import Rrf  # For hybrid search
  ```

  ```typescript TypeScript theme={null}
  import { Search, K, Knn } from 'chromadb';

  // Optional: For advanced features
  import { Rrf } from 'chromadb';  // For hybrid search
  ```

  ```rust Rust theme={null}
  use chroma::types::{Key, RankExpr, SearchPayload};
  ```
</CodeGroup>

Make sure you're connected to a Chroma Cloud instance, as the Search API is currently only available for cloud deployments.

## Complete Example

Here's a practical example searching for science articles:

<CodeGroup>
  ```python Python theme={null}
  import chromadb
  from chromadb import Search, K, Knn

  # Connect to Chroma Cloud
  client = chromadb.CloudClient(
      tenant="your-tenant",
      database="your-database",
      api_key="your-api-key"
  )
  collection = client.get_collection("articles")

  # Build the base search query
  search = (
      Search()
      .where((K("category") == "science") & (K("year") >= 2020))
      .limit(5)
      .select(K.DOCUMENT, K.SCORE, "title", "author")
  )

  # Option 1: Search with pre-computed embeddings
  query_embedding = [0.12, -0.34, 0.56, ...]
  result = collection.search(search.rank(Knn(query=query_embedding)))

  # Option 2: Search with text query (embedding created automatically)
  query_text = "recent quantum computing breakthroughs"
  result = collection.search(search.rank(Knn(query=query_text)))

  # Access results using the convenient rows() method
  # Note: Results are ordered by score (ascending - lower is better)
  # For KNN search, score represents distance
  rows = result.rows()[0]  # Get first (and only) search results
  for row in rows:
      print(f"ID: {row['id']}")
      print(f"Title: {row['metadata']['title']}")
      print(f"Distance: {row['score']:.3f}")
      print(f"Document: {row['document'][:100]}...")
      print("---")
  ```

  ```typescript TypeScript theme={null}
  import { CloudClient, Search, K, Knn } from 'chromadb';

  // Connect to Chroma Cloud
  const client = new CloudClient({
    tenant: "your-tenant",
    database: "your-database",
    apiKey: "your-api-key"
  });

  const collection = await client.getCollection({ name: "articles" });

  // Build the base search query
  const search = new Search()
    .where(K("category").eq("science").and(K("year").gte(2020)))
    .limit(5)
    .select(K.DOCUMENT, K.SCORE, "title", "author");

  // Option 1: Search with pre-computed embeddings
  const queryEmbedding = [0.12, -0.34, 0.56, ...];
  const result = await collection.search(search.rank(Knn({ query: queryEmbedding })));

  // Option 2: Search with text query (embedding created automatically)
  const queryText = "recent quantum computing breakthroughs";
  result = await collection.search(search.rank(Knn({ query: queryText })));

  // Access results using the convenient rows() method
  // Note: Results are ordered by score (ascending - lower is better)
  // For KNN search, score represents distance
  const rows = result.rows()[0];  // Get first (and only) search results
  for (const row of rows) {
    console.log(`ID: ${row.id}`);
    console.log(`Title: ${row.metadata?.title}`);
    console.log(`Distance: ${row.score?.toFixed(3)}`);
    console.log(`Document: ${row.document?.substring(0, 100)}...`);
    console.log("---");
  }
  ```

  ```rust Rust theme={null}
  use chroma::{ChromaHttpClient, ChromaHttpClientOptions};
  use chroma::types::{Key, QueryVector, RankExpr, SearchPayload};

  let client = ChromaHttpClient::new(ChromaHttpClientOptions::cloud(
      "your-api-key",
      "your-database",
  )?);
  let collection = client.get_collection("articles").await?;

  let search = SearchPayload::default()
      .r#where((Key::field("category").eq("science")) & (Key::field("year").gte(2020)))
      .limit(Some(5), 0)
      .select([Key::Document, Key::Score, Key::field("title"), Key::field("author")]);

  let response = collection
      .search(vec![search.rank(RankExpr::Knn {
          query: QueryVector::Dense(vec![0.12, -0.34, 0.56]),
          key: Key::Embedding,
          limit: 5,
          default: None,
          return_rank: false,
      })])
      .await?;
  ```
</CodeGroup>

Example output:

```
ID: doc_123
Title: Advances in Quantum Computing
Distance: 0.234
Document: Recent developments in quantum computing have shown promising results for...
---
ID: doc_456
Title: Machine Learning in Biology
Distance: 0.412
Document: The application of machine learning techniques to biological data has...
---
```

## Performance

The Search API provides the same performance as existing Chroma query endpoints, with the added benefit of more flexible query construction and batch operations that can reduce the number of round trips.

## Feedback

<Callout>
  Please report issues or feedback through the [Chroma GitHub repository](https://github.com/chroma-core/chroma/issues).
</Callout>

## What's Next?

* **[Search Basics](./search-basics)** - Learn how to construct searches
* **[Filtering with Where](./filtering)** - Master metadata filtering
* **[Ranking and Scoring](./ranking)** - Understand ranking expressions
* **[Group By & Aggregation](./group-by)** - Diversify results with grouping
* **[Hybrid Search](./hybrid-search)** - Combine multiple strategies
* **[Examples](./examples)** - See real-world patterns