> For the complete documentation index, see [llms.txt](https://docs.biobox.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biobox.io/guide/how-to/ask-biobox-with-claude/tools/run-bxql.md).

# run\_bxql — Run a read-only BxQL query

Run a read-only BxQL query

Run a read-only BxQL query

## What it does

Run an ontology-respecting, read-only BxQL query and get back correlated multi-column path rows — one row per matched path, keyed by the query's variables. The general-purpose BxQL counterpart to run\_graph\_query (raw Cypher).

**When to use:** you have (or can author) a BxQL query and want its actual result rows — the correlated entities along each matched path (e.g. Gene → Mutation → Disease); a multi-hop question where you need each column's entity, not just one anchor's nodes (BxQL returns the whole path, correlated per row); you want an ontology-validated query by construction — BxQL uses concept/relationship names, not raw graph labels; you need each result node's uuid to drill further with get\_entity.

**When NOT to use:** you want raw Cypher, or just one variable's node list, counts-first (use run\_graph\_query); you only want to CHECK a BxQL query parses / preview its compiled Cypher without running it (use validate\_bxql); you want the data behind a STORED dashboard widget by its uuid (use get\_widget\_data — it runs the widget's saved query; run\_bxql runs a query YOU supply).

**Parameters:**

* `query` — the BxQL query to run (ontology-respecting: concept/relationship names, not raw labels). Example: '(g:Gene { displayName="MTOR" })<- found on <-(m:Mutation { impact = "HIGH" })-> associated with disease ->(d:Disease)'. A query that doesn't parse returns a clean error. Use validate\_bxql first if unsure. Read-only — write operations are not expressible in BxQL.
* `limit` — optional (default 50, max 500). Max rows to return; values above 500 are clamped. A full page (returnedCount == limit) sets truncated:true — request the next page by raising offset.
* `offset` — optional (default 0). Row offset for paging through a large result.
* `nodeProperties` — optional (default true). Include each result node's full property bag (each cell always carries uuid/displayName/dbLabels regardless). Node bags can be LARGE (synonyms, normalized names, summaries), so with this on a wide/tall page can exceed the client's per-result size cap and be spilled to a file — pass false for lean identity-only nodes when you don't need the properties.
* `edgeProperties` — optional (default true). Include each relationship cell's property bag — the small analytical payload (log2FC/padj/evidenceCode). Pass false to drop it, leaving just { type }.

**Returns:** Flat at the root: finalCypher (the compiled Cypher — gives the row column order — or null); rows (each a map of the correlated cells along one path). Node cells are keyed "variable:Label" (e.g. "d:Disease") = { uuid, displayName, dbLabels } (the noise label "Object" is stripped; the node properties bag is included unless nodeProperties:false). Relationship (edge) cells sit on the SAME row keyed "variable:type" (e.g. "\_r:differentially expresses") = { type, properties } — the edge properties bag (log2FC/padj/evidenceCode) is included unless edgeProperties:false (then the cell is just { type }). Plus returnedCount; total (exact count when the last page was reached, else null); and truncated (true when the page filled the limit — more rows may exist, page via offset). Each node cell's uuid chains into get\_entity. A query that fails to parse returns a clean error (isError) naming the diagnostic.

## Parameters

