Query & search registries

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

# pip install lamindb
!lamin init --storage ./test-registries --modules bionty

Show code cell output 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()

Show code cell output Hide code cell output

→ connected lamindb: testuser1/test-registries

→ created Transform('1quXazN4y3mp0000', key='registries.ipynb'), started new Run('sgx6X0TG8ID2fFPU') at 2026-01-11 16:52:34 UTC

→ notebook imports: bionty==2.0.0 lamindb==2.0.0

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

→ writing the in-memory object into cache

! rather than passing a string 'cat[Record]' to dtype, consider passing a Python object

! rather than passing a string 'str' to dtype, consider passing a Python object

! rather than passing a string 'cat[bionty.CellType]' to dtype, consider passing a Python object

! rather than passing a string 'cat[bionty.CellType]' to dtype, consider passing a Python object

! rather than passing a string 'float' to dtype, consider passing a Python object

! rather than passing a string 'cat[Record]' to dtype, consider passing a Python object

! rather than passing a string 'date' to dtype, consider passing a Python object

! rather than passing a string 'str' to dtype, consider passing a Python object

→ writing the in-memory object into cache

→ loading artifact into memory for validation

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

→ writing the in-memory object into cache

→ loading artifact into memory for validation

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

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

Show code cell output Hide 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
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	None	.h5ad	dataset	AnnData	26896	RKJjWbINYNIwYU8BxCejMw	None	3.0	None	True	False	2026-01-11 16:52:41.799000+00:00	1	1	3	1	3.0	3
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3.0	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3.0	3
3	mC8fyHQqBUPG3oMl0000	iris.parquet	None	.parquet	dataset	DataFrame	5202	LnPHC8qIQlHJMqcum1eWVQ	None	150.0	None	True	False	2026-01-11 16:52:35.554000+00:00	1	1	3	1	NaN	3
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	None	.jpg	None	None	29358	r4tnqmKI_SjrkdLzpuWp4g	None	NaN	None	True	False	2026-01-11 16:52:35.394000+00:00	1	1	3	1	NaN	3
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	None	.fastq.gz	None	None	20	hi7ZmAzz8sfMd3vIQr-57Q	None	NaN	None	True	False	2026-01-11 16:52:35.240000+00:00	1	1	3	1	NaN	3

You can include features.

ln.Artifact.to_dataframe(include="features")

Show code cell output Hide code cell output

→ queried for all categorical features of dtypes Record or ULabel 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	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	{IFNG, DMSO}	22.6	Experiment 2	2025-02-13	NaN	{'detail1': '456', 'detail2': 2}
4	aVheemRVsaXofykN0000	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}
3	mC8fyHQqBUPG3oMl0000	iris.parquet	NaN	NaN	NaN	NaT	NaN	NaN
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	NaN	NaN	NaN	NaT	NaN	NaN
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	NaN	NaN	NaN	NaT	NaN	NaN

You can include fields from other registries.

ln.Artifact.to_dataframe(
    include=[
        "created_by__name",
        "records__name",
        "cell_types__name",
        "schemas__itype",
    ]
)

Show code cell output Hide code cell output

	uid	key	created_by__name	records__name	cell_types__name	schemas__itype
id
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	Test User1	{IFNG, DMSO, Experiment 2}	{B cell, T cell}	{bionty.Gene.ensembl_gene_id, Feature}
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	Test User1	{IFNG, DMSO, Experiment 1}	{B cell, T cell, CD8-positive, alpha-beta T cell}	{bionty.Gene.ensembl_gene_id, Feature}
3	mC8fyHQqBUPG3oMl0000	iris.parquet	Test User1	{None}	{None}	{None}
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	Test User1	{None}	{None}	{None}
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	Test User1	{None}	{None}	{None}

You can also get an overview of the entire database.

ln.view()

