Jupyter Notebook

Query & search registries

This guide walks through different ways of querying & searching LaminDB registries.

# pip install lamindb
!lamin init --storage ./test-registries --modules bionty
Hide code cell output 
→ initialized lamindb: testuser1/test-registries

Let’s start by creating a few exemplary datasets and saving them into a LaminDB instance using, e.g., save_mini_immuno_datasets().

import lamindb as ln

ln.track("Wc8F4siRSKMZ")

ln.Artifact(
    ln.examples.datasets.file_jpg_paradisi05(), key="images/my_image.jpg"
).save()
ln.Artifact(ln.examples.datasets.file_fastq(), key="raw/my_fastq.fastq.gz").save()
ln.Artifact.from_dataframe(ln.examples.datasets.df_iris(), key="iris.parquet").save()
ln.examples.datasets.mini_immuno.save_mini_immuno_datasets()
Hide code cell output 
→ connected lamindb: testuser1/test-registries

→ created Transform('Wc8F4siRSKMZ0000', key='registries.ipynb'), started new Run('JuDGwproYJ6Y0uZZ') at 2025-10-15 20:32:25 UTC

→ notebook imports: bionty==1.8.1 lamindb==1.13.0

! 4 terms not validated in feature 'columns' in slot 'obs': 'assay_oid', 'concentration', 'treatment_time_h', 'donor'
    → fix typos, remove non-existent values, or save terms via: curator.slots['obs'].cat.add_new_from('columns')

! moved records to trash (branch_id = -1)

! 3 terms not validated in feature 'columns' in slot 'obs': 'concentration', 'treatment_time_h', 'donor'
    → fix typos, remove non-existent values, or save terms via: curator.slots['obs'].cat.add_new_from('columns')

! moved records to trash (branch_id = -1)

Get an overview

The easiest way to get an overview over all artifacts is by typing df(), which returns the 100 latest artifacts in the Artifact registry.

ln.Artifact.to_dataframe()
Hide code cell output
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
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:33.197000+00:00 1 {'af': {'0': True}} None 1
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1
3 zj57bUkranOBJd6k0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.761000+00:00 1 {'af': {'0': True}} None 1
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.616000+00:00 1 {'af': {'0': True}} None 1
1 aqH45WkcWo8I3yv00000 images/my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.604000+00:00 1 {'af': {'0': True}} None 1

You can include fields from other registries.

ln.Artifact.to_dataframe(
    include=[
        "created_by__name",
        "records__name",
        "cell_types__name",
        "feature_sets__itype",
        "suffix",
    ]
)
Hide code cell output
uid key created_by__name records__name cell_types__name feature_sets__itype suffix
id
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad Test User1 {Experiment 2, IFNG, DMSO} {B cell, T cell} {Feature, bionty.Gene.ensembl_gene_id} .h5ad
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad Test User1 {IFNG, Experiment 1, DMSO} {B cell, T cell, CD8-positive, alpha-beta T cell} {Feature, bionty.Gene.ensembl_gene_id} .h5ad
3 zj57bUkranOBJd6k0000 iris.parquet Test User1 {None} {None} {None} .parquet
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz Test User1 {None} {None} {None} .fastq.gz
1 aqH45WkcWo8I3yv00000 images/my_image.jpg Test User1 {None} {None} {None} .jpg

You can include information about which artifact measures which feature.

