How to Model Relations in a Headless CMS (Beginner Guide)

Connect Your Content: A Step-by-Step Guide to Relations in ElmapiCMS

Relations are one of the most powerful features in ElmapiCMS. They let you link entries from different collections together, creating meaningful connections between your content. Whether you're building a blog with authors and categories, an e-commerce site with products and brands, or any content-driven application, relations help you organize and structure your data efficiently.

In this tutorial, we'll walk through everything you need to know about relations in ElmapiCMS—from the basics to advanced API usage.

Table of Contents

• What Are Relations?
• When Should You Use Relations?
• Understanding Relation Types
• Step 1: Create Your Collections
• Step 2: Add a Relation Field
• Step 3: Using Relations in the CMS
• Step 4: Using Relations in the API
• Step 5: Filtering by Relations
• Real-World Examples
• Best Practices
• Common Pitfalls and Solutions
• Next Steps
• Conclusion

What Are Relations?

A relation is a field type that connects entries from one collection to entries in another collection. Think of it like a foreign key in a database or a reference between tables.

Common use cases:

• Blog posts → Authors (each post has one author)
• Blog posts → Categories (each post belongs to one category)
• Products → Brands (each product has one brand)
• Products → Categories (each product can belong to multiple categories)
• Articles → Tags (each article can have multiple tags)

Relations make your content structure more organized and allow you to query related data efficiently through the API.

When Should You Use Relations?

Use relations when:

You need to reuse content - Instead of duplicating author information in every blog post, create an "Authors" collection and link to it.

You want to maintain consistency - If a category name changes, updating it in one place updates it everywhere it's referenced.

You need to filter or query by related content - Find all blog posts by a specific author, or all products in a certain category.

You're building relationships between entities - Products and brands, posts and categories, events and venues.

Don't use relations for:

• Simple text fields (use a text field instead)
• Data that changes frequently per entry (use regular fields)
• Content that's unique to each entry (no need to relate)

Understanding Relation Types

ElmapiCMS supports two types of relations:

One-to-One (1:1)

One entry in Collection A relates to exactly one entry in Collection B.

Example: A user profile that relates to exactly one user account.

One-to-Many (1:N)

One entry in Collection A can relate to multiple entries in Collection B.

Example: A blog post can have multiple tags, or a category can contain multiple blog posts.

Note: When you create a relation field, you choose the relation type. The "One-to-One" option means each entry can link to one related entry, while "One-to-Many" allows multiple related entries.

Step 1: Create Your Collections

Before you can create relations, you need at least two collections. Let's use a blog example:

Collection 1: Blog Posts

• Fields: title (text), content (richtext), slug (slug)

Collection 2: Authors

• Fields: name (text), email (email), bio (longtext), avatar (media)

Collection 3: Categories

• Fields: name (text), slug (slug), description (longtext)

If you haven't created these collections yet, follow these steps:

1. Go to your project dashboard
2. Click "+ Add New" button in the "Collections" sidebar
3. Fill in the collection name and slug
4. Click the settings icon (gear icon) to open collection settings
5. Click "Add Field" button in the Fields panel
6. Add fields you need for the collection (e.g. name, slug, description)

Step 2: Add a Relation Field

Now let's add a relation field to connect blog posts to authors. You can add relation fields to any collection you want to connect.

1. Open Collection Settings

   • In the sidebar, find your "Blog Posts" collection
   • Click the gear icon ⚙️ to open Collection Settings

2. Add a New Field

   • Click ➕ Add Field in the Fields panel
   • Select Relation from the field type picker

3. Configure the Relation Field

   • Label: "Author" (this is what editors will see)
   • Name: "author" (this is the API field name)
   • Description: "Select the author of this blog post" (optional but helpful)

4. Set Relation Options

   • Relation Collection: Choose "Authors" from the dropdown
   • Relation Type: Select "One-to-One" (each post has one author)
   • Include Draft: Toggle this if you want to allow linking to unpublished author entries

5. Save the Field

   • Click Create to add the relation field

Step 3: Using Relations in the CMS

Once you've created a relation field, using it is straightforward:

