Organizing with Clusters

Reading time: ~5 minutes | Level: Beginner Prerequisites: Walkthrough 4: Understanding Components and Data Types

What You'll Learn

  • What clusters are and why they matter
  • How to create a cluster using the three-step Cluster Wizard
  • How to select and order components in the picker
  • Best practices for organizing your data model

What is a Cluster?

A cluster is a container that groups related components together. In SDC4, clusters correspond to ClusterType, a structural element that holds other components via XdAdapterType wrappers.

Think of clusters like folders for your data fields:

Customer Cluster
├── customer_id  (XdCount)
├── first_name   (XdString)
├── last_name    (XdString)
├── email        (XdString)
└── signup_date  (XdTemporal)

Every data model has one Data cluster at its root. The AI creates this automatically when it processes your uploaded file, grouping all columns into a single cluster.

Why Use Clusters?

Logical organization: Group related fields so the model structure mirrors the real-world domain. A "Contact Info" cluster groups email, phone, and address. A "Payment" cluster groups method, amount, and status.

Shallow grouping: A cluster can contain other clusters (the Nested Clusters group in the wizard's picker, or the Nested Clusters field in the cluster editor), but a single level is easiest to read. Keep related fields together in one cluster where you can:

Order Cluster
├── order_id
├── order_date
├── order_status
├── customer_id
├── customer_email
├── payment_method
├── total_amount
└── currency

Reusability: A published cluster and its components can be reused across multiple data models. Define a "Contact Info" cluster once, then choose it as the Data cluster of any model that needs those fields.

Creating a Cluster with the Wizard

Open the Cluster Wizard with New Cluster on the Clusters list (/app/clusters), or at /app/clusters/wizard. You also reach it from the Component Wizard: click Create Component on the Components page, choose Cluster under Structural, and on the Cluster Configuration step follow the Cluster Assembly Wizard link. New accounts fund the wallet with at least $10 (10,000 credits) at /app/welcome before creating anything.

The Cluster Wizard has three steps: Basics, Add Components, and Review & Save. There is no Semantic Linking step at creation; add semantic links afterward in the cluster editor.

Step 1: Basics

Cluster Wizard step 1: Basics

  • Project (required): which project the cluster belongs to
  • Label (required): a clear name for the cluster (for example "Customer Contact Information")
  • Description: purpose and contents of this grouping
  • Language: default en-US

Click Next.

Step 2: Add Components

Cluster Wizard step 2: Add Components

This step has two panels:

  • Available Components (left): every component you can see, grouped into Data Types, List Types and Nested Clusters, as in the cluster edit form; a component from another project or a public library shows its project's name in parentheses. Expand a group and use the search box (label, type, project or identifier) to narrow the list
  • Selected Components (right): the components that will be in this cluster

To add a component, click it in the left panel (the + marker); it moves to the right panel and is grayed out on the left. To remove one, click its X in the right panel.

The order of the right panel is the order of the components in the cluster. Drag the handle on a row to reorder.

Click Next.

Step 3: Review & Save

The new cluster, in draft

Cluster Wizard step 3: Review

Review the basics and the selected components. Click Create Cluster to save the cluster (100 credits; a cluster is a component). You are taken to its detail page.

Editing a Cluster

The cluster edit form, step 2: Cluster Configuration

To edit an existing cluster:

  1. Open the cluster's detail page (/app/clusters lists them)
  2. Click Edit Cluster (only shown while the cluster is unpublished)
  3. The editor has four steps, all open for free navigation: Basic Information, Cluster Configuration, Semantic Linking, Review & Save
  4. Go to Cluster Configuration to add or remove components, including nested clusters
  5. Go to Semantic Linking to attach RDF Objects to the cluster itself, which adds meaning to the grouping rather than to the individual fields
  6. Go to Review & Save and click Save or Save & Publish

Publishing a cluster is refused while any of its member components is unpublished; publish the members first.

Best Practices

Group by domain concept: Put related fields together. All address fields in an "Address" cluster. All payment fields in a "Payment" cluster.

Name clusters clearly: Use descriptive names that indicate what the cluster contains. "Patient Demographics" is better than "Cluster 1".

Avoid single-component clusters: If a cluster would only contain one component, the cluster adds complexity without value. Only group when there are two or more related fields.

Plan before creating: Sketch your cluster organization on paper or in a diagram before creating clusters in SDCStudio. It is easier to reorganize on paper than to recreate clusters.

Keep it shallow: Nesting is available, but one level of grouping keeps models simple, predictable, and easy to understand.

Summary

  • Clusters group related components into logical units
  • The Cluster Wizard has three steps: Basics → Add Components → Review & Save
  • The component picker lets you search, add, remove and reorder members
  • Semantic links are added in the cluster editor after creation; nested clusters can be picked in the wizard or the editor
  • A cluster publishes only after all of its members are published

Next walkthrough

Semantic Linking: Adding Meaning to Your Data covers how to connect your components to ontologies using RDF predicates.