mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-16 08:42:29 +00:00
82 lines
3.5 KiB
Plaintext
82 lines
3.5 KiB
Plaintext
---
|
|
title: "Guarantees"
|
|
sidebarTitle: "Guarantees"
|
|
description: "Understand table commits, concurrent writes and the boundaries of recovery."
|
|
icon: shield-check
|
|
keywords: ["guarantees", "consistency", "atomicity", "durability", "concurrency"]
|
|
---
|
|
|
|
## What commits together? {#writes}
|
|
|
|
A table transaction commits its changes atomically: readers see the committed
|
|
table version, not a partially applied transaction. For example, a committed
|
|
append adds its rows together.
|
|
|
|
This boundary is one table transaction. A workflow that updates several tables
|
|
or runs a background job can contain multiple commits. Do not assume the whole
|
|
workflow is atomic.
|
|
|
|
<span id="schema" />
|
|
|
|
Schema changes are also part of table history. Changing a column's type can
|
|
rewrite data; adding a derived column can write the new column independently.
|
|
|
|
## What does a read observe? {#reads}
|
|
|
|
A read of a table uses a consistent snapshot. A consistent snapshot can still
|
|
be older than another writer's latest commit. [Consistency](/tables/consistency)
|
|
explains how OSS and Enterprise choose the version a reader sees.
|
|
|
|
For an experiment that must keep using the same data, select a specific retained
|
|
table version rather than relying on a connection's default freshness.
|
|
|
|
## What happens with concurrent writes? {#concurrency}
|
|
|
|
Lance uses optimistic concurrency control. Writers prepare changes, then check
|
|
compatibility with intervening commits. Compatible changes can be committed;
|
|
conflicts may be retried or returned as errors.
|
|
|
|
Applications must handle failed writes. Concurrent appends are compatible, but
|
|
that does not promise success through storage failures or exhausted retries.
|
|
Do not rely on a particular ordering between independent writers.
|
|
|
|
The [Lance transaction specification](https://lance.org/format/table/transaction/)
|
|
describes commit behavior and compatibility between operations.
|
|
|
|
<span id="jobs" />
|
|
|
|
## What survives completion or failure? {#durability}
|
|
|
|
A successful commit records the change in the table's storage. With OSS, that
|
|
storage can be local disk or an object store; Enterprise uses its configured
|
|
storage infrastructure. Durability depends on that backend and its configuration.
|
|
|
|
A job being accepted is not the same as its work completing. Wait for its
|
|
successful outcome before depending on the result. Some background operations
|
|
commit batches as they progress, so failure or cancellation can leave completed
|
|
work in place. See the operation's guide for its commit behavior.
|
|
|
|
A client timeout can leave the outcome unknown. Check the job or resulting data
|
|
before repeating work that could create duplicates.
|
|
|
|
## What can history recover? {#history}
|
|
|
|
Retained table versions let you inspect earlier data and restore a prior state.
|
|
Cleanup can remove old versions and the files they need. Set retention for your
|
|
recovery and reproducibility requirements before cleanup runs.
|
|
|
|
Dropping a table is different from deleting rows: table versioning does not
|
|
provide an undo for `drop_table`. Keep backups appropriate to your storage and
|
|
recovery requirements.
|
|
|
|
<span id="not-guaranteed" />
|
|
|
|
## Learn more {#next}
|
|
|
|
- [Consistency](/tables/consistency): control when reads observe updates.
|
|
- [Table versioning](/management/table#versioning): inspect and restore history.
|
|
- [Cleanup](/maintenance/cleanup): configure retention and understand protected versions.
|
|
- [Jobs](/basics/jobs): distinguish submission, completion and cancellation.
|
|
- [Column refresh](/feature-engineering/refresh-column): understand partial progress.
|
|
- [Architecture](/architecture): understand storage and background maintenance.
|