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.

import lamindb as ln

ln.track()
ln.Artifact(ln.examples.datasets.file_fastq(), key="raw/my_fastq.fastq.gz").save()
ln.Artifact(ln.examples.datasets.file_jpg_paradisi05(), key="my_image.jpg").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('0cRj7ibwCnqX0000', key='registries.ipynb'), started new Run('45HKdrbyHMYeSoOn') at 2025-10-27 08:26:56 UTC

→ notebook imports: bionty==1.8.1 lamindb==1.14a1

• recommendation: to identify the notebook across renames, pass the uid: ln.track("0cRj7ibwCnqX")

→ writing the in-memory object into cache

→ writing the in-memory object into cache

→ loading artifact into memory for validation

! 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)

→ writing the in-memory object into cache

→ loading artifact into memory for validation

! 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 to_dataframe(), 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 version is_latest is_locked created_at branch_id space_id storage_id run_id schema_id created_by_id
id
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 None True False 2025-10-27 08:27:04.365000+00:00 1 1 1 1 3.0 1
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 None True False 2025-10-27 08:27:01.877000+00:00 1 1 1 1 3.0 1
3 h5yntxOqRHvrdnJe0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 None True False 2025-10-27 08:26:58.130000+00:00 1 1 1 1 NaN 1
2 RLUqL0sOD1afo8eB0000 my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN None True False 2025-10-27 08:26:57.960000+00:00 1 1 1 1 NaN 1
1 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN None True False 2025-10-27 08:26:57.680000+00:00 1 1 1 1 NaN 1

You can include features.

ln.Artifact.to_dataframe(include="features")
Hide code cell output 
→ queried for all categorical features with dtype 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
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad {DMSO, IFNG} 22.6 Experiment 2 2025-02-13 NaN {'detail1': '456', 'detail2': 2}
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad {DMSO, IFNG} 21.6 Experiment 1 2024-12-01 We had a great time performing this study and ... {'detail1': '123', 'detail2': 1}
3 h5yntxOqRHvrdnJe0000 iris.parquet NaN NaN NaN NaN NaN NaN
2 RLUqL0sOD1afo8eB0000 my_image.jpg NaN NaN NaN NaN NaN NaN
1 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz NaN NaN NaN NaN NaN NaN

You can include fields from other registries.

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

You can also get an overview of the entire database.

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

* module: core *

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

