Skip to main content
LanceDB Enterprise deploys on a Kubernetes cluster (AKS, EKS, GKE, or self-managed) with object storage for data persistence and your cloud’s private networking for secure connectivity. The architecture below is the same shape on every cloud; the only cloud-specific part is how storage containers are organized, covered at the end of this page for Azure Blob Storage.

General architecture overview

Function workloads require operator-prepared worker capacity and runtime permissions. See Function worker availability for the supported compute boundary and Function operations for application budgets and admission behavior.

Key components

  • LanceDB architecture is deployed in a Kubernetes cluster within its own VPC.
  • Client applications connect to the cluster securely using your cloud’s private link service.
  • The cluster is granted object storage read/write permissions using cloud-native workload identity (Azure Workload Identity, IRSA on EKS, or Workload Identity Federation on GKE).
  • A message queue — a managed service such as Azure EventHub, or a self-hosted Kafka cluster in Kubernetes — carries LanceDB’s internal message passing.

Read path architecture

Read path flow

  1. Client application sends a query request through the private link.
  2. Query nodes receive and process the request.
  3. Executors execute the query using the distributed data cache to speed up read queries.
  4. Object storage stores data and indices in Lance format, while executors maintain a distributed cache for performance.

Write path architecture

Write path flow

Query nodes write data and indices synchronously to object storage in Lance format while asynchronously sending data modification events to the message queue (a managed service such as Azure EventHub, or a self-hosted Kafka cluster). These write events are processed by the Lance Agent, which launches indexing pods or data optimization pods to optimize data for better read performance.

Write timeouts and large merges

REST merge_insert uploads its input, performs the merge, and returns one JSON result. It does not send progress or heartbeat bytes while processing. Without an x-request-timeout-ms header, the server applies a 50-second request deadline and returns 504 Gateway Timeout when it expires. This deadline includes input upload and processing. It is shorter than the router’s default 55-second upstream read/write timeouts and an AWS ALB’s default 60-second idle timeout. Deployments with shorter proxy or client timeouts need a correspondingly shorter request deadline. Ask your deployment operator about the effective server and proxy limits. For a remote table, Python merge_insert(...).execute(data, timeout=...) sends the requested timeout to the server as x-request-timeout-ms. An explicit header replaces the default server deadline; it does not extend an ALB, NLB, PrivateLink, ingress, or client read timeout. Increasing only the SDK timeout cannot keep a silent response connection alive through a shorter intermediary idle window. The embedded SDK’s default conflict-retry budget is separate from this remote request deadline.
The equivalent TypeScript and Rust calls set the same request deadline:
For Rust, wrap the Arrow RecordBatch in a reader before executing the merge:
For standard, non-Realtime tables, cancelling computation before it enters final manifest publication stops the merge from publishing table changes. Uncommitted objects may remain for later cleanup. Once publication starts, a timeout or disconnection can leave a committed write whose response was lost. Neither a 504 nor a closed connection proves that the data was rolled back. An immediate read with missing keys cannot rule out a later commit by the original request. Establish its terminal result or a publication fence before reconciling a fresh snapshot by stable logical keys and content identities under serialized writers. See Verify writes and handle retries for the recovery procedure and Configure large uploads for batch-size guidance. SDK versions that automatically retry non-idempotent writes on 5xx must have those retries disabled; replay can duplicate writes or repeat side effects. For large insert/update-only upserts, use smaller batches that complete within the synchronous window. Around 25,000 rows per batch is a starting point for tuning, not a size or latency guarantee: row width, blobs, table size, indexes, and fragment layout affect runtime. Where practical, group updates by their destination fragment to avoid repeatedly rewriting the same fragments. Each batch commits independently, so the entire import is not atomic. Do not split a when_not_matched_by_source_delete merge this way: each batch would treat rows outside that batch as absent and could delete them.

Deployment models

LanceDB Enterprise supports three deployment models, available on AWS, GCP, and Azure:

1. Fully managed service

  • Infrastructure and storage in LanceDB’s cloud account.
  • Complete management by the LanceDB team.
  • Simplest setup for customers.

2. BYOC (bring your own cloud)

  • Infrastructure and storage in the customer’s cloud account.
  • Fully managed by LanceDB.
  • Full control over data residency.

3. Hybrid — bring your own container

  • Infrastructure in LanceDB’s account.
  • Storage containers in the customer’s account.
For private deployments, high performance at extreme scale, or if you have strict security requirements, contact us about LanceDB Enterprise.

Azure-specific: storage containers

The one part of this architecture that is genuinely cloud-specific is how object storage is organized. On Azure, data lives in Blob Storage containers, grouped under one or more storage accounts — the same multi-tenant or multi-workload layout applies whether you use a single account with several containers, or split workloads across accounts:
The equivalent on other clouds is an S3 bucket (AWS) or a Cloud Storage bucket (GCP); everything else on this page — the Kubernetes cluster layout, the read and write paths, and the deployment models — applies unchanged.