Data Sources Tools

Tools for creating and managing datasources - reusable lists of options used in dropdowns, multi-select fields, and other structured content.

Overview

Datasources provide centralized management of option lists:

• Datasources - Container for related options (e.g., "Categories", "Authors", "Tags")
• Datasource Entries - Individual options within a datasource (e.g., "Technology", "Business", "Sports")
• Dimensions - Support for multi-language or variant options
• Reusability - Use the same datasource across multiple components

Total tools: 10 (Datasources: 5, Entries: 5)

Common use cases:

• Product categories and tags
• Author/contributor lists
• Country/region selectors
• Content categorization
• Multi-language option lists

Datasources (5 tools)

Datasources are containers that hold lists of options.

Listing Datasources

retrieve_multiple_datasources

Purpose: Get all datasources in your space.

When to use:

• See what datasources exist
• Find datasource IDs and slugs
• Search for specific datasources

Common conversation examples:

Show me all datasources in my space

Find datasources with "category" in the name

List all available option lists

Key parameters:

• search - Filter by datasource name
• by_ids - Get specific datasources by ID (comma-separated)

Returns: Array of datasource objects.

retrieve_single_datasource

Purpose: Get details of a specific datasource.

When to use:

• Check datasource configuration
• See all entries in a datasource
• Verify datasource slug

Common conversation examples:

Show me datasource ID 123

What's in the "blog-categories" datasource?

Key parameters:

• datasource_id - Datasource ID (required)

Returns: Single datasource object with configuration.

Creating Datasources

create_datasource

Purpose: Create a new datasource.

When to use:

• Set up new option lists
• Create categorization systems
• Define structured data options

Common conversation examples:

Create a datasource called "Product Categories"

Set up a new datasource for blog post authors

Make a "Countries" datasource for location selectors

Key parameters:

• name - Datasource display name (required)
• slug - Unique identifier slug (required)
• dimensions - Array of dimension objects for multi-language support (optional)

Returns: Newly created datasource object.

Dimension example:

{
  "dimensions": [
    {"entry_value": "en", "name": "English"},
    {"entry_value": "es", "name": "Spanish"}
  ]
}

Tip: Use a descriptive slug like "product-categories" for easy reference in components

Updating Datasources

update_datasource

Purpose: Update an existing datasource.

When to use:

• Rename datasource
• Change slug
• Add or modify dimensions

Common conversation examples:

Rename datasource 456 to "Product Types"

Change the slug to "product-types"

Add German language dimension to datasource

Key parameters:

• datasource_id - Datasource to update (required)
• name - New display name
• slug - New slug
• dimensions - Updated dimensions array

Returns: Updated datasource object.

Deleting Datasources

delete_datasource

Purpose: Delete a datasource.

When to use:

• Remove unused datasources
• Clean up test datasources
• Consolidate option lists

Common conversation examples:

Delete datasource ID 789

Remove the old categories datasource

Key parameters:

• datasource_id - Datasource to delete (required)

Returns: Deletion confirmation.

Warning: Cannot delete datasources that are in use by components!

Datasource Entries (5 tools)

Entries are the individual options within a datasource.

Listing Entries

retrieve_multiple_datasource_entries

Purpose: Get all entries in a datasource.

When to use:

• See available options
• List all categories/tags
• Export datasource content

Common conversation examples:

Show me all entries in the "blog-categories" datasource

List all product categories

What options are in datasource 123?

Key parameters:

• datasource_id - Datasource ID
• datasource_slug - Datasource slug (alternative to ID)
• dimension - Filter by dimension

Returns: Array of datasource entry objects.

Note: Must provide either datasource_id or datasource_slug

retrieve_single_datasource_entry

Purpose: Get details of a specific entry.

When to use:

• Check entry value
• Verify entry ID
• Inspect dimension values

Common conversation examples:

Show me datasource entry 456

What's the value of this category?

Key parameters:

• datasource_entry_id - Entry ID (required)

Returns: Single entry object.

Creating Entries

create_datasource_entry

Purpose: Add a new option to a datasource.

When to use:

• Add new categories
• Create new options
• Expand option lists

Common conversation examples:

Add "Technology" as a new category in the blog-categories datasource

Create a new entry "United Kingdom" in the countries datasource

Add "John Smith" to the authors datasource

Key parameters:

• datasource_id - Datasource ID (required)
• name - Display name for the option (required)
• value - Internal value/slug (required)

Returns: Newly created entry object.

Name vs Value:

• name - What users see ("United Kingdom")
• value - What's stored in content ("uk" or "united-kingdom")