df = ln.Artifact.to_dataframe(features=True)
ln.view(df)  # optionally use ln.view() to see dtypes
Hide code cell output 
→ queried for all categorical features with dtype ULabel or Record and non-categorical features: (7) ['perturbation', 'sample_note', 'temperature', 'experiment', 'date_of_study', 'study_note', 'study_metadata']
uidkeyperturbationtemperatureexperimentdate_of_studystudy_notestudy_metadata
idstrstrcat[Record]floatcat[Record]datestrdict
5PhdYmzsXCM08HBLV0000examples/dataset2.h5ad{'IFNG', 'DMSO'}22.6Experiment 22025-02-13nan{'detail1': '456', 'detail2': 2}
4ONn1hIQSokFgAgRH0000examples/dataset1.h5ad{'IFNG', 'DMSO'}21.6Experiment 12024-12-01We had a great time performing this study and the results look compelling.{'detail1': '123', 'detail2': 1}
3zj57bUkranOBJd6k0000iris.parquetnannannannannannan
2RyfPBkpHIBcd3st30000raw/my_fastq.fastq.gznannannannannannan
1aqH45WkcWo8I3yv00000images/my_image.jpgnannannannannannan

The flattened table that includes information from all relevant registries is easier to understand than the normalized data.

ln.view()
Hide code cell output 
****************

* module: core *

****************

