[ENH] Eventual consistency in clients

chromadb/__init__.py

@@ -23,6 +23,7 @@
     Include,
     Metadata,
     Metadatas,
+    ReadLevel,
     Where,
     QueryResult,
     GetResult,

chromadb/api/__init__.py

@@ -62,6 +62,7 @@
     IncludeMetadataDocuments,
     Loadable,
     Metadatas,
+    ReadLevel,
     Schema,
     URIs,
     Where,
@@ -704,6 +705,7 @@ def _search(
         searches: List[Search],
         tenant: str = DEFAULT_TENANT,
         database: str = DEFAULT_DATABASE,
+        read_level: ReadLevel = ReadLevel.INDEX_AND_WAL,
     ) -> SearchResult:
         pass
 

chromadb/api/async_api.py

@@ -21,6 +21,7 @@
     Include,
     Loadable,
     Metadatas,
+    ReadLevel,
     Schema,
     URIs,
     Where,
@@ -655,6 +656,7 @@ async def _search(
         searches: List[Search],
         tenant: str = DEFAULT_TENANT,
         database: str = DEFAULT_DATABASE,
+        read_level: ReadLevel = ReadLevel.INDEX_AND_WAL,
     ) -> SearchResult:
         pass
 

chromadb/api/async_fastapi.py

@@ -34,6 +34,7 @@
     Include,
     Schema,
     Metadatas,
+    ReadLevel,
     URIs,
     Where,
     WhereDocument,
@@ -422,9 +423,13 @@ async def _search(
         searches: List[Search],
         tenant: str = DEFAULT_TENANT,
         database: str = DEFAULT_DATABASE,
+        read_level: ReadLevel = ReadLevel.INDEX_AND_WAL,
     ) -> SearchResult:
         """Performs hybrid search on a collection"""
