Creating an SQLite file directly from a BIDS dataset

Index a BIDS dataset with bids2table, including JSON sidecar metadata, into a SQLite file using bids2db.py.

utilities/bids2db.py indexes a BIDS dataset with bids2table (the same as b2t2 index), adds each file’s JSON sidecar metadata, and writes the result to a SQLite file that SQLite Browser can open.

Use this instead of parquets2db.py when you want sidecar metadata, because bids2table v2 Parquet files don’t include it.

Prerequisites

  • SQLite Browser dependencies installed (uv sync in the repo root), which includes bids2table
  • A BIDS dataset folder containing dataset_description.json and sub-* folders

Usage

uv run python utilities/bids2db.py PATH -o SQLITE_FILE [options]
ArgumentRequiredDescription
PATHYesRoot folder of the BIDS dataset
-o / --outputYesPath for the output .sqlite file (must end in .sqlite)
--subjectsNoSubject folder names or glob patterns to include, with the sub- prefix (e.g. sub-01 'sub-1*')
-j / --workersNoWorker processes for loading metadata (0 = main process (the default), -1 = all cores)
--use-threadsNoUse threads instead of processes when --workers > 0
-q / --no-progressNoDisable the progress bar
-v / --verboseNo-v for warnings, -vv for more logging

Example:

uv run python utilities/bids2db.py /path/to/ds001553 -o data/ds001553.sqlite -j -1

Output

The result is written to a table named data, with one row per BIDS data file:

  • The standard bids2table v2 columns: dataset, one column per BIDS entity (sub, ses, task, …), datatype, suffix, ext, extra_entities, root, and path.
  • metadata: the file’s sidecar JSON as text, merged from all applicable sidecars following the BIDS inheritance principle. Files without a sidecar get {}.
  • extra_entities (entities that aren’t in the BIDS schema) is stored as JSON text, or NULL when there are none.

Notes

  • An existing table in the output file is replaced.
  • Sidecar loading reads JSON files from disk for every row, so -j can speed up large datasets considerably.
  • If no BIDS files are found, the script exits without writing anything; rerun with -v to see why.
Last modified October 6, 2026: Update utilities docs titles and linkTitles (2b2ec55)