> 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/validate-bxql.md).

# validate\_bxql — Validate a BxQL query

Validate a BxQL query

Validate a BxQL query

## What it does

Check whether a BxQL query is well-formed and compiles to Cypher, by parse-only compiling it through the gateway — the query is validated, NOT executed. Use it to confirm a query parses before returning or running it.

**When to use:** you have assembled a BxQL query and want to confirm it parses before relying on it; a query failed and you need the parse error to correct it, then re-validate.

**When NOT to use:** actually running a query to get rows back (use run\_graph\_query for read-only Cypher); discovering the valid labels / relationships to build a query (use get\_graph\_schema, list\_entity\_types, describe\_entity\_type).

**Parameters:**

* `query` — the BxQL query to validate, e.g. "(g:Gene {displayName = "BRCA1"})-> associated\_with-> (d:Disease)". It is parsed/compiled only — never executed.

**Returns:** An object { valid, error, cypher }. `valid` is true when the BxQL compiles. When invalid, `error` is the gateway's parse diagnostic and `cypher` is null — fix the query and re-validate. When valid, `error` is null and `cypher` is the Cypher the BxQL compiles to (null if the gateway did not return it). This checks SYNTAX/compilation only — a well-formed query over a label or relationship that isn't in the ontology can still be valid, so confirm the ontology terms with get\_graph\_schema / list\_entity\_types.

## Parameters

| Parameter | Type   | Required | Description                                                                                                                                        |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`   | string | yes      | the BxQL query to validate, e.g. "(g:Gene {displayName = "BRCA1"})-> associated\_with-> (d:Disease)". It is parsed/compiled only — never executed. |

## Response

```ts
{
  valid: boolean;
  error: string | null;
  cypher: string | null;
}
```

## Notes

* Uses the submitBxQLQuery MUTATION with returnWithoutRunning:true — parse-only, no side effects (unlike run\_graph\_query, which reads via getOntologyObjectsFromQLCypher).
* An invalid query is a successful { valid:false } result, not an isError — so the model can read the diagnostic and self-correct. Only auth/infra failures throw.
* cypher is read from result.statements\[0].statement; the exact success-payload path is PENDING a Phase-0 live check — if it differs, cypher is null and the valid verdict is unaffected.

## Example

```json
// validate_bxql({"query":"(g:Gene {displayName = \"ERBB4\"})"})
{
  "query": "(g:Gene {displayName = \"ERBB4\"})"
}
```

Response (arrays truncated):

```json
{
  "valid": true,
  "error": null,
  "cypher": "MATCH\n(g:`Gene`)\nWHERE ((g.`displayName`='ERBB4'))\nWITH g LIMIT 100000 \nRETURN DISTINCT g \nSKIP 0\nLIMIT 25"
}
```