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.

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)`,
     );
   });
 

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)");

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]
+    }
   });
 });

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 {

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/