-        payload = {"searches": [s.to_dict() for s in searches]}
+        payload = {
+            "searches": [s.to_dict() for s in searches],
+            "read_level": read_level,
+        }
 
         resp_json = await self._make_request(
             "post",

chromadb/api/fastapi.py

@@ -28,6 +28,7 @@
     Include,
     Schema,
     Metadatas,
+    ReadLevel,
     URIs,
     Where,
     WhereDocument,
@@ -387,10 +388,14 @@ def _search(
         searches: List[Search],
         tenant: str = DEFAULT_TENANT,
         database: str = DEFAULT_DATABASE,
+        read_level: ReadLevel = ReadLevel.INDEX_AND_WAL,
     ) -> SearchResult:
         """Performs hybrid search on a collection"""
         # Convert Search objects to dictionaries
-        payload = {"searches": [s.to_dict() for s in searches]}
+        payload = {
+            "searches": [s.to_dict() for s in searches],
+            "read_level": read_level,
+        }
 
         resp_json = self._make_request(
             "post",

chromadb/api/models/AsyncCollection.py

@@ -15,6 +15,7 @@
     QueryResult,
     ID,
     OneOrMany,
+    ReadLevel,
     WhereDocument,
     SearchResult,
     maybe_cast_one_to_many,
@@ -294,6 +295,7 @@ async def fork(
     async def search(
         self,
         searches: OneOrMany[Search],
+        read_level: ReadLevel = ReadLevel.INDEX_AND_WAL,
     ) -> SearchResult:
         """Perform hybrid search on the collection.
         This is an experimental API that only works for Hosted Chroma for now.
@@ -304,6 +306,11 @@ async def search(
                 - rank: Ranking expression for hybrid search (defaults to Val(0.0))
                 - limit: Limit configuration for pagination (defaults to no limit)
                 - select: Select configuration for keys to return (defaults to empty)
+            read_level: Controls whether to read from the write-ahead log (WAL):
+                - ReadLevel.INDEX_AND_WAL: Read from both the compacted index and WAL (default).
+                  All committed writes will be visible.
+                - ReadLevel.INDEX_ONLY: Read only from the compacted index, skipping the WAL.
+                  Faster, but recent writes that haven't been compacted may not be visible.
 
         Returns:
             SearchResult: Column-major format response with:
@@ -351,6 +358,10 @@ async def search(
                 Search().where(K("type") == "paper").rank(Knn(query=[0.3, 0.4]))
             ]
             results = await collection.search(searches)
+
+            # Skip WAL for faster queries (may miss recent uncommitted writes)
+            from chromadb.api.types import ReadLevel
+            result = await collection.search(search, read_level=ReadLevel.INDEX_ONLY)
         """
         # Convert single search to list for consistent handling
         searches_list = maybe_cast_one_to_many(searches)
@@ -367,6 +378,7 @@ async def search(
             searches=cast(List[Search], embedded_searches),
             tenant=self.tenant,
             database=self.database,
+            read_level=read_level,
         )
 
     async def update(

chromadb/api/models/Collection.py

@@ -16,6 +16,7 @@
     QueryResult,
     ID,
     OneOrMany,
+    ReadLevel,
     WhereDocument,
     SearchResult,
     maybe_cast_one_to_many,
@@ -303,6 +304,7 @@ def fork(
     def search(
         self,
         searches: OneOrMany[Search],
+        read_level: ReadLevel = ReadLevel.INDEX_AND_WAL,
     ) -> SearchResult:
         """Perform hybrid search on the collection.
         This is an experimental API that only works for Hosted Chroma for now.
@@ -313,6 +315,11 @@ def search(
                 - rank: Ranking expression for hybrid search (defaults to Val(0.0))
                 - limit: Limit configuration for pagination (defaults to no limit)
                 - select: Select configuration for keys to return (defaults to empty)
+            read_level: Controls whether to read from the write-ahead log (WAL):
+                - ReadLevel.INDEX_AND_WAL: Read from both the compacted index and WAL (default).
+                  All committed writes will be visible.
+                - ReadLevel.INDEX_ONLY: Read only from the compacted index, skipping the WAL.
+                  Faster, but recent writes that haven't been compacted may not be visible.
 
         Returns:
             SearchResult: Column-major format response with:
@@ -360,6 +367,10 @@ def search(
                 Search().where(K("type") == "paper").rank(Knn(query=[0.3, 0.4]))
             ]
             results = collection.search(searches)
+
+            # Skip WAL for faster queries (may miss recent uncommitted writes)
+            from chromadb.api.types import ReadLevel
+            result = collection.search(search, read_level=ReadLevel.INDEX_ONLY)
         """
         # Convert single search to list for consistent handling
         searches_list = maybe_cast_one_to_many(searches)
@@ -376,6 +387,7 @@ def search(
             searches=cast(List[Search], embedded_searches),
             tenant=self.tenant,
             database=self.database,
+            read_level=read_level,
         )
 
     def update(

chromadb/api/rust.py

@@ -39,6 +39,7 @@
     IncludeMetadataDocuments,
     IncludeMetadataDocumentsDistances,
     IncludeMetadataDocumentsEmbeddings,
+    ReadLevel,
     Schema,
     SearchResult,
 )
@@ -341,6 +342,7 @@ def _search(
         searches: List[Search],
         tenant: str = DEFAULT_TENANT,
         database: str = DEFAULT_DATABASE,
+        read_level: ReadLevel = ReadLevel.INDEX_AND_WAL,
     ) -> SearchResult:
         raise NotImplementedError("Search is not implemented for Local Chroma")
 

chromadb/api/segment.py

@@ -40,6 +40,7 @@
     Embeddings,
     Metadatas,
     Documents,
+    ReadLevel,
     Schema,
     URIs,
     Where,
@@ -439,6 +440,7 @@ def _search(
         searches: List[Search],
         tenant: str = DEFAULT_TENANT,
         database: str = DEFAULT_DATABASE,
+        read_level: ReadLevel = ReadLevel.INDEX_AND_WAL,
     ) -> SearchResult:
         raise NotImplementedError("Search is not implemented for SegmentAPI")
 

chromadb/api/types.py

@@ -750,6 +750,19 @@ class IndexMetadata(TypedDict):
 
 Space = Literal["cosine", "l2", "ip"]
 
+class ReadLevel(str, Enum):
+    """Controls whether search queries read from the write-ahead log (WAL).
+
+    Attributes:
+        INDEX_AND_WAL: Read from both the compacted index and the WAL (default).
+            All committed writes will be visible.
+        INDEX_ONLY: Read only from the compacted index, skipping the WAL.
+            Faster, but recent writes that haven't been compacted may not be visible.
+    """
+
+    INDEX_AND_WAL = "index_and_wal"
+    INDEX_ONLY = "index_only"
+
 
 # TODO: make warnings prettier and add link to migration docs
 @runtime_checkable

chromadb/test/api/test_search_api.py

@@ -0,0 +1,102 @@
+"""Tests for the Search API endpoint."""
+
+from typing import Tuple
+from uuid import uuid4
+
+import pytest
+
+from chromadb.api import ClientAPI
+from chromadb.api.models.Collection import Collection
+from chromadb.api.types import Embeddings, ReadLevel
+from chromadb.execution.expression import Knn, Search
+from chromadb.test.conftest import (
+    ClientFactories,
+    is_spann_disabled_mode,
+    skip_reason_spann_disabled,
+)
+
+
+def _create_test_collection(
+    client_factories: ClientFactories,
+) -> Tuple[Collection, ClientAPI]:
+    """Create a test collection with some data."""
+    client = client_factories.create_client_from_system()
+    client.reset()
+
+    collection_name = f"search_api_test_{uuid4().hex}"
+    collection = client.get_or_create_collection(name=collection_name)
+
+    return collection, client
+
+
+@pytest.mark.skipif(is_spann_disabled_mode, reason=skip_reason_spann_disabled)
+def test_search_with_read_level_index_and_wal(
+    client_factories: ClientFactories,
+) -> None:
+    """Test search with ReadLevel.INDEX_AND_WAL (default) returns results."""
+    collection, _ = _create_test_collection(client_factories)
+
+    # Add some data
+    collection.add(
+        ids=["doc1", "doc2", "doc3"],
+        documents=["apple fruit", "banana fruit", "car vehicle"],
+        embeddings=[[0.1, 0.2, 0.3, 0.4], [0.2, 0.3, 0.4, 0.5], [0.9, 0.8, 0.7, 0.6]],
+    )
+
+    # Search with explicit INDEX_AND_WAL (default behavior)
+    search = Search().rank(Knn(query=[0.1, 0.2, 0.3, 0.4], limit=10))
+    results = collection.search(search, read_level=ReadLevel.INDEX_AND_WAL)
+
+    assert results["ids"] is not None
+    assert len(results["ids"]) == 1
+    assert len(results["ids"][0]) > 0
+
+
+@pytest.mark.skipif(is_spann_disabled_mode, reason=skip_reason_spann_disabled)
+def test_search_with_read_level_index_only(
+    client_factories: ClientFactories,
+) -> None:
+    """Test search with ReadLevel.INDEX_ONLY returns results."""
+    collection, _ = _create_test_collection(client_factories)
+
+    # Add some data
+    collection.add(
+        ids=["doc1", "doc2", "doc3"],
+        documents=["apple fruit", "banana fruit", "car vehicle"],
+        embeddings=[[0.1, 0.2, 0.3, 0.4], [0.2, 0.3, 0.4, 0.5], [0.9, 0.8, 0.7, 0.6]],
+    )
+
+    # Search with INDEX_ONLY - this skips the WAL
+    # Note: Results may or may not include recent writes depending on compaction state
+    search = Search().rank(Knn(query=[0.1, 0.2, 0.3, 0.4], limit=10))
+    results = collection.search(search, read_level=ReadLevel.INDEX_ONLY)
+
+    # Just verify the API works and returns a valid response structure
+    assert results["ids"] is not None
+    assert len(results["ids"]) == 1
+    # Results may be empty if data hasn't been compacted yet, which is expected behavior
+
+
+@pytest.mark.skipif(is_spann_disabled_mode, reason=skip_reason_spann_disabled)
+def test_search_default_read_level(
+    client_factories: ClientFactories,
+) -> None:
+    """Test search without explicit read_level uses default (INDEX_AND_WAL)."""
+    collection, _ = _create_test_collection(client_factories)
+
+    # Add some data
+    collection.add(
+        ids=["doc1", "doc2"],
+        documents=["hello world", "goodbye world"],
+        embeddings=[[0.1, 0.2, 0.3, 0.4], [0.5, 0.6, 0.7, 0.8]],
+    )
+
+    # Search without specifying read_level (should use default)
+    search = Search().rank(Knn(query=[0.1, 0.2, 0.3, 0.4], limit=10))
+    results = collection.search(search)
+
+    # Should return results since default is INDEX_AND_WAL (full consistency)
+    assert results["ids"] is not None
+    assert len(results["ids"]) == 1
+    assert len(results["ids"][0]) > 0
+

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

@@ -412,6 +412,8 @@ export type RawWhereFields = {
     where_document?: unknown;
 };
 
+export type ReadLevel = 'index_and_wal' | 'index_only';
+
 /**
  * Schema representation for collection index configurations
  *
@@ -467,6 +469,11 @@ export type SearchPayload = {
 };
 
 export type SearchRequestPayload = {
+    /**
+     * Specifies the read level for consistency vs performance tradeoffs.
+     * Defaults to IndexAndWal (full consistency).
+     */
+    read_level?: ReadLevel;
     searches: Array<SearchPayload>;
 };