# # 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
- List Collections
- Retrieve a Collection
- Create a Collection
- Update a Collection
- Delete a Collection

## # The Collection Object

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

#### # Meta

Gitaflow 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.

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
    	}
    }

## # List Collections

List the available collections.

### # Query Parameters

This endpoint doesn't currently support any query parameters.

### # Returns

An array of collection objects.

### # REST API

    GET /collections
    SEARCH /collections

Learn more about SEARCH ->

### # GraphQL

    POST /graphql/system

    type Query {
    	collections: [gitaflow_collections]
    }

##### # Example

    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.

### # REST API

    GET /collections/:collection

##### # Example

    GET /collections/articles

### # GraphQL

    POST /graphql/system

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

##### # Example

    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 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.

### # Returns

The collection object for the collection created in this request.

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.

### # REST API

    POST /collections

##### # Example

    // POST /collections

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

### # GraphQL

    POST /graphql/system

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

##### # Example

    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 collection object. Updating the collection name is not supported at this time.

### # Returns

The collection object for the updated collection in this request.

### # REST API

    PATCH /collections/:collection

##### # Example

    // PATCH /collections/testimonials

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

### # GraphQL

    POST /graphql/system

    type Mutation {
    	update_collections_item(collection: String!, data: update_gitaflow_collections_input!): gitaflow_collections
    }

##### # Example

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

## # Delete a Collection

Delete a collection.

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

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

##### # Example

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