Linking Entries

1. Create or Edit a Blog Post

   • Click "Blog Posts" collection in the sidebar
   • Click "+ Create New" button or edit an existing post by clicking the post row in the list
   • You'll see your new "Author" field in the form

2. Select a Related Entry

   • Click the "+ Select Relation Entry" button for the "Author" field
   • A modal opens showing all entries from the "Authors" collection (you can also search for entries by name, email, etc.)
   • Use the search bar to find the author you want
   • Click on an author to select it

3. Save the Entry

   • The selected author is now linked to your blog post
   • You'll see the author's name displayed in the relation field
   • You can change the author by clicking the "+ Change Relation Entry" button and selecting a different author or you can clear the selection.
   • Save the entry as draft or publish it.

One-to-Many Relations

If you created a "One-to-Many" relation (e.g., a post can have multiple tags):

1. Create or Edit a Blog Post

   • Click "Blog Posts" collection in the sidebar
   • Click "+ Create New" button or edit an existing post by clicking the post row in the list
   • You'll see your new "Tags" field in the form

2. Select Multiple Related Entries

   • Click the "+ Select Relation Entries" button for the "Tags" field
   • A modal opens showing all entries from the "Tags" collection (you can also search for entries by name, description, etc.)
   • Use the search bar to find the tags you want
   • Select multiple entries from the list and click "Add Selected" button
   • Selected entries are displayed in the relation field as a table
   • You can order the entries by dragging and dropping the rows in the table.

Step 4: Using Relations in the API

Relations are automatically included in API responses. When you fetch an entry, related entries are embedded in the response.

Fetching an Entry with Relations

// Using the ElmapiCMS JavaScript SDK
import { createClient } from '@elmapicms/js-sdk';

const client = createClient(
  'https://your-domain.com/api',
  'YOUR_API_TOKEN',
  'YOUR_PROJECT_UUID'
);

// Get a blog post - the author relation is automatically included
const post = await client.getEntry('blog-posts', 'post-uuid-here');

console.log(post.data.fields.title); // "My Blog Post"
console.log(post.data.fields.author); // Full author entry object

API Response Structure

When you fetch an entry with relations, the related entry is included as a nested object:

{
  "data": {
    "uuid": "post-uuid-123",
    "locale": "en",
    "published_at": "2025-01-15T10:00:00Z",
    "fields": {
      "title": "Getting Started with ElmapiCMS",
      "slug": "getting-started-with-elmapicms",
      "content": "<p>Content here...</p>",
      "author": {
        "uuid": "author-uuid-456",
        "locale": "en",
        "fields": {
          "name": "John Doe",
          "email": "[email protected]",
          "bio": "Tech writer and developer",
          "avatar": "asset-uuid-789"
        }
      }
    }
  }
}

Creating Entries with Relations

When creating or updating an entry via the API, you reference related entries using their UUID:

// Create a blog post with an author relation
const newPost = await client.createEntry('blog-posts', {
  locale: 'en',
  state: 'published',
  data: {
    title: 'My New Post',
    slug: 'my-new-post',
    content: '<p>Post content here...</p>',
    author: 'author-uuid-456' // UUID of the author entry
  }
});

For One-to-Many relations, pass an array of UUIDs:

// Create a post with multiple tags
const newPost = await client.createEntry('blog-posts', {
  locale: 'en',
  state: 'published',
  data: {
    title: 'My New Post',
    slug: 'my-new-post',
    tags: ['tag-uuid-1', 'tag-uuid-2', 'tag-uuid-3'] // Array of tag UUIDs
  }
});

Step 5: Filtering by Relations

One of the most powerful features of relations is the ability to filter entries based on related content.

Filter by Related Entry Field

Find all blog posts by a specific author:

// Get all posts by author name
const posts = await client.getEntries('blog-posts', {
  where: {
    author: { name: 'John Doe' }
  }
});

Or using the raw API:

GET /api/blog-posts?where[author][name]=John Doe

Filter by Related Entry UUID

Find all posts by a specific author UUID:

