# Zucms

## Relations

> Category: Models

---

## Pages

- [Introduction](https://docs.zucms.co/introduction)

### API

- [RESTful API](https://docs.zucms.co/api/rest)
- [Typescript SDK](https://docs.zucms.co/api/typescript)

### Getting Started

- [Quick Start](https://docs.zucms.co/getting-started/quick-start)
- [Core Concepts](https://docs.zucms.co/getting-started/core-concepts)

### Models

- [Overview](https://docs.zucms.co/models/overview)
- [Field Types](https://docs.zucms.co/models/field-types)
- [Relations](https://docs.zucms.co/models/relations)

### Content

- [Working with Entries](https://docs.zucms.co/content/working-with-entries)
- [Localization](https://docs.zucms.co/content/localization)

### Access & Security

- [Roles](https://docs.zucms.co/access-security/roles)
- [Access Policies](https://docs.zucms.co/access-security/access-policies)

### Organization

- [Members & Roles](https://docs.zucms.co/organization/members-roles)
- [Audit Log](https://docs.zucms.co/organization/audit-log)
- [Billing & Plans](https://docs.zucms.co/organization/billing-plans)

---

# Relations

A relation field links entries in one model to entries in another model (or back to itself). Zucms supports five relation types.

## Relation types

### `one_to_one`

One entry in model A links to exactly one entry in model B.

**Example:** a `User` has one `Profile`.

### `one_to_many`

One entry in model A links to many entries in model B.

**Example:** a `Category` has many `Posts`.

### `many_to_one`

Many entries in model A each link to one entry in model B. This is the inverse of `one_to_many`.

**Example:** many `Posts` belong to one `Author`.

### `many_to_many`

Many entries in model A link to many entries in model B.

**Example:** `Posts` and `Tags` — a post can have many tags, and a tag can belong to many posts.

### `self_reference`

An entry links to another entry in the same model. Used for hierarchical structures.

**Example:** a `Category` has a parent `Category`.

## Creating a relation

1. Open a model in **Model Builder**.
2. Add a new field and choose `relation` as the data type.
3. Select the **target model**.
4. Select the **relation type**.
5. Configure the **delete behavior**.
6. Save.

## Delete behaviors

When a related entry is deleted, Zucms needs to know what to do with the reference.

| Behavior | Effect |
|---|---|
| `restrict` | Block the delete if any entry still references this record |
| `set_null` | Clear the relation field on referencing entries |

## Querying relations via the API

Use the `include` parameter to expand relation fields inline:

```bash
GET /api/models/post/entries?include=author,categories
```

Without `include`, the API returns only the related entry's ID.

```json
{
  "author": "abc123"
}
```

With `include=author`:

```json
{
  "author": {
    "id": "abc123",
    "name": "Jane Doe"
  }
}
```

## Model Map

The **Model Builder → Map** view renders all models and their relations as a graph, making it easy to spot unintended cycles or missing links.