Show code cell output Hide 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
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	None	.h5ad	dataset	AnnData	26896	RKJjWbINYNIwYU8BxCejMw	None	3.0	None	True	False	2026-01-11 16:52:41.799000+00:00	1	1	3	1	3.0	3
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3.0	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3.0	3
3	mC8fyHQqBUPG3oMl0000	iris.parquet	None	.parquet	dataset	DataFrame	5202	LnPHC8qIQlHJMqcum1eWVQ	None	150.0	None	True	False	2026-01-11 16:52:35.554000+00:00	1	1	3	1	NaN	3
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	None	.jpg	None	None	29358	r4tnqmKI_SjrkdLzpuWp4g	None	NaN	None	True	False	2026-01-11 16:52:35.394000+00:00	1	1	3	1	NaN	3
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	None	.fastq.gz	None	None	20	hi7ZmAzz8sfMd3vIQr-57Q	None	NaN	None	True	False	2026-01-11 16:52:35.240000+00:00	1	1	3	1	NaN	3

Feature

	uid	name	_dtype_str	unit	description	array_rank	array_size	array_shape	synonyms	default_value	nullable	coerce	is_locked	is_type	created_at	branch_id	space_id	created_by_id	run_id	type_id
id
9	YZfjJRyBAgUH	study_metadata	dict	None	None	0	0	None	None	None	True	None	False	False	2026-01-11 16:52:36.528000+00:00	1	1	3	1	None
8	oxI5niQ0GMNA	study_note	str	None	None	0	0	None	None	None	True	None	False	False	2026-01-11 16:52:36.522000+00:00	1	1	3	1	None
7	OR9XEkaVp5lf	date_of_study	date	None	None	0	0	None	None	None	True	None	False	False	2026-01-11 16:52:36.515000+00:00	1	1	3	1	None
6	QnF4SskOO8kO	experiment	cat[Record]	None	None	0	0	None	None	None	True	None	False	False	2026-01-11 16:52:36.508000+00:00	1	1	3	1	None
5	UeJrQi3nLaGI	temperature	float	None	None	0	0	None	None	None	True	None	False	False	2026-01-11 16:52:36.500000+00:00	1	1	3	1	None
4	QrnW1mal9EAn	cell_type_by_model	cat[bionty.CellType]	None	None	0	0	None	None	None	True	None	False	False	2026-01-11 16:52:36.493000+00:00	1	1	3	1	None
3	fXPZzUQn2ZeI	cell_type_by_expert	cat[bionty.CellType]	None	None	0	0	None	None	None	True	None	False	False	2026-01-11 16:52:36.486000+00:00	1	1	3	1	None

JsonValue

	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	2026-01-11 16:52:41.843000+00:00	1	1	3	1	9
6	2025-02-13	SGTsR3XvXFi5jZ8UjC6YaQ	False	2026-01-11 16:52:41.842000+00:00	1	1	3	1	7
5	22.6	54rmFUZH0WdllA5alp-64g	False	2026-01-11 16:52:41.835000+00:00	1	1	3	1	5
4	{'detail1': '123', 'detail2': 1}	nJ33A6k51yp-1ZlqFabWdw	False	2026-01-11 16:52:39.538000+00:00	1	1	3	1	9
3	We had a great time performing this study and ...	ixx1CqAyBO8WO7lLdLpqTg	False	2026-01-11 16:52:39.536000+00:00	1	1	3	1	8
2	2024-12-01	gNXeOkGaab5bqWC7D--aHQ	False	2026-01-11 16:52:39.534000+00:00	1	1	3	1	7
1	21.6	XftFE5byhwPHY-11WjfNAw	False	2026-01-11 16:52:39.527000+00:00	1	1	3	1	5

Record

	uid	name	description	reference	reference_type	extra_data	is_locked	is_type	created_at	branch_id	space_id	created_by_id	type_id	schema_id	run_id
