directus/docs/reference/api/system/relations.md

pageClass

pageClass
page-reference

Relations

What data is linked to what other data. Allows you to assign authors to articles, products to sales, and whatever other structures you can think of. Learn more about Relationships.

toc

---

The Relation Object

collection string
Name of the collection. This matches the table name in the database.

field string
Name of the field that holds the related primary key. This matches the column name in the database.

related_collection string
Name of the related collection. This matches the table name in the database.

Meta

Directus metadata. Used to enable non-database relationship types

id integer
Primary key of the metadata row in directus_relations.

many_collection string
Name of the collection. Matches the top level collection field.

many_field string
Name of the field. Matches the top level field field.

one_collection string
Name of the related collection. Matches the top level related_collection field.

one_field string
Name of the one to many field on the other side of the relation.

one_allowed_collections string
What collections are allowed to be used in a many-to-any context.

one_collection_field string
Field that holds the collection name in a many-to-any context.

one_deselect_action nullify | delete
Whether to nullify or delete related one-to-many records.

sort_field string
What field is used to hold the sort field.

junction_field string
What field connects two relations in a many-to-many (o2m-m2o) context.

Schema

"Raw" database information. Based on the database vendor used, different information might be returned. The following are available for all drivers.

table string
The table name.

column string
The column name.

foreign_key_table string
Related table name.

foreign_key_column string
Related column name.

constraint_name string
Name for the foreign key constraint.

on_update string
Update trigger for the foreign key constraint.

on_delete string
Delete trigger for the foreign key constraint.

{
	"collection": "about_us",
	"field": "logo",
	"related_collection": "directus_files",
	"schema": {
		"table": "about_us",
		"column": "logo",
		"foreign_key_table": "directus_files",
		"foreign_key_column": "id",
		"constraint_name": "about_us_logo_foreign",
		"on_update": "NO ACTION",
		"on_delete": "SET NULL"
	},
	"meta": {
		"id": 1,
		"junction_field": null,
		"many_collection": "about_us",
		"many_field": "logo",
		"one_allowed_collections": null,
		"one_collection": "directus_files",
		"one_collection_field": null,
		"one_deselect_action": "nullify",
		"one_field": null,
		"sort_field": null
	}
}

---

List relations

List all relations that exist in Directus.

::: tip Permissions

The data returned in this endpoint will be filtered based on the user's permissions. For example, relations that apply to a collection that the current user doesn't have access to are stripped out.

:::

Query Parameters

Doesn't support any query parameters.

Returns

Array of relation objects. If no items are available, data will be an empty array.

REST API

GET /relations

GraphQL

POST /graphql/system

type Query {
	relations: [directus_relations]
}

Example

query {
	relations {
		collection
		field
	}
}

---

List relations in collection

List all relations that exist in a given collection.

::: tip Permissions

The data returned in this endpoint will be filtered based on the user's permissions. For example, relations that apply to a collection that the current user doesn't have access to are stripped out.

:::

Query Parameters

Doesn't support any query parameters.

Returns

Array of relation objects. If no items are available, data will be an empty array.

REST API

GET /relations/:collection

Example

GET /relations/articles

GraphQL

POST /graphql/system

type Query {
	relations_in_collection(collection: String!): [directus_relations]
}

Example

query {
	relations_in_collection(collection: "articles") {
		collection
		field
	}
}

---

Retrieve a relation

List an existing relation by collection/field name.

Query Parameters

Doesn't support any query parameters.

Returns

Returns the requested relation object.

REST API

GET /relations/:collection/:field

Example

GET /relations/articles/featured_image

GraphQL

POST /graphql/system

type Query {
	relations_by_name(collection: String!, field: String!): directus_relations
}

Example

query {
	relations_by_name(collection: "articles", field: "featured_image") {
		collection
		field
		related_collection
	}
}

---

Create a Relation

Create a new relation.

Query Parameters

Doesn't support any query parameters.

Request Body

A partial relation object.

Returns

Returns the relation object for the created relation.

REST API

POST /relations

Example

// POST /relations

{
	"collection": "articles",
	"field": "featured_image",
	"related_collection": "directus_files"
}

GraphQL

POST /graphql/system

type Mutation {
	create_relations_item(data: create_directus_relations_input!): directus_relations
}

Example

mutation {
	create_relations_item(
		data: { collection: "articles", field: "featured_image", related_collection: "directus_files" }
	) {
		collection
		field
		related_collection
	}
}

---

Update a Relation

Update an existing relation.

Query Parameters

Doesn't support any query parameters.

Request Body

A partial relation object.

Returns

Returns the relation object for the created relation.

REST API

PATCH /relations/:id

Example

// PATCH /relations/15

{
	"meta": {
		"one_field": "articles"
	}
}

GraphQL

POST /graphql/system

type Mutation {
	update_relations_item(id: ID!, data: update_directus_relations_input!): directus_relations
}

Example

mutation {
	update_relations_item(id: 15, data: { meta: { one_field: "articles" } }) {
		collection
		field
		related_collection
	}
}

---

Delete a Relation

Delete an existing relation.

Returns

Empty body.

REST API

DELETE /relations/:id

Example

DELETE /relations/15

GraphQL

POST /graphql/system

type Mutation {
	delete_relations_item(id: ID!): delete_one
}

Example

mutation {
	delete_relations_item(id: 15) {
		id
	}
}