Artifact
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
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 None True False 2025-10-27 08:27:04.365000+00:00 1 1 1 1 3.0 1
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 None True False 2025-10-27 08:27:01.877000+00:00 1 1 1 1 3.0 1
3 h5yntxOqRHvrdnJe0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 None True False 2025-10-27 08:26:58.130000+00:00 1 1 1 1 NaN 1
2 RLUqL0sOD1afo8eB0000 my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN None True False 2025-10-27 08:26:57.960000+00:00 1 1 1 1 NaN 1
1 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN None True False 2025-10-27 08:26:57.680000+00:00 1 1 1 1 NaN 1 
Feature
uid name dtype is_type unit description array_rank array_size array_shape proxy_dtype synonyms is_locked created_at branch_id space_id created_by_id run_id type_id
id
9 PHqRKsTgESf4 study_metadata dict None None None 0 0 None None None False 2025-10-27 08:26:58.524000+00:00 1 1 1 1 None
8 ODZguYeubU86 study_note str None None None 0 0 None None None False 2025-10-27 08:26:58.517000+00:00 1 1 1 1 None
7 v4qRx6GWQn9g date_of_study date None None None 0 0 None None None False 2025-10-27 08:26:58.511000+00:00 1 1 1 1 None
6 nlyrY9AwgJPT experiment cat[Record] None None None 0 0 None None None False 2025-10-27 08:26:58.505000+00:00 1 1 1 1 None
5 XmyYYqbqvYRQ temperature float None None None 0 0 None None None False 2025-10-27 08:26:58.497000+00:00 1 1 1 1 None
4 WtPtQUbhVIVx cell_type_by_model cat[bionty.CellType] None None None 0 0 None None None False 2025-10-27 08:26:58.489000+00:00 1 1 1 1 None
3 wCCn89V3QCun cell_type_by_expert cat[bionty.CellType] None None None 0 0 None None None False 2025-10-27 08:26:58.482000+00:00 1 1 1 1 None 
FeatureValue
value hash is_locked created_at branch_id space_id created_by_id run_id feature_id
id
7 {'detail1': '456', 'detail2': 2} QAU2Is6uXBBgz8zC_p-rAQ False 2025-10-27 08:27:04.416000+00:00 1 1 1 1 9
6 2025-02-13 SGTsR3XvXFi5jZ8UjC6YaQ False 2025-10-27 08:27:04.415000+00:00 1 1 1 1 7
5 22.6 54rmFUZH0WdllA5alp-64g False 2025-10-27 08:27:04.408000+00:00 1 1 1 1 5
4 {'detail1': '123', 'detail2': 1} nJ33A6k51yp-1ZlqFabWdw False 2025-10-27 08:27:01.938000+00:00 1 1 1 1 9
3 We had a great time performing this study and ... ixx1CqAyBO8WO7lLdLpqTg False 2025-10-27 08:27:01.936000+00:00 1 1 1 1 8
2 2024-12-01 gNXeOkGaab5bqWC7D--aHQ False 2025-10-27 08:27:01.934000+00:00 1 1 1 1 7
1 21.6 XftFE5byhwPHY-11WjfNAw False 2025-10-27 08:27:01.927000+00:00 1 1 1 1 5 
Record
uid name is_type description reference reference_type is_locked created_at branch_id space_id created_by_id type_id schema_id run_id
id
4 B7AljDVFaChRH4b9 Experiment 2 False None None None False 2025-10-27 08:26:58.547000+00:00 1 1 1 None None 1
3 lV3Qhb6EfVeqfXRe Experiment 1 False None None None False 2025-10-27 08:26:58.547000+00:00 1 1 1 None None 1
2 eDXsfLMh03upSomU IFNG False None None None False 2025-10-27 08:26:58.536000+00:00 1 1 1 None None 1
1 iFlCrecI2ztt6ik7 DMSO False None None None False 2025-10-27 08:26:58.536000+00:00 1 1 1 None None 1 
Run
uid name started_at finished_at params reference reference_type is_locked created_at branch_id space_id transform_id report_id _logfile_id environment_id created_by_id initiated_by_run_id
id
1 45HKdrbyHMYeSoOn None 2025-10-27 08:26:56.636810+00:00 None None None None False 2025-10-27 08:26:56.637000+00:00 1 1 1 None None None 1 None 
Schema
uid name description n is_type itype otype dtype hash minimal_set ordered_set maximal_set slot is_locked created_at branch_id space_id created_by_id run_id type_id validated_by_id composite_id
id
7 ksqaJnzPl20ecmVQ None None 3 False bionty.Gene.ensembl_gene_id None num E_omq1L6l9JkW_T50wgyfg True False False None False 2025-10-27 08:27:04.392000+00:00 1 1 1 1 None None None
6 mtE7EqpqVCiEM5kA None None 2 False Feature None None smjkpOczV5qhlasKjVcaLg True False False None False 2025-10-27 08:27:04.384000+00:00 1 1 1 1 None None None
5 b8zJYB6s4C6cMpVb None None 3 False bionty.Gene.ensembl_gene_id None num WlLDN3zWgqWe_JijdKPOlg True False False None False 2025-10-27 08:27:01.909000+00:00 1 1 1 1 None None None
4 gwkupwTM11vhfpoC None None 4 False Feature None None BRLAdj7nzhynOS384df0Ag True False False None False 2025-10-27 08:27:01.901000+00:00 1 1 1 1 None None None
3 0000000000000002 anndata_ensembl_gene_ids_and_valid_features_in... None -1 False Composite AnnData num UR_ozz2VI2sY8ckXop2RAg True False False None False 2025-10-27 08:26:58.580000+00:00 1 1 1 1 None None None
2 0000000000000001 valid_ensembl_gene_ids None -1 False bionty.Gene.ensembl_gene_id None num 1gocc_TJ1RU2bMwDRK-WUA True False False None False 2025-10-27 08:26:58.574000+00:00 1 1 1 1 None None None
1 0000000000000000 valid_features None -1 False Feature None None kMi7B_N88uu-YnbTLDU-DA True False False None False 2025-10-27 08:26:58.566000+00:00 1 1 1 1 None None None 
Storage
uid root description type region instance_uid is_locked created_at branch_id space_id created_by_id run_id
id
1 tzIBKYIEox27 /home/runner/work/lamindb/lamindb/docs/test-re... None local None hlGq1WkbeSSf False 2025-10-27 08:26:53.369000+00:00 1 1 1 None 
Transform
uid key description type source_code hash reference reference_type version is_latest is_locked created_at branch_id space_id created_by_id _template_id
id
1 0cRj7ibwCnqX0000 registries.ipynb Query & search registries notebook None None None None None True False 2025-10-27 08:26:56.632000+00:00 1 1 1 None 
******************