id
4	k3HvcILRn7nmod3J	Experiment 2	None	None	None	None	False	False	2026-01-11 16:52:35.922000+00:00	1	1	3	None	None	1
3	4mgZ3d50qEqxb4QF	Experiment 1	None	None	None	None	False	False	2026-01-11 16:52:35.922000+00:00	1	1	3	None	None	1
2	xVnkbMb0gxsfERwn	IFNG	None	None	None	None	False	False	2026-01-11 16:52:35.910000+00:00	1	1	3	None	None	1
1	WCLBbEmovPKD889X	DMSO	None	None	None	None	False	False	2026-01-11 16:52:35.910000+00:00	1	1	3	None	None	1

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
1	sgx6X0TG8ID2fFPU	None	None	2026-01-11 16:52:34.248619+00:00	None	None	None	None	None	False	2026-01-11 16:52:34.249000+00:00	1	1	1	None	None	3	None

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
7	wtBTBN1sqZrwHYdW	None	None	3.0	None	False	bionty.Gene.ensembl_gene_id	None	fSbuKqXueizoVnttx06vsw	True	False	False	False	False	2026-01-11 16:52:41.822000+00:00	1	1	3	1	None
6	3wxLloQ5ET91YjxZ	None	None	2.0	None	False	Feature	None	pKW8ucZdD5Kcb1kzUqaGOA	True	False	False	False	False	2026-01-11 16:52:41.814000+00:00	1	1	3	1	None
5	DCxLs229vY1mwOXl	None	None	3.0	None	False	bionty.Gene.ensembl_gene_id	None	P5KzXILi0TzYDHB82Pvt-w	True	False	False	False	False	2026-01-11 16:52:39.513000+00:00	1	1	3	1	None
4	WrpBxlSCpkOy2llk	None	None	4.0	None	False	Feature	None	CRZnVS0YhigFkVtwoCllxQ	True	False	False	False	False	2026-01-11 16:52:39.505000+00:00	1	1	3	1	None
3	0000000000000002	anndata_ensembl_gene_ids_and_valid_features_in...	None	NaN	None	True	None	AnnData	aqGWHvyY49W_PHELUMiBMw	True	False	False	False	False	2026-01-11 16:52:36.552000+00:00	1	1	3	1	None
2	0000000000000001	valid_ensembl_gene_ids	None	NaN	None	True	bionty.Gene.ensembl_gene_id	None	1gocc_TJ1RU2bMwDRK-WUA	True	False	False	False	False	2026-01-11 16:52:36.545000+00:00	1	1	3	1	None
1	0000000000000000	valid_features	None	NaN	None	True	Feature	None	kMi7B_N88uu-YnbTLDU-DA	True	False	False	False	False	2026-01-11 16:52:36.538000+00:00	1	1	3	1	None

Storage

	uid	root	description	type	region	instance_uid	is_locked	created_at	branch_id	space_id	created_by_id	run_id
id
3	kLsvFBzVdsnd	/home/runner/work/lamindb/lamindb/docs/test-re...	None	local	None	hlGq1WkbeSSf	False	2026-01-11 16:52:30.648000+00:00	1	1	3	None

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
1	1quXazN4y3mp0000	registries.ipynb	Query & search registries	notebook	None	None	None	None	None	True	False	2026-01-11 16:52:34.244000+00:00	1	1	None	3

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

* 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	2OTzqBTMlYe5n3	mature T cell	CL:0002419	None	mature T-cell|CD3e-positive T cell	A T Cell That Expresses A T Cell Receptor Comp...	False	2026-01-11 16:52:37.443000+00:00	1	1	3	1	49
15	4BEwsp1Qruxeii	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	2026-01-11 16:52:37.443000+00:00	1	1	3	1	49
14	6By01L04BqiLTW	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	2026-01-11 16:52:37.443000+00:00	1	1	3	1	49
13	6IC9NGJEv2Y4TD	CD8-positive, alpha-beta T cell	CL:0000625	None	CD8-positive, alpha-beta T-lymphocyte|CD8-posi...	A T Cell Expressing An Alpha-Beta T Cell Recep...	False	2026-01-11 16:52:37.221000+00:00	1	1	3	1	49
12	u3sr1GdfF3aIV9	nucleate cell	CL:0002242	None	None	A Cell Containing At Least One Nucleus.	False	2026-01-11 16:52:36.455000+00:00	1	1	3	1	49
11	4Ilrnj9ULJe69Z	hematopoietic cell	CL:0000988	None	haemopoietic cell|haematopoietic cell|hemopoie...	A Cell Of A Hematopoietic Lineage.	False	2026-01-11 16:52:36.455000+00:00	1	1	3	1	49
10	7GpphKmr4cyIoB	lymphocyte of B lineage	CL:0000945	None	None	A Lymphocyte Of B Lineage With The Commitment ...	False	2026-01-11 16:52:36.455000+00:00	1	1	3	1	49

