Link datasets

Use relationships when rows in one dataset point to rows in another dataset. Use reference columns when a cell points at a Rowset dataset or project object. For a practical modeling guide, read How to model relationships between agent-managed datasets.

Dataset relationships

A relationship says: this source column stores index values from that target dataset.

Example:

• People is indexed by person_id
• Messages has a person_id column
• a relationship links Messages.person_id to People.person_id

With enforcement enabled, row writes fail when a non-blank source value does not match an existing target row index. Blank values are allowed.

MCP tools

list_dataset_relationships
create_dataset_relationship
resolve_dataset_relationship
delete_dataset_relationship

get_dataset also includes outgoing and incoming relationship summaries, so an agent sees links during normal inspection.

REST endpoints

GET /api/datasets/{dataset_key}/relationships
POST /api/datasets/{dataset_key}/relationships
GET /api/datasets/{dataset_key}/relationships/{relationship_key}/resolve
DELETE /api/datasets/{dataset_key}/relationships/{relationship_key}

Reference columns

Use a reference column when a row should store a Rowset object key:

{
  "related_dataset": {
    "type": "reference",
    "target": "dataset"
  },
  "project": {
    "type": "reference",
    "target": "project"
  }
}

References are useful for metadata, source tracking, and internal Rowset links. Relationships are better when the cell points to a row in another dataset. If you are deciding whether to split a workflow into multiple datasets first, use the relationship-modeling guide before creating links.