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

# Relations

> Cross-references and connections in the drawing knowledge graph.

A **Relation** is a typed edge in the Drawing Index knowledge graph. It connects two entities -- blocks or features -- with a specific relationship type. Relations are what make the Drawing Index a graph, not just a tree.

Without relations, you have isolated entities: a door here, a schedule there, a legend somewhere else. Relations connect them: this door is **scheduled in** that schedule, this symbol is **defined by** that legend entry, these two rooms are **adjacent to** each other.

## Polymorphic source and target

Relations can connect blocks to blocks, features to features, or features to blocks. The `source_type` and `target_type` discriminator fields indicate which:

| Reference | From | To |
| - | - | - |
| Detail callout `3/A-501` | Feature (detail\_callout on Plan) | Block (Detail on sheet A-501) |
| Door tag to schedule | Feature (door on Plan) | Block (Door Schedule) |
| Symbol to legend definition | Feature (receptacle on Plan) | Feature (legend entry in Legend) |
| Room adjacency | Feature (room) | Feature (room) |
| Cross-revision matching | Block (Plan rev A) | Block (Plan rev B) |

## Relation types

| Type | Direction | Description | Example |
| - | - | - | - |
| `references` | Feature → Block | Callout pointing to another block | Detail callout → Detail block on sheet A-501 |
| `defined_by` | Feature → Feature | Symbol referencing its definition | Receptacle on plan → legend entry that defines it |
| `scheduled_in` | Feature → Block | Tag referencing a schedule row | Door 104 → Door Schedule block |
| `adjacent_to` | Feature ↔ Feature | Spatial adjacency | Room 201 ↔ Room 202 |
| `connects_to` | Feature → Feature | Physical connection | Duct segment → AHU equipment |
| `section_of` | Block → Block | Section view cutting through a plan | Section A-A → Plan it cuts through |
| `similar_to` | Block ↔ Block | Cross-revision block matching | Plan (rev A) ↔ Plan (rev B) |
| `coordinates_with` | Feature ↔ Feature | Same element across disciplines | Arch column ↔ Structural column at same grid |
| `clashes_with` | Feature ↔ Feature | Spatial conflict | Duct ↔ Beam at same location |
| `revises` | Feature → Feature | Revision replacement | New door → old door it replaced |

<Info>
  `relation_type` is a free string, like Feature `type`. The list above covers the current vocabulary but will grow as new cross-reference patterns are discovered.
</Info>

## Key fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier |
| `relation_type` | string | Edge type (see table above) |
| `source_type` | string | `"block"` or `"feature"` |
| `source_id` | string | ID of the source entity |
| `target_type` | string | `"block"` or `"feature"` |
| `target_id` | string | ID of the target entity |
| `metadata` | JSON? | Edge-specific properties (confidence, context) |

Each relation is unique by the combination of `(source_type, source_id, target_type, target_id, relation_type)`.

## Note linking patterns

Construction drawings have three distinct note reference patterns, each modeled differently in the Drawing Index:

### Keynotes (point-specific)

A tag like "KN-3" with a leader arrow pointing to a specific element on the plan. Modeled as a Feature (`type="keynote"`, `label="KN-3"`) linked via a `defined_by` Relation to a keynote entry Feature in the KeyNotes block.

```
Feature(keynote, "KN-3") --defined_by--> Feature(keynote_entry, "KN-3" in KeyNotes block)
```

### General notes (categorical)

Statements like "All GFCI receptacles shall be installed within 6' of any water source." These apply to categories of features, not specific instances. Instead of creating explosive N x M relations, notes are parsed into the block's `metadata` with `applies_to` tags:

```json theme={null}
{
  "entries": [
    {
      "number": "7",
      "text": "Install GFCI receptacles within 6' of any water source.",
      "applies_to": ["gfci_receptacle"]
    }
  ]
}
```

At query time, the system matches `Feature.type` against `applies_to` tags from notes blocks on the same sheet. No explicit Relations needed.

### Sheet notes (sheet-scoped)

Notes specific to one sheet (e.g., "See structural for beam sizes at grid B"). Same metadata structure as general notes, matched contextually via tags.

## API access

<Tabs>
  <Tab title="CMS API">
    ```bash theme={null}
    # List relations for a feature
    GET /relations?source_type=feature&source_id=ftr_01ABC

    # List relations by type
    GET /relations?relation_type=scheduled_in&source_id=ftr_01ABC

    # List all relations targeting a block
    GET /relations?target_type=block&target_id=blk_01ABC
    ```
  </Tab>

  <Tab title="MCP Tools">
    ```
    query_feature({ block_id: "blk_01A", type: "door", label: "104", include: "relations" })
    ```

    Relations are returned inline with feature queries when `include: "relations"` is specified.
  </Tab>
</Tabs>

## Example: door to schedule

Door 104 on a plan view is linked to the Door Schedule via a `scheduled_in` relation:

```json theme={null}
{
  "id": "rel_01ABC",
  "relation_type": "scheduled_in",
  "source_type": "feature",
  "source_id": "ftr_door104",
  "target_type": "block",
  "target_id": "blk_schedule_01",
  "metadata": {
    "row_key": "104"
  }
}
```

The agent reads the schedule block's `metadata.rows["104"]` to get the door specifications:

```json theme={null}
{
  "size": "3070",
  "material": "HM",
  "fire_rating": "45-min",
  "hardware_set": "HW-3"
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Grid System" href="/guides/concepts/grid-system">
    Spatial coordination across disciplines using shared grid lines.
  </Card>

  <Card title="Features" href="/guides/concepts/features">
    The entities that relations connect.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.