> 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/ground-query.md).

# ground\_query — Ground query mentions to real, data-backed values

Ground query mentions to real, data-backed values

Ground query mentions to real, data-backed values

## What it does

Resolve each question mention to a REAL, data-backed value for a subgraph: enumerate a slot's valid values conditioned on the already-resolved filters (co-occurrence, not just name-existence), fuzzy-match the closest, and verify the assembled query returns rows. Run it after find\_guidance to turn a playbook's template into a query that actually returns data.

**When to use:** you have a guidance playbook (groundingBxql/bxql) and the question's entity mentions to ground; a mention may not exactly match a data-backed value (e.g. 'basal cell' -> 'basal cell of epidermis'); you want to confirm the assembled query returns the answer node before finalizing.

**When NOT to use:** you only need to resolve one entity by name with no co-occurrence context — use search\_entities; the filters are numeric thresholds ON a relationship (e.g. dependency\_score > 0.5) — those come from the question, not from grounding.

**Parameters:**

* `groundingBxql` — the playbook's discovery sub-path (no answer node), whose nodes carry the slots. Required.
* `slots` — the mentions to ground: \[{ variable, mention, property? }], each mapping a question mention to a variable in the groundingBxql. property defaults to displayName. Required.
* `bxql` — the full query template (with the answer node), for final verification (optional).
* `answerVariable` — which variable in bxql is the answer node, to count and verify (optional).
* `limit` — max candidate values to consider per slot (optional; default 200).

**Returns:** An object { grounded, unresolved, groundedBxql, verified, answerCount }. `grounded` is one entry per resolved slot { variable, mention, property, value, match (exact|fuzzy), confidence, candidateCount } — use `value` as the filter for `variable`. `groundedBxql` is your bxql with the grounded values already injected (use it directly, then validate\_bxql). `verified`/`answerCount` report whether the assembled query returns the answer node. `unresolved` lists mentions with no data-backed match (consider expand\_anchor or telling the user there is no data for X).

## Parameters

| Parameter        | Type   | Required | Description                                                                                                                                                                  |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groundingBxql`  | string | yes      | the playbook's discovery sub-path (no answer node), whose nodes carry the slots. Required.                                                                                   |
| `slots`          | array  | yes      | the mentions to ground: \[{ variable, mention, property? }], each mapping a question mention to a variable in the groundingBxql. property defaults to displayName. Required. |
| `bxql`           | string | no       | the full query template (with the answer node), for final verification (optional).                                                                                           |
| `answerVariable` | string | no       | which variable in bxql is the answer node, to count and verify (optional).                                                                                                   |
| `limit`          | number | no       | max candidate values to consider per slot (optional; default 200).                                                                                                           |

## Response

```ts
{
  grounded: Array<{
    variable: string;
    mention: string;
    property: string;
    value: string;
    match: string;
    confidence: number;
    candidateCount: number;
  }>;
  unresolved: Array<{
    variable: string;
    mention: string;
    reason: string;
  }>;
  groundedBxql: string;
  verified: boolean | null;
  answerCount: number | null;
}
```

## Example

```json
// ground_query({"groundingBxql":"(c:CellType)<- analyzes celltype <-(d:DiffExpDataset)","slots":[{"variable":"c","mention":"basal cell","property":"displayName"}]})
{
  "groundingBxql": "(c:CellType)<- analyzes celltype <-(d:DiffExpDataset)",
  "slots": [
    {
      "variable": "c",
      "mention": "basal cell",
      "property": "displayName"
    }
  ]
}
```

Response (arrays truncated):

```json
{
  "grounded": [
    {
      "variable": "c",
      "mention": "basal cell",
      "property": "displayName",
      "value": "respiratory basal cell",
      "match": "fuzzy",
      "confidence": 0.85,
      "candidateCount": 13,
      "candidatesTruncated": false
    }
  ],
  "unresolved": [],
  "groundedBxql": "(c:CellType {displayName = \"respiratory basal cell\"})<- analyzes celltype <-(d:DiffExpDataset)",
  "verified": null,
  "answerCount": null
}
```