How do I trash or archive records?¶

Any record in LaminDB has the following 3 levels of visibility through 3 default branches:

1: “default”, visible by default
0: “archive”, excluded from query & search by default
-1: “trash”, excluded from query & search by default

# pip install lamindb
!lamin init --storage test-branch

→ initialized lamindb: testuser1/test-branch

import lamindb as ln
import pandas as pd

→ connected lamindb: testuser1/test-branch

artifact = ln.Artifact.from_dataframe(
    pd.DataFrame({"a": [1, 2], "b": [3, 4]}), key="dataset.parquet"
).save()

! no run & transform got linked, call `ln.track()` & re-run

An artifact is by default created on the main branch and then visible.

assert artifact.branch.name == "main"

If you delete an artifact, it gets moved into the trash branch.

artifact.delete()
assert artifact.branch.name == "trash"

! moved record to trash (branch_id = -1): Artifact(uid='ochG6MIcIvqevwJC0000', is_latest=True, key='dataset.parquet', suffix='.parquet', kind='dataset', otype='DataFrame', size=2068, hash='eM_il92GbTmhwqdnSMYd2w', n_observations=2, branch_id=-1, space_id=1, storage_id=1, created_by_id=1, created_at=2025-10-13 20:36:20 UTC, is_locked=False)

Artifacts in trash won’t via default queries:

ln.Artifact.filter(key="dataset.parquet").to_dataframe()

	uid	id	key	description	suffix	kind	otype	size	hash	n_files	n_observations	_hash_type	_key_is_virtual	_overwrite_versions	space_id	storage_id	schema_id	version	is_latest	is_locked	run_id	created_at	created_by_id	_aux	_real_key	branch_id

You can query for them by adding the trash branch to the filter.

ln.Artifact.filter(key="dataset.parquet", branch__name="trash").to_dataframe()

	uid	key	description	suffix	kind	otype	size	hash	n_files	n_observations	_hash_type	_key_is_virtual	_overwrite_versions	space_id	storage_id	schema_id	version	is_latest	is_locked	run_id	created_at	created_by_id	_aux	_real_key	branch_id
id
1	ochG6MIcIvqevwJC0000	dataset.parquet	None	.parquet	dataset	DataFrame	2068	eM_il92GbTmhwqdnSMYd2w	None	2	md5	True	False	1	1	None	None	True	False	None	2025-10-13 20:36:20.265000+00:00	1	{'af': {'0': True}}	None	-1

You can restore an artifact from trash:

artifact.restore()
assert artifact.branch.name == "main"
ln.Artifact.filter(key="dataset.parquet").to_dataframe()

	uid	key	description	suffix	kind	otype	size	hash	n_files	n_observations	_hash_type	_key_is_virtual	_overwrite_versions	space_id	storage_id	schema_id	version	is_latest	is_locked	run_id	created_at	created_by_id	_aux	_real_key	branch_id
id
1	ochG6MIcIvqevwJC0000	dataset.parquet	None	.parquet	dataset	DataFrame	2068	eM_il92GbTmhwqdnSMYd2w	None	2	md5	True	False	1	1	None	None	True	False	None	2025-10-13 20:36:20.265000+00:00	1	{'af': {'0': True}}	None	1