directus/docs/reference/system/relations.md

description, readTime, pageClass

description	readTime	pageClass
REST and GraphQL API documentation on the Relations collection in Directus.	5 min read	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.

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.

:::

Request

GET /relations

POST /graphql/system

type Query {
	relations: [directus_relations]
}

import { createDirectus } from '@directus/sdk';
import { rest, readRelations } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readRelations({
		fields: ['*'],
	})
);

Query Parameters

Doesn't support any query parameters.

Response

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

Example

GET /relations

POST /graphql/system

query {
	relations {
		collection
		field
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, readRelations } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readRelations({
		fields: ['*'],
	})
);

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.

:::

Request

GET /relations/:collection

POST /graphql/system

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

import { createDirectus } from '@directus/sdk';
import { rest, readRelationByCollection } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readRelationByCollection('collection_name', {
		fields: ['*'],
	})
);

Query Parameters

Doesn't support any query parameters.

Response

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

Example

GET /relations/articles

POST /graphql/system

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

import { createDirectus } from '@directus/sdk';
import { rest, readRelationByCollection } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readRelationByCollection('articles', {
		fields: ['*'],
	})
);

Retrieve a relation

List an existing relation by collection/field name.

Request

GET /relations/:collection/:field

POST /graphql/system

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

import { createDirectus } from '@directus/sdk';
import { rest, readRelation } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readRelation('collection_name', 'field_name', {
		fields: ['*'],
	})
);

Query Parameters

Doesn't support any query parameters.

Response

Returns the requested relation object.

Example

GET /relations/articles/featured_image

POST /graphql/system

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

import { createDirectus } from '@directus/sdk';
import { rest, readRelation } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readRelation('articles', 'authors', {
		fields: ['*'],
	})
);

Create a Relation

Create a new relation.

Request

POST /relations

{
	"relations_field_1": "value_1",
	"relations_field_2": "value_2",
	"relations_field_3": "value_3"
}

POST /graphql/system

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

import { createDirectus } from '@directus/sdk';
import { rest, createRelation } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createRelation({
		relations_field_1: 'value_1',
		relations_field_2: 'value_2',
		relations_field_3: 'value_3',
	})
);

Query Parameters

Doesn't support any query parameters.

Request Body

A partial relation object.

Response

Returns the relation object for the created relation.

Example

POST /relations

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

POST /graphql/system

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

import { createDirectus } from '@directus/sdk';
import { rest, createRelation } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createRelation({
		collection: 'articles',
		field: 'header_image',
		related_collection: 'header_images',
	})
);

Update a Relation

Update an existing relation.

Request

PATCH /relations/:collection/:field

{
	"relations_field": {
		"relations_subfield": "value"
	}
}

POST /graphql/system

type Mutation {
	update_relations_item(collection: String!, field: String!, data: update_directus_relations_input!): directus_relations
}

import { createDirectus } from '@directus/sdk';
import { rest, updateRelation } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateRelation('collection_name', 'field_name', {
		field: {
			sub_field: 'value',
		},
	})
);

Query Parameters

Doesn't support any query parameters.

Request Body

A partial relation object.

Response

Returns the relation object for the created relation.

Example

PATCH /relations/articles/author

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

POST /graphql/system

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

import { createDirectus } from '@directus/sdk';
import { rest, updateRelation } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateRelation('articles', 'authors', {
		meta: {
			sort_field: 'articles',
		},
	})
);

Delete a Relation

Delete an existing relation.

Request

DELETE /relations/:collection/:field

POST /graphql/system

type Mutation {
	delete_relations_item(collection: String!, field: String!): delete_one
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteRelation } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteRelation('collection_name', 'field_name'));

Returns

Empty body.

Example

DELETE /relations/articles/author

POST /graphql/system

mutation {
	delete_relations_item(collection: "articles", field: "author") {
		collection
		field
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteRelation } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteRelation('articles', 'authors'));