Artifact
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
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:33.197000+00:00 1 {'af': {'0': True}} None 1
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1
3 zj57bUkranOBJd6k0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.761000+00:00 1 {'af': {'0': True}} None 1
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.616000+00:00 1 {'af': {'0': True}} None 1
1 aqH45WkcWo8I3yv00000 images/my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.604000+00:00 1 {'af': {'0': True}} None 1 
Feature
uid name dtype is_type unit description array_rank array_size array_shape proxy_dtype synonyms _expect_many _curation space_id type_id is_locked run_id created_at created_by_id _aux branch_id
id
9 o1w1PuWiSR2w study_metadata dict None None None 0 0 None None None None None 1 None False 1 2025-10-15 20:32:27.135000+00:00 1 {'af': {'0': None, '1': True, '2': False}} 1
8 AOF4feVcJZPm study_note str None None None 0 0 None None None None None 1 None False 1 2025-10-15 20:32:27.129000+00:00 1 {'af': {'0': None, '1': True, '2': False}} 1
7 kSzPzfIpRmS5 date_of_study date None None None 0 0 None None None None None 1 None False 1 2025-10-15 20:32:27.122000+00:00 1 {'af': {'0': None, '1': True, '2': False}} 1
6 EAF2Jk1BbeEi experiment cat[Record] None None None 0 0 None None None None None 1 None False 1 2025-10-15 20:32:27.115000+00:00 1 {'af': {'0': None, '1': True, '2': False}} 1
5 4tEECJ390XM7 temperature float None None None 0 0 None None None None None 1 None False 1 2025-10-15 20:32:27.108000+00:00 1 {'af': {'0': None, '1': True, '2': False}} 1
4 wyNJqGGGRq5C cell_type_by_model cat[bionty.CellType] None None None 0 0 None None None None None 1 None False 1 2025-10-15 20:32:27.101000+00:00 1 {'af': {'0': None, '1': True, '2': False}} 1
3 vzI1Ba6NRFrC cell_type_by_expert cat[bionty.CellType] None None None 0 0 None None None None None 1 None False 1 2025-10-15 20:32:27.094000+00:00 1 {'af': {'0': None, '1': True, '2': False}} 1 
FeatureValue
value hash space_id feature_id is_locked run_id created_at created_by_id _aux branch_id
id
1 21.6 XftFE5byhwPHY-11WjfNAw 1 5 False 1 2025-10-15 20:32:30.879000+00:00 1 None 1
2 2024-12-01 gNXeOkGaab5bqWC7D--aHQ 1 7 False 1 2025-10-15 20:32:30.887000+00:00 1 None 1
3 We had a great time performing this study and ... ixx1CqAyBO8WO7lLdLpqTg 1 8 False 1 2025-10-15 20:32:30.889000+00:00 1 None 1
4 {'detail1': '123', 'detail2': 1} nJ33A6k51yp-1ZlqFabWdw 1 9 False 1 2025-10-15 20:32:30.891000+00:00 1 None 1
5 22.6 54rmFUZH0WdllA5alp-64g 1 5 False 1 2025-10-15 20:32:33.241000+00:00 1 None 1
6 2025-02-13 SGTsR3XvXFi5jZ8UjC6YaQ 1 7 False 1 2025-10-15 20:32:33.247000+00:00 1 None 1
7 {'detail1': '456', 'detail2': 2} QAU2Is6uXBBgz8zC_p-rAQ 1 9 False 1 2025-10-15 20:32:33.249000+00:00 1 None 1 
Record
uid name is_type description reference reference_type space_id type_id schema_id is_locked run_id created_at created_by_id _aux branch_id
id
3 CPrRSJWQsFgqUSMm Experiment 1 False None None None 1 None None False 1 2025-10-15 20:32:27.157000+00:00 1 None 1
4 WHZ9tVK1dMG0zc6a Experiment 2 False None None None 1 None None False 1 2025-10-15 20:32:27.157000+00:00 1 None 1
1 XV6hlA4Lc6Wskcil DMSO False None None None 1 None None False 1 2025-10-15 20:32:27.146000+00:00 1 None 1
2 oFa7TI2jKHIr0N8l IFNG False None None None 1 None None False 1 2025-10-15 20:32:27.146000+00:00 1 None 1 
Run
uid name started_at finished_at params reference reference_type _is_consecutive _status_code space_id transform_id report_id _logfile_id environment_id initiated_by_run_id is_locked created_at created_by_id _aux branch_id
id
1 JuDGwproYJ6Y0uZZ None 2025-10-15 20:32:25.356712+00:00 None None None None None -1 1 1 None None None None False 2025-10-15 20:32:25.357000+00:00 1 None 1 
Schema
uid name description n is_type itype otype dtype hash minimal_set ordered_set maximal_set _curation slot space_id type_id validated_by_id composite_id is_locked run_id created_at created_by_id _aux branch_id
id
1 0000000000000000 valid_features None -1 False Feature None None kMi7B_N88uu-YnbTLDU-DA True False False None None 1 None None None False 1 2025-10-15 20:32:27.177000+00:00 1 {'af': {'2': True}} 1
2 0000000000000001 valid_ensembl_gene_ids None -1 False bionty.Gene.ensembl_gene_id None num 1gocc_TJ1RU2bMwDRK-WUA True False False None None 1 None None None False 1 2025-10-15 20:32:27.185000+00:00 1 {'af': {'2': True}} 1
3 0000000000000002 anndata_ensembl_gene_ids_and_valid_features_in... None -1 False Composite AnnData num UR_ozz2VI2sY8ckXop2RAg True False False None None 1 None None None False 1 2025-10-15 20:32:27.191000+00:00 1 {'af': {'2': True}} 1
4 6oABnUrZqGUNIxTJ None None 4 False Feature None None N1xzA69lR7L8a5T1d9DnrQ True False False None None 1 None None None False 1 2025-10-15 20:32:30.853000+00:00 1 {'af': {'2': False}} 1
5 qEPkEJZjQub4VJXQ None None 3 False bionty.Gene.ensembl_gene_id None num WlLDN3zWgqWe_JijdKPOlg True False False None None 1 None None None False 1 2025-10-15 20:32:30.862000+00:00 1 {'af': {'2': False}} 1
6 7r9B4tLtXvjnmuxE None None 2 False Feature None None vLhcZ8kJpmhv-Yt3uWmYOQ True False False None None 1 None None None False 1 2025-10-15 20:32:33.215000+00:00 1 {'af': {'2': False}} 1
7 fHW1P7pdDQYSiSQb None None 3 False bionty.Gene.ensembl_gene_id None num E_omq1L6l9JkW_T50wgyfg True False False None None 1 None None None False 1 2025-10-15 20:32:33.224000+00:00 1 {'af': {'2': False}} 1 
Storage
uid root description type region instance_uid space_id is_locked run_id created_at created_by_id _aux branch_id
id
1 1iZYqxtg7fGm /home/runner/work/lamindb/lamindb/docs/test-re... None local None hlGq1WkbeSSf 1 False None 2025-10-15 20:32:21.983000+00:00 1 None 1 
Transform
uid key description type source_code hash reference reference_type space_id _template_id version is_latest is_locked created_at created_by_id _aux branch_id
id
1 Wc8F4siRSKMZ0000 registries.ipynb Query & search registries notebook None None None None 1 None None True False 2025-10-15 20:32:25.352000+00:00 1 None 1 
******************