Gene

	uid	abbr	synonyms	description	symbol	stable_id	ensembl_gene_id	ncbi_gene_ids	biotype	is_locked	created_at	branch_id	space_id	created_by_id	run_id	source_id	organism_id
id
4	iFxDa8hoEWuWi9	None	CADPR1	CD38 molecule	CD38	None	ENSG00000004468	952	protein_coding	False	2026-01-11 16:52:41.793000+00:00	1	1	3	1	40	1
3	3bhNYquOnA4sdo	None		CD14 molecule	CD14	None	ENSG00000170458	929	protein_coding	False	2026-01-11 16:52:39.478000+00:00	1	1	3	1	40	1
2	1j4At3x7akJU8n	None	T4|LEU-3	CD4 molecule	CD4	None	ENSG00000010610	920	protein_coding	False	2026-01-11 16:52:39.478000+00:00	1	1	3	1	40	1
1	6Aqvc8ckDYeNrD	None	P32|CD8|CD8ALPHA	CD8 subunit alpha	CD8A	None	ENSG00000153563	925	protein_coding	False	2026-01-11 16:52:39.478000+00:00	1	1	3	1	40	1

Organism

	uid	name	ontology_id	abbr	synonyms	description	scientific_name	is_locked	created_at	branch_id	space_id	created_by_id	run_id	source_id
id
1	1dpCL6TduFJ3AP	human	NCBITaxon:9606	None	None	None	Homo sapiens	False	2026-01-11 16:52:36.947000+00:00	1	1	3	1	34

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
66	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-11 16:52:30.751000+00:00	1	1	3	None	None
65	MJRqduf9	bionty.Ethnicity	human	hancestro	3.0	False	True	Human Ancestry Ontology	http://purl.obolibrary.org/obo/hancestro/relea...	None	https://github.com/EBISPOT/hancestro	False	2026-01-11 16:52:30.751000+00:00	1	1	3	None	None
64	10va5JSt	bionty.DevelopmentalStage	mouse	mmusdv	2024-05-28	False	True	Mouse Developmental Stages	https://github.com/obophenotype/developmental-...	None	https://github.com/obophenotype/developmental-...	False	2026-01-11 16:52:30.751000+00:00	1	1	3	None	None
63	1GbFkOdz	bionty.DevelopmentalStage	human	hsapdv	2024-05-28	False	True	Human Developmental Stages	https://github.com/obophenotype/developmental-...	None	https://github.com/obophenotype/developmental-...	False	2026-01-11 16:52:30.751000+00:00	1	1	3	None	None
62	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-11 16:52:30.751000+00:00	1	1	3	None	None
61	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-11 16:52:30.751000+00:00	1	1	3	None	None
60	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-11 16:52:30.751000+00:00	1	1	3	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

Show code cell output Hide code cell output

Record(uid='4mgZ3d50qEqxb4QF', is_type=False, name='Experiment 1', description=None, reference=None, reference_type=None, extra_data=None, branch_id=1, space_id=1, created_by_id=3, type_id=None, schema_id=None, run_id=1, created_at=2026-01-11 16:52:35 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

Show code cell output Hide code cell output

Record(uid='4mgZ3d50qEqxb4QF', is_type=False, name='Experiment 1', description=None, reference=None, reference_type=None, extra_data=None, branch_id=1, space_id=1, created_by_id=3, type_id=None, schema_id=None, run_id=1, created_at=2026-01-11 16:52:35 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_tag	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")

Show code cell output Hide code cell output

→ queried for all categorical features of dtypes Record or ULabel 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	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	{IFNG, DMSO}	22.6	Experiment 2	2025-02-13	NaN	{'detail1': '456', 'detail2': 2}
4	aVheemRVsaXofykN0000	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}

You can also query for nested dictionary-like features.

ln.Artifact.filter(study_metadata__detail1="123").to_dataframe(include="features")

Show code cell output Hide code cell output

→ queried for all categorical features of dtypes Record or ULabel 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	aVheemRVsaXofykN0000	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}