* module: bionty *

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

CellType
uid name ontology_id abbr synonyms description is_locked created_at branch_id space_id created_by_id run_id source_id
id
16 2OTzqBTM mature T cell CL:0002419 None mature T-cell|CD3e-positive T cell A T Cell That Expresses A T Cell Receptor Comp... False 2025-10-27 08:26:59.476000+00:00 1 1 1 1 16
15 u3sr1Gdf nucleate cell CL:0002242 None None A Cell Containing At Least One Nucleus. False 2025-10-27 08:26:59.476000+00:00 1 1 1 1 16
14 4Ilrnj9U hematopoietic cell CL:0000988 None haemopoietic cell|haematopoietic cell|hemopoie... A Cell Of A Hematopoietic Lineage. False 2025-10-27 08:26:59.476000+00:00 1 1 1 1 16
13 2Jgr5Xx4 mononuclear leukocyte CL:0000842 None mononuclear cell A Leukocyte With A Single Non-Segmented Nucleu... False 2025-10-27 08:26:59.476000+00:00 1 1 1 1 16
12 4BEwsp1Q mature alpha-beta T cell CL:0000791 None mature alpha-beta T-cell|mature alpha-beta T l... A Alpha-Beta T Cell That Has A Mature Phenotype. False 2025-10-27 08:26:59.476000+00:00 1 1 1 1 16
11 6By01L04 alpha-beta T cell CL:0000789 None alpha-beta T-cell|alpha-beta T-lymphocyte|alph... A T Cell That Expresses An Alpha-Beta T Cell R... False 2025-10-27 08:26:59.476000+00:00 1 1 1 1 16
10 3VEAlFdi leukocyte CL:0000738 None leucocyte|white blood cell An Achromatic Cell Of The Myeloid Or Lymphoid ... False 2025-10-27 08:26:59.476000+00:00 1 1 1 1 16 
Gene
uid symbol stable_id ensembl_gene_id ncbi_gene_ids biotype synonyms description is_locked created_at branch_id space_id created_by_id run_id source_id organism_id
id
4 iFxDa8hoEWuW CD38 None ENSG00000004468 952 protein_coding CADPR1 CD38 molecule False 2025-10-27 08:27:04.355000+00:00 1 1 1 1 7 1
3 3bhNYquOnA4s CD14 None ENSG00000170458 929 protein_coding CD14 molecule False 2025-10-27 08:27:01.867000+00:00 1 1 1 1 7 1
2 1j4At3x7akJU CD4 None ENSG00000010610 920 protein_coding T4|LEU-3 CD4 molecule False 2025-10-27 08:27:01.867000+00:00 1 1 1 1 7 1
1 6Aqvc8ckDYeN CD8A None ENSG00000153563 925 protein_coding P32|CD8|CD8ALPHA CD8 subunit alpha False 2025-10-27 08:27:01.867000+00:00 1 1 1 1 7 1 
Organism
uid name ontology_id scientific_name synonyms description is_locked created_at branch_id space_id created_by_id run_id source_id
id
1 1dpCL6Td human NCBITaxon:9606 Homo sapiens None None False 2025-10-27 08:26:59.943000+00:00 1 1 1 1 1 
Source
uid entity organism name in_db currently_used description url md5 source_website version is_locked created_at branch_id space_id created_by_id run_id dataframe_artifact_id
id
33 5JnVODh4 BioSample all ncbi False True NCBI BioSample attributes s3://bionty-assets/df_all__ncbi__2023-09__BioS... None https://www.ncbi.nlm.nih.gov/biosample/docs/at... 2023-09 False 2025-10-27 08:26:53.468000+00:00 1 1 1 None None
32 MJRqduf9 bionty.Ethnicity human hancestro False True Human Ancestry Ontology http://purl.obolibrary.org/obo/hancestro/relea... None https://github.com/EBISPOT/hancestro 3.0 False 2025-10-27 08:26:53.468000+00:00 1 1 1 None None
31 10va5JSt bionty.DevelopmentalStage mouse mmusdv False True Mouse Developmental Stages https://github.com/obophenotype/developmental-... None https://github.com/obophenotype/developmental-... 2024-05-28 False 2025-10-27 08:26:53.468000+00:00 1 1 1 None None
30 1GbFkOdz bionty.DevelopmentalStage human hsapdv False True Human Developmental Stages https://github.com/obophenotype/developmental-... None https://github.com/obophenotype/developmental-... 2024-05-28 False 2025-10-27 08:26:53.468000+00:00 1 1 1 None None
29 1atB0WnU Drug all chebi False False Chemical Entities of Biological Interest s3://bionty-assets/df_all__chebi__2024-07-27__... None https://www.ebi.ac.uk/chebi/ 2024-07-27 False 2025-10-27 08:26:53.468000+00:00 1 1 1 None None
28 ugaIoIlj Drug all dron False True Drug Ontology http://purl.obolibrary.org/obo/dron/releases/2... None https://bioportal.bioontology.org/ontologies/DRON 2024-08-05 False 2025-10-27 08:26:53.468000+00:00 1 1 1 None None
27 3rm9aOzL BFXPipeline all lamin False True Bioinformatics Pipeline s3://bionty-assets/df_all__lamin__1.0.0__BFXpi... None https://lamin.ai 1.0.0 False 2025-10-27 08:26:53.468000+00:00 1 1 1 None None

