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

# Relations

> The typed biological sources that queries import and join — structures, sequences, evidence, and ligands.

A **relation** is a typed source of biological facts: a table whose columns
carry a declared [kind, namespace, and coordinate system](/ontology/identity).
The ontology declares 54 of them, and each also fixes its **grain**, **primary
key**, **default order**, and **recommended filters**. Relations are the nouns of
the ontology. An [RQL recipe](/ontology/rql) begins by importing the
relations it needs, and every [join](/ontology/joins) connects one
relation to another.

## Importing a relation

Recipes pull relations in by name. Importing a relation brings its typed columns
into scope — nothing about a source is available to a query until it is
imported.

```yaml theme={"dark"}
imports:
  - relation: variant_features
  - relation: ligand_neighbors
from: variant_features
```

The `from` line names the relation the query starts from; every other imported
relation reaches it through the join tree.

## The relation families

Relations are organized into families that mirror how biological evidence is
produced. These are the sources recipes draw on most often.

### Structures

Everything anchored to a solved or predicted 3-D structure.

| Relation            | What it holds                                                     |
| ------------------- | ----------------------------------------------------------------- |
| `structure_summary` | Structure identity and per-structure quality (e.g. `mean_plddt`)  |
| `residue_features`  | Per-residue signals along a structure                             |
| `pocket_features`   | Measured binding pockets (`volume_angstrom3`, `mean_local_plddt`) |

### Sequences

The sequence layer and its bridges into structure.

| Relation                   | What it holds                                 |
| -------------------------- | --------------------------------------------- |
| `source_sequence_records`  | Canonical sequences                           |
| `protein_variant_mappings` | Variant positions mapped sequence → structure |
| `variant_features`         | Per-variant annotations (`variant_raw`)       |

### Evidence

Relationships derived *between* entities — similarity and contact.

| Relation               | What it holds                                                                |
| ---------------------- | ---------------------------------------------------------------------------- |
| `fold_hits`            | Structure fold-similarity hits (`query_structure_id`, `target_structure_id`) |
| `homology_search_hits` | Sequence-similarity hits                                                     |
| `interface_features`   | Chain–chain interfaces (`chain_a_id`, `chain_b_id`)                          |
| `interface_contacts`   | Residue contacts across an interface (`distance_angstrom`)                   |

### Ligands

Small molecules and their spatial relationship to protein.

| Relation           | What it holds                                             |
| ------------------ | --------------------------------------------------------- |
| `ligand_neighbors` | Ligands near a residue (`ligand_id`, `distance_angstrom`) |
| `pocket_features`  | Pockets as ligand-binding candidates                      |

## Relations are typed, not raw tables

The difference between a relation and the underlying database table is the
types. Two relations may both expose a `structure_id` column, but each column
declares its kind and coordinate system — so the ontology knows whether they can
be joined directly, need a [lossy or range mapping](/ontology/equivalences),
or must never be compared at all.

<Note>
  **One schema, many sources**

  Every relation is validated against one shared, versioned ontology schema
  before it can be imported. That single schema is what makes a join between two
  independently produced sources safe to write.
</Note>

Next: [Joins & join safety](/ontology/joins) — how relations are
connected, and what the ontology checks before a single row is read.