ln.Artifact.filter(study_metadata__detail2=2).to_dataframe(include="features")

Show code cell output Hide code cell output

→ queried for all categorical features of dtypes Record or ULabel 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	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	{IFNG, DMSO}	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")

Show code cell output Hide code cell output

→ queried for all categorical features of dtypes Record or ULabel and non-categorical features: (7) ['perturbation', 'sample_note', 'temperature', 'experiment', 'date_of_study', 'study_note', 'study_metadata']

	uid	key
id
3	mC8fyHQqBUPG3oMl0000	iris.parquet
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz

ln.Artifact.filter(perturbation__isnull=False).to_dataframe(include="features")

Show code cell output Hide code cell output

→ queried for all categorical features of dtypes Record or ULabel 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	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	{IFNG, DMSO}	22.6	Experiment 2	2025-02-13	NaN	{'detail1': '456', 'detail2': 2}
4	aVheemRVsaXofykN0000	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}

Query runs by parameters

Here is an example for querying by parameters: Track parameters & features.

Search for records

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

ln.Artifact.search("iris").to_dataframe()

Show code cell output Hide 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
3	mC8fyHQqBUPG3oMl0000	iris.parquet	None	.parquet	dataset	DataFrame	5202	LnPHC8qIQlHJMqcum1eWVQ	None	150	None	True	False	2026-01-11 16:52:35.554000+00:00	1	1	3	1	None	3

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

Query related registries

Django has a double-under-score syntax to filter based on related tables.

This syntax enables you to traverse several layers of relations and leverage different comparators.

ln.Artifact.filter(created_by__handle__startswith="testuse").to_dataframe()

Show code cell output Hide 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
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	None	.h5ad	dataset	AnnData	26896	RKJjWbINYNIwYU8BxCejMw	None	3.0	None	True	False	2026-01-11 16:52:41.799000+00:00	1	1	3	1	3.0	3
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3.0	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3.0	3
3	mC8fyHQqBUPG3oMl0000	iris.parquet	None	.parquet	dataset	DataFrame	5202	LnPHC8qIQlHJMqcum1eWVQ	None	150.0	None	True	False	2026-01-11 16:52:35.554000+00:00	1	1	3	1	NaN	3
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	None	.jpg	None	None	29358	r4tnqmKI_SjrkdLzpuWp4g	None	NaN	None	True	False	2026-01-11 16:52:35.394000+00:00	1	1	3	1	NaN	3
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	None	.fastq.gz	None	None	20	hi7ZmAzz8sfMd3vIQr-57Q	None	NaN	None	True	False	2026-01-11 16:52:35.240000+00:00	1	1	3	1	NaN	3

The filter selects all artifacts based on the users who ran the generating notebook. Under the hood, in the SQL database, it’s joining the artifact table with the user table.

Another typical example is querying all datasets that measure a particular feature. For instance, which datasets measure "CD8A". Here is how to do it:

cd8a = bt.Gene.get(symbol="CD8A")
# query for all feature sets that contain CD8A
schemas_with_cd8a = ln.Schema.filter(genes=cd8a)
# get all artifacts
ln.Artifact.filter(schemas__in=schemas_with_cd8a).to_dataframe()

Show code cell output Hide 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
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	None	.h5ad	dataset	AnnData	26896	RKJjWbINYNIwYU8BxCejMw	None	3	None	True	False	2026-01-11 16:52:41.799000+00:00	1	1	3	1	3	3
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3	3

Instead of splitting this across three queries, the double-underscore syntax allows you to define a path for one query.

ln.Artifact.filter(schemas__genes__symbol="CD8A").to_dataframe()

