Transfer data¶
This guide shows how to transfer data from a source database into the currently connected database.
# pip install lamindb
!lamin init --storage ./test-transfer --modules bionty
Show code cell output
! using anonymous user (to identify, call: lamin login)
→ initialized lamindb: anonymous/test-transfer
import lamindb as ln
ln.track()
Show code cell output
→ connected lamindb: anonymous/test-transfer
→ created Transform('DWHy7YleTgkw0000', key='transfer.ipynb'), started new Run('H9HdZZZFkSsYOIyi') at 2026-01-26 16:01:19 UTC
→ notebook imports: lamindb==2.0.1
• recommendation: to identify the notebook across renames, pass the uid: ln.track("DWHy7YleTgkw")
Query all artifacts in the laminlabs/lamindata instance and filter them to their latest versions.
# query all latest artifact versions
artifacts = ln.Artifact.connect("laminlabs/lamindata").filter(is_latest=True)
# convert the QuerySet to a DataFrame and show the latest 5 versions
artifacts.to_dataframe().head()
Show code cell output
| uid | key | description | suffix | kind | otype | size | hash | n_files | n_observations | version_tag | is_latest | is_locked | created_at | branch_id | space_id | storage_id | run_id | schema_id | created_by_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | ||||||||||||||||||||
| 13000 | KSBdSTY5mFmBmsxr0000 | None | Output artifact for run 2153 | .json | None | None | 136 | o26PF2tnK9L4DTSAqjiSNw | NaN | NaN | None | True | False | 2026-01-26 14:11:10.166802+00:00 | 1 | 1 | 2 | 2153.0 | NaN | 18 |
| 12999 | lpMWUWGX1TuXxcZ50000 | None | Output artifact for run 2152 | .json | None | None | 136 | frW35gabzG3qRsxd0i5gmg | NaN | NaN | None | True | False | 2026-01-26 14:11:05.272139+00:00 | 1 | 1 | 2 | 2152.0 | NaN | 18 |
| 12998 | JEKdPeHzxITaXyjw0000 | None | Output artifact for run 2153 | .json | None | None | 136 | Osy8KPQ3-bSMKD1ntxAKNg | NaN | NaN | None | True | False | 2026-01-26 14:11:02.396557+00:00 | 1 | 1 | 2 | 2153.0 | NaN | 18 |
| 12997 | yjUIvTbQ6WDcCtEl0000 | None | Output artifact for run 2152 | .json | None | None | 136 | 3W0-X5fLMiMTKJYhvJep7g | NaN | NaN | None | True | False | 2026-01-26 14:10:59.059582+00:00 | 1 | 1 | 2 | 2152.0 | NaN | 18 |
| 12948 | 4j5sSaYQZcphb2B90000 | None | Output artifact for run 2053 | .json | None | None | 136 | zSis_mC9o_4qyr-ETWeyqA | NaN | NaN | None | True | False | 2026-01-26 05:20:58.341493+00:00 | 1 | 1 | 2 | 2053.0 | NaN | 18 |
You can now further subset or search the QuerySet. Here we query by whether the description contains “tabula sapiens”.
artifact = artifacts.filter(description__contains="Tabula Sapiens").first()
artifact.describe()
Show code cell output
Artifact: tabula_sapiens_lung.h5ad (6Wph) | description: Part of Tabula Sapiens, a benchmark, first-draft human cell atlas. ├── uid: dPraor9rU1EofcFb6Wph run: IeeCQQO (ux-session-tb-lung) │ hash: 8mB1KK2wd51F6HQdvqipcQ size: 3.6 GB │ branch: main space: all │ created_at: 2023-07-14 19:00:30 UTC created_by: Koncopd ├── storage/path: s3://lamindata/tabula_sapiens_lung.h5ad └── Labels └── .ulabels ULabel TSP1, TSP2, TSP14 .tissues bionty.Tissue lung .cell_types bionty.CellType CD8-positive, alpha-beta T cell, fibro… .experimental_factors bionty.ExperimentalFactor anoxya, stroke
By saving the artifact record that’s currently attached to the source database instance, you transfer it to the default database instance.
artifact.save()
Show code cell output
→ transferred: Artifact(uid='dPraor9rU1EofcFb6Wph'), Storage(uid='D9BilDV2')
Artifact(uid='dPraor9rU1EofcFb6Wph', version_tag=None, is_latest=True, key='tabula_sapiens_lung.h5ad', description='Part of Tabula Sapiens, a benchmark, first-draft human cell atlas.', suffix='.h5ad', kind=None, otype=None, size=3899435772, hash='8mB1KK2wd51F6HQdvqipcQ', n_files=None, n_observations=None, branch_id=1, space_id=1, storage_id=4, run_id=2, schema_id=None, created_by_id=3, created_at=2023-07-14 19:00:30 UTC, is_locked=False)
How do I know if a record is saved in the default database instance or not?
Every record has an attribute ._state.db which can take the following values:
None: the record has not yet been saved to any database"default": the record is saved on the default database instance"account/name": the record is saved on a non-default database instance referenced byaccount/name(e.g.,laminlabs/lamindata)
The artifact record has been transferred to the current database without feature & label annotations, but with updated data lineage.
artifact.describe()
Show code cell output
Artifact: tabula_sapiens_lung.h5ad (6Wph) | description: Part of Tabula Sapiens, a benchmark, first-draft human cell atlas. ├── uid: dPraor9rU1EofcFb6Wph run: 8lW6jIo (__lamindb_transfer__/4XIuR0tvaiXM) │ hash: 8mB1KK2wd51F6HQdvqipcQ size: 3.6 GB │ branch: main space: all │ created_at: 2023-07-14 19:00:30 UTC created_by: anonymous └── storage/path: s3://lamindata/tabula_sapiens_lung.h5ad
You see that the data itself remained in the original storage location, which has been added to the current instance’s storage location as a read-only location (indicated by the fact that the instance_uid doesn’t match the current instance).
ln.Storage.to_dataframe()
Show code cell output
| uid | root | description | type | region | instance_uid | is_locked | created_at | branch_id | space_id | created_by_id | run_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | ||||||||||||
| 4 | D9BilDV2 | s3://lamindata | None | s3 | us-east-1 | 4XIuR0tvaiXM | False | 2023-04-22 05:50:06.537267+00:00 | 1 | 1 | 3 | 2.0 |
| 3 | 0LmYYiSaufMb | /home/runner/work/lamindb/lamindb/docs/test-tr... | None | local | None | 1FHu5eE0uxm4 | False | 2026-01-26 16:01:15.287000+00:00 | 1 | 1 | 3 | NaN |
See the state of the database.
ln.view()
Show code cell output
****************
* module: core *
****************
Artifact
| uid | key | description | suffix | kind | otype | size | hash | n_files | n_observations | version_tag | is_latest | is_locked | created_at | branch_id | space_id | storage_id | run_id | schema_id | created_by_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | ||||||||||||||||||||
| 1 | dPraor9rU1EofcFb6Wph | tabula_sapiens_lung.h5ad | Part of Tabula Sapiens, a benchmark, first-dra... | .h5ad | None | None | 3899435772 | 8mB1KK2wd51F6HQdvqipcQ | None | None | None | True | False | 2023-07-14 19:00:30.621330+00:00 | 1 | 1 | 4 | 2 | None | 3 |
Run
| uid | name | entrypoint | started_at | finished_at | params | reference | reference_type | cli_args | is_locked | created_at | branch_id | space_id | transform_id | report_id | environment_id | created_by_id | initiated_by_run_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | ||||||||||||||||||
| 2 | 8lW6jIoXwFmm3OkI | None | None | 2026-01-26 16:01:21.488000+00:00 | None | None | None | None | None | False | 2026-01-26 16:01:21.488000+00:00 | 1 | 1 | 2 | None | None | 3 | 1.0 |
| 1 | H9HdZZZFkSsYOIyi | None | None | 2026-01-26 16:01:19.029993+00:00 | None | None | None | None | None | False | 2026-01-26 16:01:19.031000+00:00 | 1 | 1 | 1 | None | None | 3 | NaN |
Storage
| uid | root | description | type | region | instance_uid | is_locked | created_at | branch_id | space_id | created_by_id | run_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | ||||||||||||
| 4 | D9BilDV2 | s3://lamindata | None | s3 | us-east-1 | 4XIuR0tvaiXM | False | 2023-04-22 05:50:06.537267+00:00 | 1 | 1 | 3 | 2.0 |
| 3 | 0LmYYiSaufMb | /home/runner/work/lamindb/lamindb/docs/test-tr... | None | local | None | 1FHu5eE0uxm4 | False | 2026-01-26 16:01:15.287000+00:00 | 1 | 1 | 3 | NaN |
Transform
| uid | key | description | kind | source_code | hash | reference | reference_type | version_tag | is_latest | is_locked | created_at | branch_id | space_id | environment_id | created_by_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | ||||||||||||||||
| 2 | 4XIuR0tvaiXM0000 | __lamindb_transfer__/4XIuR0tvaiXM | Transfer from `laminlabs/lamindata` | function | None | None | None | None | None | True | False | 2026-01-26 16:01:21.483000+00:00 | 1 | 1 | None | 3 |
| 1 | DWHy7YleTgkw0000 | transfer.ipynb | Transfer data | notebook | None | None | None | None | None | True | False | 2026-01-26 16:01:19.023000+00:00 | 1 | 1 | None | 3 |
******************
* module: bionty *
******************
Source
| uid | entity | organism | name | version | in_db | currently_used | description | url | md5 | source_website | is_locked | created_at | branch_id | space_id | created_by_id | run_id | dataframe_artifact_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | ||||||||||||||||||
| 67 | 5JnVODh4 | BioSample | all | ncbi | 2023-09 | False | True | NCBI BioSample attributes | s3://bionty-assets/df_all__ncbi__2023-09__BioS... | None | https://www.ncbi.nlm.nih.gov/biosample/docs/at... | False | 2026-01-26 16:01:15.398000+00:00 | 1 | 1 | 3 | None | None |
| 66 | 7au3ZQrD | bionty.Ethnicity | human | hancestro | 2025-10-14 | False | True | Human Ancestry Ontology | http://purl.obolibrary.org/obo/hancestro/relea... | None | https://github.com/EBISPOT/hancestro | False | 2026-01-26 16:01:15.398000+00:00 | 1 | 1 | 3 | None | None |
| 65 | 6na9vRls | bionty.DevelopmentalStage | mouse | mmusdv | 2025-01-23 | False | True | Mouse Developmental Stages | https://github.com/obophenotype/developmental-... | None | https://github.com/obophenotype/developmental-... | False | 2026-01-26 16:01:15.398000+00:00 | 1 | 1 | 3 | None | None |
| 64 | 7JO1x6p1 | bionty.DevelopmentalStage | human | hsapdv | 2025-01-23 | False | True | Human Developmental Stages | https://github.com/obophenotype/developmental-... | None | https://github.com/obophenotype/developmental-... | False | 2026-01-26 16:01:15.398000+00:00 | 1 | 1 | 3 | None | None |
| 63 | 1atB0WnU | Drug | all | chebi | 2024-07-27 | False | False | Chemical Entities of Biological Interest | s3://bionty-assets/df_all__chebi__2024-07-27__... | None | https://www.ebi.ac.uk/chebi/ | False | 2026-01-26 16:01:15.398000+00:00 | 1 | 1 | 3 | None | None |
| 62 | ugaIoIlj | Drug | all | dron | 2024-08-05 | False | True | Drug Ontology | http://purl.obolibrary.org/obo/dron/releases/2... | None | https://bioportal.bioontology.org/ontologies/DRON | False | 2026-01-26 16:01:15.398000+00:00 | 1 | 1 | 3 | None | None |
| 61 | 3rm9aOzL | BFXPipeline | all | lamin | 1.0.0 | False | True | Bioinformatics Pipeline | s3://bionty-assets/df_all__lamin__1.0.0__BFXpi... | None | https://lamin.ai | False | 2026-01-26 16:01:15.398000+00:00 | 1 | 1 | 3 | None | None |
View lineage:
artifact.view_lineage()
Show code cell output
! calling anonymously, will miss private instances
The transferred dataset is linked to a special type of transform that stores the slug and uid of the source instance:
artifact.transform.description
Show code cell output
'Transfer from `laminlabs/lamindata`'
The transform key has the form f"__lamindb_transfer__/{source_instance.uid}":
artifact.transform.key
Show code cell output
'__lamindb_transfer__/4XIuR0tvaiXM'
The current notebook run is linked as the initiated_by_run of the “transfer run”:
artifact.run.initiated_by_run.transform
Show code cell output
Transform(uid='DWHy7YleTgkw0000', version_tag=None, is_latest=True, key='transfer.ipynb', description='Transfer data', kind='notebook', hash=None, reference=None, reference_type=None, environment=None, branch_id=1, space_id=1, created_by_id=3, created_at=2026-01-26 16:01:19 UTC, is_locked=False)
Upon re-transferring a record, it will identify that the record already exists in the target database and simply map the record.
artifact = artifacts.filter(description__contains="Tabula Sapiens").first()
artifact.save()
Show code cell output
→ mapped: Artifact(uid='dPraor9rU1EofcFb6Wph')
Artifact(uid='dPraor9rU1EofcFb6Wph', version_tag=None, is_latest=True, key='tabula_sapiens_lung.h5ad', description='Part of Tabula Sapiens, a benchmark, first-draft human cell atlas.', suffix='.h5ad', kind=None, otype=None, size=3899435772, hash='8mB1KK2wd51F6HQdvqipcQ', n_files=None, n_observations=None, branch_id=1, space_id=1, storage_id=4, run_id=2, schema_id=None, created_by_id=3, created_at=2023-07-14 19:00:30 UTC, is_locked=False)
If you also want to transfer annotations of the artifact, you can pass transfer="annotations" to save(). Just note that this might populate your target database with metadata that doesn’t match the conventions you want to enforce.
artifact = artifacts.filter(description__contains="Tabula Sapiens").first()
artifact.save(transfer="annotations")
Show code cell output
→ mapped: Artifact(uid='dPraor9rU1EofcFb6Wph'), Tissue(uid='7Tt4iEKcwoe1EE'), CellType(uid='4PSMdO3IsR9UI9'), CellType(uid='6IC9NGJEv2Y4TD'), CellType(uid='1lMgAPE8davgkf'), CellType(uid='ryEtgi1yGtAcX2'), CellType(uid='zQ4dyjEsTCun7d'), CellType(uid='01NqvhnIKKA3J8'), CellType(uid='5Z76sCeph8fn9W'), CellType(uid='3kaL3W1cIViKcg'), CellType(uid='5i19XYugz9zzxA'), CellType(uid='puGNwNrsaxodk3'), CellType(uid='3JO0EdVdJlYE7f'), CellType(uid='2OWUH6Z1pimtBB'), CellType(uid='3eecYgWR9YMp2H'), CellType(uid='37mWPv6otCyJLC'), CellType(uid='5tiBvp96QTiJ4H'), CellType(uid='5NceZTYmYMzJq0'), CellType(uid='2nPA0h4FyOt2Ok'), CellType(uid='6UmKFrznjmJlgN'), CellType(uid='1HYtHpIc3MU77g'), CellType(uid='6dzoXJ3Y9BCQIq'), CellType(uid='7Crr32HI5C8Bht'), CellType(uid='6rfrjhvo5IhEEE'), CellType(uid='5TU8SFt5py6wml'), CellType(uid='7m6Ruz32IspRBU'), CellType(uid='42qbvc90CcrBt2'), CellType(uid='1T8bGe2IeRoE0f'), CellType(uid='6ujMwy7schFoIZ'), CellType(uid='7mNqzyFEkVRvSX'), CellType(uid='5A9EFjNBQaFYGC'), CellType(uid='3lsrLTv6Ul2DtB'), CellType(uid='7eZArDponrZegi'), CellType(uid='2KCFdGIk1eN8qu'), CellType(uid='1V5wVqK5FoNNvI'), CellType(uid='5Xi2OLvZ2Frw6O'), ExperimentalFactor(uid='5YDCOg0VWNpKIK'), ExperimentalFactor(uid='7R1OhRJ7PT4MFP')
→ transferred: ULabel(uid='gk6w8qC5'), ULabel(uid='ZaVLDCZE'), ULabel(uid='vfLXaHgD'), ULabel(uid='tZCTk48f'), CellType(uid='4mZaXZQgvIQPxZ'), CellType(uid='5rVn0X39cCXji2'), CellType(uid='EWy46SeyNSZ8H0'), CellType(uid='4yqLzwwmGv0nAv')
Artifact(uid='dPraor9rU1EofcFb6Wph', version_tag=None, is_latest=True, key='tabula_sapiens_lung.h5ad', description='Part of Tabula Sapiens, a benchmark, first-draft human cell atlas.', suffix='.h5ad', kind=None, otype=None, size=3899435772, hash='8mB1KK2wd51F6HQdvqipcQ', n_files=None, n_observations=None, branch_id=1, space_id=1, storage_id=4, run_id=2, schema_id=None, created_by_id=3, created_at=2023-07-14 19:00:30 UTC, is_locked=False)
The artifact is now annotated.
artifact.describe()
Show code cell output
Artifact: tabula_sapiens_lung.h5ad (6Wph) | description: Part of Tabula Sapiens, a benchmark, first-draft human cell atlas. ├── uid: dPraor9rU1EofcFb6Wph run: 8lW6jIo (__lamindb_transfer__/4XIuR0tvaiXM) │ hash: 8mB1KK2wd51F6HQdvqipcQ size: 3.6 GB │ branch: main space: all │ created_at: 2023-07-14 19:00:30 UTC created_by: anonymous ├── storage/path: s3://lamindata/tabula_sapiens_lung.h5ad └── Labels └── .ulabels ULabel TSP2, TSP1, TSP14 .tissues bionty.Tissue lung .cell_types bionty.CellType CD4-positive, alpha-beta T cell, CD8-p… .experimental_factors bionty.ExperimentalFactor anoxya, stroke
Show code cell content
# test the last 3 cells here
assert artifact.transform.description == "Transfer from `laminlabs/lamindata`"
assert artifact.transform.key == "__lamindb_transfer__/4XIuR0tvaiXM"
assert artifact.transform.uid == "4XIuR0tvaiXM0000"
assert artifact.run.initiated_by_run.transform.description == "Transfer data"