BIQL Language Reference

BIQL (BIDS Query Language) is a SQL-like query language for querying Brain Imaging Data Structure (BIDS) datasets. This reference describes all language constructs, clauses, and operators.

What BIQL Queries

BIQL queries operate on BIDS datasets, which are structured neuroimaging data repositories following the Brain Imaging Data Structure specification. When you query with BIQL, you’re searching through:

1. BIDS Entities from Filenames

BIDS filenames encode metadata using key-value pairs separated by underscores. For example:

sub-01_ses-pre_task-rest_run-1_bold.nii.gz

From this filename, BIQL extracts:

  • sub = “01” (subject identifier)
  • ses = “pre” (session identifier)
  • task = “rest” (task name)
  • run = “1” (run number)
  • suffix = “bold” (file type suffix)
  • datatype = “func” (from parent directory)

Common BIDS entities include:

  • sub - Subject identifier
  • ses - Session identifier
  • task - Task name
  • run - Run number
  • acq - Acquisition label
  • ce - Contrast enhancing agent
  • rec - Reconstruction label
  • dir - Phase encoding direction
  • echo - Echo number
  • part - Part label (e.g., mag, phase)
  • space - Spatial reference
  • res - Resolution
  • den - Density
  • label - Label or atlas name
  • desc - Description

The complete list of entities is defined in the BIDS specification.

2. JSON Sidecar Metadata

BIDS datasets include JSON sidecar files that contain additional metadata. BIQL makes these accessible through the metadata namespace:

WHERE metadata.EchoTime < 0.005
WHERE metadata.RepetitionTime = 2.0
SELECT metadata.MagneticFieldStrength, metadata.ManufacturerModelName

Common metadata fields include:

  • RepetitionTime (TR)
  • EchoTime (TE)
  • FlipAngle
  • SliceTiming
  • PhaseEncodingDirection
  • MagneticFieldStrength
  • Manufacturer
  • ManufacturerModelName
  • SequenceName

The metadata follows BIDS inheritance principle: metadata defined at higher levels (e.g., dataset or subject level) applies to all applicable files below unless overridden.

3. Participants Information

The participants.tsv file contains subject-level information. BIQL makes these accessible through the participants namespace:

WHERE participants.age > 18
SELECT sub, participants.sex, participants.handedness

Common participants fields include:

  • age
  • sex
  • handedness
  • group
  • Any custom columns defined in your participants.tsv file

4. Computed Fields

BIQL also provides computed fields for convenience:

  • filename - Just the file name
  • filepath - Full absolute path to the file
  • relative_path - Path relative to dataset root
  • extension - File extension (e.g., “.nii.gz”)

Query Structure

BIQL queries follow a SQL-like structure:

SELECT fields
WHERE conditions
GROUP BY fields
HAVING aggregate_conditions
ORDER BY fields [ASC|DESC]
FORMAT output_type

Minimal queries can be just conditions:

sub=01

Clauses

SELECT

Specifies which fields to return in the result set.

SELECT sub, ses, task, filepath

WHERE

Filters data based on conditions.

WHERE datatype=func AND task=rest

GROUP BY

Groups results by specified fields.

GROUP BY sub, ses

HAVING

Filters grouped results based on aggregate conditions.

HAVING COUNT(*) > 10

ORDER BY

Sorts results by specified fields in ascending (ASC) or descending (DESC) order.

ORDER BY sub ASC, task DESC

FORMAT

Specifies the output format for results.

FORMAT json

Keywords

DISTINCT

Returns only unique values.

SELECT DISTINCT task

AS

Creates aliases for fields or expressions.

SELECT COUNT(*) AS file_count

AND, OR, NOT

Logical operators for combining conditions.

WHERE datatype=func AND (task=rest OR task=nback)
WHERE NOT suffix=events

IN

Tests if a value is within a list.

WHERE task IN [rest, nback, flanker]

Operators

Comparison Operators

  • = or == - Equality
  • != - Not equal
  • > - Greater than
  • < - Less than
  • >= - Greater than or equal
  • <= - Less than or equal
WHERE run > 2
WHERE metadata.RepetitionTime <= 3.0

Pattern Matching Operator

  • ~= - Regular expression match
WHERE task~=/.*back.*/

Range Operator

Specifies a range of values using [start:end] syntax.

WHERE run=[1:5]

Aggregate Functions

COUNT

Counts records or non-null values.

SELECT COUNT(*) AS total_files
SELECT COUNT(ses) AS sessions_with_data

AVG

Calculates the average of numeric values.

SELECT AVG(metadata.RepetitionTime) AS avg_tr

MAX

Returns the maximum value.

SELECT MAX(run) AS max_run

MIN

Returns the minimum value.

SELECT MIN(metadata.EchoTime) AS min_echo_time

SUM

Calculates the sum of numeric values.

SELECT SUM(metadata.NumberOfVolumes) AS total_volumes

ARRAY_AGG

Collects values into an array, optionally with conditions.

SELECT ARRAY_AGG(filename) AS all_files
SELECT ARRAY_AGG(filename WHERE part='mag') AS magnitude_files

Pattern Matching

Wildcards

  • * - Matches any sequence of characters
  • ? - Matches single character
WHERE suffix=*bold*
WHERE task=?back

Regular Expressions

Use the ~= operator with regex patterns in string literals:

WHERE suffix~="T[12]w"
WHERE task~="rest|task"

Data Types

BIQL takes a flexible approach to data types, automatically handling type conversions based on context. This makes queries more intuitive and forgiving of different data representations.

Strings

Enclosed in single or double quotes:

WHERE task='rest' OR task="n-back"

Numbers

Integer or floating-point values:

WHERE run=1
WHERE metadata.RepetitionTime=2.5

Flexible Value Matching

BIQL intelligently matches values regardless of their representation:

  • Leading zeros are handled automatically: sub=01 matches sub=1 and sub=001
  • String and numeric comparisons work interchangeably: run=1 matches run='1'
  • The comparison adapts to the context:
    • For BIDS entities that are typically zero-padded (like sub-01), queries work with or without padding
    • For numeric metadata fields, string representations are converted appropriately

Examples:

WHERE sub=1        # Matches sub-01, sub-001, etc.
WHERE sub=01       # Also matches sub-1, sub-01, sub-001
WHERE run='2'      # Matches run-2, run-02
WHERE echo=1       # Matches echo-1, echo-01

Lists

Comma-separated values in square brackets:

WHERE task IN [rest, nback, flanker]
WHERE sub IN [1, 2, 3]    # Matches sub-01, sub-02, sub-03

Ranges

Start and end values in square brackets with colon:

WHERE run=[1:5]      # Matches run-1 through run-5 (including run-01, etc.)
WHERE echo=[1:3]     # Matches echo-1, echo-2, echo-3

Output Formats

Available output formats for the FORMAT clause:

  • json - JSON format (default)
  • table - ASCII table
  • csv - Comma-separated values
  • tsv - Tab-separated values
  • paths - Just file paths
  • dataframe - Pandas DataFrame (Python API only)
FORMAT table
FORMAT csv

Special Features

Implicit AND

Adjacent conditions without explicit AND are treated as AND:

subject=01 task=rest
-- Equivalent to:
subject=01 AND task=rest

Comments

Lines starting with # are treated as comments:

# This query finds all functional data
WHERE datatype=func

Case Sensitivity

  • Keywords are case-insensitive: SELECT, select, Select are equivalent
  • Entity values preserve case: task=Rest is different from task=rest

Flexible Identifiers

Identifiers can contain hyphens:

WHERE task=n-back