This is list of platform-specific terminology, and their meanings. Most are simply more approachable names for technical database terms.
Admin / Administrator
An "Administrator" Role (with Admin access enabled) is included when you first install the platform. All admin roles bypass the permissions check, providing unrestricted access to all data within the App and API. Additionally, only roles with the admin option enabled can manage Settings within the app.
Fields that do not map directly to an actual database column are called "alias" fields. For example, presentation fields (such as dividers and groups) and certain relational types that display data stored elsewhere (such as One-to-Many (O2M) and Many-to-Many (M2M)).
The Application Programming Interface (API) provided by the platform is how you can programmatically connect your project's content, files, and system information to external code (like a website) or with other third-party services.
An intuitive no-code application for managing database content. Powered by the API, the modular and highly extensible App is written in Vue.js.
Activity is a log of all events that take place within the platform. Used for accountability, each activity record tracks the event type, user, timestamp, IP address, user-agent, and any associated revision data.
Collections are containers for specific types of Items and contain any number of fields. Each collection represents a table in your database. By default, the title formatter is used to display any existing database table names as human-readable collection titles. There are also "folder" collections that are exclusively used for organizational purposes, and don't hold any data themselves.
Collections can be organized in any way that is appropriate for your project. You can architect them platform-specific (e.g., pages of a website), or in a more platform-agnostic way (e.g., raw customers of your business). While there's no right or wrong way to structure your data-model, we recommend keeping your data as agnostic as possible so it is easier to repurpose in the future. In short, learn to see your data as its own asset — not only through the lens of your immediate project needs.
The only requirement of a collection is that it must contain a Primary Key field. This field stores a unique value that is used to reference the Collection's items throughout the database/platform.
Dashboards within the Insights module organize different Panels into an at-a-glance view. They can be used to group data based on department, objective, business process or anything you choose.
Directus supports mirroring all the most widely used SQL databases, including PostgreSQL, MySQL, Microsoft SQL Server, SQLite, OracleDB, MariaDB, CockroachDB, and other variants. Each vendor has subtle (and sometimes not so subtle) differences in how they function, so Directus includes an abstraction layer that helps it avoid writing different code for each type.
This means there is also the possibility of supporting other datastores in the future, such as NoSQL options like MongoDB, or even third-party data services like Firebase or Heroku. However these options are fundamentally different from the relational SQL databases we currently support, and so more research is needed.
Displays are the smaller, read-only counterpart to Interfaces, defining how a field's data will be displayed inline throughout the App.
For example, you may have a "Status" field that uses a Dropdown Interface on the Item Detail page, and a smaller Badge Display when the field is referenced throughout the rest of the App. Directus includes many Displays out-of-the-box, below are the some key examples:
- Raw — The exact value, straight from the API
- Formatted Value — Provides options for string formatting
- Boolean — Customizable True/False icons
- Color — A color swatch preview
- DateTime — Formatted or relative datetimes
- Image — Thumbnail previews
- Labels — Small, custom colored badges
- Rating — Customizable stars
- Related Values — Displays relational display titles
- User — Avatar and name of a system user
In addition to the included core displays, custom displays allow for creating new and/or proprietary ways to view or represent field data. For example, you could create progress indicators, tooltips for relational data, specific formatting styles, or anything else.
Environments (e.g., dev, staging, prod) are tracked as separate Project instances. You can then use schema/content migrations to promote data between them.
The platform has been built to be modular and extensible. This helps keep the core codebase simple and clean (see the 80/20 Rule), while allowing the flexibility needed to satisfy all use-cases... no matter how complex. There are many different types of supported extensions, each offering a way to deeply customize, override, or extend the core platform. Learn more about Extensions.
Fields are a specific type of value within a Collection, storing the data of your item's content. Each field represents a column in your database. For example, an
articles Collection might have
date_published field. Fields mirror the characteristics of their associated column, including its
Files & Assets
As you might have guessed, files includes images, videos, PDFs, text documents, or anything else. While files can technically be stored as code in the database, it is far more common to manage them as individual assets on a "drive". The platform supports many options for uploading, storing, transforming, and retrieving different types of files, and it is an excellent Digital Asset Management system.
Full list of icons can be found here. Directus supports both filled & outlined variants of Material icons.
Interfaces determine how you view or interact with a field. In most cases, they offer some sort of input tailored to managing data of a specific type, but can also be used exclusively for presentation. Examples include text inputs, toggles, WYSIWYG editors, dropdowns, sliders, image galleries, and more.
In addition to the many core interfaces included out-of-the-box, custom interfaces allow for creating more tailored or proprietary options, such as seating charts, QR codes, or Stripe customer info.
Items are objects within a Collection which contain values for one or more fields. Each collection represents a record in your database.
Items are the primary building blocks of your project content. Similar to a "row" within a spreadsheet, all data within the platform is accessed via these "atomic" data units. Items themselves are fairly straightforward, however their real power comes from the complexity that begins to form when items are relationally connected to each other.
Items are referenced (both individually and relationally) by their unique primary key.
The platform allows you to group Items within different Collections. But often times it is important to "link" items across different collections (such as relating
ingredients) — this is called a relationship. There are several different types of relationships, but only some (M2M and M2A) require an additional collection to properly connect data. For instance, if you have a
recipes collection and an
ingredients collection, you would also need a
recipe_ingredients junction collection to sit between and connect the two.
Layouts determine how you view or interact with a Collection. In most cases, they offer a way to browse items based on a specific type of data, but can also be used to visualize or interact with data. Directus includes several Layout options out-of-the-box, each with different features and configuration options.
- Table — Works with any type of data, showing items as rows and their fields as columns.
- Cards — Ideal for image data, this layout shows items as a grid of image cards.
- Calendar — Ideal for "temporal" data that is sorted by date or datetime.
- Map — Ideal for "geospatial" data that is shown on a world map.
In addition to these core layouts, custom layouts allow for creating more tailored or proprietary ways to experience data within the App, such as Gantt charts, seating maps, or spreadsheets.
Modules are the highest and broadest level of organization within the App. There are several modules included out-of-the-box, however you can also add your own.
The Module Bar lists all available Modules and allows you to switch between them. Each module also controls its own navigation bar to provide tailored access to sub-pages. All core functionality within the App can be bucketed into one of the following modules:
- Content — The primary way to view and interact with database content
- User Directory — A dedicated section for the platform's system Users
- File Library — An aggregate of all files uploaded and managed within the platform
- Insights — Access to infinitely customizable data dashboards
- App Guide — A tailored, in-app portal for the platform's concepts, guides, and reference
- Settings — An admin-only section for configuring the project and system settings
In addition to these core modules, custom modules offer a blank canvas for creating altogether new/different experiences within the App, such as proprietary dashboards, compound datasets, or third-party integrations (e.g., a Stripe Payments Console).
Multitenancy is an architecture that allows multiple tenants (e.g., customers) to be managed by the platform. There are two main ways to achieve multitenancy:
- Project Scoping — Creating a super-admin layer that provisions new tenant projects has been made easier by the Cloud-native model of Directus 9+. This method involves developing custom code that can dynamically spin up/down projects, but is also the most flexible, supporting scoped extensions and differentiated project settings.
- Role Scoping — In this method, you create one Role per tenant, and configure their permissions to properly scope them within a single project. This direction allows for tenants to share a single schema using item scoped permissions, or different schemas by using collection scoped permissions.
Permissions are attached directly to a Role, defining what a user can create, read, update, and delete within the platform. Extremely granular, these filter-based permissions control access for the entire system.
Presets store the exact state of a collection page. They are used to set layout defaults for a user, or to define bookmarks that can be used to quickly recall specific datasets.
Primary Key (PK)
When we're trying to view or reference a specific Item within a Collection, you need some sort of unique identifier to know exactly where to look. Much like an address for a house, the primary key field provides the location of an item within its collection. For that reason, every collection must have a primary key field, and so they are configured when you create the collection. There are different types of identifiers you can use, but the field is often called
A Project is a complete instance of the platform. Each project represents a Database, but also encapsulates a config file, asset storage, and any custom extensions. Projects are the highest level of organization in Directus.
- Creating a Project
- Configuring a Project
- Adjusting Project Settings
- Upgrading a Project
- Backing-up a Project
- Migrating a Project
- Deleting a Project
The platform allows you to group Items within different Collections. But often times it is important to "link" items across different collections (such as relating
ingredients) — this is called a relationship, a crucial concept within any relational database. There are several different types of relationships, each serving a specific purpose. Learn more about Relationships.
Revisions are created whenever an Item is updated. These alternate versions are 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 (the delta). The revisions system is tightly coupled to the activity logs system, with each revision linked to the activity event where it was created.
Roles define a specific set of access permissions, and are the primary organizational structure for Users within the platform. You can create an unlimited number of roles, so organize your users in whatever way feels most appropriate.
During the installation process, Directus automatically creates an "Administrators" Role, which is used to provide the initial admin user with full platform access. However this is just a normal role, and so it can still be updated, renamed, or even deleted. Keep in mind that your project must maintain at least one role with Admin Access at all times.
There is also a "Public" role that determines access for unauthenticated access.
- Creating a Role
- Configuring a Role
- Configuring Role Permissions
- Configuring System Permissions
- Deleting a Role
- Directus - A collection that only contains one single item
- Design pattern - Classes which can be instantiated once and can be accessed globally. This single instance can be shared throughout our application, which makes singletons great for managing global state in an application.
Storage adapters allow project files to be stored in different locations or services. By default, Directus includes the following drivers:
- Local Filesystem — The default, any file system location or network-attached storage
- S3 or Equivalent — Including AWS S3, DigitalOcean Spaces, Alibaba OSS, and others
- Google Cloud Storage — A RESTful web service on the Google Cloud Platform
- Azure Blob Storage — Azure storage account containers
Special Casing — If you are trying to update the specific casing (uppercase/lowercase) for a word (e.g.,
DNA) you will want to add the edge-case to the Format Title package. If you feel the case passes our 80/20 rule you should submit a Pull Request to the codebase, otherwise you can update this in your instance.
The platform supports internationalization across its entire Admin App. Many languages are currently supported, with more being added all the time. Anyone can add or refine any languages through the integration with Crowdin.
In addition to the App itself being multilingual, the platform allows translating your schema too. By default, collections and field names come from the database's naming, but you can override this in different languages.
The platform also includes different ways to manage multilingual content. The built-in translation interface supports authoring content in any number of languages, side-by-side reference editing, and mixing in language agnostic content (such as dates or toggles).
The "type" defines how field content is stored in the database and how it is returned by the API. Often called a data-type, these are important in ensuring field values are saved in a standardized format. Changing a field's type can cause data loss, so types are locked within the platform after a field is created.
Data Type Superset
Directus uses its built-in database abstraction to properly support all the different SQL vendors. However, these vendors do not share support for the same data types, instead, each SQL vendor maintains their own list. To standardize all of these differences, Directus has a single superset of types that map to the vendor-specific ones.
- String — A shorter set of characters with a configurable max length
- Text — A longer set of characters with no real-world max length
- Boolean — A True or False value
- Binary — The data of a binary file
- Integer — A number without a decimal point
- Big Integer — A larger number without a decimal point
- Float — A less exact number with a floating decimal point
- Decimal — A higher precision, exact decimal number often used in finances
- Timestamp — A date, time, and timezone saved in ISO 8601 format
- DateTime — A date and time saved in the database vendor's format
- Date — A date saved in the database vendor's format
- Time — A time saved in the database vendor's format
- CSV — A comma-separated value, returned as an array of strings
- UUID — A universally unique identifier saved in UUIDv4 format
- Hash — A string hashed using argon2 cryptographic hash algorithm
- Alias — For fields that do not have a database column Learn More
For SQLite, the Timestamp type is stored as a DateTime.
An active User is required to access a project. Each user is assigned to a Role that determines what they have access to see and do. This means that the experience of users may vary significantly depending on their role's permissions.