> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dataerai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grounded OR-tree search

> How AI search designs a rich, multi-branch query from the data you can actually see — with a gallery of worked examples.

When you ask AI search a question, Dataerai doesn't just rephrase your words into one filter. It looks at **statistics of the data you can see** — which fields exist, their most common values, their ranges — and designs a **structured OR-condition query** that captures the *facets* of your request. You see that designed query, with a live match count next to every branch, before you run it.

<Note>
  This page is the deep dive, with a gallery of examples. For the short version and how to turn AI search on, see [AI search](/ai/llm-search).
</Note>

## What changed

Earlier, a question like *"electron microscopy data"* often became a single fuzzy text match on the phrase — a rephrasing of what you typed. That misses the point: your corpus might record electron microscopy as `technique = "SEM"`, `"TEM"`, or `"STEM"`, and a phrase match finds none of them reliably.

Grounded search instead enumerates the real values:

<CodeGroup>
  ```text You type theme={null}
  electron microscopy data
  ```

  ```json Dataerai designs theme={null}
  { "or": [
      { "technique": "SEM" },
      { "technique": "TEM" },
      { "technique": "STEM" }
  ] }
  ```
</CodeGroup>

Every branch is a value that **actually exists in your data** — surfaced from the field statistics, not invented. `AFM` is in the corpus too, but it isn't electron microscopy, so it's left out.

## Anatomy of a grounded search

<Steps>
  <Step title="Evidence">
    Dataerai assembles the metadata fields you can see, each with its top values (and how often they occur), numeric/date ranges, and how *discriminating* the field is. A field that splits your corpus many ways (like `technique`) ranks above one that's the same everywhere.
  </Step>

  <Step title="Design">
    The model maps each facet of your question onto those fields and enumerates alternatives as `or` branches, conjunctions as `and`, exclusions as `not`. It prefers exact values from the evidence over guesses.
  </Step>

  <Step title="Verify">
    Each top-level branch is probed against your visible data for a match count. A branch that matches **nothing** is flagged, and Dataerai makes one corrective pass to repair or widen it.
  </Step>

  <Step title="Show">
    You see the designed query — as editable chips when it's a simple list, or as a read-only OR-tree when it nests — with a count beside each branch, before anything runs.
  </Step>
</Steps>

<Note>
  Grounding never widens your permissions. Every value, statistic, and result is drawn from assets you can already access — a value another team can see but you can't will never appear in your query, your counts, or your suggestions.
</Note>

## Example gallery

Each example shows what you type and the query Dataerai designs. The exact values depend on *your* corpus — these use a materials-science workspace.