Auto-complete records

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

records = ln.Record.lookup()

With auto-complete, we find a record:

experiment_1 = records.experiment_1
experiment_1
Hide code cell output 
Record(uid='lV3Qhb6EfVeqfXRe', name='Experiment 1', is_type=False, description=None, reference=None, reference_type=None, branch_id=1, space_id=1, created_by_id=1, type_id=None, schema_id=None, run_id=1, created_at=2025-10-27 08:26:58 UTC, is_locked=False)

This works for any SQLRecord registry, e.g., also for plugin bionty.

import bionty as bt

cell_types = bt.CellType.lookup()
Show me a screenshot

Get one record

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

ln.Record.get(experiment_1.uid)  # by uid
ln.Record.get(name="Experiment 1")  # by field
Hide code cell output 
Record(uid='lV3Qhb6EfVeqfXRe', name='Experiment 1', is_type=False, description=None, reference=None, reference_type=None, branch_id=1, space_id=1, created_by_id=1, type_id=None, schema_id=None, run_id=1, created_at=2025-10-27 08:26:58 UTC, is_locked=False)

Query records by fields

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

qs = ln.Artifact.filter(suffix=".fastq.qz")

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.

Alternatively,

  • use the QuerySet as an iterator

  • get individual records via qs[0], qs[1]

For example:

qs.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

Note that the SQLRecord registries in LaminDB are Django Models and any Django query works.

Query records by features

The Artifact, Record, and Run registries can be queried by features.

