# # Fields

> Fields are individual pieces of content within an item. They are mapped to columns in the database. Learn more about Fields.

- The Field Object
- List All Fields
- List Fields in Collection
- Retrieve a Field
- Create a Field
- Update a Field
- Delete a Field

## # The Field Object

`collection` string
Name of the collection the field resides in.

`field` string
The identifier of the field. This matches the table column name.

`type` string
The Gitaflow data type of the field. See Types for possible options.

#### # Meta

Gitaflow metadata, primarily used in the Admin App. Meta is optional.

`id` integer
Primary key of the metadata row in `gitaflow_fields`.

`collection` string
The name of the collection this field resides in.

`field` string
Identifier of the field. Matches the column name in the database.

`special` string
Any special transform flags that apply to this field.

`interface` string
The interface used for this field.

`options` object
The interface options configured for this field. The structure is based on the interface used.

`display` string
The display used for this field.

`display_options` string
The configured options for the used display.

`readonly` boolean
If the field is considered readonly in the Admin App.

`hidden` boolean
If the field is hidden from the edit page in the Admin App.

`sort` integer
Where this field is shown on the edit page in the Admin App.

`width` string
How wide the interface is rendered on the edit page in the Admin App. One of `half`, `half-left`, `half-right`, `half-space`, `full`, `fill`.

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

`note` string
Short description displayed in the Admin App.

#### # Schema

"Raw" database information. Based on the database vendor used, different information might be returned. The following are available for all drivers. Note: schema is optional. If a field exist in gitaflow_fields, but not in the database, it's an alias commonly used for relational (o2m) or presentation purposes in the Admin App.

`name` string
Identifier of the field. Matches the column name in the database.

`table` string
Name of the table the column resides in.

`data_type` string
The datatype as used in the database. Note: this value is database vendor specific.

`default_value` any
The configured default value for the column.

`max_length` integer
Configured length for varchar-type columns.

`numeric_precision` integer
Precision for integer/float/decimal type fields.

`numeric_scale` integer
Scale for integer/float/decimal type fields.

`is_nullable` boolean
Whether or not the column is nullable. This is what is used as the "required" state in Gitaflow.

`is_primary_key` boolean
Whether or not the field is the primary key of the table.

`foreign_key_column` string
If the current column has a foreign key constraint, this points to the related column.

`foreign_key_table` string
If the current column has a foreign key constraint, this points to the related table.

`comment` string
Comment as stored in the database.

    {
    	"collection": "articles",
    	"field": "id",
    	"type": "integer",
    	"meta": {
    		"id": 16,
    		"collection": "articles",
    		"field": "id",
    		"special": null,
    		"interface": "numeric",
    		"options": null,
    		"display": null,
    		"display_options": null,
    		"readonly": true,
    		"hidden": true,
    		"sort": 1,
    		"width": "full",
    		"translations": null,
    		"note": "The unique identifier of the article"
    	},
    	"schema": {
    		"name": "id",
    		"table": "articles",
    		"data_type": "integer",
    		"default_value": null,
    		"max_length": null,
    		"numeric_precision": 32,
    		"numeric_scale": 0,
    		"is_nullable": false,
    		"is_primary_key": true,
    		"has_auto_increment": true,
    		"foreign_key_column": null,
    		"foreign_key_table": null,
    		"comment": null
    	}
    }

## # List All Fields

List the available fields.

### # Query Parameters

This endpoint doesn't currently support any query parameters.

### # Returns

An array of field objects.

### # REST API

    GET /fields

### # GraphQL

    POST /graphql/system

    type Query {
    	fields: [gitaflow_fields]
    }

##### # Example

    query {
    	fields {
    		collection
    		field
    	}
    }

## # List Fields in Collection

List the available fields in a given collection.

### # Query Parameters

This endpoint doesn't currently support any query parameters.

### # Returns

An array of field objects.

### # REST API

    GET /fields/:collection

##### # Example

    GET /fields/articles

### # GraphQL

    POST /graphql/system

    type Query {
    	fields_in_collection(collection: String!): gitaflow_fields
    }

##### # Example

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

## # Retrieve a Field

Get a single field in a given collection.

### # Query Parameters

This endpoint doesn't currently support any query parameters.

### # Returns

A field object.

### # REST API

    GET /fields/:collection/:field

##### # Example

    GET /fields/articles/title

### # GraphQL

    POST /graphql/system

    type Query {
    	fields_by_name(collection: String!, field: String!): gitaflow_fields
    }

##### # Example

    query {
    	fields_by_name(collection: "articles", field: "title") {
    		collection
    		field
    	}
    }

## # Create a Field

Create a new field in the given collection.

### # Query Parameters

This endpoint doesn't currently support any query parameters.

### # Request Body

`field` Required
Field key, also used as the column name.

`type` Required
One of the Gitaflow types. This in turn controls what datatype is used for the column in the database. Setting the type to `alias` prevents a column from being created in the database.

`meta`
Any of the optional meta values in the field object.

`schema`
Any of the optional schema values in the field object.

### # Returns

The field object for the created field.

### # REST API

    POST /fields/:collection

##### # Example

    // POST /fields/articles

    {
    	"field": "title",
    	"type": "string",
    	"meta": {
    		"icon": "title"
    	},
    	"schema": {
    		"default_value": "Hello World"
    	}
    }

### # GraphQL

    POST /graphql/system

    type Mutation {
    	create_fields_item(collection: String!, data: create_gitaflow_fields_input!): gitaflow_fields
    }

##### # Example

    mutation {
    	create_fields_item(
    		collection: "articles"
    		data: { field: "title", type: "string", meta: { icon: "title" }, schema: { default_value: "Hello World" } }
    	) {
    		collection
    		field
    	}
    }

## # Update a Field

Updates the given field in the given collection.

### # Query Parameters

This endpoint doesn't currently support any query parameters.

### # Request Body

`type`
The new type for the field.

Changing Type

Types may not be compatible, and/or data might be truncated / corrupted. Please be careful when changing types of an existing field with content.

`meta`
Any of the optional meta values in the field object.

`schema`
Any of the optional schema values in the field object.

Updating the field name is not supported at this time.

### # Returns

The field object for the updated field.

### # REST API

    PATCH /fields/:collection/:field

##### # Example

    // PATCH /fields/articles/title

    {
    	"meta": {
    		"note": "Put the title here"
    	},
    	"schema": {
    		"default_value": "Hello World!"
    	}
    }

### # GraphQL

    POST /graphql/system

    type Mutation {
    	update_fields_item(collection: String!, field: String!, data: update_gitaflow_fields_input!): gitaflow_fields
    }

##### # Example

    mutation {
    	update_fields_item(
    		collection: "articles"
    		field: "title"
    		data: { meta: { note: "Put the title here" }, schema: { default_value: "Hello World!" } }
    	) {
    		collection
    		field
    	}
    }

## # Delete a Field

Deletes the given field in the given collection.

Destructive

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

### # REST API

    DELETE /fields/:collection/:field

##### # Example

    DELETE /fields/articles/title

### # GraphQL

    POST /graphql/system

    type Mutation {
    	delete_fields_item(collection: String!, field: String!): delete_field
    }

##### # Example

    mutation {
    	delete_fields_item(collection: "articles", field: "title") {
    		collection
    		field
    	}
    }