SDK Collections Operations

Manage and retrieve collection metadata in Directus

Overview

Collections represent tables in your database. The SDK provides methods to retrieve collection metadata, including information about fields, relationships, and collection settings.

Read Operations

Read All Collections

Retrieve a list of all available collections:

TypeScript

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

const client = createDirectus<Schema>('https://your-directus-url.com')
  .with(rest());

const collections = await client.request(
  readCollections()
);

collections.forEach(collection => {
  console.log(collection.collection); // Collection name
  console.log(collection.meta?.singleton); // Is singleton?
  console.log(collection.schema); // Database schema info
});

JavaScript

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

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

const collections = await client.request(
  readCollections()
);

collections.forEach(collection => {
  console.log(collection.collection);
});

Read Single Collection

Retrieve metadata for a specific collection:

TypeScript

import { readCollection } from '@directus/sdk';

const collection = await client.request(
  readCollection('articles')
);

console.log(collection.collection); // "articles"
console.log(collection.meta?.note); // Collection note/description
console.log(collection.meta?.icon); // Collection icon
console.log(collection.meta?.display_template); // Display template

JavaScript

import { readCollection } from '@directus/sdk';

const collection = await client.request(
  readCollection('articles')
);

console.log(collection.meta?.icon);

Collection Properties

The collection object contains the following key properties:

Collection Name

The unique identifier for the collection:

collection.collection // "articles"

Meta Information

Collection metadata managed by Directus:

collection.meta = {
  collection: 'articles',
  icon: 'article',
  note: 'Blog articles and posts',
  display_template: '{{title}}',
  hidden: false,
  singleton: false,
  translations: [...],
  archive_field: 'status',
  archive_value: 'archived',
  unarchive_value: 'draft',
  sort_field: 'sort',
  accountability: 'all',
  color: null,
  item_duplication_fields: null,
  sort: 1,
  group: null,
  collapse: 'open',
}

Schema Information

Database-level schema information:

collection.schema = {
  name: 'articles',
  comment: null,
}

Working with System Collections

Directus includes several built-in system collections:

TypeScript

import { readCollection } from '@directus/sdk';

// Read users collection
const usersCollection = await client.request(
  readCollection('directus_users')
);

// Read files collection
const filesCollection = await client.request(
  readCollection('directus_files')
);

// Read roles collection
const rolesCollection = await client.request(
  readCollection('directus_roles')
);

JavaScript

import { readCollection } from '@directus/sdk';

const usersCollection = await client.request(
  readCollection('directus_users')
);

Common System Collections

• directus_users - User accounts
• directus_files - Uploaded files
• directus_folders - File organization folders
• directus_roles - User roles
• directus_permissions - Access permissions
• directus_activity - Activity logs
• directus_settings - Global settings
• directus_flows - Automation flows
• directus_operations - Flow operations

Filtering Collections

You can filter the collections list programmatically after retrieval:

TypeScript

const collections = await client.request(
  readCollections()
);

// Get only user-created collections (non-system)
const userCollections = collections.filter(
  collection => !collection.collection.startsWith('directus_')
);

// Get only singleton collections
const singletons = collections.filter(
  collection => collection.meta?.singleton === true
);

// Get only visible collections
const visibleCollections = collections.filter(
  collection => collection.meta?.hidden !== true
);

JavaScript

const collections = await client.request(
  readCollections()
);

const userCollections = collections.filter(
  collection => !collection.collection.startsWith('directus_')
);

Use Cases

Building Dynamic Forms

Use collection metadata to build dynamic forms:

const collection = await client.request(
  readCollection('articles')
);

const displayName = collection.meta?.translations?.find(
  t => t.language === 'en-US'
)?.translation || collection.collection;

console.log(`Creating form for: ${displayName}`);

Collection Discovery

Discover available collections for your application:

const collections = await client.request(
  readCollections()
);

const availableCollections = collections
  .filter(c => !c.meta?.hidden)
  .map(c => ({
    name: c.collection,
    icon: c.meta?.icon || 'box',
    singleton: c.meta?.singleton || false,
  }));

console.log('Available collections:', availableCollections);

Check if Collection Exists

try {
  const collection = await client.request(
    readCollection('my_collection')
  );
  console.log('Collection exists');
} catch (error) {
  console.log('Collection does not exist');
}

Type Signatures

// DirectusCollection interface
interface DirectusCollection<Schema> {
  collection: string;
  meta: {
    collection: string;
    icon: string | null;
    note: string | null;
    display_template: string | null;
    hidden: boolean;
    singleton: boolean;
    translations: any[];
    archive_field: string | null;
    archive_value: string | null;
    unarchive_value: string | null;
    sort_field: string | null;
    accountability: string | null;
    color: string | null;
    item_duplication_fields: any | null;
    sort: number | null;
    group: string | null;
    collapse: string;
  } | null;
  schema: {
    name: string;
    comment: string | null;
  } | null;
}

// Read all collections
function readCollections<Schema>(): RestCommand<
  DirectusCollection<Schema>[],
  Schema
>;

// Read single collection
function readCollection<Schema>(
  collection: string
): RestCommand<DirectusCollection<Schema>, Schema>;

Notes

Collection metadata is read-only via the SDK. To create or modify collections, use the Directus Admin App or the Collections REST API endpoints directly.

System collections (prefixed with directus_) have special behavior and permissions. Always check permissions before accessing system collections.

Next Steps

Items Operations

Work with items in your collections

Fields

Retrieve field metadata and schema

Relations

Work with relationships between collections

Users

Manage users and permissions