<AccordionGroup>
  <Accordion title="Enumerate matching values — “electron microscopy data”" icon="layer-group">
    A topical term fans out over the listed values that fit it.

    ```json theme={null}
    { "or": [
        { "technique": "SEM" },
        { "technique": "TEM" },
        { "technique": "STEM" }
    ] }
    ```

    *Why:* `technique` has values `SEM ×1240`, `TEM ×890`, `STEM ×310`, `AFM ×95`. The first three are electron microscopy; `AFM` isn't, so it's excluded.
  </Accordion>

  <Accordion title="Combine a list with a range — “recent SEM or TEM studies”" icon="calendar">
    A value-OR ANDed with a numeric threshold read from the field's distribution.

    ```json theme={null}
    { "and": [
        { "or": [ { "technique": "SEM" }, { "technique": "TEM" } ] },
        { "year": { ">=": 2024 } }
    ] }
    ```

    *Why:* `year` ranges `2018–2026` with a median of `2024`, so "recent" anchors to `>= 2024`.
  </Accordion>

  <Accordion title="Discriminate by field presence — “stained liver or kidney samples”" icon="flask">
    When a field's mere *presence* separates a population, grounded search uses `exists`.

    ```json theme={null}
    { "and": [
        { "or": [ { "sample.tissue": "liver" }, { "sample.tissue": "kidney" } ] },
        { "exists": "staining" }
    ] }
    ```

    *Why:* tissue is enumerated from real values; "stained" maps to *has a `staining` field*, not a specific value.
  </Accordion>

  <Accordion title="Exact values plus a widening arm — “graphene-based samples”" icon="atom">
    Listed exact values first, with a `contains` arm to catch close variants.

    ```json theme={null}
    { "or": [
        { "material": "graphene" },
        { "material": "graphene oxide" },
        { "contains": { "material": "graphene" } }
    ] }
    ```

    *Why:* both `graphene` and `graphene oxide` are real values; the `contains` arm catches any other graphene-prefixed material the statistics didn't surface.
  </Accordion>

  <Accordion title="Exclusion — “everything except retracted work”" icon="ban">
    A `not` around a real value.

    ```json theme={null}
    { "not": { "status": "retracted" } }
    ```

    *Why:* `status` has `published ×5000`, `draft ×900`, `retracted ×40`; the request is the complement of one value.
  </Accordion>

  <Accordion title="Cross-field conjunction — “Titan or Talos sessions with a HAADF detector”" icon="microscope">
    Two facets, each grounded, combined with `and`.

    ```json theme={null}
    { "and": [
        { "or": [ { "instrument": "Titan" }, { "instrument": "Talos" } ] },
        { "detector": "HAADF" }
    ] }
    ```
  </Accordion>

  <Accordion title="Structured + topical — “bar charts about battery degradation”" icon="chart-column">
    The structured facet stays structured; the descriptive remainder rides one similarity arm.

    ```json theme={null}
    { "and": [
        { "chart_type": "bar" },
        { "similar_to": "battery degradation" }
    ] }
    ```

    *Why:* `chart_type = "bar"` is a real value; "battery degradation" has no matching field value, so it becomes a single visual/topical-similarity arm (requires the similarity lane — see [AI search](/ai/llm-search#topical--visual-matching)).
  </Accordion>

  <Accordion title="Date window — “data acquired in 2025”" icon="calendar-days">
    A natural date phrase becomes a half-open range.

    ```json theme={null}
    { "and": [
        { "acquired": { ">=": "2025-01-01" } },
        { "acquired": { "<":  "2026-01-01" } }
    ] }
    ```
  </Accordion>

  <Accordion title="Presence and absence together — “datasets without provenance but with a license”" icon="file-shield">
    `not_exists` and `exists` in one conjunction.

    ```json theme={null}
    { "and": [
        { "not_exists": "provenance_id" },
        { "exists": "license" }
    ] }
    ```
  </Accordion>

  <Accordion title="Nested branches — “SEM graphene or TEM silicon studies”" icon="diagram-project">
    Two complete conditions, each an `and`, joined by `or`.

    ```json theme={null}
    { "or": [
        { "and": [ { "technique": "SEM" }, { "material": "graphene" } ] },
        { "and": [ { "technique": "TEM" }, { "material": "silicon" } ] }
    ] }
    ```

    *Why:* this nests, so it shows as a **read-only OR-tree** rather than editable chips — chips can't yet represent grouped OR/NOT. To narrow it, rephrase.
  </Accordion>

  <Accordion title="Don't know the exact value — “scanning-electron-type techniques”" icon="wand-sparkles">
    When you describe a value you can't name precisely, Dataerai resolves your phrase to the **real values that exist and that you can see**.

    ```json theme={null}
    { "or": [
        { "technique": "SEM" },
        { "technique": "STEM" }
    ] }
    ```

    *Why:* "scanning electron" is matched against the embedded value space for `technique`, and every candidate is checked against your visible data before it's offered. If nothing visible matches, the request falls back to a text search and you're told so (see [Grounding misses](#grounding-misses)). Requires the value-similarity lane to be enabled.
  </Accordion>

  <Accordion title="Genuinely descriptive — “fatigue measurement experiments”" icon="quote-left">
    When *no* field maps to any facet, a single similarity arm is the right answer.

    ```json theme={null}
    { "similar_to": "fatigue measurement experiments" }
    ```

    *Why:* grounded search decomposes when it can and only falls back to pure similarity when the request has no structured facet — the opposite of always rephrasing.
  </Accordion>
</AccordionGroup>

## Reading the results panel

When you translate a query, the panel shows you what was designed and how it landed.

<CardGroup cols={2}>
  <Card title="Per-branch match counts" icon="list-ol">
    A count beside each condition. **Amber “no matches”** means that branch is empty in your data — useful to spot a value that doesn't exist before you commit. `1000+` and `—` (unknown) are shown when a count is large or couldn't be measured in time.
  </Card>

  <Card title="Editable chips vs. read-only tree" icon="diagram-subtask">
    A flat list of conditions becomes editable chips. A nested OR/NOT query renders as a **read-only tree** with a note that it can't be refined as chips yet — rephrase to narrow it.
  </Card>

  <Card title="Grounding misses" icon="triangle-alert">
    If a *“like this”* phrase resolves to no value you can see, you get an amber badge — *“No visible values matched … — widened to a text search”* — instead of a silently empty page.
  </Card>

  <Card title="Broadened results" icon="maximize-2">
    If a precise query matches nothing when you run it, Dataerai widens to the closest results by meaning and shows a **“No exact matches — showing the closest results by meaning”** banner, rather than a bare empty page.
  </Card>
</CardGroup>

<Tip>
  A branch flagged **“no matches”** is the fastest way to see that a value you expected isn't in your data (a typo, a different spelling, or simply not present) — Dataerai also makes one automatic pass to repair or widen such a branch.
</Tip>

## Built for scale

Grounding stays fast no matter how large the catalog grows. Dataerai profiles the **vocabulary** of your metadata — the distinct fields and values — not every record, and refreshes those profiles from bounded samples in the background. The query you see, the per-branch probes, and the value matching all cost the same whether your workspace holds thousands of assets or trillions.

## Availability

Grounded OR-tree design turns on with AI search for your organization. The value-similarity lane (the *“like this”* matching in the gallery above) is enabled separately by an administrator once value embeddings are ready; until then those phrases fall back to a text search. See [AI policy & access](/ai/policy-and-access) and [Configuration reference](/ai/configuration-reference).

## Next steps

<CardGroup cols={3}>
  <Card title="AI search" icon="sparkles" href="/ai/llm-search">
    The overview and how to enable it.
  </Card>

  <Card title="Structured search" icon="search" href="/discover/search">
    The clause-and-operator query grounded search compiles to.
  </Card>

  <Card title="Configuration reference" icon="sliders" href="/ai/configuration-reference">
    The flags and knobs admins use to tune the lane.
  </Card>
</CardGroup>