Create and manage relationships between Directus Collections.

<prerequisites>
Before creating relations:
✓ Collections must exist (use `collections` tool)
✓ Fields must be created with correct types (use `fields` tool)
✓ Junction collections must exist for M2M/M2A relationships
✓ Optional system user fields (`user_created`/`user_updated`) require relations to `directus_users` (see `collections` tool `<system_fields>` section)
</prerequisites>

<actions>
- `create`: Establish relationship between collections
- `read`: View existing relationships
- `update`: Modify relationship settings (only schema.on_delete/on_update and meta can be updated)
- `delete`: Remove relationships
</actions>

<basic_relation> After creating relational fields, define the relationship:

```json
{
	"action": "create",
	"data": {
		"collection": "articles",
		"field": "author",
		"related_collection": "directus_users",
		"meta": { "sort_field": null },
		"schema": { "on_delete": "SET NULL" }
	}
}
```

</basic_relation>

<relationship_types> <m2o_workflow>

### M2O (Many-to-One)

Multiple items in one collection relate to one item in another.

**Example**: Many articles → one author

**Complete M2O Workflow**:

1. **Add M2O field** to the "many" collection → Use `fields` tool with `type: "uuid"` and
   `interface: "select-dropdown-m2o"` (see `fields` tool `<relationship_fields>` M2O example)

2. **Create relation** (use `relations` tool):

```json
{
	"action": "create",
	"collection": "articles",
	"field": "author",
	"data": {
		"collection": "articles",
		"field": "author",
		"related_collection": "directus_users",
		"schema": { "on_delete": "SET NULL" }
	}
}
```

</m2o_workflow>

<o2m_workflow>

### O2M (One-to-Many)

One item in a collection relates to many items in another collection.

**Example**: One author → many articles

**Complete O2M Workflow**:

1. **Add O2M field** to the "one" collection → Use `fields` tool with `type: "alias"`, `special: ["o2m"]`, and
   `interface: "list-o2m"`

2. **Create relation** connecting to existing M2O field (use `relations` tool):

```json
{
	"action": "create",
	"collection": "articles",
	"field": "author",
	"data": {
		"collection": "articles",
		"field": "author",
		"related_collection": "authors",
		"meta": {
			"one_field": "articles",
			"sort_field": null
		},
		"schema": {
			"on_delete": "SET NULL"
		}
	}
}
```

</o2m_workflow>

<m2m_workflow>

### M2M (Many-to-Many)

Items in both collections can relate to multiple items in the other.

**Example**: Articles ↔ Tags

**Complete M2M Workflow**:

1. **Create junction collection** → Use `collections` tool to create `article_tags` with UUID primary key

2. **Add alias fields** to both collections → Use `fields` tool with `type: "alias"`, `special: ["m2m"]`, and
   `interface: "list-m2m"` (see `fields` tool `<relationship_fields>` M2M example)

3. **Add junction fields** → Use `fields` tool to add `article_id` (UUID), `tag_id` (UUID), and optional `sort`
   (integer) fields to junction collection

4. **Create bidirectional relations** (use `relations` tool with CASCADE):

```json
// First relation
{
  "action": "create",
  "collection": "article_tags",
  "field": "article_id",
  "data": {
    "collection": "article_tags",
    "field": "article_id",
    "related_collection": "articles",
    "meta": {
      "one_field": "tags",
      "junction_field": "tag_id",
      "sort_field": "sort"
    },
    "schema": {"on_delete": "CASCADE"}
  }
}

// Second relation
{
  "action": "create",
  "collection": "article_tags",
  "field": "tag_id",
  "data": {
    "collection": "article_tags",
    "field": "tag_id",
    "related_collection": "tags",
    "meta": {
      "one_field": "articles",
      "junction_field": "article_id"
    },
    "schema": {"on_delete": "CASCADE"}
  }
}
```

</m2m_workflow>

<m2a_workflow>

### M2A (Many-to-Any)

Items can relate to items from multiple different collections.

**Example**: Page blocks (hero, text, gallery)

**Complete M2A Workflow**:

1. **Create block collections** → Use `collections` tool to create each block type (e.g., `block_hero`, `block_text`,
   `block_gallery`) with UUID primary keys and specific fields

2. **Create junction collection** → Use `collections` tool to create `page_blocks` junction (hidden collection with UUID
   primary key)

3. **Add M2A field** → Use `fields` tool with `type: "alias"`, `special: ["m2a"]`, and `interface: "list-m2a"`

4. **Add junction fields** → Use `fields` tool to add `page` (UUID), `item` (string), `collection` (string), and `sort`
   (integer) fields to junction

5. **Create relations** (use `relations` tool):

