Collections
Collections are database tables with additional metadata and configuration used by Directus.
All Directus-specific settings and data is held only in system collections prefixed with directus_. Should you wish to remove Directus, you can remove these collections with no proprietary data left behind.
There are two types of collections: user collections and system collections.
Creating Collections
User collections are created directly in your database or via Directus. They describe your specific data models and configurations and can be queried via APIs created by Connect or via Explore.
You can create collections from the Data Model settings in the Directus Data Studio, or using the Collections API.
Name
The unique name for your collection must be set on creation, is case sensitive, and will be used throughout the Data Studio and Directus APIs.
The collection name cannot be modified after collection creation, which includes casing. However, you can override how it is displayed in the Data Studio with collection naming translations.
Primary Key
The primary key field contains a unique value for each item in the collection. This unique identifier is used in a number of places:
- When creating relationships between items across different collections.
- When fetching or performing actions on data using the Items API.
The primary key type defines the strategy for creating unique primary keys. Once selected, this cannot be modified.
Additionally, Directus can create some common fields, including a status field, sort, as well as fields related to who and when items are created or edited. Directus supports the following types of IDs:
- Auto-Incremented Integer: IDs increment from
1to2^31-1(2,147,483,647). - Auto-Incremented Big Integer: IDs increment from
1to2^63-1(9,223,372,036,854,775,807). This is only available if using MySQL and PostgreSQL as your database. - Generated UUID: Universally Unique Identifier. Creates a completely unique ID. IDs generated with this system (not just in your database, but anywhere this system is used) are so statistically unlikely to be repeated that for all practical purposes they are unique.
- Manually Entered String: you manually type out a unique string as the ID for each item. Directus will ensure they are unique by forbidding new item creation with a duplicate ID.
Configuring Collections
Once a collection is created, there are a number of configuration options available.
Collection Setup
- Note: set a helpful note that explains the collection's purpose. Seen in Data Model settings page.
- Icon: icon used throughout the Data Studio when referencing this collection.
- Color: color for the icon, shown in the navigation bar and page headers.
- Display Template: display templates are used to represent an item in relationship fields - for example to show the value of the
Namefield when displaying a post's author. - Hidden: toggle whether the collection should be globally hidden in the Data Studio.
- Singleton: toggle to bypass the collection page and take users to the single item details page.
- Collection Naming Translations: translate the collection name across multiple languages. When the default language is changed, the relevant translation will be used throughout the Data Studio.
Content Versioning
Content versioning is used by Editor and allows teams to create and manage different versions of their content. There are several reasons to use content versioning, including drafting content without publishing it, and more ways to collaborate with others.
This feature can be enabled for specific collections, and will be available for all items. Once enabled, item versions can be created, and later have some or all fields promoted to the main version, typically used for publishing.
Live Preview
Live preview is used by Editor and allows for your application to be shown in a pane next to your content, which can be used for previewing content before publishing.
You can use item field values to construct the URL used by the live preview, including unique identifiers and content version, allowing for previewing content versions before promoting them to the main version.
Accountability
Revisions are created whenever an item is updated. This history of versions is tracked so that previous states can be recovered. Every change made to items in Directus is stored as a complete versioned snapshot and a set of specific changes made.
Activity is a log of all events that take place within the platform. Each activity record tracks the event type, user, timestamp, IP address, user-agent, and any associated revision data.
By default, your Directus project tracks all activity and revisions for collections. However, you can override this and choose to only track activity, or nothing.
Accountability is a log of who does what in your project. It is for your team's own use. This is different from telemetry, which is configured in environment variables.
Sorting
The sort feature enables users to manually sort items in the Data Studio and via the API. If not selected as an optional field when creating a collection, you will need to create a new field with an integer type. It can then be selected as the sort field.
To configure manual sorting within a relational field (e.g., M2M, O2M, or M2A), also set the sort field within the relationship section of the field's configuration drawer.
Once configured, click in the configured sort column, and then drag items by their handle. You can also sort by the sort field with querying data via the Items API.
Duplication
The Save as Copy option in Editor offers a way to effectively duplicate the current item. Duplication settings define which field values will be copied.
Archive Settings
Archived items still exist in your collections, but are filtered within the Data Studio. If not selected as an optional field when creating a collection, you will need to create a new field.
To configure an archive field, set the following four input fields as desired.
- Archive Field: selects the archive field.
- Archive App Filter: can users filter for archived items.
- Archive Value: assigned value to archive field when an item is archived.
- Unarchive Value: assigned value to archive field when an item is unarchived.
Archived items are hidden in the app by default, but they are still returned normally via the API unless explicitly filtered out. This gives you the flexibility to manage archived items however you want when working with the API.
Advanced Field Creation Mode
You can use these advanced options to automatically set the values of fields at specific events by clicking on "Continue in Advanced Field Creation Mode".
For example, you can set the default value of a Many-to-One (M2O) relationship to be the current user.
Below is an example showing a updated_on Datetime field on a posts collection that is set to the current time upon creation and updating:
You can also set this mode after the field has been created.
System Collections
System collections are the automatically-created collections required for Directus to operate. These collections are surfaced throughout Directus to power different parts of the system - like notifications, users, roles, and even collection configuration itself.
While fields that come system collection fields cannot be altered, you can extend system collections.
| Collection | Purpose |
|---|---|
directus_activity | Accountability logs for all events. |
directus_collections | Additional collection configuration and metadata. |
directus_dashboards | Dashboards within the Insights module. |
directus_extensions | Configuration of extensions. |
directus_fields | Additional field configuration and metadata. |
directus_files | Metadata for all managed file assets. |
directus_flows | Automation flows. |
directus_folders | Provides virtual directories for files. |
directus_migrations | What version of the database you're using. |
directus_notifications | Notifications sent to users. |
directus_operations | Operations that run in Flows. |
directus_panels | Individual panels within Insights dashboards. |
directus_permissions | Access permissions for each role. |
directus_presets | Presets for collection defaults and bookmarks. |
directus_relations | Relationship configuration and metadata. |
directus_revisions | Data snapshots for all activity. |
directus_roles | Permission groups for system users. |
directus_sessions | User session information. |
directus_settings | Project configuration options. |
directus_shares | Tracks externally shared items. |
directus_translations | Custom translations. |
directus_users | System users for the platform. |
directus_versions | Content Versions for items. |
Existing Database Tables
When Directus is connected to an existing database, it will introspect existing tables and relationships and collections will be made available to admins via the Items API.
To access the collection via the Data Studio, you must configure the collection with additional Directus-specific metadata, such as interfaces, displays, and icons.
To access the collection without an admin role, you must also configure access control as with any other collection.
Finally, any relationships not configured in the database must also be set up inside of Directus.
Directus does not currently support composite keys, or the creation of virtual tables via SQL views.
Resources & Links
Key links across the Directus ecosystem.
Fields
Directus fields let you define how your data is stored and displayed. Learn about creating fields, data types, interfaces, validations, relationships, and more. Discover how to configure fields to perfectly suit your data modeling needs in Directus.