Show code cell output Hide 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
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	None	.h5ad	dataset	AnnData	26896	RKJjWbINYNIwYU8BxCejMw	None	3	None	True	False	2026-01-11 16:52:41.799000+00:00	1	1	3	1	3	3
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3	3

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

Show code cell output Hide 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
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3	3

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

Show code cell output Hide 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
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3	3

in

ln.Artifact.filter(suffix__in=[".jpg", ".fastq.gz"]).to_dataframe()

Show code cell output Hide 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
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	None	.jpg	None	None	29358	r4tnqmKI_SjrkdLzpuWp4g	None	None	None	True	False	2026-01-11 16:52:35.394000+00:00	1	1	3	1	None	3
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	None	.fastq.gz	None	None	20	hi7ZmAzz8sfMd3vIQr-57Q	None	None	None	True	False	2026-01-11 16:52:35.240000+00:00	1	1	3	1	None	3

order by

ln.Artifact.filter().order_by("created_at").to_dataframe()

Show code cell output Hide 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
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	None	.fastq.gz	None	None	20	hi7ZmAzz8sfMd3vIQr-57Q	None	NaN	None	True	False	2026-01-11 16:52:35.240000+00:00	1	1	3	1	NaN	3
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	None	.jpg	None	None	29358	r4tnqmKI_SjrkdLzpuWp4g	None	NaN	None	True	False	2026-01-11 16:52:35.394000+00:00	1	1	3	1	NaN	3
3	mC8fyHQqBUPG3oMl0000	iris.parquet	None	.parquet	dataset	DataFrame	5202	LnPHC8qIQlHJMqcum1eWVQ	None	150.0	None	True	False	2026-01-11 16:52:35.554000+00:00	1	1	3	1	NaN	3
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3.0	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3.0	3
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	None	.h5ad	dataset	AnnData	26896	RKJjWbINYNIwYU8BxCejMw	None	3.0	None	True	False	2026-01-11 16:52:41.799000+00:00	1	1	3	1	3.0	3

# reverse ordering
ln.Artifact.filter().order_by("-created_at").to_dataframe()

Show code cell output Hide 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
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	None	.h5ad	dataset	AnnData	26896	RKJjWbINYNIwYU8BxCejMw	None	3.0	None	True	False	2026-01-11 16:52:41.799000+00:00	1	1	3	1	3.0	3
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3.0	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3.0	3
3	mC8fyHQqBUPG3oMl0000	iris.parquet	None	.parquet	dataset	DataFrame	5202	LnPHC8qIQlHJMqcum1eWVQ	None	150.0	None	True	False	2026-01-11 16:52:35.554000+00:00	1	1	3	1	NaN	3
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	None	.jpg	None	None	29358	r4tnqmKI_SjrkdLzpuWp4g	None	NaN	None	True	False	2026-01-11 16:52:35.394000+00:00	1	1	3	1	NaN	3
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	None	.fastq.gz	None	None	20	hi7ZmAzz8sfMd3vIQr-57Q	None	NaN	None	True	False	2026-01-11 16:52:35.240000+00:00	1	1	3	1	NaN	3

ln.Artifact.filter().order_by("key").to_dataframe()

Show code cell output Hide 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
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3.0	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3.0	3
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	None	.h5ad	dataset	AnnData	26896	RKJjWbINYNIwYU8BxCejMw	None	3.0	None	True	False	2026-01-11 16:52:41.799000+00:00	1	1	3	1	3.0	3
3	mC8fyHQqBUPG3oMl0000	iris.parquet	None	.parquet	dataset	DataFrame	5202	LnPHC8qIQlHJMqcum1eWVQ	None	150.0	None	True	False	2026-01-11 16:52:35.554000+00:00	1	1	3	1	NaN	3
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	None	.jpg	None	None	29358	r4tnqmKI_SjrkdLzpuWp4g	None	NaN	None	True	False	2026-01-11 16:52:35.394000+00:00	1	1	3	1	NaN	3
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	None	.fastq.gz	None	None	20	hi7ZmAzz8sfMd3vIQr-57Q	None	NaN	None	True	False	2026-01-11 16:52:35.240000+00:00	1	1	3	1	NaN	3

