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

id integer
Primary key of the relation.

many_collection string
Collection on the "many" side of the relation.

many_field string
Field on the "many" side of the relation.

one_collection string
Collection on the "one" side of the relation.

one_field string
Field on the "one" side of the relation.

one_collection_field string
In Many-to-Any type fields, this holds the field in the many collection that holds the name of the "one" collection.

one_allowed_collections string
In Many-to-Any type fields, this holds a csv of collection names the user is allowed to use through the m2a relation.

junction_field string
For Many-to-Many type fields, this holds the name of the field that "links" a many-to-one to a one-to-many, creating a many-to-many.

{
	"id": 13,
	"many_collection": "articles",
	"many_field": "featured_image",
	"one_collection": "directus_files",
	"one_field": null,
	"one_collection_field": null,
	"one_allowed_collections": null,
	"junction_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

Supports all global query parameters.

Returns

An array of up to limit relation objects. If no items are available, data will be an empty array.

REST API

GET /relations

GraphQL

type Query {
	relations: [directus_relations]
}

Example

query {
	relations {
		id
		many_collection
		one_collection
	}
}

---

Retrieve a relation

List an existing relation by primary key.

Query Parameters

Supports all global query parameters.

Returns

Returns the requested relation object.

REST API

GET /relations/:id

Example

GET /relations/15

GraphQL

type Query {
	relations_by_id(id: ID!): directus_relations
}

Example

query {
	relations_by_id(id: 15) {
		id
		many_collection
		one_collection
	}
}

---

Create a Relation

Create a new relation.

Query Parameters

Supports all global query parameters.

Request Body

A partial relation object.

Returns

Returns the relation object for the created relation.

REST API

POST /relations

Example

// POST /relations

{
	"many_collection": "articles",
	"many_field": "featured_image",
	"one_collection": "directus_files"
}

GraphQL

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

Example

mutation {
	create_relations_item(
		data: { many_collection: "articles", many_field: "featured_image", one_collection: "directus_files" }
	) {
		id
		many_collection
		one_collection
	}
}

---

Create Multiple Relations

Create multiple new relations.

Query Parameters

Supports all global query parameters.

Request Body

An array of partial relation objects.

Returns

Returns the relation objects for the created relations.

REST API

POST /relations

Example

// POST /relations

[
	{
		"many_collection": "articles",
		"many_field": "featured_image",
		"one_collection": "directus_files"
	},
	{
		"many_collection": "articles",
		"many_field": "category",
		"one_collection": "categories"
	}
]

GraphQL

type Mutation {
	create_relations_items(data: [create_directus_relations_input!]!): [directus_relations]
}

Example

mutation {
	create_relations_items(
		data: [
			{ many_collection: "articles", many_field: "featured_image", one_collection: "directus_files" }
			{ many_collection: "articles", many_field: "category", one_collection: "categories" }
		]
	) {
		id
		many_collection
		one_collection
	}
}

---

Update a Relation

Update an existing relation.

Query Parameters

Supports all global 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

{
	"one_field": "articles"
}

GraphQL

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

Example

mutation {
	update_relations_item(id: 15, data: { one_field: "articles" }) {
		id
		many_collection
		one_collection
	}
}

---

Delete a Relation

Delete an existing relation.

Returns

Empty body.

REST API

DELETE /relations/:id

Example

DELETE /relations/15

GraphQL

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

Example

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

---

Delete Multiple Relations

Delete multiple existing relations.

Request Body

An array of relation primary keys.

Returns

Empty body.

REST API

DELETE /relations

Example

// DELETE /relations
[15, 251, 810]

GraphQL

type Mutation {
	delete_relations_items(ids: [ID!]!): delete_many
}

Example

mutation {
	delete_relations_items(ids: [15, 251, 810]) {
		ids
	}
}

---