ln.Artifact.filter(perturbation="DMSO").to_dataframe(include="features")
Hide code cell output 
→ queried for all categorical features with dtype 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
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad {DMSO, IFNG} 22.6 Experiment 2 2025-02-13 NaN {'detail1': '456', 'detail2': 2}
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad {DMSO, IFNG} 21.6 Experiment 1 2024-12-01 We had a great time performing this study and ... {'detail1': '123', 'detail2': 1}

You can also query for nested dictionary-like features.

ln.Artifact.filter(study_metadata__detail1="123").to_dataframe(include="features")
Hide code cell output 
→ queried for all categorical features with dtype 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 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad {DMSO, IFNG} 21.6 Experiment 1 2024-12-01 We had a great time performing this study and ... {'detail1': '123', 'detail2': 1} 
ln.Artifact.filter(study_metadata__detail2=2).to_dataframe(include="features")
Hide code cell output 
→ queried for all categorical features with dtype 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_metadata
id
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad {DMSO, IFNG} 22.6 Experiment 2 2025-02-13 {'detail1': '456', 'detail2': 2}

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

ln.Artifact.filter(perturbation__isnull=True).to_dataframe(include="features")
Hide code cell output 
→ queried for all categorical features with dtype Record and non-categorical features: (7) ['perturbation', 'sample_note', 'temperature', 'experiment', 'date_of_study', 'study_note', 'study_metadata']
uid key
id
3 h5yntxOqRHvrdnJe0000 iris.parquet
2 RLUqL0sOD1afo8eB0000 my_image.jpg
1 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz 
ln.Artifact.filter(perturbation__isnull=False).to_dataframe(include="features")
Hide code cell output 
→ queried for all categorical features with dtype 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
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad {DMSO, IFNG} 22.6 Experiment 2 2025-02-13 NaN {'detail1': '456', 'detail2': 2}
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad {DMSO, IFNG} 21.6 Experiment 1 2024-12-01 We had a great time performing this study and ... {'detail1': '123', 'detail2': 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 version is_latest is_locked created_at branch_id space_id storage_id run_id schema_id created_by_id
id
3 h5yntxOqRHvrdnJe0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150 None True False 2025-10-27 08:26:58.130000+00:00 1 1 1 1 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=experiment_1).to_dataframe()
Hide code cell output
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
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3 None True False 2025-10-27 08:27:01.877000+00:00 1 1 1 1 3 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=experiment_1, size__gt=1e4).to_dataframe()
Hide code cell output
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
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3 None True False 2025-10-27 08:27:01.877000+00:00 1 1 1 1 3 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 version is_latest is_locked created_at branch_id space_id storage_id run_id schema_id created_by_id
id
2 RLUqL0sOD1afo8eB0000 my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None None None True False 2025-10-27 08:26:57.960000+00:00 1 1 1 1 None 1
1 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None None None True False 2025-10-27 08:26:57.680000+00:00 1 1 1 1 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 version is_latest is_locked created_at branch_id space_id storage_id run_id schema_id created_by_id
id
1 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN None True False 2025-10-27 08:26:57.680000+00:00 1 1 1 1 NaN 1
2 RLUqL0sOD1afo8eB0000 my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN None True False 2025-10-27 08:26:57.960000+00:00 1 1 1 1 NaN 1
3 h5yntxOqRHvrdnJe0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 None True False 2025-10-27 08:26:58.130000+00:00 1 1 1 1 NaN 1
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 None True False 2025-10-27 08:27:01.877000+00:00 1 1 1 1 3.0 1
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 None True False 2025-10-27 08:27:04.365000+00:00 1 1 1 1 3.0 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 version is_latest is_locked created_at branch_id space_id storage_id run_id schema_id created_by_id
id
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 None True False 2025-10-27 08:27:04.365000+00:00 1 1 1 1 3.0 1
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 None True False 2025-10-27 08:27:01.877000+00:00 1 1 1 1 3.0 1
3 h5yntxOqRHvrdnJe0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 None True False 2025-10-27 08:26:58.130000+00:00 1 1 1 1 NaN 1
2 RLUqL0sOD1afo8eB0000 my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN None True False 2025-10-27 08:26:57.960000+00:00 1 1 1 1 NaN 1
1 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN None True False 2025-10-27 08:26:57.680000+00:00 1 1 1 1 NaN 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 version is_latest is_locked created_at branch_id space_id storage_id run_id schema_id created_by_id
id
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 None True False 2025-10-27 08:27:01.877000+00:00 1 1 1 1 3.0 1
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 None True False 2025-10-27 08:27:04.365000+00:00 1 1 1 1 3.0 1
3 h5yntxOqRHvrdnJe0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 None True False 2025-10-27 08:26:58.130000+00:00 1 1 1 1 NaN 1
2 RLUqL0sOD1afo8eB0000 my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN None True False 2025-10-27 08:26:57.960000+00:00 1 1 1 1 NaN 1
1 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN None True False 2025-10-27 08:26:57.680000+00:00 1 1 1 1 NaN 1 
# reverse ordering
ln.Artifact.filter().order_by("-key").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 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN None True False 2025-10-27 08:26:57.680000+00:00 1 1 1 1 NaN 1
2 RLUqL0sOD1afo8eB0000 my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None NaN None True False 2025-10-27 08:26:57.960000+00:00 1 1 1 1 NaN 1
3 h5yntxOqRHvrdnJe0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 None True False 2025-10-27 08:26:58.130000+00:00 1 1 1 1 NaN 1
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 None True False 2025-10-27 08:27:04.365000+00:00 1 1 1 1 3.0 1
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 None True False 2025-10-27 08:27:01.877000+00:00 1 1 1 1 3.0 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 version is_latest is_locked created_at branch_id space_id created_by_id _template_id
id
1 0cRj7ibwCnqX0000 registries.ipynb Query & search registries notebook None None None None None True False 2025-10-27 08:26:56.632000+00:00 1 1 1 None

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 version is_latest is_locked created_at branch_id space_id created_by_id _template_id
id
1 0cRj7ibwCnqX0000 registries.ipynb Query & search registries notebook None None None None None True False 2025-10-27 08:26:56.632000+00:00 1 1 1 None

