[DOC] Document Search related types and methods (#5700)

## Description of changes

_Summarize the changes made by this PR._

- Improvements & Bug fixes
    - N/A
- New functionality
    - Derived docstrs for `Search` related Rust types

## Test plan

_How are these changes tested?_

- [ ] Tests pass locally with `pytest` for python, `yarn test` for js,
`cargo test` for rust

## Migration plan

_Are there any migrations, or any forwards/backwards compatibility
changes needed in order to make sure this change deploys reliably?_

## Observability plan

_What is the plan to instrument and monitor this change?_

## Documentation Changes

_Are all docstrings for user-facing APIs updated if required? Do we need
to make documentation changes in the_ [_docs
section](https://github.com/chroma-core/chroma/tree/main/docs/docs.trychroma.com)?_

Author: Sicheng-Pan

clients/new-js/packages/chromadb/src/api/types.gen.ts

@@ -244,6 +244,72 @@ export type IntValueType = {
     int_inverted_index?: null | IntInvertedIndexType;
 };
 
+/**
+ * Represents a field key in search queries.
+ *
+ * Used for both selecting fields to return and building filter expressions.
+ * Predefined keys access special fields, while custom keys access metadata.
+ *
+ * # Predefined Keys
+ *
+ * - `Key::Document` - Document text content (`#document`)
+ * - `Key::Embedding` - Vector embeddings (`#embedding`)
+ * - `Key::Metadata` - All metadata fields (`#metadata`)
+ * - `Key::Score` - Search scores (`#score`)
+ *
+ * # Custom Keys
+ *
+ * Use `Key::field()` or `Key::from()` to reference metadata fields:
+ *
+ * ```
+ * use chroma_types::operator::Key;
+ *
+ * let key = Key::field("author");
+ * let key = Key::from("title");
+ * ```
+ *
+ * # Examples
+ *
+ * ## Building filters
+ *
+ * ```
+ * use chroma_types::operator::Key;
+ *
+ * // Equality
+ * let filter = Key::field("status").eq("published");
+ *
+ * // Comparisons
+ * let filter = Key::field("year").gte(2020);
+ * let filter = Key::field("score").lt(0.9);
+ *
+ * // Set operations
+ * let filter = Key::field("category").is_in(vec!["tech", "science"]);
+ * let filter = Key::field("status").not_in(vec!["deleted", "archived"]);
+ *
+ * // Document content
+ * let filter = Key::Document.contains("machine learning");
+ * let filter = Key::Document.regex(r"\bAPI\b");
+ *
+ * // Combining filters
+ * let filter = Key::field("status").eq("published")
+ * & Key::field("year").gte(2020);
+ * ```
+ *
+ * ## Selecting fields
+ *
+ * ```
+ * use chroma_types::plan::SearchPayload;
+ * use chroma_types::operator::Key;
+ *
+ * let search = SearchPayload::default()
+ * .select([
+ * Key::Document,
+ * Key::Score,
+ * Key::field("title"),
+ * Key::field("author"),
+ * ]);
+ * ```
+ */
 export type Key = 'Document' | 'Embedding' | 'Metadata' | 'Score' | {
     MetadataField: string;
 };

rust/chroma/src/client/chroma_http_client.rs

@@ -91,10 +91,10 @@ static METRICS: std::sync::LazyLock<crate::client::metrics::Metrics> =
 /// # Examples
 ///
 /// ```
-/// use chroma::{ChromaHttpClient, client::ChromaClientOptions, client::ChromaAuthMethod};
+/// use chroma::{ChromaHttpClient, client::ChromaHttpClientOptions, client::ChromaAuthMethod};
 ///
 /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
-/// let options = ChromaClientOptions {
+/// let options = ChromaHttpClientOptions {
 ///     endpoint: "https://api.trychroma.com".parse()?,
 ///     auth_method: ChromaAuthMethod::cloud_api_key("my-key")?,
 ///     ..Default::default()
@@ -158,10 +158,10 @@ impl ChromaHttpClient {
     /// # Examples
     ///
     /// ```
-    /// use chroma::{ChromaHttpClient, client::ChromaClientOptions, client::ChromaAuthMethod};
+    /// use chroma::{ChromaHttpClient, client::ChromaHttpClientOptions, client::ChromaAuthMethod};
     ///
     /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
-    /// let options = ChromaClientOptions {
+    /// let options = ChromaHttpClientOptions {
     ///     endpoint: "https://api.trychroma.com".parse()?,
     ///     auth_method: ChromaAuthMethod::cloud_api_key("my-key")?,
     ///     ..Default::default()

rust/chroma/src/client/options.rs

@@ -157,10 +157,10 @@ impl ChromaHttpClientOptions {
     /// # Examples
     ///
     /// ```no_run
-    /// use chroma::client::ChromaClientOptions;
+    /// use chroma::client::ChromaHttpClientOptions;
     ///
     /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
-    /// let options = ChromaClientOptions::from_env()?;
+    /// let options = ChromaHttpClientOptions::from_env()?;
     /// # Ok(())
     /// # }
     /// ```
@@ -200,10 +200,10 @@ impl ChromaHttpClientOptions {
     /// # Examples
     ///
     /// ```no_run
-    /// use chroma::client::ChromaClientOptions;
+    /// use chroma::client::ChromaHttpClientOptions;
     ///
     /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
-    /// let options = ChromaClientOptions::from_cloud_env()?;
+    /// let options = ChromaHttpClientOptions::from_cloud_env()?;
     /// # Ok(())
     /// # }
     /// ```
@@ -241,10 +241,10 @@ impl ChromaHttpClientOptions {
     /// # Examples
     ///
     /// ```
-    /// use chroma::client::ChromaClientOptions;
+    /// use chroma::client::ChromaHttpClientOptions;
     ///
     /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
-    /// let options = ChromaClientOptions::cloud("my-api-key", "production-db")?;
+    /// let options = ChromaHttpClientOptions::cloud("my-api-key", "production-db")?;
     /// # Ok(())
     /// # }
     /// ```

rust/chroma/src/collection.rs

@@ -42,8 +42,8 @@ use crate::{client::ChromaHttpClientError, ChromaHttpClient};
 ///
 /// ```
 /// # use chroma::collection::ChromaCollection;
-/// # use chroma::client::ChromaClientError;
-/// # async fn example(collection: ChromaCollection) -> Result<(), ChromaClientError> {
+/// # use chroma::client::ChromaHttpClientError;
+/// # async fn example(collection: ChromaCollection) -> Result<(), ChromaHttpClientError> {
 /// let count = collection.count().await?;
 /// println!("Collection contains {} records", count);
 ///
@@ -325,87 +325,144 @@ impl ChromaCollection {
         self.send("query", Method::POST, Some(request)).await
     }
 
-    /// Executes advanced search with multiple search payloads in a single request.
+    /// Performs hybrid search on the collection using the Search API.
     ///
-    /// Each [`SearchPayload`] can specify distinct query vectors, filters, and result counts,
-    /// enabling efficient batch similarity search with heterogeneous parameters.
+    /// The Search API provides a powerful, flexible interface for vector similarity search
+    /// combined with metadata filtering and custom ranking expressions.
     ///
-    /// # Errors
+    /// # Arguments
     ///
-    /// Returns an error if:
-    /// - Any search payload fails validation
-    /// - Network communication fails
+    /// * `searches` - One or more search payloads to execute in a single request
+    ///
+    /// # Returns
+    ///
+    /// A `SearchResponse` containing results for each search payload
     ///
     /// # Examples
     ///
-    /// Basic search with default parameters:
+    /// ## Basic similarity search
+    ///
     /// ```
-    /// # use chroma::collection::ChromaCollection;
-    /// # use chroma_types::plan::SearchPayload;
-    /// # async fn example(collection: ChromaCollection) -> Result<(), Box<dyn std::error::Error>> {
-    /// let search1 = SearchPayload {
-    ///     filter: Default::default(),
-    ///     rank: Default::default(),
-    ///     limit: Default::default(),
-    ///     select: Default::default(),
+    /// use chroma_types::plan::SearchPayload;
+    /// use chroma_types::operator::{RankExpr, QueryVector, Key};
+    ///
+    /// # async fn example(collection: &chroma::collection::ChromaCollection) -> Result<(), Box<dyn std::error::Error>> {
+    /// // Search with a query vector
+    /// let search = SearchPayload::default()
+    ///     .rank(RankExpr::Knn {
+    ///         query: QueryVector::Dense(vec![0.1, 0.2, 0.3]),
+    ///         key: Key::Embedding,
+    ///         limit: 100,
+    ///         default: None,
+    ///         return_rank: false,
+    ///     })
+    ///     .limit(Some(10), 0)
+    ///     .select([Key::Document, Key::Score]);
+    ///
+    /// let results = collection.search(vec![search]).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    ///
+    /// ## Filtered search with metadata
+    ///
+    /// ```
+    /// use chroma_types::plan::SearchPayload;
+    /// use chroma_types::operator::{RankExpr, QueryVector, Key};
+    ///
+    /// # async fn example(collection: &chroma::collection::ChromaCollection) -> Result<(), Box<dyn std::error::Error>> {
+    /// // Filter by category and year, then rank by similarity
+    /// let search = SearchPayload::default()
+    ///     .r#where(
+    ///         Key::field("category").eq("science")
+    ///             & Key::field("year").gte(2020)
+    ///     )
+    ///     .rank(RankExpr::Knn {
+    ///         query: QueryVector::Dense(vec![0.1, 0.2, 0.3]),
+    ///         key: Key::Embedding,
+    ///         limit: 200,
+    ///         default: None,
+    ///         return_rank: false,
+    ///     })
+    ///     .limit(Some(5), 0)
+    ///     .select([Key::Document, Key::Score, Key::field("title")]);
+    ///
+    /// let results = collection.search(vec![search]).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    ///
+    /// ## Hybrid search with custom ranking
+    ///
+    /// ```
+    /// use chroma_types::plan::SearchPayload;
+    /// use chroma_types::operator::{RankExpr, QueryVector, Key};
+    ///
+    /// # async fn example(collection: &chroma::collection::ChromaCollection) -> Result<(), Box<dyn std::error::Error>> {
+    /// // Combine two KNN searches with weights
+    /// let dense_knn = RankExpr::Knn {
+    ///     query: QueryVector::Dense(vec![0.1, 0.2, 0.3]),
+    ///     key: Key::Embedding,
+    ///     limit: 200,
+    ///     default: None,
+    ///     return_rank: false,
     /// };
-    /// let search2 = SearchPayload {
-    ///     filter: Default::default(),
-    ///     rank: Default::default(),
-    ///     limit: Default::default(),
-    ///     select: Default::default(),
+    ///
+    /// let sparse_knn = RankExpr::Knn {
+    ///     query: QueryVector::Dense(vec![0.1, 0.2, 0.3]), // Use sparse vector in practice
+    ///     key: Key::field("sparse_embedding"),
+    ///     limit: 200,
+    ///     default: None,
+    ///     return_rank: false,
     /// };
     ///
-    /// let response = collection.search(vec![search1, search2]).await?;
-    /// println!("Executed {} searches", response.ids.len());
+    /// // Weighted combination: 70% dense + 30% sparse
+    /// let hybrid_rank = dense_knn * 0.7 + sparse_knn * 0.3;
+    ///
+    /// let search = SearchPayload::default()
+    ///     .rank(hybrid_rank)
+    ///     .limit(Some(10), 0)
+    ///     .select([Key::Document, Key::Score]);
+    ///
+    /// let results = collection.search(vec![search]).await?;
     /// # Ok(())
     /// # }
     /// ```
     ///
-    /// Advanced search with all fields configured:
+    /// ## Batch operations
+    ///
     /// ```
-    /// # use chroma::collection::ChromaCollection;
-    /// # use chroma_types::plan::SearchPayload;
-    /// # use chroma_types::{Filter, Rank, RankExpr, QueryVector, Key, Limit, Select};
-    /// # use chroma_types::{Where, MetadataExpression, MetadataComparison, PrimitiveOperator, MetadataValue};
-    /// # use std::collections::HashSet;
-    /// # async fn example(collection: ChromaCollection) -> Result<(), Box<dyn std::error::Error>> {
-    /// let search = SearchPayload {
-    ///     filter: Filter {
-    ///         query_ids: Some(vec!["doc1".to_string(), "doc2".to_string()]),
-    ///         where_clause: Some(Where::Metadata(MetadataExpression {
-    ///             key: "category".to_string(),
-    ///             comparison: MetadataComparison::Primitive(
-    ///                 PrimitiveOperator::Equal,
-    ///                 MetadataValue::Str("research".to_string()),
-    ///             ),
-    ///         })),
-    ///     },
-    ///     rank: Rank {
-    ///         expr: Some(RankExpr::Knn {
-    ///             query: QueryVector::Dense(vec![0.1, 0.2, 0.3, 0.4]),
+    /// use chroma_types::plan::SearchPayload;
+    /// use chroma_types::operator::{RankExpr, QueryVector, Key};
+    ///
+    /// # async fn example(collection: &chroma::collection::ChromaCollection) -> Result<(), Box<dyn std::error::Error>> {
+    /// // Run multiple searches in one request
+    /// let searches = vec![
+    ///     SearchPayload::default()
+    ///         .r#where(Key::field("category").eq("tech"))
+    ///         .rank(RankExpr::Knn {
+    ///             query: QueryVector::Dense(vec![0.1, 0.2, 0.3]),
     ///             key: Key::Embedding,
-    ///             limit: 50,
+    ///             limit: 100,
     ///             default: None,
     ///             return_rank: false,
-    ///         }),
-    ///     },
-    ///     limit: Limit {
-    ///         offset: 0,
-    ///         limit: Some(10),
-    ///     },
-    ///     select: Select {
-    ///         keys: HashSet::from([
-    ///             Key::Document,
-    ///             Key::Metadata,
-    ///             Key::Embedding,
-    ///             Key::Score,
-    ///         ]),
-    ///     },
-    /// };
+    ///         })
+    ///         .limit(Some(5), 0),
+    ///     SearchPayload::default()
+    ///         .r#where(Key::field("category").eq("science"))
+    ///         .rank(RankExpr::Knn {
+    ///             query: QueryVector::Dense(vec![0.1, 0.2, 0.3]),
+    ///             key: Key::Embedding,
+    ///             limit: 100,
+    ///             default: None,
+    ///             return_rank: false,
+    ///         })
+    ///         .limit(Some(5), 0),
+    /// ];
     ///
-    /// let response = collection.search(vec![search]).await?;
-    /// println!("Found {} results", response.ids[0].len());
+    /// let results = collection.search(searches).await?;
+    /// // results.results[0] contains first search results
+    /// // results.results[1] contains second search results
     /// # Ok(())
     /// # }
     /// ```