directus/docs/reference/system/fields.md

description, readTime, pageClass

description	readTime	pageClass
REST and GraphQL API documentation on the Fields collection in Directus.	7 min read	page-reference

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

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 Directus data type of the field. See Types for possible options.

Meta

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

id integer
Primary key of the metadata row in directus_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 directus_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 Directus.

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.

Request

GET /fields

POST /graphql/system

type Query {
	fields: [directus_fields]
}

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

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

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

Query Parameters

This endpoint doesn't currently support any query parameters.

Response

An array of field objects.

Example

GET /fields

POST /graphql/system

query {
	fields {
		collection
		field
	}
}

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

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

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

List Fields in Collection

List the available fields in a given collection.

Request

GET /fields/:collection

POST /graphql/system

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

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

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

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

Query Parameters

This endpoint doesn't currently support any query parameters.

Response

An array of field objects.

Example

GET /fields/articles

POST /graphql/system

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

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

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

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

Retrieve a Field

Get a single field in a given collection.

Request

GET /fields/:collection/:field

POST /graphql/system

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

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

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

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

Query Parameters

This endpoint doesn't currently support any query parameters.

Response

A field object.

Example

GET /fields/articles/title

POST /graphql/system

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

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

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

const result = await client.request(readField('articles', 'title'));

Create a Field

Create a new field in the given collection.

Request

POST /fields/:collection

{
	"field": "field_key",
	"type": "value_type",
	"field_field": {
		"field_sub_field": "value_1"
	}
}

POST /graphql/system

type Mutation {
	create_fields_item(collection: String!, data: create_directus_fields_input!): directus_fields
}

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

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

const result = await client.request(
	createField('collection_name', {
		field: 'field_name',
		type: 'field_type',
		field_field: {
			field_sub_field: 'value_3',
		},
	})
);

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

Response

The field object for the created field.

Example

POST /fields/articles

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

POST /graphql/system

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

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

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

const result = await client.request(
	createField('articles', {
		field: 'subject tags',
		type: 'csv',
		meta: {
			interface: 'tags',
			note: 'subject tags for an article',
		},
	})
);

Update a Field

Updates the given field in the given collection.

PATCH /fields/articles/title

{
	"field": {
		"sub_field": "value_1"
	}
}

POST /graphql/system

type Mutation {
	update_fields_item(collection: String!, field: String!, data: update_directus_fields_input!): directus_fields
}

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

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

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

Query Parameters

This endpoint doesn't currently support any query parameters.

Request Body

type
The new type for the field.

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

Response

The field object for the updated field.

Example

PATCH /fields/articles/title

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

POST /graphql/system

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

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

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

const result = await client.request(
	updateField('articles', 'subject tags', {
		meta: {
			note: 'tags for the article based on subjects addressed',
		},
	})
);

Delete a Field

Deletes the given field in the given collection.

::: danger Destructive

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

:::

Request

DELETE /fields/:collection/:field

POST /graphql/system

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

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

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

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

Example

DELETE /fields/articles/title

POST /graphql/system

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

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

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

const result = await client.request(deleteField('articles', 'featured_quote'));