# reverse ordering
ln.Artifact.filter().order_by("-key").to_dataframe()

	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	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	None	.fastq.gz	None	None	20	hi7ZmAzz8sfMd3vIQr-57Q	None	NaN	None	True	False	2026-01-11 16:52:35.240000+00:00	1	1	3	1	NaN	3
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	None	.jpg	None	None	29358	r4tnqmKI_SjrkdLzpuWp4g	None	NaN	None	True	False	2026-01-11 16:52:35.394000+00:00	1	1	3	1	NaN	3
3	mC8fyHQqBUPG3oMl0000	iris.parquet	None	.parquet	dataset	DataFrame	5202	LnPHC8qIQlHJMqcum1eWVQ	None	150.0	None	True	False	2026-01-11 16:52:35.554000+00:00	1	1	3	1	NaN	3
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	None	.h5ad	dataset	AnnData	26896	RKJjWbINYNIwYU8BxCejMw	None	3.0	None	True	False	2026-01-11 16:52:41.799000+00:00	1	1	3	1	3.0	3
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3.0	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3.0	3

contains

ln.Transform.filter(description__contains="search").to_dataframe().head(5)

Show code cell output Hide code cell output

	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
1	1quXazN4y3mp0000	registries.ipynb	Query & search registries	notebook	None	None	None	None	None	True	False	2026-01-11 16:52:34.244000+00:00	1	1	None	3

And case-insensitive:

ln.Transform.filter(description__icontains="Search").to_dataframe().head(5)

Show code cell output Hide code cell output

	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
1	1quXazN4y3mp0000	registries.ipynb	Query & search registries	notebook	None	None	None	None	None	True	False	2026-01-11 16:52:34.244000+00:00	1	1	None	3

startswith

ln.Transform.filter(description__startswith="Query").to_dataframe()

Show code cell output Hide code cell output

	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
1	1quXazN4y3mp0000	registries.ipynb	Query & search registries	notebook	None	None	None	None	None	True	False	2026-01-11 16:52:34.244000+00:00	1	1	None	3

or

ln.Artifact.filter(ln.Q(suffix=".jpg") | ln.Q(suffix=".fastq.gz")).to_dataframe()

Show code cell output Hide 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
2	FoGoKg7Tt0qSsdWk0000	my_image.jpg	None	.jpg	None	None	29358	r4tnqmKI_SjrkdLzpuWp4g	None	None	None	True	False	2026-01-11 16:52:35.394000+00:00	1	1	3	1	None	3
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	None	.fastq.gz	None	None	20	hi7ZmAzz8sfMd3vIQr-57Q	None	None	None	True	False	2026-01-11 16:52:35.240000+00:00	1	1	3	1	None	3

negate/ unequal

ln.Artifact.filter(~ln.Q(suffix=".jpg")).to_dataframe()

Show code cell output Hide 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
5	Qnrtuw9rBxCRzJjG0000	examples/dataset2.h5ad	None	.h5ad	dataset	AnnData	26896	RKJjWbINYNIwYU8BxCejMw	None	3.0	None	True	False	2026-01-11 16:52:41.799000+00:00	1	1	3	1	3.0	3
4	aVheemRVsaXofykN0000	examples/dataset1.h5ad	None	.h5ad	dataset	AnnData	31672	FB3CeMjmg1ivN6HDy6wsSg	None	3.0	None	True	False	2026-01-11 16:52:39.485000+00:00	1	1	3	1	3.0	3
3	mC8fyHQqBUPG3oMl0000	iris.parquet	None	.parquet	dataset	DataFrame	5202	LnPHC8qIQlHJMqcum1eWVQ	None	150.0	None	True	False	2026-01-11 16:52:35.554000+00:00	1	1	3	1	NaN	3
1	GZOK2tlQyALrlRRB0000	raw/my_fastq.fastq.gz	None	.fastq.gz	None	None	20	hi7ZmAzz8sfMd3vIQr-57Q	None	NaN	None	True	False	2026-01-11 16:52:35.240000+00:00	1	1	3	1	NaN	3