Version history, snapshots, restore and version tags.
Summary
Functions
Creates a tag pointing to an existing version. Duplicate names return an error. Tagged versions are protected: cleanup fails if it would prune one. Tag mutations require a handle that is not checked out.
Deletes a tag without deleting its version. Missing tags return an error.
Returns a new live handle on the same branch, observing the latest version. The source handle remains unchanged, including when it is a pinned snapshot. The new handle retains the source session and read-consistency configuration.
Lists tags as a map keyed by tag name. Values contain string keys "version", "manifest_size", and "branch" (nil for the main branch). Tags are durable names for retained versions, not moving aliases for latest.
Lists retained History.Version structs with version, UTC timestamp and string-keyed metadata.
Restores an explicit historical version onto a live table handle as a new commit. Returns a WriteResult containing the committed version. The target must be live; existing snapshot handles remain pinned. Other live handles follow their read-consistency policy.
Returns an independent read-only handle pinned to the given version. The source handle and other processes using it are unchanged. The snapshot retains the source session and shares its caches and counters.
Resolves a tag and returns an independent read-only handle. Moving or deleting the tag later does not change that snapshot. It retains the source session.
Resolves a tag to its version number. Missing tags return an error.
Moves an existing tag to an existing version, returning an error if either is missing.
Returns the version currently visible through this table handle.
Types
@type result(value) :: LanceDB.result(value)
@type table() :: LanceDB.Table.t()
Functions
@spec create_tag(table(), String.t(), pos_integer()) :: result(:created)
Creates a tag pointing to an existing version. Duplicate names return an error. Tagged versions are protected: cleanup fails if it would prune one. Tag mutations require a handle that is not checked out.
Deletes a tag without deleting its version. Missing tags return an error.
Returns a new live handle on the same branch, observing the latest version. The source handle remains unchanged, including when it is a pinned snapshot. The new handle retains the source session and read-consistency configuration.
Lists tags as a map keyed by tag name. Values contain string keys "version", "manifest_size", and "branch" (nil for the main branch). Tags are durable names for retained versions, not moving aliases for latest.
@spec list_versions(table()) :: result([LanceDB.History.Version.t()])
Lists retained History.Version structs with version, UTC timestamp and string-keyed metadata.
@spec restore(table(), pos_integer()) :: result(LanceDB.WriteResult.t())
Restores an explicit historical version onto a live table handle as a new commit. Returns a WriteResult containing the committed version. The target must be live; existing snapshot handles remain pinned. Other live handles follow their read-consistency policy.
@spec snapshot(table(), pos_integer()) :: result(table())
Returns an independent read-only handle pinned to the given version. The source handle and other processes using it are unchanged. The snapshot retains the source session and shares its caches and counters.
Resolves a tag and returns an independent read-only handle. Moving or deleting the tag later does not change that snapshot. It retains the source session.
@spec tag_version(table(), String.t()) :: result(pos_integer())
Resolves a tag to its version number. Missing tags return an error.
@spec update_tag(table(), String.t(), pos_integer()) :: result(:updated)
Moves an existing tag to an existing version, returning an error if either is missing.
@spec version(table()) :: result(pos_integer())
Returns the version currently visible through this table handle.