startswith

ln.Transform.filter(description__startswith="Query").to_dataframe()
Hide code cell output
uid key description type source_code hash reference reference_type version is_latest is_locked created_at branch_id space_id created_by_id _template_id
id
1 0cRj7ibwCnqX0000 registries.ipynb Query & search registries notebook None None None None None True False 2025-10-27 08:26:56.632000+00:00 1 1 1 None

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 version is_latest is_locked created_at branch_id space_id storage_id run_id schema_id created_by_id
id
2 RLUqL0sOD1afo8eB0000 my_image.jpg None .jpg None None 29358 r4tnqmKI_SjrkdLzpuWp4g None None None True False 2025-10-27 08:26:57.960000+00:00 1 1 1 1 None 1
1 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None None None True False 2025-10-27 08:26:57.680000+00:00 1 1 1 1 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 version is_latest is_locked created_at branch_id space_id storage_id run_id schema_id created_by_id
id
5 vJZG8HcQ1r3CpOgq0000 examples/dataset2.h5ad None .h5ad dataset AnnData 26896 RKJjWbINYNIwYU8BxCejMw None 3.0 None True False 2025-10-27 08:27:04.365000+00:00 1 1 1 1 3.0 1
4 bY5g1rvmSa6TxjdS0000 examples/dataset1.h5ad None .h5ad dataset AnnData 31672 FB3CeMjmg1ivN6HDy6wsSg None 3.0 None True False 2025-10-27 08:27:01.877000+00:00 1 1 1 1 3.0 1
3 h5yntxOqRHvrdnJe0000 iris.parquet None .parquet dataset DataFrame 5131 uibx2Y2NVd4NYDRysAecBA None 150.0 None True False 2025-10-27 08:26:58.130000+00:00 1 1 1 1 NaN 1
1 E9lBLim9YxXQGRcf0000 raw/my_fastq.fastq.gz None .fastq.gz None None 20 hi7ZmAzz8sfMd3vIQr-57Q None NaN None True False 2025-10-27 08:26:57.680000+00:00 1 1 1 1 NaN 1