Link datasets
Last updated: November 2, 2026.
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:
Peopleis indexed byperson_idMessageshas aperson_idcolumn- a relationship links
Messages.person_idtoPeople.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.
Enforcement also blocks deleting a referenced target row or changing its index while source rows still point to it. Handle the dependent rows explicitly first. For the parent-first write, read-back, orphan-audit, and deletion workflow, read Referential Integrity for AI-Agent Datasets.
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.
Create and resolve your first relationship
Start with two private datasets you are authorized to change. If you have not connected an agent, follow MCP setup first. Creating a relationship needs an account-wide Read + write or Admin key, not a per-dataset grant.
This fictional example uses People, indexed by person_id, and Messages,
indexed by message_id, with a separate person_id column. Use the
row-work guide to save and read back People.person_id =
P-17, then a message with message_id = M-42 and person_id = P-17.
Inspect both datasets and list existing relationships before creating one;
reuse a matching definition instead of retrying creation blindly.
The following are MCP argument objects, not complete protocol requests. They match the current Rowset tool definitions, checked November 2, 2026. Replace angle-bracket placeholders with returned keys and check your connected client's live tool schema.
Call create_dataset_relationship on Messages, the source dataset:
{
"dataset_key": "<messages_dataset_key>",
"source_column": "person_id",
"target_dataset_key": "<people_dataset_key>",
"enforce_integrity": true
}
Save relationship.key from the result. Then call
resolve_dataset_relationship with the message's own index, not the
person ID:
{
"dataset_key": "<messages_dataset_key>",
"relationship_key": "<relationship_key>",
"source_index_value": "M-42"
}
Confirm source_row.data.message_id is M-42, target_index_value is P-17,
and target_row.data.person_id is P-17. A successful response alone is not
enough: a blank source link returns success with no target row. An unenforced
relationship can also return success with a missing target. Inspect the
returned values before using the linked record.
If enforcement rejects existing unmatched values, review those source rows first. Do not invent people or disable enforcement just to clear the error. Target existence does not prove the person is the intended one; ambiguous identity still needs review.
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.