---
pageClass: 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](/concepts/collections/).
[[toc]]
---
## 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.
#### 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.
```json
{
"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"
},
"schema": {
"name": "pages",
"comment": null
}
}
```
---
## List Collections
List the available collections.
### Query Parameters
This endpoint doesn't currently support any query parameters.
### Returns
An array of [collection objects](#the-collection-object).
### REST API
```
GET /collections
SEARCH /collections
```
[Learn more about SEARCH ->](/reference/api/introduction/#search-http-method)
### GraphQL
```
POST /graphql/system
```
```graphql
type Query {
collections: [directus_collections]
}
```
##### Example
```graphql
query {
collections {
...
}
}
```
---
## Retrieve a Collection
Retrieve a single collection by table name.
### Query Parameters
This endpoint doesn't currently support any query parameters.
### Returns
A [collection object](#the-collection-object).
### REST API
```
GET /collections/:collection
```
##### Example
```
GET /collections/articles
```
### GraphQL
```
POST /graphql/system
```
```graphql
type Query {
collections_by_name(name: String!): directus_collections
}
```
##### Example
```graphql
query {
collections_by_name(name: "articles") {
...
}
}
```
---
## Create a Collection
Create a new Collection. This will create a new table in the database as well.
### 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](#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](/reference/api/system/fields/#the-fields-object) for more information on what properties are available
in a field.
### Returns
The [collection object](#the-collection-object) for the collection created in this request.
### REST API
```
POST /collections
```
##### Example
```json
// POST /collections
{
"collection": "testimonials",
"meta": {
"icon": "format_quote"
}
}
```
### GraphQL
```
POST /graphql/system
```
```graphql
type Mutation {
create_collections_item(data: directus_collections): directus_collections
}
```
##### Example
```graphql
mutation {
create_collections_item(data: {
collection: "testimonials",
meta: {
icon: "format_quote"
}
}) {
...
}
}
```
---
## Update a Collection
Update the metadata for an existing collection.
### Query Parameters
This endpoint doesn't currently support any query parameters.
### Request Body
You can only update the `meta` values of the the [collection object](#the-collection-object). Updating the collection
name is not supported at this time.
### Returns
The [collection object](#the-collection-object) for the updated collection in this request.
### REST API
```
PATCH /collections/:collection
```
##### Example
```json
// PATCH /collections/testimonials
{
"meta": {
"note": "Short quotes from happy customers."
}
}
```
### GraphQL
```
POST /graphql/system
```
```graphql
type Mutation {
update_collections_item(collection: String!, data: update_directus_collections_input!): directus_collections
}
```
##### Example
```graphql
mutation {
update_collections_item(collection: "testimonials", data: { meta: { note: "Short quotes from happy customers." } }) {
collection
}
}
```
---
## 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.
:::
### REST API
```
DELETE /collections/:collection
```
##### Example
```
DELETE /collections/articles
```
### GraphQL
```
POST /graphql/system
```
```graphql
type Mutation {
delete_collections_item(collection: String!): delete_collection
}
```
##### Example
```graphql
mutation {
delete_collections_item(collection: "articles") {
collection
}
}
```
---