> 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-graph-query.md). # run\_graph\_query — Run a read-only graph query Run a read-only graph query Run a read-only graph query ## What it does Run a read-only, ontology-validated graph query — a Cypher MATCH pattern — and get back the anchored nodes, counts-first. The escape hatch for graph questions the fixed tools don't cover. **When to use:** a graph question the fixed tools don't answer directly: a custom multi-hop pattern or a property filter on a class; exploring relationships between classes (e.g. which Diseases a Gene connects to). **When NOT to use:** an ontology-respecting (BxQL) query, or correlated multi-column path rows rather than one anchor's node list (use run\_bxql — the BxQL counterpart); a single entity's typed neighbors (use get\_entity\_connections); the shortest path between two specific nodes (use find\_paths); ranked / scored results from a reasoning model (use get\_report\_scores). **Parameters:** * `cypher` — a single Cypher MATCH pattern with NO RETURN (the query anchors on `anchor` and the rows returned are that variable's nodes — the resolver appends the RETURN itself). Writes (SET/CREATE/MERGE/DELETE/DETACH/REMOVE/DROP/FOREACH/LOAD), procedure CALL, a user RETURN, multiple statements (';'), and backtick-quoted identifiers are REJECTED. Every node label must be a real ontology class (from get\_graph\_schema / list\_entity\_types). Example: "MATCH (g:Gene {displayName: 'ERBB4'})-\[]-(d:Disease)". * `anchor` — the variable in the MATCH pattern whose nodes you want back (e.g. "d" to return the Disease nodes from the example above). Must be a single bare identifier — no punctuation or whitespace. * `limit` — max rows to return (optional; default 25, max 100) — `total` still reports all matches. * `offset` — rows to skip for paging (optional; default 0). * `includeProperties` — Optional (default false): also return each row's raw stored properties (e.g. chr, biotype, summary for a Gene). Off by default — properties can be large and `total` here can be huge, so only ask for this when you actually need the node's raw data, not just its identity. **Returns:** An object { total, hasMore, truncated, returnedCount, rows }. `total` is the full match count and MAY BE HUGE (counts-first — e.g. MATCH (g:Gene) anchored on g is \~144,858); only `returnedCount` rows (≤ limit) are returned. Each row has: uuid, displayName, and dbLabels (graph labels), plus properties (the node's raw stored property bag) when `includeProperties` was set. `hasMore` is true if the gateway has more beyond this page; `truncated` is true if the page was capped client-side. Narrow the MATCH pattern (add a property filter) when `total` is large. ## Parameters | Parameter | Type | Required | Description | | ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `cypher` | string | yes | a single Cypher MATCH pattern with NO RETURN (the query anchors on `anchor` and the rows returned are that variable's nodes — the resolver appends the RETURN itself). Writes (SET/CREATE/MERGE/DELETE/DETACH/REMOVE/DROP/FOREACH/LOAD), procedure CALL, a user RETURN, multiple statements (';'), and backtick-quoted identifiers are REJECTED. Every node label must be a real ontology class (from get\_graph\_schema / list\_entity\_types). Example: "MATCH (g:Gene {displayName: 'ERBB4'})-\[]-(d:Disease)". | | `anchor` | string | yes | the variable in the MATCH pattern whose nodes you want back (e.g. "d" to return the Disease nodes from the example above). Must be a single bare identifier — no punctuation or whitespace. | | `limit` | number | no | max rows to return (optional; default 25, max 100) — `total` still reports all matches. | | `offset` | number | no | rows to skip for paging (optional; default 0). | | `includeProperties` | boolean | no | Optional (default false): also return each row's raw stored properties (e.g. chr, biotype, summary for a Gene). Off by default — properties can be large and `total` here can be huge, so only ask for this when you actually need the node's raw data, not just its identity. | ## Response ```ts { total: number; hasMore: boolean; truncated: boolean; returnedCount: number; rows: Array<{ uuid: string; displayName: string | null; dbLabels: string[]; properties?: { [key: string]: unknown } | undefined | null; }>; } ``` ## Example ```json // run_graph_query({"cypher":"MATCH (g:Gene {displayName:'ERBB4'})-[]-(d:Disease)","anchor":"d","includeProperties":true}) { "cypher": "MATCH (g:Gene {displayName:'ERBB4'})-[]-(d:Disease)", "anchor": "d", "includeProperties": true } ``` Response (arrays truncated): ```json { "total": 321, "hasMore": true, "truncated": false, "returnedCount": 25, "rows": [ { "uuid": "EFO:0000681", "displayName": "renal cell carcinoma", "dbLabels": [ "Disease", "EFO", "Trait" ], "properties": { "normalized_names": [ "hypernephroma", "renal cell carcinoma disease", "kidney adenocarcinoma", "… 3 more" ], "in_subset": [], "CURIE": "EFO:0000681", "parentInstances": [ "carcinoma", "kidney cancer", "glandular cell neoplasm", "… 17 more" ], "displayName": "renal cell carcinoma", "parentInstancesUUIDs": [ "MONDO:0002118", "EFO:0000616", "EFO:0003865", "… 21 more" ], "description": "A carcinoma that arises from glandular epithelial cells of the kidney", "parentInstancesFlat": "carcinoma|kidney cancer|glandular cell neoplasm|urinary system neoplasm|epithelial neoplasm|disease|urinary system disorder|kidney disease|kidney disorder|urinary system disease|human disease|neoplast…", "has_related_synonym": [ "kidney adenocarcinoma", "renal cell adenocarcinoma" ], "label": "renal cell carcinoma", "uuid": "EFO:0000681", "uri": "http://www.ebi.ac.uk/efo/EFO_0000681", "obo_short": "EFO_0000681", "has_exact_synonym": [ "RCC", "hypernephroma", "kidney adenocarcinoma", "… 2 more" ], "parentInstancesUUIDsFlat": "MONDO:0002118|EFO:0000616|EFO:0003865|EFO:0000228|MONDO:0021163|EFO:0000681|MONDO:0000001|MONDO:0024276|MONDO:0021066|MONDO:0045024|EFO:0009690|EFO:0003086|EFO:0002890|MONDO:0005626|MONDO:0005070|MOND…", "database_cross_reference": [ "DOID:4450", "EFO:0000681", "GARD:0013215", "… 14 more" ], "dbXRefs": [ "ONCOTREE:RCC", "EFO:0000681", "SCTID:702391001", "… 12 more" ], "synonyms_json": "{\"hasExactSynonym\": [\"RCC\", \"renal cell carcinoma (disease)\", \"kidney adenocarcinoma\", \"hypernephroma\", \"renal cell carcinoma\"], \"hasRelatedSynonym\": [\"kidney adenocarcinoma\", \"renal cell adenocarcino…", "definition": [ "A carcinoma that arises from glandular epithelial cells of the kidney" ], "therapeuticAreas": [ "EFO_0009690", "MONDO_0045024" ] } }, { "uuid": "MONDO:0000448", "displayName": "paraganglioma", "dbLabels": [ "Resource", "MONDO", "Disease" ], "properties": { "normalized_names": [ "paraganglioma" ], "CURIE": "MONDO:0000448", "ontologyNamespace": "MONDO", "parentInstances": [ "central nervous system disease", "peripheral nervous system disorder", "central nervous system neoplasm", "… 23 more" ], "displayName": "paraganglioma", "parentInstancesUUIDs": [ "MONDO:0005071", "MONDO:0019496", "EFO:0009386", "… 25 more" ], "description": "A benign or malignant neoplasm arising from paraganglia located along the sympathetic or parasympathetic nerves. Infrequently, it may arise outside the usual distribution of the sympathetic and parasy…", "parentInstancesFlat": "central nervous system disease|peripheral nervous system disorder|central nervous system neoplasm|tumour of cranial and spinal nerves|nervous system disease|hereditary disease|hereditary neurological …", "label": "paraganglioma", "uuid": "MONDO:0000448", "obo_short": "MONDO_0000448", "uri": "http://purl.obolibrary.org/obo/MONDO_0000448", "parentInstancesUUIDsFlat": "MONDO:0005071|MONDO:0019496|EFO:0009386|MONDO:0001406|EFO:0000616|MONDO:0000448|EFO:0009387|MONDO:0000001|MONDO:0002602|MONDO:0003620|MONDO:0002366|EFO:0009532|MONDO:0021635|EFO:1000158|MONDO:0045024|…", "forQL": true, "name": "MONDO_0000448", "bxID": "MONDO:0000448" } }, { "uuid": "MONDO:0003295", "displayName": "leiomyomatosis", "dbLabels": [ "Resource", "MONDO", "Disease", "… 1 more" ], "properties": { "normalized_names": [ "leiomyomatosis no icd o subtype morphologic abnormality", "leiomyomatosis no icd o subtype", "leiomyomatosis" ], "CURIE": "MONDO:0003295", "ontologyNamespace": "MONDO", "parentInstances": [ "smooth muscle tumor", "leiomyoma", "benign neoplasm", "… 16 more" ], "displayName": "leiomyomatosis", "parentInstancesUUIDs": [ "EFO:1000121", "MONDO:0003061", "OTAR:0000006", "… 20 more" ], "description": "A condition characterized by the presence of numerous small benign smooth muscle neoplasms located throughout the body.", "parentInstancesFlat": "smooth muscle tumor|leiomyoma|benign neoplasm|mesenchymal cell neoplasm|disease|myomatous neoplasm|muscular disease|musculoskeletal or connective tissue disease|musculoskeletal system disorder|benign …", "label": "leiomyomatosis", "uuid": "MONDO:0003295", "obo_short": "MONDO_0003295", "uri": "http://purl.obolibrary.org/obo/MONDO_0003295", "has_exact_synonym": [ "leiomyomatosis", "leiomyomatosis, no ICD-O subtype", "leiomyomatosis, no ICD-O subtype (morphologic abnormality)" ], "parentInstancesUUIDsFlat": "EFO:1000121|MONDO:0003061|OTAR:0000006|EFO:0000616|MONDO:0005165|MONDO:0021545|MONDO:0006975|MONDO:0003295|EFO:0002422|MONDO:0006106|MONDO:0000001|MONDO:0002616|MONDO:0000636|EFO:0002970|MONDO:0001572…", "database_cross_reference": [ "DOID:5138", "ICDO:8890/1", "MESH:D018231", "… 2 more" ], "dbXRefs": [ "MESH:D018231", "NCIT:C3748", "UMLS:C0206654", "… 2 more" ], "forQL": true, "synonyms_json": "{\"hasExactSynonym\": [\"leiomyomatosis\", \"leiomyomatosis, no ICD-O subtype (morphologic abnormality)\", \"leiomyomatosis, no ICD-O subtype\"]}", "name": "MONDO_0003295", "definition": [ "A condition characterized by the presence of numerous small benign smooth muscle neoplasms located throughout the body." ], "therapeuticAreas": [ "OTAR_0000006", "MONDO_0045024" ], "bxID": "MONDO:0003295" } }, "… 22 more" ] } ```