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

→ writing the in-memory object into cache

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='J3GNJGPUeeghbvH30000', version=None, is_latest=True, key='dataset.parquet', description=None, suffix='.parquet', kind='dataset', otype='DataFrame', size=2068, hash='eM_il92GbTmhwqdnSMYd2w', n_files=None, n_observations=2, branch_id=-1, space_id=1, storage_id=1, run_id=None, schema_id=None, created_by_id=1, created_at=2025-10-30 08:02:52 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	version	is_latest	is_locked	created_at	branch_id	space_id	storage_id	run_id	schema_id	created_by_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	version	is_latest	is_locked	created_at	branch_id	space_id	storage_id	run_id	schema_id	created_by_id
id
1	J3GNJGPUeeghbvH30000	dataset.parquet	None	.parquet	dataset	DataFrame	2068	eM_il92GbTmhwqdnSMYd2w	None	2	None	True	False	2025-10-30 08:02:52.141000+00:00	-1	1	1	None	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	version	is_latest	is_locked	created_at	branch_id	space_id	storage_id	run_id	schema_id	created_by_id
id
1	J3GNJGPUeeghbvH30000	dataset.parquet	None	.parquet	dataset	DataFrame	2068	eM_il92GbTmhwqdnSMYd2w	None	2	None	True	False	2025-10-30 08:02:52.141000+00:00	1	1	1	None	None	1