When does visibility of artifacts and collections change?

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

  • 1: “default”, visible by default

  • 0: “archive”, excluded from query & search by default

  • -1: “trash”, excluded from the query results, set with .delete()

These values are represented in the database via a private integer field _branch_code that also models the branches involved in merge requests.

However, .filter() also accepts the visibility keyword, see below.

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

→ initialized lamindb: testuser1/test-_branch_code

import lamindb as ln
import pandas as pd

→ connected lamindb: testuser1/test-_branch_code

artifact = ln.Artifact.from_df(
    pd.DataFrame({"a": [1, 2], "b": [3, 4]}), description="mydf"
)
artifact.save()

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

Artifact(uid='6PyYwG3qQWvQSEb40000', is_latest=True, description='mydf', suffix='.parquet', kind='dataset', otype='DataFrame', size=2054, hash='HesrmwkODFQaQpPQYsXffg', space_id=1, storage_id=1, created_by_id=1, created_at=2025-01-12 14:08:38 UTC)

A new artifact has default visibility 1 via _branch_code:

assert artifact._branch_code == 1

When you delete an artifact, its _branch_code is set to -1 (“trash”):

artifact.delete()

→ moved artifact to trash (_branch_code = -1)

assert artifact._branch_code == -1

Files in trash won’t be returned from default queries:

ln.Artifact.filter(description="mydf").all()

<QuerySet []>

Unless you specify visibility=None to see all hidden and trashed artifacts.

ln.Artifact.filter(description="mydf", visibility=None).all()

<QuerySet [Artifact(uid='6PyYwG3qQWvQSEb40000', is_latest=True, description='mydf', suffix='.parquet', kind='dataset', otype='DataFrame', size=2054, hash='HesrmwkODFQaQpPQYsXffg', space_id=1, storage_id=1, created_by_id=1, created_at=2025-01-12 14:08:38 UTC)]>

You can restore an artifact from trash:

artifact.restore()

assert artifact._branch_code == 1

ln.Artifact.filter(description="mydf").all()

<QuerySet [Artifact(uid='6PyYwG3qQWvQSEb40000', is_latest=True, description='mydf', suffix='.parquet', kind='dataset', otype='DataFrame', size=2054, hash='HesrmwkODFQaQpPQYsXffg', space_id=1, storage_id=1, created_by_id=1, created_at=2025-01-12 14:08:38 UTC)]>

Delete test artifact and instance:

artifact.delete(permanent=True)

!lamin delete --force test-_branch_code

• deleting instance testuser1/test-_branch_code