directus/docs/reference/system/collections.md

description, readTime, pageClass

description	readTime	pageClass
REST and GraphQL API documentation on the "Collections" collection in Directus.	5 min read	page-reference

Collections

Collections are the individual collections of items, similar to tables in a database. Changes to collections will alter the schema of the database. Learn more about Collections.

The Collection Object

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

Meta

Directus metadata, primarily used in the Admin App.

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

icon string
Icon displayed in the Admin App when working with this collection.

note string
Short description displayed in the Admin App.

display_template string
How items in this collection should be displayed when viewed relationally in the Admin App.

hidden boolean
Whether or not this collection is hidden in the Admin App.

singleton boolean
Whether or not this collection is treated as a singleton.

translations array
How this collection's name is displayed in the different languages in the Admin App.

archive_field string
What field in the collection holds the archived state.

archive_value string
What value the archive field should be set to when archiving an item.

unarchive_value string
What value the archive field should be set to when unarchiving an item.

archive_app_filter boolean
Whether or not the Admin App should allow the user to view archived items.

sort_field boolean
What field holds the sort value on the collection. The Admin App uses this to allow drag-and-drop manual sorting.

accountability string
What data is tracked. One of all, activity. See Accountability for more information.

item_duplication_fields array
What fields are duplicated during "Save as copy" action of an item in this collection. See Duplication for more information.

group string
The name of the parent collection. This is used in grouping/nesting of collections.

sort number
What sort order of the collection relative to other collections of the same level. This is used in sorting of collections.

collapse string
What is the default behavior of this collection or "folder" collection when it has nested collections. One of open, closed, locked.

Schema

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

name string
The table name.

comment string
The table comment.

Fields

This holds an array of initial fields used for the collection. You can use the same model as used in Fields to submit fields here. You can use this to set a custom primary key type as well. If a primary key field is omitted, the request will auto-generate an auto-incremented primary key field named id.

::: tip

"folder" collections do not hold any data, hence their schema would be null.

:::

{
	"collection": "articles",
	"meta": {
		"collection": "articles",
		"icon": "article",
		"note": "Blog posts",
		"display_template": "{{ title }}",
		"hidden": false,
		"singleton": false,
		"translations": [
			{
				"language": "en-US",
				"translation": "Articles"
			},
			{
				"language": "nl-NL",
				"translation": "Artikelen"
			}
		],
		"archive_field": "status",
		"archive_value": "archived",
		"unarchive_value": "draft",
		"archive_app_filter": true,
		"sort_field": "sort",
		"item_duplication_fields": null,
		"sort": 1
	},
	"schema": {
		"name": "pages",
		"comment": null
	},
	"fields": [
		{
			"field": "title",
			"type": "string",
			"meta": {
				"icon": "title"
			},
			"schema": {
				"is_primary_key": true,
				"is_nullable": false
			}
		}
	]
}

List Collections

List the available collections.

Request

GET /collections

SEARCH /collections

POST /graphql/system

type Query {
	collections: [directus_collections]
}

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

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

const result = await client.request(readCollections());

Learn more about SEARCH ->

Query Parameters

This endpoint doesn't currently support any query parameters.

Response

An array of collection objects.

Example

GET /collections

SEARCH /collections

POST /graphql/system

query {
	collections {
		# ...
	}
}

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

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

const result = await client.request(readCollections());

Retrieve a Collection

Retrieve a single collection by table name.

Request

GET /collections/:collection

POST /graphql/system

type Query {
	collections_by_name(name: String!): directus_collections
}

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

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

const result = await client.request(readCollection('collection_name'));

Query Parameters

This endpoint doesn't currently support any query parameters.

Response

A collection object.

Example

GET /collections/articles

POST /graphql/system

query {
	collections_by_name(name: "articles") {
		# ...
	}
}

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

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

const result = await client.request(readCollection('articles'));

Create a Collection

Create a new Collection. This will create a new table in the database as well.

Request

POST /collections

{
	"collection": "collection_name",
	"field": {
		"sub_field": "value"
	}
}

POST /graphql/system

type Mutation {
	create_collections_item(data: directus_collections): directus_collections
}

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

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

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

Query Parameters

This endpoint doesn't currently support any query parameters.

Request Body

The collection property is required, all other properties of the collection object are optional.

You are able to provide an array of fields to be created during the creation of the collection. See the fields object for more information on what properties are available in a field.

::: tip

Make sure to pass an empty object for schema (schema: {}) when creating collections. Alternatively, you can omit it entirely or use schema: null to create "folder" collections.

:::

Returns

The collection object for the collection created in this request.

Example

POST /collections

{
	"collection": "testimonials",
	"meta": {
		"icon": "format_quote"
	}
}

POST /graphql/system

mutation {
	create_collections_item(data: { collection: "testimonials", meta: { icon: "format_quote" } }) {
		# ...
	}
}

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

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

const result = await client.request(
	createCollection({
		collection: 'testimonials',
		meta: {
			note: 'Some quotes from our readers',
		},
	})
);

Update a Collection

Update the metadata for an existing collection.

Request

PATCH /collections/:collection

{
	"meta": {
		"field": "value"
	}
}

POST /graphql/system

type Mutation {
	update_collections_item(collection: String!, data: update_directus_collections_input!): directus_collections
}

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

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

const result = await client.request(
	updateCollection('collection_name', {
		meta: {
			field: 'value',
		},
	})
);

Query Parameters

This endpoint doesn't currently support any query parameters.

Request Body

You can only update the meta values of the collection object. Updating the collection name is not supported at this time.

Response

The collection object for the updated collection in this request.

Example

PATCH /collections/testimonials

{
	"meta": {
		"note": "Short quotes from happy customers."
	}
}

POST /graphql/system

mutation {
	update_collections_item(collection: "testimonials", data: { meta: { note: "Short quotes from happy customers." } }) {
		collection
	}
}

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

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

const result = await client.request(
	updateCollection('testimonials', {
		meta: {
			note: 'Will be removing these at the end of first quarter',
		},
	})
);

Delete a Collection

Delete a collection.

::: danger Destructive

Be aware, this will delete the table from the database, including all items in it. This action can't be undone.

:::

Request

DELETE /collections/:collection

POST /graphql/system

type Mutation {
	delete_collections_item(collection: String!): delete_collection
}

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

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

const result = await client.request(deleteCollection('collection_name'));

Example

DELETE /collections/articles

POST /graphql/system

mutation {
	delete_collections_item(collection: "articles") {
		collection
	}
}

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

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

const result = await client.request(deleteCollection('testimonials'));