# SpatialData-DB

> SpatialData-DB is a catalog of 8,471 public spatial omics datasets, grouped into 506 collections (the SQL below counts them per technology). Each dataset is converted to the SpatialData format and loads with one Python call. This file is for AI agents, and it is generated from catalog release catalog-2026-11-01.

## How to query the catalog

The catalog is one Parquet file per release, with one row per dataset, and collections.parquet has one row per collection. DuckDB reads both over HTTPS, so any SQL works without a download. Datasets per technology:

```sql
INSTALL httpfs; LOAD httpfs;
SELECT technology, count(*) AS datasets
FROM read_parquet('https://github.com/theislab/spatialdata-db-client/releases/download/catalog-2026-11-01/catalog.parquet')
GROUP BY technology ORDER BY datasets DESC;
```

Human Xenium datasets of the lung, with their size and licence:

```sql
INSTALL httpfs; LOAD httpfs;
SELECT uid, slug, title, n_obs, license
FROM read_parquet('https://github.com/theislab/spatialdata-db-client/releases/download/catalog-2026-11-01/catalog.parquet')
WHERE organism = 'human' AND technology = 'Xenium' AND tissue = 'lung';
```

Gene queries ("which datasets measure gene X") are not available to agents yet. They come with a gene-sorted index in a later release. Until then, a person can use the gene filter on /datasets/.

## Columns

- `uid`: the dataset's id; the last 4 characters are its version.
- `study_id`: the study key; it is also the citation key in citations.bib.
- `organism`: human, mouse and so on.
- `tissue`: the tissue, as a name; tissue_id holds the ontology id (UBERON, or PO for plants).
- `disease`: the disease or condition; disease_id holds the MONDO id.
- `technology`: the platform, e.g. Visium, Xenium, Merscope, MIBI.
- `assay`: the assay name as the source gives it.
- `panel_size`: the number of target genes for targeted panels.
- `tier`: the quality tier (bronze, silver, gold).
- `license`: the dataset's own licence (an SPDX-like id); check it before reuse.
- `license_url`: a link to the licence text.
- `license_noncommercial`: true when the licence forbids commercial use.
- `n_obs`: the number of observations (cells, spots, bins or pixels, see obs_unit).
- `n_features`: the number of genes or other features in the default table.
- `zarr_url`: the SpatialData store (.zarr) the client loads.
- `size_bytes`: the store's size.
- `slug`: the dataset's page on this site: /datasets/<slug>/.
- `title`: the source's title for the sample.
- `modality`: RNA, protein, metabolomics and so on; several are joined with |.
- `n_transcripts`: decoded transcripts, for imaging assays.
- `publication_date`: when the source published the data.
- `doi`: the publication DOI, when known.
- `dataset_url`: the source page the data came from.
- `collections`: the slugs of the collections the dataset belongs to.

The full column list is in /llms-full.txt.

## Load a dataset

Install the client (Python 3.12 or newer):

```bash
pip install "spatialdata-db @ git+https://github.com/theislab/spatialdata-db-client@v0.1.3"
```

```python
from sddb import Catalog

ds = Catalog().dataset("VkGigAlvHGdpmGVG0000")
ds.elements()          # inspect without downloading
sdata = ds.to_sdata()  # cached locally, reused
print(sdata)
```

## Cite

Cite the dataset's publication, from the `doi` column, or the source in `dataset_url` when there is none. The release also has citations.bib (https://github.com/theislab/spatialdata-db-client/releases/download/catalog-2026-11-01/citations.bib), keyed by `study_id`. Every dataset page on this site has a "Cite this dataset" section.

## Releases and versions

Each catalog release is a GitHub release named catalog-YYYY-MM-DD (https://github.com/theislab/spatialdata-db-client/releases). This site and this file are built from catalog-2026-11-01. Put the release tag in every URL you store, so a result can be reproduced. A dataset's uid ends in a 4-character version, and the client release is v0.1.3.

## Licences

Every row carries its own licence (`license`, `license_url`, `license_noncommercial`) and its source (`dataset_url`). Check them before reusing a dataset. Some sources allow non-commercial use only.

## Pages

- [Datasets](/datasets/): all datasets with filters.
- [Collections](/collections/): studies and other groups of datasets.
- [Statistics](/stats/): counts and distributions.
- [Full agent guide](/llms-full.txt): this file plus every column and collection query.
- [OpenAPI description](/openapi.json): every route above, with the release as a parameter.
- Markdown: every page links its Markdown version in its head (`<link rel="alternate" type="text/markdown">`). Datasets are in 256 files, [/datasets/md/00.md](/datasets/md/00.md) to /datasets/md/ff.md, and collections in 16, [/collections/md/0.md](/collections/md/0.md) to /collections/md/f.md, each section anchored by its slug.
- [Client documentation](https://spatialdata-db.readthedocs.io/en/latest/).