| Parameter        | Type    | Required | Description                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query`          | string  | yes      | the BxQL query to run (ontology-respecting: concept/relationship names, not raw labels). Example: '(g:Gene { displayName="MTOR" })<- found on <-(m:Mutation { impact = "HIGH" })-> associated with disease ->(d:Disease)'. A query that doesn't parse returns a clean error. Use validate\_bxql first if unsure. Read-only — write operations are not expressible in BxQL.                 |
| `limit`          | number  | no       | optional (default 50, max 500). Max rows to return; values above 500 are clamped. A full page (returnedCount == limit) sets truncated:true — request the next page by raising offset.                                                                                                                                                                                                      |
| `offset`         | number  | no       | optional (default 0). Row offset for paging through a large result.                                                                                                                                                                                                                                                                                                                        |
| `nodeProperties` | boolean | no       | optional (default true). Include each result node's full property bag (each cell always carries uuid/displayName/dbLabels regardless). Node bags can be LARGE (synonyms, normalized names, summaries), so with this on a wide/tall page can exceed the client's per-result size cap and be spilled to a file — pass false for lean identity-only nodes when you don't need the properties. |
| `edgeProperties` | boolean | no       | optional (default true). Include each relationship cell's property bag — the small analytical payload (log2FC/padj/evidenceCode). Pass false to drop it, leaving just { type }.                                                                                                                                                                                                            |

## Response

```ts
_(identity shaper — response = the handler result; see the tool source.)_
```

## Example

```json
// run_bxql({"query":"(g:Gene { displayName=\"MTOR\" })<- found on <-(m:Mutation { impact = \"HIGH\" })-> associated with disease ->(d:Disease)"})
{
  "query": "(g:Gene { displayName=\"MTOR\" })<- found on <-(m:Mutation { impact = \"HIGH\" })-> associated with disease ->(d:Disease)"
}
```

Response (arrays truncated):

```json
{
  "finalCypher": "MATCH path0=((g:`Gene`)<-[_r:`found on`]-(m:`Mutation`)-[_r2:`associated with disease`]->(d:`Disease`))\nWHERE (g.`displayName`='MTOR') AND (m.`impact`='HIGH')\nWITH g, m, d, path0\nRETURN DISTINCT path0…",
  "rows": [
    {
      "g:Gene": {
        "uuid": "ENSG00000198793",
        "displayName": "MTOR",
        "dbLabels": [
          "Gene"
        ],
        "properties": {
          "symbol": "MTOR",
          "normalized_names": [
            "fk506 binding protein 12 rapamycin associated protein 1",
            "rapamycin associated protein frap2",
            "fk506 binding protein 12 rapamycin associated protein 2",
            "… 16 more"
          ],
          "displayName": "MTOR",
          "source": "HAVANA",
          "uuid": "ENSG00000198793",
          "synonym": "RAFT1|RAPT1|FLJ44809|FK506 binding protein 12-rapamycin associated protein 2|rapamycin target protein|FKBP12-rapamycin complex-associated protein 1|FKBP-rapamycin associated protein|rapamycin associat…",
          "strand": "-",
          "ensembl_gene_id_version": "ENSG00000198793.14",
          "HGNC": "HGNC:3942",
          "ensembl_gene_id": "ENSG00000198793",
          "assembly": "GRCh38.p14",
          "NCBI": 2475,
          "alias": [
            "FRAP",
            "FRAP1",
            "FRAP2",
            "… 3 more"
          ],
          "taxon": 9606,
          "end": 11262556,
          "tag": [
            ""
          ],
          "band": "p36.22",
          "HGNC symbol": "MTOR",
          "bxID": "ENSG00000198793",
          "biotype": "protein_coding",
          "summary": "The protein encoded by this gene belongs to a family of phosphatidylinositol kinase-related kinases. These kinases mediate cellular responses to stresses such as DNA damage and nutrient deprivation. T…",
          "percentGC": 44.55,
          "level": "manually annotated loci",
          "start": 11106535,
          "chr": "1",
          "name": "mechanistic target of rapamycin kinase",
          "fullname": "mechanistic target of rapamycin kinase"
        }
      },
      "m:Mutation": {
        "uuid": "CLINVAR:1213781",
        "displayName": "CLINVAR:1213781",
        "dbLabels": [
          "Mutation"
        ],
        "properties": {
          "clinvarID": 1213781,
          "mut_type": "Duplication",
          "ref": "T",
          "transcripts": "[[\"ENSG00000198793\", \"ENST00000361445\", \"frameshift_variant\", \"HIGH\", \"p.Asn2071fs\"], [\"ENSG00000198793\", \"ENST00000376838\", \"frameshift_variant\", \"HIGH\", \"p.Asn276fs\"], [\"ENSG00000198793\", \"ENST00000…",
          "pos": 11127629,
          "displayName": "CLINVAR:1213781",
          "effect": "frameshift_variant",
          "impact": "HIGH",
          "alt": "TA",
          "chr": 1,
          "uuid": "CLINVAR:1213781"
        }
      },
      "d:Disease": {
        "uuid": "MONDO:0014716",
        "displayName": "macrocephaly-intellectual disability-neurodevelopmental disorder-small thorax syndrome",
        "dbLabels": [
          "Disease"
        ],
        "properties": {
          "normalized_names": [
            "macrocephaly intellectual disability neurodevelopmental disorder small thorax syndrome"
          ],
          "CURIE": "MONDO:0014716",
          "ontologyNamespace": "MONDO",
          "parentInstances": [
            "multiple congenital anomalies/dysmorphic syndrome",
            "disease",
            "multiple congenital anomalies/dysmorphic syndrome-intellectual disability",
            "… 13 more"
          ],
          "displayName": "macrocephaly-intellectual disability-neurodevelopmental disorder-small thorax syndrome",
          "parentInstancesUUIDs": [
            "MONDO:0015330",
            "MONDO:0002320",
            "MONDO:0100283",
            "… 13 more"
          ],
          "description": "A rare multiple congenital anomalies/dysmorphic syndrome with intellectual disability, characterized by macrocephaly, intellectual disability, seizures, dysmorphic facial features (including tall fore…",
          "parentInstancesFlat": "multiple congenital anomalies/dysmorphic syndrome|disease|multiple congenital anomalies/dysmorphic syndrome-intellectual disability|hereditary neurological disease|overgrowth syndrome and/or cerebral …",
          "label": "macrocephaly-intellectual disability-neurodevelopmental disorder-small thorax syndrome",
          "uuid": "MONDO:0014716",
          "obo_short": "MONDO_0014716",
          "uri": "http://purl.obolibrary.org/obo/MONDO_0014716",
          "parentInstancesUUIDsFlat": "MONDO:0015330|MONDO:0002320|MONDO:0100283|MONDO:0020022|MONDO:0005071|MONDO:0003847|OTAR:0000018|MONDO:0015159|MONDO:0019042|MONDO:0100545|MONDO:0019755|EFO:0000618|MONDO:0700096|MONDO:0000001|MONDO:0…",
          "forQL": true,
          "name": "MONDO_0014716",
          "bxID": "MONDO:0014716"
        }
      },
      "_r:found on": {
        "type": "found on",
        "properties": {
          "impact": "MODIFIER|HIGH",
          "effect": "downstream_gene_variant|frameshift_variant",
          "aaChange": "p.Asn2071fs|p.Asn276fs"
        }
      },
      "_r2:associated with disease": {
        "type": "associated with disease",
        "properties": {}
      }
    },
    {
      "g:Gene": {
        "uuid": "ENSG00000198793",
        "displayName": "MTOR",
        "dbLabels": [
          "Gene"
        ],
        "properties": {
          "symbol": "MTOR",
          "normalized_names": [
            "fk506 binding protein 12 rapamycin associated protein 1",
            "rapamycin associated protein frap2",
            "fk506 binding protein 12 rapamycin associated protein 2",
            "… 16 more"
          ],
          "displayName": "MTOR",
          "source": "HAVANA",
          "uuid": "ENSG00000198793",
          "synonym": "RAFT1|RAPT1|FLJ44809|FK506 binding protein 12-rapamycin associated protein 2|rapamycin target protein|FKBP12-rapamycin complex-associated protein 1|FKBP-rapamycin associated protein|rapamycin associat…",
          "strand": "-",
          "ensembl_gene_id_version": "ENSG00000198793.14",
          "HGNC": "HGNC:3942",
          "ensembl_gene_id": "ENSG00000198793",
          "assembly": "GRCh38.p14",
          "NCBI": 2475,
          "alias": [
            "FRAP",
            "FRAP1",
            "FRAP2",
            "… 3 more"
          ],
          "taxon": 9606,
          "end": 11262556,
          "tag": [
            ""
          ],
          "band": "p36.22",
          "HGNC symbol": "MTOR",
          "bxID": "ENSG00000198793",
          "biotype": "protein_coding",
          "summary": "The protein encoded by this gene belongs to a family of phosphatidylinositol kinase-related kinases. These kinases mediate cellular responses to stresses such as DNA damage and nutrient deprivation. T…",
          "percentGC": 44.55,
          "level": "manually annotated loci",
          "start": 11106535,
          "chr": "1",
          "name": "mechanistic target of rapamycin kinase",
          "fullname": "mechanistic target of rapamycin kinase"
        }
      },
      "m:Mutation": {
        "uuid": "CLINVAR:1054057",
        "displayName": "CLINVAR:1054057",
        "dbLabels": [
          "Mutation",
          "SNV"
        ],
        "properties": {
          "mut_type": "SNV",
          "clinvarID": 1054057,
          "ref": "T",
          "transcripts": "[[\"ENSG00000198793\", \"1NSG:B_2023-B_2057:ENST00000361445\", \"structural_interaction_variant\", \"HIGH\", \"\"], [\"ENSG00000198793\", \"ENST00000361445\", \"missense_variant\", \"MODERATE\", \"p.Met2057Val\"], [\"ENSG…",
          "pos": 11127671,
          "displayName": "CLINVAR:1054057",
          "effect": "structural_interaction_variant",
          "impact": "HIGH",
          "alt": "C",
          "chr": 1,
          "uuid": "CLINVAR:1054057"
        }
      },
      "d:Disease": {
        "uuid": "MONDO:0014716",
        "displayName": "macrocephaly-intellectual disability-neurodevelopmental disorder-small thorax syndrome",
        "dbLabels": [
          "Disease"
        ],
        "properties": {
          "normalized_names": [
            "macrocephaly intellectual disability neurodevelopmental disorder small thorax syndrome"
          ],
          "CURIE": "MONDO:0014716",
          "ontologyNamespace": "MONDO",
          "parentInstances": [
            "multiple congenital anomalies/dysmorphic syndrome",
            "disease",
            "multiple congenital anomalies/dysmorphic syndrome-intellectual disability",
            "… 13 more"
          ],
          "displayName": "macrocephaly-intellectual disability-neurodevelopmental disorder-small thorax syndrome",
          "parentInstancesUUIDs": [
            "MONDO:0015330",
            "MONDO:0002320",
            "MONDO:0100283",
            "… 13 more"
          ],
          "description": "A rare multiple congenital anomalies/dysmorphic syndrome with intellectual disability, characterized by macrocephaly, intellectual disability, seizures, dysmorphic facial features (including tall fore…",
          "parentInstancesFlat": "multiple congenital anomalies/dysmorphic syndrome|disease|multiple congenital anomalies/dysmorphic syndrome-intellectual disability|hereditary neurological disease|overgrowth syndrome and/or cerebral …",
          "label": "macrocephaly-intellectual disability-neurodevelopmental disorder-small thorax syndrome",
          "uuid": "MONDO:0014716",
          "obo_short": "MONDO_0014716",
          "uri": "http://purl.obolibrary.org/obo/MONDO_0014716",
          "parentInstancesUUIDsFlat": "MONDO:0015330|MONDO:0002320|MONDO:0100283|MONDO:0020022|MONDO:0005071|MONDO:0003847|OTAR:0000018|MONDO:0015159|MONDO:0019042|MONDO:0100545|MONDO:0019755|EFO:0000618|MONDO:0700096|MONDO:0000001|MONDO:0…",
          "forQL": true,
          "name": "MONDO_0014716",
          "bxID": "MONDO:0014716"
        }
      },
      "_r:found on": {
        "type": "found on",
        "properties": {
          "impact": "MODIFIER|MODERATE|HIGH",
          "effect": "downstream_gene_variant|missense_variant|structural_interaction_variant",
          "aaChange": "p.Met262Val|p.Met2057Val"
        }
      },
      "_r2:associated with disease": {
        "type": "associated with disease",
        "properties": {}
      }
    },
    {
      "g:Gene": {
        "uuid": "ENSG00000198793",
        "displayName": "MTOR",
        "dbLabels": [
          "Gene"
        ],
        "properties": {
          "symbol": "MTOR",
          "normalized_names": [
            "fk506 binding protein 12 rapamycin associated protein 1",
            "rapamycin associated protein frap2",
            "fk506 binding protein 12 rapamycin associated protein 2",
            "… 16 more"
          ],
          "displayName": "MTOR",
          "source": "HAVANA",
          "uuid": "ENSG00000198793",
          "synonym": "RAFT1|RAPT1|FLJ44809|FK506 binding protein 12-rapamycin associated protein 2|rapamycin target protein|FKBP12-rapamycin complex-associated protein 1|FKBP-rapamycin associated protein|rapamycin associat…",
          "strand": "-",
          "ensembl_gene_id_version": "ENSG00000198793.14",
          "HGNC": "HGNC:3942",
          "ensembl_gene_id": "ENSG00000198793",
          "assembly": "GRCh38.p14",
          "NCBI": 2475,
          "alias": [
            "FRAP",
            "FRAP1",
            "FRAP2",
            "… 3 more"
          ],
          "taxon": 9606,
          "end": 11262556,
          "tag": [
            ""
          ],
          "band": "p36.22",
          "HGNC symbol": "MTOR",
          "bxID": "ENSG00000198793",
          "biotype": "protein_coding",
          "summary": "The protein encoded by this gene belongs to a family of phosphatidylinositol kinase-related kinases. These kinases mediate cellular responses to stresses such as DNA damage and nutrient deprivation. T…",
          "percentGC": 44.55,
          "level": "manually annotated loci",
          "start": 11106535,
          "chr": "1",
          "name": "mechanistic target of rapamycin kinase",
          "fullname": "mechanistic target of rapamycin kinase"
        }
      },
      "m:Mutation": {
        "uuid": "CLINVAR:918028",
        "displayName": "CLINVAR:918028",
        "dbLabels": [
          "Mutation"
        ],
        "properties": {
          "clinvarID": 918028,
          "mut_type": "Duplication",
          "ref": "G",
          "transcripts": "[[\"ENSG00000198793\", \"ENST00000361445\", \"frameshift_variant&stop_gained\", \"HIGH\", \"p.Tyr2225fs\"], [\"ENSG00000198793\", \"ENST00000376838\", \"frameshift_variant&stop_gained\", \"HIGH\", \"p.Tyr430fs\"]]",
          "pos": 11122114,
          "displayName": "CLINVAR:918028",
          "effect": "frameshift_variant&stop_gained",
          "impact": "HIGH",
          "alt": "GT",
          "chr": 1,
          "uuid": "CLINVAR:918028"
        }
      },
      "d:Disease": {
        "uuid": "MONDO:0011818",
        "displayName": "isolated focal cortical dysplasia type ii",
        "dbLabels": [
          "Disease",
          "EFO"
        ],
        "properties": {
          "normalized_names": [
            "cortical dysplasia taylor type",
            "focal cortical dysplasia of taylor",
            "focal cortical dysplasia type ii somatic",
            "… 19 more"
          ],
          "in_subset": [],
          "CURIE": "MONDO:0011818",
          "ontologyNamespace": "MONDO",
          "parentInstances": [
            "isolated focal cortical dysplasia type ii",
            "disease",
            "obsolete cerebral malformation",
            "… 13 more"
          ],
          "displayName": "isolated focal cortical dysplasia type ii",
          "parentInstancesUUIDs": [
            "MONDO:0015330",
            "MONDO:0016054",
            "MONDO:0100283",
            "… 13 more"
          ],
          "description": "",
          "parentInstancesFlat": "isolated focal cortical dysplasia type ii|disease|obsolete cerebral malformation|human disease|overgrowth syndrome and/or cerebral malformations due to abnormalities in mtor pathway genes|developmenta…",
          "has_related_synonym": [
            "CDT",
            "FCD 2A",
            "FCD 2B",
            "… 16 more"
          ],
          "label": "isolated focal cortical dysplasia type II",
          "uuid": "MONDO:0011818",
          "obo_short": "MONDO_0011818",
          "uri": "http://purl.obolibrary.org/obo/MONDO_0011818",
          "has_exact_synonym": [
            "FCD type II",
            "cortical dysplasia, Taylor type",
            "focal cortical dysplasia, type II, somatic",
            "… 1 more"
          ],
          "database_cross_reference": [
            "GARD:10190",
            "MESH:C537067",
            "OMIM:607341",
            "… 1 more"
          ],
          "parentInstancesUUIDsFlat": "MONDO:0015330|MONDO:0016054|MONDO:0100283|MONDO:0020022|MONDO:0005071|OTAR:0000018|MONDO:0005560|MONDO:0011818|MONDO:0019755|EFO:0000618|MONDO:0700096|MONDO:0019009|MONDO:0002602|MONDO:0017094|MONDO:0…",
          "dbXRefs": [
            "OMIM:607341",
            "GARD:0010190",
            "Orphanet:268994",
            "… 1 more"
          ],
          "see also": [
            "https://rarediseases.info.nih.gov/diseases/10190/focal-cortical-dysplasia-of-taylor"
          ],
          "forQL": true,
          "synonyms_json": "{\"hasExactSynonym\": [\"FCD type II\", \"focal cortical dysplasia, type II, somatic\", \"cortical dysplasia, Taylor type\", \"isolated focal cortical dysplasia type 2\"], \"hasRelatedSynonym\": [\"FCD 2A\", \"corti…",
          "name": "MONDO_0011818",
          "therapeuticAreas": [
            "OTAR_0000018",
            "EFO_0000618"
          ],
          "bxID": "MONDO:0011818"
        }
      },
      "_r:found on": {
        "type": "found on",
        "properties": {
          "effect": "frameshift_variant&stop_gained",
          "impact": "HIGH",
          "aaChange": "p.Tyr430fs|p.Tyr2225fs"
        }
      },
      "_r2:associated with disease": {
        "type": "associated with disease",
        "properties": {}
      }
    },
    "… 6 more"
  ],
  "returnedCount": 9,
  "total": 9,
  "truncated": false
}
```