GIQL

Genomic Interval Query Language (GIQL)

/JEE-quel/

docs | syntax | transpiler

GIQL is an extended SQL dialect that allows you to declaratively express genomic interval operations.

The giql Python package transpiles GIQL queries into standard SQL syntax for execution on any database or analytics engine.

Note: This project is in active development — APIs, syntax, and behavior may change.

Installation

To install the transpiler:

pip install giql

Usage (transpilation)

The giql package transpiles GIQL queries to standard SQL.

from giql import transpile

sql = transpile(
    "SELECT * FROM peaks WHERE interval INTERSECTS 'chr1:1000-2000'",
    tables=["peaks"],
)
print(sql)

SELECT
  *
FROM peaks
WHERE
  (
    "chrom" = 'chr1' AND "start" < 2000 AND "end" > 1000
  )

Each table referenced in a GIQL query exposes a genomic "pseudo-column" that maps to separate logical chromosome, start, end, and strand columns. You can customize the column mappings.

from giql import Table, transpile

sql = transpile(
    "SELECT * FROM variants WHERE position INTERSECTS 'chr1:1000-2000'",
    tables=[
        Table(
            "variants",
            genomic_col="position",
            chrom_col="chromosome",
            start_col="start_pos",
            end_col="end_pos",
        )
    ],
)
print(sql)

The transpiled SQL can be executed with fast genome-unaware databases or in-memory analytic engines like DuckDB.

By default a column-to-column INTERSECTS join emits the naive overlap predicate (a.chrom = b.chrom AND a.start < b.end AND b.start < a.end) as a plain ON condition, which each engine's optimizer plans as a range join. For DuckDB you can additionally pass dialect="duckdb" to opt into a per-chromosome IEJoin plan for INNER, SEMI, ANTI, and LEFT/RIGHT outer joins; shapes it declines fall through to the naive predicate. See DuckDB IEJoin Dialect for the supported shapes and fallback rules.

You can also use oxbow to efficiently stream specialized genomics formats into DuckDB.

import duckdb
import oxbow as ox
from giql import transpile

conn = duckdb.connect()

# Load a streaming data source as a DuckDB relation
peaks = ox.from_bed("peaks.bed", bed_schema="bed6+4").to_duckdb(conn)

sql = transpile(
    "SELECT * FROM peaks WHERE interval INTERSECTS 'chr1:1000-2000'",
    tables=["peaks"],
)

# Execute and return the output as a dataframe
df = con.execute(sql).fetchdf()

MCP Server

GIQL includes an MCP server that gives LLM-powered tools access to operator references, syntax guides, and documentation. Install with the mcp extra:

pip install giql[mcp]

Or spawn a server directly with uvx:

uvx --from "giql[mcp]" giql-mcp

To add the GIQL MCP server to a specific project in Claude Code:

claude mcp add --scope project giql-mcp -- uvx --from "giql[mcp]" giql-mcp

See src/giql/mcp/README.md for configuration and usage details.

Development

git clone https://github.com/abdenlab/giql.git
cd giql
uv sync

To build the documentation locally:

uv run --group docs sphinx-build docs docs/_build
# The built docs will be in docs/_build/html/

For serve the docs locally with automatic rebuild:

uv run --group docs sphinx-autobuild docs docs/_build