```json
// Item relation (polymorphic)
{
  "action": "create",
  "collection": "page_blocks",
  "field": "item",
  "data": {
    "collection": "page_blocks",
    "field": "item",
    "related_collection": null,
    "meta": {
      "one_allowed_collections": ["block_hero", "block_text", "block_gallery"],
      "one_collection_field": "collection",
      "junction_field": "page_id"
    }
  }
}

// Page relation
{
  "action": "create",
  "collection": "page_blocks",
  "field": "page_id",
  "data": {
    "collection": "page_blocks",
    "field": "page_id",
    "related_collection": "pages",
    "meta": {
      "one_field": "blocks",
      "junction_field": "item",
      "sort_field": "sort"
    },
    "schema": {"on_delete": "CASCADE"}
  }
}
```

</m2a_workflow>

<file_relationships>

### File/Files Relationships

**Single File (M2O)**:

1. **Add file field** → Use `fields` tool with `type: "uuid"`, `special: ["file"]`, and `interface: "file"`

2. **Create relation** (use `relations` tool):

```json
{
	"action": "create",
	"collection": "articles",
	"field": "cover_image",
	"data": {
		"collection": "articles",
		"field": "cover_image",
		"related_collection": "directus_files",
		"schema": { "on_delete": "SET NULL" }
	}
}
```

**Multiple Files (M2M)**:

**Complete Files Workflow**:

1. **Create junction collection** → Use `collections` tool to create junction with UUID primary key

2. **Add files field** to main collection → Use `fields` tool with `type: "alias"`, `special: ["files"]`, and
   `interface: "files"` (see `fields` tool `<relationship_fields>` Files example)

3. **Add junction fields** → Use `fields` tool to add hidden `article_id` and `directus_files_id` (both UUID) fields to
   junction

4. **Create relations** (use `relations` tool):

```json
// Article relation
{
  "action": "create",
  "collection": "article_images",
  "field": "article_id",
  "data": {
    "collection": "article_images",
    "field": "article_id",
    "related_collection": "articles",
    "meta": {
      "one_field": "images",
      "junction_field": "directus_files_id"
    },
    "schema": {"on_delete": "CASCADE"}
  }
}

// File relation
{
  "action": "create",
  "collection": "article_images",
  "field": "directus_files_id",
  "data": {
    "collection": "article_images",
    "field": "directus_files_id",
    "related_collection": "directus_files",
    "meta": {
      "junction_field": "article_id"
    },
    "schema": {"on_delete": "CASCADE"}
  }
}
```

</file_relationships>

<translations_workflow>

### Translations

Special M2M relationship with `languages` collection.

**Complete Translations Workflow**:

1. **Ensure languages collection exists** (use `schema` tool to check)

2. **Create translations junction** → Use `collections` tool to create junction with UUID primary key

3. **Add translations field** → Use `fields` tool with `type: "alias"`, `special: ["translations"]`, and
   `interface: "translations"` (see `fields` tool `<relationship_fields>` Translations example)

4. **Configure junction fields and relations** → Follow M2M pattern with languages collection </translations_workflow>
   </relationship_types>

<relation_settings>

## Relation Settings

### Schema Options

- `on_delete`:
  - `CASCADE` (default for M2M) - Delete related items
  - `SET NULL` (default for M2O) - Set field to null
  - `NO ACTION` - Prevent deletion
  - `RESTRICT` - Prevent if related items exist
  - `SET DEFAULT` - Set to default value

- `on_update`:
  - Same options as `on_delete`

### Meta Options

- `one_field`: Field name in related collection (for O2M side)
- `junction_field`: Opposite field in junction table
- `sort_field`: Enable manual sorting (typically an integer field)
- `one_deselect_action`: `nullify` or `delete`
- `one_allowed_collections`: Array of collection names for M2A
- `one_collection_field`: Field that stores collection name in M2A </relation_settings>

<common_patterns>

## Common Patterns

### Blog System

1. `articles` M2O `directus_users` (author)
2. `articles` M2M `tags`
3. `articles` M2O `directus_files` (cover_image)
4. `articles` M2M `directus_files` (gallery)
5. `articles` O2M `comments`
6. `comments` M2O `directus_users` (author)

### E-commerce

1. `products` M2M `categories`
2. `products` M2O `brands`
3. `products` O2M `reviews`
4. `products` M2M `directus_files` (gallery)
5. `orders` O2M `order_items`
6. `order_items` M2O `products`
7. `orders` M2O `directus_users` (customer)
8. `reviews` M2O `directus_users` (reviewer)

### Page Builder

- `pages` M2A `blocks` field (`page_blocks` junction collection)
- Collections: `block_hero`, `block_text`, `block_gallery` </common_patterns>

<naming_conventions>

## Naming Conventions

- Junction collections: `{singular}_{plural}` (e.g., `product_categories`)
- Junction fields: Singular form of related collection (e.g., `product_id`, `category_id`)
- Alias fields: Plural form for many relations (e.g., `tags`, `categories`)
- M2O fields: Singular form (e.g., `author`, `brand`) </naming_conventions>

<related_tools>

## Related Tools

- `collections`: Create collections and junctions first
- `fields`: Add relational fields before creating relations
- `schema`: View complete relationship structure </related_tools>