Updating Entries

update_datasource_entry

Purpose: Update an existing entry.

When to use:

• Rename options
• Change values
• Update dimension translations

Common conversation examples:

Rename entry 789 to "Tech & Innovation"

Change the value to "tech-innovation"

Update the Spanish translation for this entry

Key parameters:

• datasource_entry_id - Entry to update (required)
• name - New display name
• value - New internal value
• dimension_value - Translation for a dimension
• dimension_id - Dimension ID (required when setting dimension_value)

Returns: Updated entry object.

Important: Changing value affects existing content using this option!

Deleting Entries

delete_datasource_entry

Purpose: Delete an entry from a datasource.

When to use:

• Remove deprecated options
• Clean up unused categories
• Consolidate similar options

Common conversation examples:

Delete the "Old Category" entry

Remove entry 999 from the datasource

Key parameters:

• datasource_entry_id - Entry to delete (required)

Returns: Deletion confirmation.

Warning: Deleting entries may break content that uses them!

When to Use What

Setting Up Datasources

Managing Entries

Managing Datasources

Common Patterns

Creating Category System

Set up a blog category system:
1. Create "blog-categories" datasource
2. Add entries: "Technology", "Business", "Lifestyle"
3. Create component field using this datasource

Uses: create_datasource → create_datasource_entry (multiple times)

Multi-Language Options

Create multi-language product categories:
1. Create datasource with English and Spanish dimensions
2. Add entries with translations
3. Use dimension values for localized content

Uses: create_datasource (with dimensions) → create_datasource_entry → update_datasource_entry (for translations)

Migrating Categories

Move from hardcoded options to datasource:
1. Create new datasource
2. Add all existing categories as entries
3. Update component to use datasource
4. Migrate existing content

Uses: create_datasource → create_datasource_entry (bulk) → component update

Cleaning Up Options

Consolidate similar categories:
1. Get all entries from datasource
2. Identify duplicates or similar options
3. Update content to use consolidated options
4. Delete deprecated entries

Uses: retrieve_multiple_datasource_entries → content updates → delete_datasource_entry

Use Cases by Industry

E-Commerce

• Product Categories - Electronics, Clothing, Home & Garden
• Product Attributes - Size, Color, Material
• Brands - Manufacturer/brand lists
• Tags - Sale, New Arrival, Bestseller

Content Publishing

• Categories - News, Opinion, Features
• Authors - Staff writers and contributors
• Topics - Politics, Technology, Sports
• Content Types - Article, Video, Podcast

Multi-Language Sites

• Languages - English, Spanish, German
• Regions - North America, Europe, Asia
• Currencies - USD, EUR, GBP

SaaS Platforms

• Features - Feature flags and options
• Plans - Pricing tier options
• Industries - Customer industry verticals

Related Resources

Guides

• Component Design Guide
• Content Translation Guide

Examples

• Common Tasks

Tips & Best Practices

1. Descriptive slugs - Use clear slugs like "product-categories" not "pc1"
2. Consistent naming - Use same format for all entries (Title Case vs lowercase)
3. Value format - Use URL-friendly values (kebab-case: "tech-news")
4. Don't over-create - Reuse datasources across components when possible
5. Plan dimensions - Set up language support from the start if needed
6. Careful deletes - Check content usage before deleting entries
7. Logical grouping - Group related options in same datasource
8. Document usage - Track which components use which datasources
9. Regular cleanup - Remove unused entries to keep lists manageable
10. Consider hierarchy - For nested categories, use multiple datasources or naming conventions

Datasource vs Component Options

When to use Datasource:

• Options shared across multiple components
• Options that change frequently
• Large lists (50+ options)
• Multi-language requirements
• Content team manages options

When to use Component Options:

• Options unique to one component
• Fixed lists that rarely change
• Small lists (< 10 options)
• Developer-managed options

Dimension Use Cases

Dimensions enable variant or translated values for datasource entries.

Multi-Language:

Datasource: product-categories
Entry: "electronics"
  - English dimension: "Electronics"
  - Spanish dimension: "Electrónica"
  - German dimension: "Elektronik"

Regional Variants:

Datasource: terminology
Entry: "apartment"
  - US dimension: "Apartment"
  - UK dimension: "Flat"

Brand Variants:

Datasource: product-names
Entry: "flagship-phone"
  - Brand A dimension: "Galaxy Ultra"
  - Brand B dimension: "iPhone Pro"

Need help with datasources? Check out our component design guide for examples of using datasources in components!