GIQL Operators

GIQL extends SQL with operators specifically designed for genomic interval queries. These operators enable powerful spatial reasoning over genomic coordinates without requiring complex SQL expressions.

Operators are organized by functionality:

Spatial Relationship Operators

Test positional relationships between genomic ranges.

Operator	Description	Example
INTERSECTS	Returns true when ranges overlap by at least one base pair	interval INTERSECTS 'chr1:1000-2000'
CONTAINS	Returns true when one range fully contains another	interval CONTAINS 'chr1:1500'
WITHIN	Returns true when one range is fully within another	interval WITHIN 'chr1:1000-5000'

See Spatial Relationship Operators for detailed documentation.

Distance and Proximity Operators

Calculate distances and find nearest features.

Operator	Description	Example
DISTANCE	Calculate genomic distance between two intervals	DISTANCE(a.interval, b.interval)
NEAREST	Find k-nearest genomic features	NEAREST(genes, reference=peaks.interval, k=5)

See Distance and Proximity Operators for detailed documentation.

Aggregation Operators

Combine and cluster genomic intervals.

Operator	Description	Example
CLUSTER	Assign cluster IDs to overlapping intervals	CLUSTER(interval) AS cluster_id
MERGE	Combine overlapping intervals into unified regions	SELECT MERGE(interval) FROM features

See Aggregation Operators for detailed documentation.

Set Quantifiers

Apply operators to multiple ranges simultaneously.

Quantifier	Description	Example
ANY	Match if condition holds for any of the specified ranges	interval INTERSECTS ANY('chr1:1000-2000', 'chr2:5000-6000')
ALL	Match if condition holds for all of the specified ranges	interval CONTAINS ALL('chr1:1500', 'chr1:1600')

See Set Quantifiers for detailed documentation.

Operator Compatibility

All operators work across supported database backends (DuckDB, SQLite, with PostgreSQL planned). Each operator page includes a compatibility table showing backend support status.