mirror of https://github.com/lancedb/lancedb.git synced 2026-06-01 19:30:45 +00:00

Files

Brendan Clement 15e75804c4 feat(remote): send read freshness headers for remote table consistency (#3439 )

Closes client side work of #3370 

### Summary
- Plumbs `read_consistency_interval` from `ConnectBuilder` through
`RestfulLanceDbClient` so remote reads attach an
`x-lancedb-min-timestamp` freshness header. None = no header (default),
zero = "now", positive = `now - interval`.
- Adds per-table `FreshnessState` on `RemoteTable`: write responses
(`update`, `delete`, `merge_insert`, `add_columns`, `alter_columns`,
`drop_columns`) track the committed version, and the next read sends
`x-lancedb-min-version` so the server's cache honors read-your-write.
- `checkout(v)` / `checkout_tag(t)` / `checkout_latest()` / `restore()`
reset the freshness state appropriately; the validating `/describe/` and
tag-resolve requests are sent without freshness headers so they don't
carry stale state.
- Updates Rust, Python, and Node docstrings and calls out that stronger
consistency raises per-read latency and cost.

### Testing
- Unit tests cover default behavior, interval=0, positive interval,
checkout_latest baseline, min_version-after-write, checkout clears
state, and the two no-stale-header invariants on `checkout(v)` and
`checkout_tag(t)`.
- Ran smoke tests against local remote table to verify functionality

2026-05-26 13:38:07 -07:00

2.4 KiB

Raw Blame History

@lancedb/lancedb • Docs

@lancedb/lancedb / ConnectionOptions

Interface: ConnectionOptions

Properties

apiKey?

optional apiKey: string;

(For LanceDB cloud only): the API key to use with LanceDB Cloud.

Can also be set via the environment variable LANCEDB_API_KEY.

clientConfig?

optional clientConfig: ClientConfig;

(For LanceDB cloud only): configuration for the remote HTTP client.

hostOverride?

optional hostOverride: string;

(For LanceDB cloud only): the host to use for LanceDB cloud. Used for testing purposes.

manifestEnabled?

optional manifestEnabled: boolean;

(For LanceDB OSS only): use directory namespace manifests as the source of truth for table metadata. Existing directory-listed root tables are migrated into the manifest on access.

namespaceClientProperties?

optional namespaceClientProperties: Record<string, string>;

(For LanceDB OSS only): extra properties for the backing namespace client used by manifest-enabled native connections.

readConsistencyInterval?

optional readConsistencyInterval: number;

The interval, in seconds, 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. As a compromise, you can set this to a non-zero value 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.

Stronger consistency is not free. The smaller the interval, the more often each read pays the cost of checking for updates against object storage, raising per-read latency and cost.

region?

optional region: string;

(For LanceDB cloud only): the region to use for LanceDB cloud. Defaults to 'us-east-1'.

session?

optional session: Session;

(For LanceDB OSS only): the session to use for this connection. Holds shared caches and other session-specific state.

storageOptions?

optional storageOptions: Record<string, string>;

(For LanceDB OSS only): configuration for object storage.

The available options are described at https://docs.lancedb.com/storage/

2.4 KiB Raw Blame History