Opt-in retention of table handles and supervised background index warming.
Add {LanceDB.TableCache, name: MyApp.Cache, uri: uri, ...} to your supervision
tree. Each instance owns one connection/session with immutable storage,
consistency and cache settings. Storage runs in supervised tasks, never in
the coordinator. Separate instances keep incompatible settings independent.
Options:
:uri(required),:storage_options(default%{}), and optional:name.:index_cache_size_bytes,:metadata_cache_size_bytes, and:read_consistency_interval_msfollowLanceDB.Connection.connect/3.:connect_timeout_msand:open_timeout_msdefault to 5_000; nil disables that native deadline. There is no native prewarming deadline.:max_tables(default 64) bounds entries, including pending opens. Least recently fetched/prewarmed entries are evicted first. Pending fetch callers protect their entries from eviction until they finish or time out.:idle_timeout_ms(default 3_600_000, nil disables expiry) measures time since fetch/prewarm requests. Queries on returned handles are not observed.:max_opens(default 4),:max_warmers(default 2) bound concurrent work. One warmer processes a table's requested indexes sequentially.:max_requests(default 256) bounds waiting fetch callers plus remembered index warming records across the instance, including completed/failed ones. Invalidation and eviction discard these records. Saturation returns:busy.
Limits and idle intervals are positive uint32 integers. Native memory is controlled separately by session cache budgets. Eviction releases this component's handle; it cannot revoke caller-held handles or flush a shared session. Warming records describe completed work, not guaranteed residency.
The application owns table names, schemas, credentials, index selection and when to warm. Direct connection/table APIs remain available. Each node owns its own cache. Cached handles are live main-branch tables; use the direct API for custom locations, branches and historical checkouts.
Summary
Functions
Returns the retained handle, sharing concurrent opens for the same name.
:timeout_ms defaults to 15_000; nil waits indefinitely. It covers queueing,
connection and open waits for this caller. Timeout/caller death removes the
waiter but does not cancel an open shared with the cache or other callers.
Failed opens are retryable. Native admission saturation returns :busy.
Discards an entry and its warming records, returning :ok even if absent. Pending fetches receive :cancelled. Later results cannot recreate the entry. Existing caller-held handles remain usable; explicitly invalidate after dropping/recreating a table. Running work stays counted until it settles.
Schedules opening and warming, returning {:ok, :scheduled} promptly.
Requires indexes: [name, ...] with distinct string/atom names. Concurrent
requests share work. Completed work is skipped only after rechecking table
version and index UUID. Warming uses a snapshot sharing the fetched session;
a table change detected during warming fails the attempt for retry.
Starts a cache and its linked task supervisor without opening storage until needed.
Returns string-keyed index names mapped to Warming structs; unretained tables return :not_found.
Functions
@spec fetch(GenServer.server(), String.t(), keyword()) :: LanceDB.result(LanceDB.Table.t())
Returns the retained handle, sharing concurrent opens for the same name.
:timeout_ms defaults to 15_000; nil waits indefinitely. It covers queueing,
connection and open waits for this caller. Timeout/caller death removes the
waiter but does not cancel an open shared with the cache or other callers.
Failed opens are retryable. Native admission saturation returns :busy.
@spec invalidate(GenServer.server(), String.t()) :: :ok
Discards an entry and its warming records, returning :ok even if absent. Pending fetches receive :cancelled. Later results cannot recreate the entry. Existing caller-held handles remain usable; explicitly invalidate after dropping/recreating a table. Running work stays counted until it settles.
@spec prewarm(GenServer.server(), String.t(), keyword()) :: LanceDB.result(:scheduled)
Schedules opening and warming, returning {:ok, :scheduled} promptly.
Requires indexes: [name, ...] with distinct string/atom names. Concurrent
requests share work. Completed work is skipped only after rechecking table
version and index UUID. Warming uses a snapshot sharing the fetched session;
a table change detected during warming fails the attempt for retry.
Failures/crashes, including native :busy, are visible through status/2
and can be retried with another request. Invalidation/eviction discard late
results. Running native prewarming cannot be forcibly interrupted.
@spec start_link(keyword()) :: GenServer.on_start()
Starts a cache and its linked task supervisor without opening storage until needed.
@spec status(GenServer.server(), String.t()) :: LanceDB.result(%{required(String.t()) => LanceDB.TableCache.Warming.t()})
Returns string-keyed index names mapped to Warming structs; unretained tables return :not_found.