const posts = await client.getEntries('blog-posts', {
  where: {
    author: 'author-uuid-456'
  }
});

Complex Relational Filters

You can combine relational filters with other conditions:

// Get published posts by "John Doe" in the "Technology" category
const posts = await client.getEntries('blog-posts', {
  where: {
    status: 'published',
    author: { name: 'John Doe' },
    category: { name: 'Technology' }
  }
});

Using Operators with Relations

You can use operators like not, in, etc. with relations:

// Get posts NOT by a specific author
const posts = await client.getEntries('blog-posts', {
  where: {
    author: { name: { not: 'John Doe' } }
  }
});

// Get posts by multiple authors
const posts = await client.getEntries('blog-posts', {
  where: {
    author: { name: { in: 'John Doe,Jane Smith' } }
  }
});

For more filtering options, see the Advanced Filtering documentation.

Real-World Examples

Let's look at some practical examples of using relations:

Example 1: E-Commerce Product Catalog

Collections:

• products (name, price, description, images)
• brands (name, logo, description)
• categories (name, slug, description)

Relations:

• products.brand → brands (One-to-One)
• products.category → categories (One-to-One)

Use Case: Find all products from "Nike" in the "Shoes" category:

const products = await client.getEntries('products', {
  where: {
    brand: { name: 'Nike' },
    category: { name: 'Shoes' }
  }
});

Example 2: Event Management

Collections:

• events (title, date, description, venue)
• venues (name, address, capacity)
• speakers (name, bio, photo)

Relations:

• events.venue → venues (One-to-One)
• events.speakers → speakers (One-to-Many)

Use Case: Find all events at a specific venue:

const events = await client.getEntries('events', {
  where: {
    venue: { name: 'Convention Center' }
  }
});

Example 3: Recipe Website

Collections:

• recipes (title, instructions, cooking_time)
• ingredients (name, unit, category)
• cuisines (name, description)

Relations:

• recipes.cuisine → cuisines (One-to-One)
• recipes.ingredients → ingredients (One-to-Many)

Use Case: Find all Italian recipes:

const recipes = await client.getEntries('recipes', {
  where: {
    cuisine: { name: 'Italian' }
  }
});

Best Practices

1. Plan Your Collections First

   • Think about what entities you need and how they relate
   • Create collections before adding relation fields

2. Use Descriptive Field Names

   • author is better than rel1
   • category is clearer than cat

3. Choose the Right Relation Type

   • Use One-to-One when each entry should link to exactly one related entry
   • Use One-to-Many when entries can have multiple related entries

4. Consider "Include Draft" Settings

   • If you want to link to unpublished entries, enable "Include Draft"
   • For production APIs, you might want to disable this

5. Validate Required Relations

   • Mark relation fields as "Required" if every entry must have a relation
   • This ensures data consistency

6. Use Relations for Reusable Content

   • Don't duplicate data that should be shared
   • Create a collection and use relations instead

Next Steps

Now that you understand relations, you can:

• Explore Advanced Filtering - Learn more about complex queries with relations
• Build Your Frontend - Use relations in your React, Vue, or Next.js applications
• Create Project Templates - Include relations in your project templates for faster setup
• Read the API Documentation - Deep dive into the Content API Reference

Conclusion

Relations are a fundamental feature that makes ElmapiCMS powerful and flexible. They help you:

• Organize your content structure
• Avoid data duplication
• Query related content efficiently
• Build complex, interconnected content models

Whether you're building a simple blog or a complex e-commerce platform, relations will help you structure your content in a way that's both maintainable and queryable.

Ready to get started? Create your first relation field and see how it transforms your content management workflow!

Need help? Check out the ElmapiCMS Documentation or reach out to [email protected].

Related posts:

• Headless CMS Content Modeling: How to Build Reusable Page Sections (Blocks) – Design flexible, reusable content types that often use relations.
• How to Build a Simple Blog Using ElmapiCMS and Next.js – Put relations to work with authors and categories in a real blog.
• RAG for Marketing Content: Using a Headless CMS as Your AI Knowledge Base – Well-structured, related content (with clear types and metadata) improves RAG quality.