* module: bionty *

******************

CellType
uid name ontology_id abbr synonyms description space_id source_id is_locked run_id created_at created_by_id _aux branch_id
id
4 4bKGljt0 cell CL:0000000 None None A Material Entity Of Anatomical Origin (Part O... 1 16 False 1 2025-10-15 20:32:27.903000+00:00 1 None 1
5 22LvKd01 T cell CL:0000084 None T lymphocyte|T-lymphocyte|T-cell A Type Of Lymphocyte Whose Defining Characteri... 1 16 False 1 2025-10-15 20:32:27.903000+00:00 1 None 1
6 2K93w3xO motile cell CL:0000219 None None A Cell That Moves By Its Own Activities. 1 16 False 1 2025-10-15 20:32:27.903000+00:00 1 None 1
7 2cXC7cgF single nucleate cell CL:0000226 None None A Cell With A Single Nucleus. 1 16 False 1 2025-10-15 20:32:27.903000+00:00 1 None 1
8 4WnpvUTH eukaryotic cell CL:0000255 None None Any Cell That In Taxon Some Eukaryota. 1 16 False 1 2025-10-15 20:32:27.903000+00:00 1 None 1
9 X6c7osZ5 lymphocyte CL:0000542 None None A Lymphocyte Is A Leukocyte Commonly Found In ... 1 16 False 1 2025-10-15 20:32:27.903000+00:00 1 None 1
10 3VEAlFdi leukocyte CL:0000738 None leucocyte|white blood cell An Achromatic Cell Of The Myeloid Or Lymphoid ... 1 16 False 1 2025-10-15 20:32:27.903000+00:00 1 None 1 
Gene
uid symbol stable_id ensembl_gene_id ncbi_gene_ids biotype synonyms description space_id source_id organism_id is_locked run_id created_at created_by_id _aux branch_id
id
4 iFxDa8hoEWuW CD38 None ENSG00000004468 952 protein_coding CADPR1 CD38 molecule 1 7 1 False 1 2025-10-15 20:32:33.187000+00:00 1 None 1
1 6Aqvc8ckDYeN CD8A None ENSG00000153563 925 protein_coding P32|CD8|CD8ALPHA CD8 subunit alpha 1 7 1 False 1 2025-10-15 20:32:30.819000+00:00 1 None 1
2 1j4At3x7akJU CD4 None ENSG00000010610 920 protein_coding T4|LEU-3 CD4 molecule 1 7 1 False 1 2025-10-15 20:32:30.819000+00:00 1 None 1
3 3bhNYquOnA4s CD14 None ENSG00000170458 929 protein_coding CD14 molecule 1 7 1 False 1 2025-10-15 20:32:30.819000+00:00 1 None 1 
Organism
uid name ontology_id scientific_name synonyms description space_id source_id is_locked run_id created_at created_by_id _aux branch_id
id
1 1dpCL6Td human NCBITaxon:9606 Homo sapiens None None 1 1 False 1 2025-10-15 20:32:28.835000+00:00 1 None 1 
Source
uid entity organism name in_db currently_used description url md5 source_website space_id dataframe_artifact_id version is_locked run_id created_at created_by_id _aux branch_id
id
16 3T9KZcjQ bionty.CellType all cl False True Cell Ontology http://purl.obolibrary.org/obo/cl/releases/202... None https://obophenotype.github.io/cell-ontology 1 None 2025-04-10 False None 2025-10-15 20:32:22.081000+00:00 1 None 1
1 33TUF039 bionty.Organism vertebrates ensembl False True Ensembl https://ftp.ensembl.org/pub/release-112/specie... None https://www.ensembl.org 1 None release-112 False None 2025-10-15 20:32:22.081000+00:00 1 None 1
2 6bbVUTCS bionty.Organism bacteria ensembl False True Ensembl https://ftp.ensemblgenomes.ebi.ac.uk/pub/bacte... None https://www.ensembl.org 1 None release-57 False None 2025-10-15 20:32:22.081000+00:00 1 None 1
3 6s9nV6xh bionty.Organism fungi ensembl False True Ensembl https://ftp.ensemblgenomes.ebi.ac.uk/pub/fungi... None https://www.ensembl.org 1 None release-57 False None 2025-10-15 20:32:22.081000+00:00 1 None 1
4 2PmTrc8x bionty.Organism metazoa ensembl False True Ensembl https://ftp.ensemblgenomes.ebi.ac.uk/pub/metaz... None https://www.ensembl.org 1 None release-57 False None 2025-10-15 20:32:22.081000+00:00 1 None 1
5 7GPHh16S bionty.Organism plants ensembl False True Ensembl https://ftp.ensemblgenomes.ebi.ac.uk/pub/plant... None https://www.ensembl.org 1 None release-57 False None 2025-10-15 20:32:22.081000+00:00 1 None 1
6 4tsksCMX bionty.Organism all ncbitaxon False True NCBItaxon Ontology http://purl.obolibrary.org/obo/ncbitaxon/2023-... None https://github.com/obophenotype/ncbitaxon 1 None 2023-06-20 False None 2025-10-15 20:32:22.081000+00:00 1 None 1

Auto-complete records

For registries with less than 100k records, auto-completing a Lookup object is the most convenient way of finding a record.

import bionty as bt

# query the database for all Records or all cell types
records = ln.Record.lookup()
cell_types = bt.CellType.lookup()
Show me a screenshot

With auto-complete, we find a record:

study1 = records.experiment_1
study1
Hide code cell output 
Record(uid='CPrRSJWQsFgqUSMm', name='Experiment 1', is_type=False, branch_id=1, space_id=1, created_by_id=1, run_id=1, created_at=2025-10-15 20:32:27 UTC, is_locked=False)

Get one record

get() errors if more than one matching records are found.

print(study1.uid)

# by uid
ln.Record.get(study1.uid)

# by field
ln.Record.get(name="Experiment 1")
Hide code cell output 
CPrRSJWQsFgqUSMm

Record(uid='CPrRSJWQsFgqUSMm', name='Experiment 1', is_type=False, branch_id=1, space_id=1, created_by_id=1, run_id=1, created_at=2025-10-15 20:32:27 UTC, is_locked=False)

Query records by fields

Filter for all artifacts annotated by a record and get the result as a dataframe:

ln.Artifact.filter(records=study1).to_dataframe()
Hide code cell output
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
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3 md5 True False 1 1 3 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1

filter() returns a QuerySet.

To access the results encoded in a filter statement, execute its return value with one of:

  • to_dataframe(): A pandas DataFrame with each record in a row.

  • one(): Exactly one record. Will raise an error if there is none. Is equivalent to the .get() method shown above.

  • one_or_none(): Either one record or None if there is no query result.

You can also use it as an iterator or get individual records via __getitem__ ([0], [1] etc.).

Note

The registries in LaminDB are Django Models and any Django query works.

LaminDB re-interprets Django’s API for data scientists.

What does this have to do with SQL?

Under the hood, any .filter() call translates into a SQL select statement.

LaminDB’s registries are object relational mappers (ORMs) that rely on Django for all the heavy lifting.

Of note, .one() and .one_or_none() are the two parts of LaminDB’s API that are borrowed from SQLAlchemy. In its first year, LaminDB built on SQLAlchemy.

Query datasets by features

The Artifact registry is the only registry that additionally allows to query by features.

ln.Artifact.filter(perturbation="DMSO").to_dataframe(features=True)

→ queried for all categorical features with dtype ULabel or Record and non-categorical features: (7) ['perturbation', 'sample_note', 'temperature', 'experiment', 'date_of_study', 'study_note', 'study_metadata']
uid key perturbation temperature experiment date_of_study study_note study_metadata
id
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad {IFNG, DMSO} 21.6 Experiment 1 2024-12-01 We had a great time performing this study and ... {'detail1': '123', 'detail2': 1}
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad {IFNG, DMSO} 22.6 Experiment 2 2025-02-13 NaN {'detail1': '456', 'detail2': 2}

You can also query for nested dictionary-like features.

ln.Artifact.filter(study_metadata__detail1="123").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
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3 md5 True False 1 1 3 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1 
ln.Artifact.filter(study_metadata__detail2=2).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
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3 md5 True False 1 1 3 None True False 1 2025-10-15 20:32:33.197000+00:00 1 {'af': {'0': True}} None 1

You can query for whether a dataset is annotated or not annotated by a feature.

ln.Artifact.filter(perturbation__isnull=True).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 aqH45WkcWo8I3yv00000 images/my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN md5 True False 1 1 None None True False 1 2025-10-15 20:32:26.604000+00:00 1 {'af': {'0': True}} None 1
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN md5 True False 1 1 None None True False 1 2025-10-15 20:32:26.616000+00:00 1 {'af': {'0': True}} None 1
3 zj57bUkranOBJd6k0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 md5 True False 1 1 None None True False 1 2025-10-15 20:32:26.761000+00:00 1 {'af': {'0': True}} None 1 
ln.Artifact.filter(perturbation__isnull=False).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
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3 md5 True False 1 1 3 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3 md5 True False 1 1 3 None True False 1 2025-10-15 20:32:33.197000+00:00 1 {'af': {'0': True}} None 1

Query runs by parameters

Here is an example for querying by parameters: Query by run parameters.

Search for records

You can search every registry via search(). For example, the Artifact registry.

ln.Artifact.search("iris").to_dataframe()
Hide code cell output
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
3 zj57bUkranOBJd6k0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150 md5 True False 1 1 None None True False 1 2025-10-15 20:32:26.761000+00:00 1 {'af': {'0': True}} None 1

Here is more background on search and examples for searching the entire cell type ontology: How does search work?

Filter operators

You can qualify the type of comparison in a query by using a comparator.

Below follows a list of the most import, but Django supports about two dozen field comparators field__comparator=value.

and

ln.Artifact.filter(suffix=".h5ad", records=study1).to_dataframe()
Hide code cell output
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
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3 md5 True False 1 1 3 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1

less than/ greater than

Or subset to artifacts greater than 10kB. Here, we can’t use keyword arguments, but need an explicit where statement.

ln.Artifact.filter(records=study1, size__gt=1e4).to_dataframe()
Hide code cell output
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
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3 md5 True False 1 1 3 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1

in

ln.Artifact.filter(suffix__in=[".jpg", ".fastq.gz"]).to_dataframe()
Hide code cell output
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 aqH45WkcWo8I3yv00000 images/my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None None md5 True False 1 1 None None True False 1 2025-10-15 20:32:26.604000+00:00 1 {'af': {'0': True}} None 1
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None None md5 True False 1 1 None None True False 1 2025-10-15 20:32:26.616000+00:00 1 {'af': {'0': True}} None 1

order by

ln.Artifact.filter().order_by("created_at").to_dataframe()
Hide code cell output
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 aqH45WkcWo8I3yv00000 images/my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.604000+00:00 1 {'af': {'0': True}} None 1
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.616000+00:00 1 {'af': {'0': True}} None 1
3 zj57bUkranOBJd6k0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.761000+00:00 1 {'af': {'0': True}} None 1
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:33.197000+00:00 1 {'af': {'0': True}} None 1 
# reverse ordering
ln.Artifact.filter().order_by("-created_at").to_dataframe()
Hide code cell output
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
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:33.197000+00:00 1 {'af': {'0': True}} None 1
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1
3 zj57bUkranOBJd6k0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.761000+00:00 1 {'af': {'0': True}} None 1
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.616000+00:00 1 {'af': {'0': True}} None 1
1 aqH45WkcWo8I3yv00000 images/my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.604000+00:00 1 {'af': {'0': True}} None 1 
ln.Artifact.filter().order_by("key").to_dataframe()
Hide code cell output
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
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:33.197000+00:00 1 {'af': {'0': True}} None 1
1 aqH45WkcWo8I3yv00000 images/my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.604000+00:00 1 {'af': {'0': True}} None 1
3 zj57bUkranOBJd6k0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.761000+00:00 1 {'af': {'0': True}} None 1
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.616000+00:00 1 {'af': {'0': True}} None 1 
# reverse ordering
ln.Artifact.filter().order_by("-key").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
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.616000+00:00 1 {'af': {'0': True}} None 1
3 zj57bUkranOBJd6k0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.761000+00:00 1 {'af': {'0': True}} None 1
1 aqH45WkcWo8I3yv00000 images/my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.604000+00:00 1 {'af': {'0': True}} None 1
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:33.197000+00:00 1 {'af': {'0': True}} None 1
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1

contains

ln.Transform.filter(description__contains="search").to_dataframe().head(5)
Hide code cell output
uid key description type source_code hash reference reference_type space_id _template_id version is_latest is_locked created_at created_by_id _aux branch_id
id
1 Wc8F4siRSKMZ0000 registries.ipynb Query & search registries notebook None None None None 1 None None True False 2025-10-15 20:32:25.352000+00:00 1 None 1

And case-insensitive:

ln.Transform.filter(description__icontains="Search").to_dataframe().head(5)
Hide code cell output
uid key description type source_code hash reference reference_type space_id _template_id version is_latest is_locked created_at created_by_id _aux branch_id
id
1 Wc8F4siRSKMZ0000 registries.ipynb Query & search registries notebook None None None None 1 None None True False 2025-10-15 20:32:25.352000+00:00 1 None 1

startswith

ln.Transform.filter(description__startswith="Query").to_dataframe()
Hide code cell output
uid key description type source_code hash reference reference_type space_id _template_id version is_latest is_locked created_at created_by_id _aux branch_id
id
1 Wc8F4siRSKMZ0000 registries.ipynb Query & search registries notebook None None None None 1 None None True False 2025-10-15 20:32:25.352000+00:00 1 None 1

or

ln.Artifact.filter(ln.Q(suffix=".jpg") | ln.Q(suffix=".fastq.gz")).to_dataframe()
Hide code cell output
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 aqH45WkcWo8I3yv00000 images/my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None None md5 True False 1 1 None None True False 1 2025-10-15 20:32:26.604000+00:00 1 {'af': {'0': True}} None 1
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None None md5 True False 1 1 None None True False 1 2025-10-15 20:32:26.616000+00:00 1 {'af': {'0': True}} None 1

negate/ unequal

ln.Artifact.filter(~ln.Q(suffix=".jpg")).to_dataframe()
Hide code cell output
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
2 RyfPBkpHIBcd3st30000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.616000+00:00 1 {'af': {'0': True}} None 1
3 zj57bUkranOBJd6k0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 md5 True False 1 1 NaN None True False 1 2025-10-15 20:32:26.761000+00:00 1 {'af': {'0': True}} None 1
4 ONn1hIQSokFgAgRH0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:30.829000+00:00 1 {'af': {'0': True}} None 1
5 PhdYmzsXCM08HBLV0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 md5 True False 1 1 3.0 None True False 1 2025-10-15 20:32:33.197000+00:00 1 {'af': {'0': True}} None 1