Transfer data 
¶
This guide shows how to transfer data from a source database to your default 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('FzDanwGN96is0000', key='transfer.ipynb'), started new Run('WLpuBbKDfoo9LICj') at 2026-02-05 16:19:16 UTC
→ notebook imports: lamindb==2.1.1
• recommendation: to identify the notebook across renames, pass the uid: ln.track("FzDanwGN96is")
Query artifacts in the laminlabs/lamindata instance:
db = ln.DB("laminlabs/lamindata")
artifacts = db.Artifact.filter(is_latest=True) # query latest versions of artifacts
artifacts.to_dataframe()
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 | ||||||||||||||||||||
| 13355 | jd1GEr3rASuvzCB00000 | None | Output artifact for run 2448 | .json | None | None | 1.360000e+02 | gQPlQcVT5dcjHj-YAi8P2w | NaN | None | None | True | False | 2026-01-31 05:24:44.088405+00:00 | 1 | 1 | 2 | 2448 | None | 18 |
| 13354 | WkxcZyD7j1z8GL3V0000 | None | Output artifact for run 2448 | .json | None | None | 1.360000e+02 | 6AnIv5ufq2H0PwfraQEhyw | NaN | None | None | True | False | 2026-01-31 05:24:41.962281+00:00 | 1 | 1 | 2 | 2448 | None | 18 |
| 13353 | HfhLVMkLQehj48Ku0000 | None | Output artifact for run 2447 | .json | None | None | 1.360000e+02 | WVxHD0BwcZarHT9aIKT0sA | NaN | None | None | True | False | 2026-01-31 05:24:21.224112+00:00 | 1 | 1 | 2 | 2447 | None | 18 |
| 13352 | qfnnZfH3GMyLYoqG0000 | None | Output artifact for run 2447 | .json | None | None | 1.360000e+02 | qEfMjT1cExPThaNUWj4MeQ | NaN | None | None | True | False | 2026-01-31 05:24:18.423401+00:00 | 1 | 1 | 2 | 2447 | None | 18 |
| 13310 | PBYhiDTCzaGwExy20000 | None | Test uploaded artifact by InstanceTest | .txt | None | None | 5.200000e+01 | W7y0oVNDshPqvliIm_33ww | NaN | None | None | True | False | 2026-01-30 14:22:09.022190+00:00 | 1 | 1 | 2 | 2344 | None | 18 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 12857 | Z1Q9alE7dBr5lZty0000 | vitessce_examples/visium.sdata.zarr | Visium SpatialData Example | .zarr | dataset | SpatialData | 1.473182e+09 | iDvq8-aqbbY8EBA1QCoMzw | 9170.0 | None | None | True | False | 2026-01-20 19:53:35.630352+00:00 | 1 | 1 | 2 | 1933 | None | 40 |
| 12854 | Ljx9cSOxELkGisVt0000 | vitessce_examples/habib17.adata.zarr | Habib et al., 2017 Nature Methods, zarr | .zarr | dataset | AnnData | 1.060106e+07 | YPuOwAd5BZ3pbPoGNBH4aw | 208.0 | None | None | True | False | 2026-01-20 19:53:03.970394+00:00 | 1 | 1 | 2 | 1932 | None | 40 |
| 12853 | cyzNRxkUQF1sMVrr0000 | vitessce_examples/habib17.reference.json | Reference JSON for H5AD file, Habib et al., 20... | .json | None | None | 5.435750e+05 | XFOV2X6Bw6_zTugTOEBehg | NaN | None | None | True | False | 2026-01-20 19:52:54.593799+00:00 | 1 | 1 | 2 | 1932 | None | 40 |
| 12852 | NNUzTpWz3a0PU2aT0000 | vitessce_examples/habib17.h5ad | Habib et al., 2017 Nature Methods, h5ad | .h5ad | dataset | AnnData | 2.258652e+07 | nBetKKNFs4mjJ04X_f4uaA | NaN | None | None | True | False | 2026-01-20 19:52:45.252392+00:00 | 1 | 1 | 2 | 1932 | None | 40 |
| 12841 | 92uPoMY9AFz4LeDk0000 | None | Output artifact for run 1925 | .json | None | None | 1.360000e+02 | pO8g4JvOro2ClwWIVnqlnQ | NaN | None | None | True | False | 2026-01-20 05:17:48.661032+00:00 | 1 | 1 | 2 | 1925 | None | 18 |
100 rows × 20 columns
You can now further subset or search the QuerySet. Here we already know what we’re looking for:
artifact = artifacts.get(key="example_datasets/mini_immuno/dataset1.h5ad")
artifact.describe()
Show code cell output
Artifact: example_datasets/mini_immuno/dataset1.h5ad (0000) | description: Flow cytometry readouts on invitro cell culture ├── uid: 9K1dteZ6Qx0EXK8g0000 run: VioVE27 (curate-anndata-mini-immuno.ipynb) │ kind: dataset otype: AnnData │ hash: FB3CeMjmg1ivN6HDy6wsSg size: 30.9 KB │ branch: main space: all │ created_at: 2025-07-29 12:27:25 UTC created_by: falexwolf │ n_observations: 3.0 ├── storage/path: s3://lamindata/.lamindb/9K1dteZ6Qx0EXK8g0000.h5ad ├── Dataset features │ ├── obs (8.0) │ │ assay_oid bionty.ExperimentalFactor.ontology… EFO:0008913 │ │ cell_type_by_expert bionty.CellType B cell, CD8-positive, alpha-beta T cell │ │ cell_type_by_model bionty.CellType B cell, T cell │ │ concentration str │ │ donor str │ │ perturbation ULabel DMSO, IFNG │ │ sample_note str │ │ treatment_time_h num │ └── var.T (3.0 bionty.Gene.ensem… │ CD14 num │ CD4 num │ CD8A num ├── External features │ └── experiment Record[6pjoBrrz4f1EzQMO] Experiment 1 │ experiment ULabel Experiment 1 │ date_of_study date 2024-12-01 │ study_metadata dict {'detail1': '123', 'detail2': 1} │ study_note str We had a great time performing this st… │ temperature float 21.6 └── Labels └── .ulabels ULabel DMSO, IFNG, Experiment 1 .records Record Experiment 1 .projects Project Tutorials .cell_types bionty.CellType B cell, T cell, CD8-positive, alpha-be… .experimental_factors bionty.ExperimentalFactor single-cell RNA sequencing
By saving the artifact that’s currently attached to the source database, you transfer it to your default database.
artifact.save()
Show code cell output
→ transferred: Artifact(uid='9K1dteZ6Qx0EXK8g0000'), Storage(uid='D9BilDV2'), Schema(uid='0000000000000002')
Artifact(uid='9K1dteZ6Qx0EXK8g0000', version_tag=None, is_latest=True, key='example_datasets/mini_immuno/dataset1.h5ad', description='Flow cytometry readouts on invitro cell culture', suffix='.h5ad', kind='dataset', otype='AnnData', size=31672.0, hash='FB3CeMjmg1ivN6HDy6wsSg', n_files=None, n_observations=3.0, branch_id=1, space_id=1, storage_id=4, run_id=2, schema_id=1, created_by_id=3, created_at=2025-07-29 12:27:25 UTC, is_locked=False)
How do I know if an object is saved in the default database or not?
Every SQLRecord object has an attribute ._state.db which can take the following values:
None: the object has not yet been saved to any database"default": the object is saved on the default database instance"account/name": the object is saved on a non-default database instance referenced byaccount/name(e.g.,laminlabs/lamindata)
The artifact has been transferred to the current database without feature & label annotations, but with updated data lineage:
artifact.describe()
Show code cell output
Artifact: example_datasets/mini_immuno/dataset1.h5ad (0000) | description: Flow cytometry readouts on invitro cell culture ├── uid: 9K1dteZ6Qx0EXK8g0000 run: HeeyrDF (__lamindb_transfer__/4XIuR0tvaiXM) │ kind: dataset otype: AnnData │ hash: FB3CeMjmg1ivN6HDy6wsSg size: 30.9 KB │ branch: main space: all │ created_at: 2025-07-29 12:27:25 UTC created_by: anonymous │ n_observations: 3 └── storage/path: s3://lamindata/.lamindb/9K1dteZ6Qx0EXK8g0000.h5ad
The data itself remained in the original storage location, which has been added to your default database’s storage location as a read-only location. This is indicated by the fact that the instance_uid does not match the uid of your default database.
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 | mlif3PdNI2Xp | /home/runner/work/lamindb/lamindb/docs/test-tr... | None | local | None | 1FHu5eE0uxm4 | False | 2026-02-05 16:19:13.538000+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 | 9K1dteZ6Qx0EXK8g0000 | example_datasets/mini_immuno/dataset1.h5ad | Flow cytometry readouts on invitro cell culture | .h5ad | dataset | AnnData | 31672 | FB3CeMjmg1ivN6HDy6wsSg | None | 3 | None | True | False | 2025-07-29 12:27:25.572900+00:00 | 1 | 1 | 4 | 2 | 1 | 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 | HeeyrDFS4cTooSOr | None | None | 2026-02-05 16:19:21.387000+00:00 | None | None | None | None | None | False | 2026-02-05 16:19:21.387000+00:00 | 1 | 1 | 2 | None | None | 3 | 1.0 |
| 1 | WLpuBbKDfoo9LICj | None | None | 2026-02-05 16:19:16.979132+00:00 | None | None | None | None | None | False | 2026-02-05 16:19:16.980000+00:00 | 1 | 1 | 1 | None | None | 3 | NaN |
Schema
| uid | name | description | n_members | coerce | flexible | itype | otype | hash | minimal_set | ordered_set | maximal_set | is_locked | is_type | created_at | branch_id | space_id | created_by_id | run_id | type_id | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | ||||||||||||||||||||
| 1 | 0000000000000002 | anndata_ensembl_gene_ids_and_valid_features_in... | None | None | None | True | Composite | AnnData | UR_ozz2VI2sY8ckXop2RAg | True | False | False | False | False | 2025-07-10 10:21:07.781328+00:00 | 1 | 1 | 3 | 2 | None |
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 | mlif3PdNI2Xp | /home/runner/work/lamindb/lamindb/docs/test-tr... | None | local | None | 1FHu5eE0uxm4 | False | 2026-02-05 16:19:13.538000+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-02-05 16:19:21.382000+00:00 | 1 | 1 | None | 3 |
| 1 | FzDanwGN96is0000 | transfer.ipynb | Transfer data [
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='FzDanwGN96is0000', version_tag=None, is_latest=True, key='transfer.ipynb', description='Transfer data [](https://github.com/laminlabs/lamindb/blob/main/docs/transfer.md)', kind='notebook', hash=None, reference=None, reference_type=None, environment=None, branch_id=1, space_id=1, created_by_id=3, created_at=2026-02-05 16:19:16 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.get(key="example_datasets/mini_immuno/dataset1.h5ad")
artifact.save()
Show code cell output
→ mapped: Artifact(uid='9K1dteZ6Qx0EXK8g0000')
Artifact(uid='9K1dteZ6Qx0EXK8g0000', version_tag=None, is_latest=True, key='example_datasets/mini_immuno/dataset1.h5ad', description='Flow cytometry readouts on invitro cell culture', suffix='.h5ad', kind='dataset', otype='AnnData', size=31672, hash='FB3CeMjmg1ivN6HDy6wsSg', n_files=None, n_observations=3, branch_id=1, space_id=1, storage_id=4, run_id=2, schema_id=1, created_by_id=3, created_at=2025-07-29 12:27:25 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.get(key="example_datasets/mini_immuno/dataset1.h5ad")
artifact.save(transfer="annotations")
Show code cell output
→ mapped: Artifact(uid='9K1dteZ6Qx0EXK8g0000'), CellType(uid='ryEtgi1yGtAcX2'), CellType(uid='22LvKd01YyNA1a'), CellType(uid='6IC9NGJEv2Y4TD'), CellType(uid='ryEtgi1yGtAcX2'), ExperimentalFactor(uid='4WYv9kl0W2SroY')
→ transferred: Feature(uid='LIrjN9FbaLR1'), Feature(uid='xFdXre6ZPLlK'), Feature(uid='fJnNc4pzxe9c'), Feature(uid='7xDpJZiVLRl3'), Feature(uid='BaPfsAPgDFrT'), Feature(uid='DLeKfqUbrUsg'), Feature(uid='zvyDVbZln36o'), Feature(uid='Q8edF7CSgjG2'), Organism(uid='1dpCL6TduFJ3AP'), Source(uid='4BENqfHn'), Source(uid='404rkf5M'), Gene(uid='1j4At3x7akJU8n'), Gene(uid='6Aqvc8ckDYeNrD'), Gene(uid='3bhNYquOnA4sdo'), ULabel(uid='vmjLLqYy'), ULabel(uid='YAhFIvh5'), ULabel(uid='Yis4YLIB'), ULabel(uid='InLummy0'), Feature(uid='4ycwa8er0EB2'), Record(uid='ZRP07Y49Ni3Ne0Ae'), Record(uid='6pjoBrrz4f1EzQMO'), Record(uid='fNBzuANAusnkFv2p'), Schema(uid='JfgNiPmWNLZz4YRh'), Feature(uid='pNaJLQh8fRA6'), Project(uid='BZF49Wr2yZAC')
Artifact(uid='9K1dteZ6Qx0EXK8g0000', version_tag=None, is_latest=True, key='example_datasets/mini_immuno/dataset1.h5ad', description='Flow cytometry readouts on invitro cell culture', suffix='.h5ad', kind='dataset', otype='AnnData', size=31672, hash='FB3CeMjmg1ivN6HDy6wsSg', n_files=None, n_observations=3, branch_id=1, space_id=1, storage_id=4, run_id=2, schema_id=1, created_by_id=3, created_at=2025-07-29 12:27:25 UTC, is_locked=False)
The artifact is now annotated.
artifact.describe()
Show code cell output
Artifact: example_datasets/mini_immuno/dataset1.h5ad (0000) | description: Flow cytometry readouts on invitro cell culture ├── uid: 9K1dteZ6Qx0EXK8g0000 run: HeeyrDF (__lamindb_transfer__/4XIuR0tvaiXM) │ kind: dataset otype: AnnData │ hash: FB3CeMjmg1ivN6HDy6wsSg size: 30.9 KB │ branch: main space: all │ created_at: 2025-07-29 12:27:25 UTC created_by: anonymous │ n_observations: 3 ├── storage/path: s3://lamindata/.lamindb/9K1dteZ6Qx0EXK8g0000.h5ad ├── Dataset features │ ├── obs (8) │ │ assay_oid bionty.ExperimentalFactor.ontology… EFO:0008913 │ │ cell_type_by_expert bionty.CellType CD8-positive, alpha-beta T cell │ │ cell_type_by_model bionty.CellType B cell, T cell │ │ concentration str │ │ donor str │ │ perturbation ULabel DMSO, IFNG │ │ sample_note str │ │ treatment_time_h num │ └── var.T (3 bionty.Gene) │ CD14 num │ CD4 num │ CD8A num ├── External features │ └── experiment Record[RNA-seq] Experiment 1 │ experiment ULabel Experiment 1 └── Labels └── .ulabels ULabel DMSO, IFNG, Experiment 1 .records Record Experiment 1 .projects Project Tutorials .cell_types bionty.CellType B cell, T cell, CD8-positive, alpha-be… .experimental_factors bionty.ExperimentalFactor single-cell RNA sequencing
# 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.startswith("Transfer data")