From a547c523c2daba9e661fd2caa6770830bb0b52bb Mon Sep 17 00:00:00 2001
From: Will Jones <willjones127@gmail.com>
Date: Fri, 28 Mar 2025 11:04:31 -0700
Subject: [PATCH] feat!: change default read_consistency_interval=5s (#2281)

Previously, when we loaded the next version of the table, we would block
all reads with a write lock. Now, we only do that if
`read_consistency_interval=0`. Otherwise, we load the next version
asynchronously in the background. This should mean that
`read_consistency_interval > 0` won't have a meaningful impact on
latency.

Along with this change, I felt it was safe to change the default
consistency interval to 5 seconds. The current default is `None`, which
means we will **never** check for a new version by default. I think that
default is contrary to most users expectations.
---
 docs/src/guides/tables.md                     |  42 ++++--
 docs/src/js/interfaces/ConnectionOptions.md   |   2 +-
 docs/src/troubleshooting.md                   |   1 +
 node/src/integration_test/test.ts             |   2 +-
 nodejs/__test__/connection.test.ts            |   2 +-
 nodejs/__test__/table.test.ts                 |   2 +-
 nodejs/examples/basic.test.ts                 |  30 +++++
 nodejs/src/connection.rs                      |  12 +-
 nodejs/src/lib.rs                             |   4 +-
 python/python/lancedb/__init__.py             |  14 +-
 python/python/lancedb/db.py                   |   9 +-
 python/python/tests/docs/test_guide_tables.py |  13 +-
 python/python/tests/test_db.py                |  11 +-
 python/python/tests/test_table.py             |   6 +-
 python/src/connection.rs                      |   4 +-
 rust/ffi/node/src/lib.rs                      |   2 +-
 rust/lancedb/src/catalog/listing.rs           |   8 +-
 rust/lancedb/src/connection.rs                |  21 +--
 rust/lancedb/src/table.rs                     |  17 +--
 rust/lancedb/src/table/dataset.rs             | 126 +++++++++++++++---
 20 files changed, 246 insertions(+), 82 deletions(-)

diff --git a/docs/src/guides/tables.md b/docs/src/guides/tables.md
index a202d2cc..5dcca406 100644
--- a/docs/src/guides/tables.md
+++ b/docs/src/guides/tables.md
@@ -1001,9 +1001,11 @@ In LanceDB OSS, users can set the `read_consistency_interval` parameter on conne
 
 There are three possible settings for `read_consistency_interval`:
 
-1. **Unset (default)**: The database does not check for updates to tables made by other processes. This provides the best query performance, but means that clients may not see the most up-to-date data. This setting is suitable for applications where the data does not change during the lifetime of the table reference.
-2. **Zero seconds (Strong consistency)**: The database checks for updates on every read. This provides the strongest consistency guarantees, ensuring that all clients see the latest committed data. However, it has the most overhead. This setting is suitable when consistency matters more than having high QPS.
-3. **Custom interval (Eventual consistency)**: The database checks for updates at a custom interval, such as every 5 seconds. This provides eventual consistency, allowing for some lag between write and read operations. Performance wise, this is a middle ground between strong consistency and no consistency check. This setting is suitable for applications where immediate consistency is not critical, but clients should see updated data eventually.
+1. **Unset**: The database does not check for updates to tables made by other processes. This setting is suitable for applications where the data does not change during the lifetime of the table reference.
+2. **Zero seconds (Strong consistency)**: The database checks for updates on every read. This provides the strongest consistency guarantees, ensuring that all clients see the latest committed data. However, it has the most overhead. This setting is suitable when consistency matters more than having high QPS. For best performance, combine this setting with the storage option `new_table_enable_v2_manifest_paths` set to `true`.
+3. **Custom interval (Eventual consistency, the default)**: The database checks for updates at a custom interval. By default, this is every 5 seconds. This provides eventual consistency, allowing for some lag between write and read operations. Performance wise, this is a middle ground between strong consistency and no consistency check. This setting is suitable for applications where immediate consistency is not critical, but clients should see updated data eventually.
+
+You can always force a synchronization by calling `checkout_latest()` / `checkoutLatest()` on a table.
 
 !!! tip "Consistency in LanceDB Cloud"
 
@@ -1041,7 +1043,21 @@ There are three possible settings for `read_consistency_interval`:
         --8<-- "python/python/tests/docs/test_guide_tables.py:table_async_eventual_consistency"
         ```
 
-    By default, a `Table` will never check for updates from other writers. To manually check for updates you can use `checkout_latest`:
+    For no consistency, use `None`:
+
+    === "Sync API"
+
+        ```python
+        --8<-- "python/python/tests/docs/test_guide_tables.py:table_no_consistency"
+        ```
+
+    === "Async API"
+
+        ```python
+        --8<-- "python/python/tests/docs/test_guide_tables.py:table_async_no_consistency"
+        ```
+
+    To manually check for updates you can use `checkout_latest`:
 
     === "Sync API"
 
@@ -1059,15 +1075,25 @@ There are three possible settings for `read_consistency_interval`:
     To set strong consistency, use `0`:
 
     ```ts
-    const db = await lancedb.connect({ uri: "./.lancedb", readConsistencyInterval: 0 });
-    const tbl = await db.openTable("my_table");
+    --8<-- "nodejs/examples/basic.test.ts:table_strong_consistency"
     ```
 
     For eventual consistency, specify the update interval as seconds:
 
     ```ts
-    const db = await lancedb.connect({ uri: "./.lancedb", readConsistencyInterval: 5 });
-    const tbl = await db.openTable("my_table");
+    --8<-- "nodejs/examples/basic.test.ts:table_eventual_consistency"
+    ```
+
+    For no consistency, use `null`:
+
+    ```ts
+    --8<-- "nodejs/examples/basic.test.ts:table_no_consistency"
+    ```
+
+    To manually check for updates you can use `checkoutLatest`:
+
+    ```ts
+    --8<-- "nodejs/examples/basic.test.ts:table_checkout_latest"
     ```
 
 <!-- Node doesn't yet support the version time travel: https://github.com/lancedb/lancedb/issues/1007
diff --git a/docs/src/js/interfaces/ConnectionOptions.md b/docs/src/js/interfaces/ConnectionOptions.md
index 4837c4c1..2a57103d 100644
--- a/docs/src/js/interfaces/ConnectionOptions.md
+++ b/docs/src/js/interfaces/ConnectionOptions.md
@@ -44,7 +44,7 @@ for testing purposes.
 ### readConsistencyInterval?
 
 ```ts
-optional readConsistencyInterval: number;
+optional readConsistencyInterval: null | number;
 ```
 
 (For LanceDB OSS only): The interval, in seconds, at which to check for
diff --git a/docs/src/troubleshooting.md b/docs/src/troubleshooting.md
index 4210c820..0b524c40 100644
--- a/docs/src/troubleshooting.md
+++ b/docs/src/troubleshooting.md
@@ -11,6 +11,7 @@ likely that someone who knows the answer will see your question.
 ## Common issues
 
 * Multiprocessing with `fork` is not supported. You should use `spawn` instead.
+* Data returned by queries may not reflect the most recent writes, depending on configuration. LanceDB uses eventual consistency by default. See [consistency](/docs/src/guides/tables.md#consistency) for more information.
 
 ## Enabling logging
 
diff --git a/node/src/integration_test/test.ts b/node/src/integration_test/test.ts
index a4098773..1be0f856 100644
--- a/node/src/integration_test/test.ts
+++ b/node/src/integration_test/test.ts
@@ -110,7 +110,7 @@ describe('LanceDB Mirrored Store Integration test', function () {
 
       fs.readdir(path.join(mirroredPath, 'data'), { withFileTypes: true }, (err, files) => {
         if (err != null) throw err
-        assert.equal(files.length, 1)
+        assert.equal(files.length, 1, `Found files: ${files.map(f => f.name)}`)
         assert.isTrue(files[0].name.endsWith('.lance'))
       })
 
diff --git a/nodejs/__test__/connection.test.ts b/nodejs/__test__/connection.test.ts
index 7fcdb85a..40085229 100644
--- a/nodejs/__test__/connection.test.ts
+++ b/nodejs/__test__/connection.test.ts
@@ -17,7 +17,7 @@ describe("when connecting", () => {
   it("should connect", async () => {
     const db = await connect(tmpDir.name);
     expect(db.display()).toBe(
-      `ListingDatabase(uri=${tmpDir.name}, read_consistency_interval=None)`,
+      `ListingDatabase(uri=${tmpDir.name}, read_consistency_interval=5s)`,
     );
   });
 
diff --git a/nodejs/__test__/table.test.ts b/nodejs/__test__/table.test.ts
index 034042e5..082805b8 100644
--- a/nodejs/__test__/table.test.ts
+++ b/nodejs/__test__/table.test.ts
@@ -58,7 +58,7 @@ describe.each([arrow15, arrow16, arrow17, arrow18])(
 
     it("be displayable", async () => {
       expect(table.display()).toMatch(
-        /NativeTable\(some_table, uri=.*, read_consistency_interval=None\)/,
+        /NativeTable\(some_table, uri=.*, read_consistency_interval=5s\)/,
       );
       table.close();
       expect(table.display()).toBe("ClosedTable(some_table)");
diff --git a/nodejs/examples/basic.test.ts b/nodejs/examples/basic.test.ts
index b56bb2f9..16ce99a1 100644
--- a/nodejs/examples/basic.test.ts
+++ b/nodejs/examples/basic.test.ts
@@ -202,5 +202,35 @@ test("basic table examples", async () => {
       // --8<-- [end:create_f16_table]
       await db.dropTable("f16_tbl");
     }
+    const uri = databaseDir;
+    await db.createTable("my_table", [{ id: 1 }, { id: 2 }]);
+    {
+      // --8<-- [start:table_strong_consistency]
+      const db = await lancedb.connect({ uri, readConsistencyInterval: 0 });
+      const tbl = await db.openTable("my_table");
+      // --8<-- [end:table_strong_consistency]
+    }
+    {
+      // --8<-- [start:table_eventual_consistency]
+      const db = await lancedb.connect({ uri, readConsistencyInterval: 5 });
+      const tbl = await db.openTable("my_table");
+      // --8<-- [end:table_eventual_consistency]
+    }
+    {
+      // --8<-- [start:table_no_consistency]
+      const db = await lancedb.connect({ uri, readConsistencyInterval: null });
+      const tbl = await db.openTable("my_table");
+      // --8<-- [end:table_no_consistency]
+    }
+    {
+      // --8<-- [start:table_checkout_latest]
+      const tbl = await db.openTable("my_table");
+
+      // (Other writes happen to test_table_async from another process)
+
+      // Check for updates
+      tbl.checkoutLatest();
+      // --8<-- [end:table_checkout_latest]
+    }
   });
 });
diff --git a/nodejs/src/connection.rs b/nodejs/src/connection.rs
index 49bbf004..6c1ecba7 100644
--- a/nodejs/src/connection.rs
+++ b/nodejs/src/connection.rs
@@ -48,8 +48,16 @@ impl Connection {
     pub async fn new(uri: String, options: ConnectionOptions) -> napi::Result<Self> {
         let mut builder = ConnectBuilder::new(&uri);
         if let Some(interval) = options.read_consistency_interval {
-            builder =
-                builder.read_consistency_interval(std::time::Duration::from_secs_f64(interval));
+            match interval {
+                Either::A(seconds) => {
+                    builder = builder.read_consistency_interval(Some(
+                        std::time::Duration::from_secs_f64(seconds),
+                    ));
+                }
+                Either::B(_) => {
+                    builder = builder.read_consistency_interval(None);
+                }
+            }
         }
         if let Some(storage_options) = options.storage_options {
             for (key, value) in storage_options {
diff --git a/nodejs/src/lib.rs b/nodejs/src/lib.rs
index 7674e370..d0e94244 100644
--- a/nodejs/src/lib.rs
+++ b/nodejs/src/lib.rs
@@ -4,6 +4,7 @@
 use std::collections::HashMap;
 
 use env_logger::Env;
+use napi::{bindgen_prelude::Null, Either};
 use napi_derive::*;
 
 mod connection;
@@ -18,7 +19,6 @@ mod table;
 mod util;
 
 #[napi(object)]
-#[derive(Debug)]
 pub struct ConnectionOptions {
     /// (For LanceDB OSS only): The interval, in seconds, at which to check for
     /// updates to the table from other processes. If None, then consistency is not
@@ -29,7 +29,7 @@ pub struct ConnectionOptions {
     /// has passed since the last check, then the table will be checked for updates.
     /// Note: this consistency only applies to read operations. Write operations are
     /// always consistent.
-    pub read_consistency_interval: Option<f64>,
+    pub read_consistency_interval: Option<Either<f64, Null>>,
     /// (For LanceDB OSS only): configuration for object storage.
     ///
     /// The available options are described at https://lancedb.github.io/lancedb/guides/storage/
diff --git a/python/python/lancedb/__init__.py b/python/python/lancedb/__init__.py
index 03f4f513..a67acd57 100644
--- a/python/python/lancedb/__init__.py
+++ b/python/python/lancedb/__init__.py
@@ -26,7 +26,7 @@ def connect(
     api_key: Optional[str] = None,
     region: str = "us-east-1",
     host_override: Optional[str] = None,
-    read_consistency_interval: Optional[timedelta] = None,
+    read_consistency_interval: Optional[timedelta] = timedelta(seconds=5),
     request_thread_pool: Optional[Union[int, ThreadPoolExecutor]] = None,
     client_config: Union[ClientConfig, Dict[str, Any], None] = None,
     storage_options: Optional[Dict[str, str]] = None,
@@ -49,9 +49,8 @@ def connect(
     read_consistency_interval: timedelta, default None
         (For LanceDB OSS only)
         The interval at which to check for updates to the table from other
-        processes. If None, then consistency is not checked. For performance
-        reasons, this is the default. For strong consistency, set this to
-        zero seconds. Then every read will check for updates from other
+        processes. If None, then consistency is not checked. For strong consistency,
+        set this to zero seconds. Then every read will check for updates from other
         processes. As a compromise, you can set this to a non-zero timedelta
         for eventual consistency. If more than that interval has passed since
         the last check, then the table will be checked for updates. Note: this
@@ -122,7 +121,7 @@ async def connect_async(
     api_key: Optional[str] = None,
     region: str = "us-east-1",
     host_override: Optional[str] = None,
-    read_consistency_interval: Optional[timedelta] = None,
+    read_consistency_interval: Optional[timedelta] = timedelta(seconds=5),
     client_config: Optional[Union[ClientConfig, Dict[str, Any]]] = None,
     storage_options: Optional[Dict[str, str]] = None,
 ) -> AsyncConnection:
@@ -143,9 +142,8 @@ async def connect_async(
     read_consistency_interval: timedelta, default None
         (For LanceDB OSS only)
         The interval at which to check for updates to the table from other
-        processes. If None, then consistency is not checked. For performance
-        reasons, this is the default. For strong consistency, set this to
-        zero seconds. Then every read will check for updates from other
+        processes. If None, then consistency is not checked. For strong consistency,
+        set this to zero seconds. Then every read will check for updates from other
         processes. As a compromise, you can set this to a non-zero timedelta
         for eventual consistency. If more than that interval has passed since
         the last check, then the table will be checked for updates. Note: this
diff --git a/python/python/lancedb/db.py b/python/python/lancedb/db.py
index d4f30b83..439186ad 100644
--- a/python/python/lancedb/db.py
+++ b/python/python/lancedb/db.py
@@ -6,6 +6,7 @@ from __future__ import annotations
 
 from abc import abstractmethod
 from pathlib import Path
+from datetime import timedelta
 from typing import TYPE_CHECKING, Dict, Iterable, List, Literal, Optional, Union
 
 from lancedb.embeddings.registry import EmbeddingFunctionRegistry
@@ -32,7 +33,6 @@ import deprecation
 if TYPE_CHECKING:
     import pyarrow as pa
     from .pydantic import LanceModel
-    from datetime import timedelta
 
     from ._lancedb import Connection as LanceDbConnection
     from .common import DATA, URI
@@ -318,9 +318,8 @@ class LanceDBConnection(DBConnection):
         The root uri of the database.
     read_consistency_interval: timedelta, default None
         The interval at which to check for updates to the table from other
-        processes. If None, then consistency is not checked. For performance
-        reasons, this is the default. For strong consistency, set this to
-        zero seconds. Then every read will check for updates from other
+        processes. If None, then consistency is not checked. For strong consistency,
+        set this to zero seconds. Then every read will check for updates from other
         processes. As a compromise, you can set this to a non-zero timedelta
         for eventual consistency. If more than that interval has passed since
         the last check, then the table will be checked for updates. Note: this
@@ -352,7 +351,7 @@ class LanceDBConnection(DBConnection):
         self,
         uri: URI,
         *,
-        read_consistency_interval: Optional[timedelta] = None,
+        read_consistency_interval: Optional[timedelta] = timedelta(seconds=5),
         storage_options: Optional[Dict[str, str]] = None,
     ):
         if not isinstance(uri, Path):
diff --git a/python/python/tests/docs/test_guide_tables.py b/python/python/tests/docs/test_guide_tables.py
index d174c5b9..0dc47090 100644
--- a/python/python/tests/docs/test_guide_tables.py
+++ b/python/python/tests/docs/test_guide_tables.py
@@ -315,6 +315,11 @@ def test_table():
     db = lancedb.connect(uri, read_consistency_interval=timedelta(seconds=5))
     tbl = db.open_table("test_table")
     # --8<-- [end:table_eventual_consistency]
+    # --8<-- [start:table_no_consistency]
+    uri = "data/sample-lancedb"
+    db = lancedb.connect(uri, read_consistency_interval=None)
+    tbl = db.open_table("test_table")
+    # --8<-- [end:table_no_consistency]
     # --8<-- [start:table_checkout_latest]
     tbl = db.open_table("test_table")
 
@@ -562,13 +567,19 @@ async def test_table_async():
     async_db = await lancedb.connect_async(uri, read_consistency_interval=timedelta(0))
     async_tbl = await async_db.open_table("test_table_async")
     # --8<-- [end:table_async_strong_consistency]
-    # --8<-- [start:table_async_ventual_consistency]
+    # --8<-- [start:table_async_eventual_consistency]
     uri = "data/sample-lancedb"
     async_db = await lancedb.connect_async(
         uri, read_consistency_interval=timedelta(seconds=5)
     )
     async_tbl = await async_db.open_table("test_table_async")
     # --8<-- [end:table_async_eventual_consistency]
+    # --8<-- [start:table_async_no_consistency]
+    uri = "data/sample-lancedb"
+    async_db = await lancedb.connect_async(uri, read_consistency_interval=None)
+    async_tbl = await async_db.open_table("test_table_async")
+    # --8<-- [end:table_async_no_consistency]
+
     # --8<-- [start:table_async_checkout_latest]
     async_tbl = await async_db.open_table("test_table_async")
 
diff --git a/python/python/tests/test_db.py b/python/python/tests/test_db.py
index 88bb33e8..9da1c6e0 100644
--- a/python/python/tests/test_db.py
+++ b/python/python/tests/test_db.py
@@ -3,7 +3,6 @@
 
 
 import re
-from datetime import timedelta
 import os
 
 import lancedb
@@ -299,13 +298,11 @@ def test_create_exist_ok(tmp_db: lancedb.DBConnection):
 @pytest.mark.asyncio
 async def test_connect(tmp_path):
     db = await lancedb.connect_async(tmp_path)
-    assert str(db) == f"ListingDatabase(uri={tmp_path}, read_consistency_interval=None)"
-
-    db = await lancedb.connect_async(
-        tmp_path, read_consistency_interval=timedelta(seconds=5)
-    )
     assert str(db) == f"ListingDatabase(uri={tmp_path}, read_consistency_interval=5s)"
 
+    db = await lancedb.connect_async(tmp_path, read_consistency_interval=None)
+    assert str(db) == f"ListingDatabase(uri={tmp_path}, read_consistency_interval=None)"
+
 
 @pytest.mark.asyncio
 async def test_close(mem_db_async: lancedb.AsyncConnection):
@@ -453,7 +450,7 @@ async def test_open_table(tmp_path):
     assert tbl.name == "test"
     assert (
         re.search(
-            r"NativeTable\(test, uri=.*test\.lance, read_consistency_interval=None\)",
+            r"NativeTable\(test, uri=.*test\.lance, read_consistency_interval=5s\)",
             str(tbl),
         )
         is not None
diff --git a/python/python/tests/test_table.py b/python/python/tests/test_table.py
index 2bb18989..74f6f4eb 100644
--- a/python/python/tests/test_table.py
+++ b/python/python/tests/test_table.py
@@ -32,7 +32,11 @@ def test_basic(mem_db: DBConnection):
     table = mem_db.create_table("test", data=data)
 
     assert table.name == "test"
-    assert "LanceTable(name='test', version=1, _conn=LanceDBConnection(" in repr(table)
+    assert (
+        "LanceTable(name='test', version=1, "
+        "read_consistency_interval=datetime.timedelta(seconds=5), "
+        "_conn=LanceDBConnection("
+    ) in repr(table)
     expected_schema = pa.schema(
         {
             "vector": pa.list_(pa.float32(), 2),
diff --git a/python/src/connection.rs b/python/src/connection.rs
index 975a756c..ba4930ec 100644
--- a/python/src/connection.rs
+++ b/python/src/connection.rs
@@ -204,7 +204,9 @@ pub fn connect(
         }
         if let Some(read_consistency_interval) = read_consistency_interval {
             let read_consistency_interval = Duration::from_secs_f64(read_consistency_interval);
-            builder = builder.read_consistency_interval(read_consistency_interval);
+            builder = builder.read_consistency_interval(Some(read_consistency_interval));
+        } else {
+            builder = builder.read_consistency_interval(None);
         }
         if let Some(storage_options) = storage_options {
             builder = builder.storage_options(storage_options);
diff --git a/rust/ffi/node/src/lib.rs b/rust/ffi/node/src/lib.rs
index 229a4cea..f04f1a82 100644
--- a/rust/ffi/node/src/lib.rs
+++ b/rust/ffi/node/src/lib.rs
@@ -60,7 +60,7 @@ fn database_new(mut cx: FunctionContext) -> JsResult<JsPromise> {
     let mut conn_builder = connect(&path).storage_options(storage_options);
 
     if let Some(interval) = read_consistency_interval {
-        conn_builder = conn_builder.read_consistency_interval(interval);
+        conn_builder = conn_builder.read_consistency_interval(Some(interval));
     }
     rt.spawn(async move {
         let database = conn_builder.execute().await;
diff --git a/rust/lancedb/src/catalog/listing.rs b/rust/lancedb/src/catalog/listing.rs
index 06cf63d1..2d8faa7b 100644
--- a/rust/lancedb/src/catalog/listing.rs
+++ b/rust/lancedb/src/catalog/listing.rs
@@ -12,7 +12,7 @@ use super::{
     Catalog, CatalogOptions, CreateDatabaseMode, CreateDatabaseRequest, DatabaseNamesRequest,
     OpenDatabaseRequest,
 };
-use crate::connection::ConnectRequest;
+use crate::connection::{ConnectRequest, DEFAULT_READ_CONSISTENCY_INTERVAL};
 use crate::database::listing::{ListingDatabase, ListingDatabaseOptions};
 use crate::database::{Database, DatabaseOptions};
 use crate::error::{CreateDirSnafu, Error, Result};
@@ -214,7 +214,7 @@ impl Catalog for ListingCatalog {
             uri: db_uri,
             #[cfg(feature = "remote")]
             client_config: Default::default(),
-            read_consistency_interval: None,
+            read_consistency_interval: DEFAULT_READ_CONSISTENCY_INTERVAL,
             options: Default::default(),
         };
 
@@ -241,7 +241,7 @@ impl Catalog for ListingCatalog {
             uri: db_path.to_string(),
             #[cfg(feature = "remote")]
             client_config: Default::default(),
-            read_consistency_interval: None,
+            read_consistency_interval: DEFAULT_READ_CONSISTENCY_INTERVAL,
             options: Default::default(),
         };
 
@@ -311,7 +311,7 @@ mod tests {
             #[cfg(feature = "remote")]
             client_config: Default::default(),
             options: Default::default(),
-            read_consistency_interval: None,
+            read_consistency_interval: DEFAULT_READ_CONSISTENCY_INTERVAL,
         };
 
         let catalog = ListingCatalog::connect(&request).await.unwrap();
diff --git a/rust/lancedb/src/connection.rs b/rust/lancedb/src/connection.rs
index 4668ae9f..cf0e6899 100644
--- a/rust/lancedb/src/connection.rs
+++ b/rust/lancedb/src/connection.rs
@@ -36,6 +36,9 @@ pub use lance_encoding::version::LanceFileVersion;
 #[cfg(feature = "remote")]
 use lance_io::object_store::StorageOptions;
 
+pub(crate) const DEFAULT_READ_CONSISTENCY_INTERVAL: Option<std::time::Duration> =
+    Some(std::time::Duration::from_secs(5));
+
 /// A builder for configuring a [`Connection::table_names`] operation
 pub struct TableNamesBuilder {
     parent: Arc<dyn Database>,
@@ -618,14 +621,15 @@ pub struct ConnectRequest {
 
     /// The interval at which to check for updates from other processes.
     ///
-    /// If None, then consistency is not checked. For performance
-    /// reasons, this is the default. For strong consistency, set this to
+    /// If None, then consistency is not checked. For strong consistency, set this to
     /// zero seconds. Then every read will check for updates from other
     /// processes. As a compromise, you can set this to a non-zero timedelta
     /// for eventual consistency. If more than that interval has passed since
     /// the last check, then the table will be checked for updates. Note: this
     /// consistency only applies to read operations. Write operations are
     /// always consistent.
+    ///
+    /// The default is 5 seconds.
     pub read_consistency_interval: Option<std::time::Duration>,
 }
 
@@ -643,7 +647,7 @@ impl ConnectBuilder {
                 uri: uri.to_string(),
                 #[cfg(feature = "remote")]
                 client_config: Default::default(),
-                read_consistency_interval: None,
+                read_consistency_interval: DEFAULT_READ_CONSISTENCY_INTERVAL,
                 options: HashMap::new(),
             },
             embedding_registry: None,
@@ -782,8 +786,7 @@ impl ConnectBuilder {
     /// The interval at which to check for updates from other processes. This
     /// only affects LanceDB OSS.
     ///
-    /// If left unset, consistency is not checked. For maximum read
-    /// performance, this is the default. For strong consistency, set this to
+    /// If left unset, consistency is not checked. For strong consistency, set this to
     /// zero seconds. Then every read will check for updates from other processes.
     /// As a compromise, set this to a non-zero duration for eventual consistency.
     /// If more than that duration has passed since the last read, the read will
@@ -792,13 +795,15 @@ impl ConnectBuilder {
     /// This only affects read operations. Write operations are always
     /// consistent.
     ///
+    /// The default is 5 seconds.
+    ///
     /// LanceDB Cloud uses eventual consistency under the hood, and is not
     /// currently configurable.
     pub fn read_consistency_interval(
         mut self,
-        read_consistency_interval: std::time::Duration,
+        read_consistency_interval: Option<std::time::Duration>,
     ) -> Self {
-        self.request.read_consistency_interval = Some(read_consistency_interval);
+        self.request.read_consistency_interval = read_consistency_interval;
         self
     }
 
@@ -882,7 +887,7 @@ impl CatalogConnectBuilder {
                 uri: uri.to_string(),
                 #[cfg(feature = "remote")]
                 client_config: Default::default(),
-                read_consistency_interval: None,
+                read_consistency_interval: DEFAULT_READ_CONSISTENCY_INTERVAL,
                 options: HashMap::new(),
             },
         }
diff --git a/rust/lancedb/src/table.rs b/rust/lancedb/src/table.rs
index c1fb5415..36c940ed 100644
--- a/rust/lancedb/src/table.rs
+++ b/rust/lancedb/src/table.rs
@@ -2611,7 +2611,7 @@ mod tests {
         let dataset_path = tmp_dir.path().join("test.lance");
         let uri = dataset_path.to_str().unwrap();
         let conn = connect(uri)
-            .read_consistency_interval(Duration::from_secs(0))
+            .read_consistency_interval(Some(Duration::from_secs(0)))
             .execute()
             .await
             .unwrap();
@@ -2694,7 +2694,7 @@ mod tests {
         let dataset_path = tmp_dir.path().join("test.lance");
         let uri = dataset_path.to_str().unwrap();
         let conn = connect(uri)
-            .read_consistency_interval(Duration::from_secs(0))
+            .read_consistency_interval(Some(Duration::from_secs(0)))
             .execute()
             .await
             .unwrap();
@@ -2891,7 +2891,7 @@ mod tests {
         let dataset_path = tmp_dir.path().join("test.lance");
         let uri = dataset_path.to_str().unwrap();
         let conn = connect(uri)
-            .read_consistency_interval(Duration::from_secs(0))
+            .read_consistency_interval(Some(Duration::from_secs(0)))
             .execute()
             .await
             .unwrap();
@@ -3462,7 +3462,8 @@ mod tests {
 
             let mut conn2 = ConnectBuilder::new(uri);
             if let Some(interval) = interval {
-                conn2 = conn2.read_consistency_interval(std::time::Duration::from_millis(interval));
+                conn2 = conn2
+                    .read_consistency_interval(Some(std::time::Duration::from_millis(interval)));
             }
             let conn2 = conn2.execute().await.unwrap();
             let table2 = conn2.open_table("my_table").execute().await.unwrap();
@@ -3498,7 +3499,7 @@ mod tests {
         let uri = tmp_dir.path().to_str().unwrap();
 
         let conn = ConnectBuilder::new(uri)
-            .read_consistency_interval(Duration::from_secs(0))
+            .read_consistency_interval(Some(Duration::from_secs(0)))
             .execute()
             .await
             .unwrap();
@@ -3519,7 +3520,7 @@ mod tests {
         let uri = tmp_dir.path().to_str().unwrap();
 
         let conn = ConnectBuilder::new(uri)
-            .read_consistency_interval(Duration::from_secs(0))
+            .read_consistency_interval(Some(Duration::from_secs(0)))
             .execute()
             .await
             .unwrap();
@@ -3594,7 +3595,7 @@ mod tests {
         let uri = tmp_dir.path().to_str().unwrap();
 
         let conn = ConnectBuilder::new(uri)
-            .read_consistency_interval(Duration::from_secs(0))
+            .read_consistency_interval(Some(Duration::from_secs(0)))
             .execute()
             .await
             .unwrap();
@@ -3656,7 +3657,7 @@ mod tests {
         let uri = tmp_dir.path().to_str().unwrap();
 
         let conn = ConnectBuilder::new(uri)
-            .read_consistency_interval(Duration::from_secs(0))
+            .read_consistency_interval(Some(Duration::from_secs(0)))
             .execute()
             .await
             .unwrap();
diff --git a/rust/lancedb/src/table/dataset.rs b/rust/lancedb/src/table/dataset.rs
index ffb5336d..fa797ef3 100644
--- a/rust/lancedb/src/table/dataset.rs
+++ b/rust/lancedb/src/table/dataset.rs
@@ -7,6 +7,7 @@ use std::{
     time::{self, Duration, Instant},
 };
 
+use futures::FutureExt;
 use lance::Dataset;
 use tokio::sync::{RwLock, RwLockReadGuard, RwLockWriteGuard};
 
@@ -22,13 +23,16 @@ pub struct DatasetConsistencyWrapper(Arc<RwLock<DatasetRef>>);
 ///
 /// The dataset is lazily loaded, and starts off as None. On the first access,
 /// the dataset is loaded.
-#[derive(Debug, Clone)]
+#[derive(Debug)]
 enum DatasetRef {
     /// In this mode, the dataset is always the latest version.
     Latest {
         dataset: Dataset,
         read_consistency_interval: Option<Duration>,
         last_consistency_check: Option<time::Instant>,
+        /// A background task loading the next version of the dataset. This happens
+        /// in the background so as not to block the current thread.
+        refresh_task: Option<tokio::task::JoinHandle<Result<Dataset>>>,
     },
     /// In this mode, the dataset is a specific version. It cannot be mutated.
     TimeTravel { dataset: Dataset, version: u64 },
@@ -41,9 +45,19 @@ impl DatasetRef {
             Self::Latest {
                 dataset,
                 last_consistency_check,
+                refresh_task,
                 ..
             } => {
                 dataset.checkout_latest().await?;
+                // Replace the refresh task
+                if let Some(refresh_task) = refresh_task {
+                    refresh_task.abort();
+                }
+                let mut new_dataset = dataset.clone();
+                refresh_task.replace(tokio::spawn(async move {
+                    new_dataset.checkout_latest().await?;
+                    Ok(new_dataset)
+                }));
                 last_consistency_check.replace(Instant::now());
             }
             Self::TimeTravel { dataset, version } => {
@@ -57,26 +71,24 @@ impl DatasetRef {
         matches!(self, Self::Latest { .. })
     }
 
-    async fn need_reload(&self) -> Result<bool> {
-        Ok(match self {
-            Self::Latest { dataset, .. } => {
-                dataset.latest_version_id().await? != dataset.version().version
-            }
-            Self::TimeTravel { dataset, version } => dataset.version().version != *version,
-        })
+    fn strong_consistency(&self) -> bool {
+        matches!(
+            self,
+            Self::Latest { read_consistency_interval: Some(interval), .. }
+            if interval.as_nanos() == 0
+        )
     }
 
     async fn as_latest(&mut self, read_consistency_interval: Option<Duration>) -> Result<()> {
         match self {
             Self::Latest { .. } => Ok(()),
             Self::TimeTravel { dataset, .. } => {
-                dataset
-                    .checkout_version(dataset.latest_version_id().await?)
-                    .await?;
+                dataset.checkout_latest().await?;
                 *self = Self::Latest {
                     dataset: dataset.clone(),
                     read_consistency_interval,
                     last_consistency_check: Some(Instant::now()),
+                    refresh_task: None,
                 };
                 Ok(())
             }
@@ -114,13 +126,74 @@ impl DatasetRef {
         match self {
             Self::Latest {
                 dataset: ref mut ds,
+                refresh_task,
+                last_consistency_check,
                 ..
             } => {
                 *ds = dataset;
+                if let Some(refresh_task) = refresh_task {
+                    refresh_task.abort();
+                }
+                *refresh_task = None;
+                *last_consistency_check = Some(Instant::now());
             }
             _ => unreachable!("Dataset should be in latest mode at this point"),
         }
     }
+
+    /// Wait for the background refresh task to complete.
+    async fn await_refresh(&mut self) -> Result<()> {
+        if let Self::Latest {
+            refresh_task: Some(refresh_task),
+            read_consistency_interval,
+            ..
+        } = self
+        {
+            let dataset = refresh_task.await.expect("Refresh task panicked")?;
+            *self = Self::Latest {
+                dataset,
+                read_consistency_interval: *read_consistency_interval,
+                last_consistency_check: Some(Instant::now()),
+                refresh_task: None,
+            };
+        }
+        Ok(())
+    }
+
+    /// Check if background refresh task is done, and if so, update the dataset.
+    fn check_refresh(&mut self) -> Result<()> {
+        if let Self::Latest {
+            refresh_task: Some(refresh_task),
+            read_consistency_interval,
+            ..
+        } = self
+        {
+            if refresh_task.is_finished() {
+                let dataset = refresh_task
+                    .now_or_never()
+                    .unwrap()
+                    .expect("Refresh task panicked")?;
+                *self = Self::Latest {
+                    dataset,
+                    read_consistency_interval: *read_consistency_interval,
+                    last_consistency_check: Some(Instant::now()),
+                    refresh_task: None,
+                };
+            }
+        }
+        Ok(())
+    }
+
+    fn refresh_is_ready(&self) -> bool {
+        matches!(
+            self,
+            Self::Latest {
+                refresh_task: Some(refresh_task),
+                ..
+            }
+            if refresh_task.is_finished()
+        )
+    }
 }
 
 impl DatasetConsistencyWrapper {
@@ -130,6 +203,7 @@ impl DatasetConsistencyWrapper {
             dataset,
             read_consistency_interval,
             last_consistency_check: Some(Instant::now()),
+            refresh_task: None,
         })))
     }
 
@@ -188,18 +262,9 @@ impl DatasetConsistencyWrapper {
     }
 
     pub async fn reload(&self) -> Result<()> {
-        if !self.0.read().await.need_reload().await? {
-            return Ok(());
-        }
-
         let mut write_guard = self.0.write().await;
-        // on lock escalation -- check if someone else has already reloaded
-        if !write_guard.need_reload().await? {
-            return Ok(());
-        }
-
-        // actually need reloading
-        write_guard.reload().await
+        write_guard.reload().await?;
+        write_guard.await_refresh().await
     }
 
     /// Returns the version, if in time travel mode, or None otherwise
@@ -245,9 +310,26 @@ impl DatasetConsistencyWrapper {
     /// Ensures that the dataset is loaded and up-to-date with consistency and
     /// version parameters.
     async fn ensure_up_to_date(&self) -> Result<()> {
+        // We may have previously created a background task to fetch the new
+        // version of the dataset. If that task is done, we should update the
+        // dataset.
+        {
+            let read_guard = self.0.read().await;
+            if read_guard.refresh_is_ready() {
+                drop(read_guard);
+                self.0.write().await.check_refresh()?;
+            }
+        }
+
         if !self.is_up_to_date().await? {
             self.reload().await?;
         }
+
+        // If we are in strong consistency mode, we should await the refresh task.
+        if self.0.read().await.strong_consistency() {
+            self.0.write().await.await_refresh().await?;
+        }
+
         Ok(())
     }
 }