Relationships

Underpeaks models link to each other with standard foreign keys. There are two places a foreign key can be declared: on the column itself, or as a table-level constraint.

Column-level foreign key

Add a foreign_key object to the column definition:

{
  "name": "project_id",
  "type": "string",
  "nullable": false,
  "foreign_key": {
    "references": "nxf_system_projects(project_id)"
  },
  "hidden": true
}

references is written as table(column) — the table and column this field points to.

Table-level foreign key

Alternatively, declare it in the model's constraints array:

{
  "constraints": [
    {
      "type": "foreign_key",
      "fields": ["created_by"],
      "references": {
        "table": "nxf_saas_users",
        "field": "user_id"
      }
    }
  ]
}

This form is useful for composite keys or when you'd rather keep constraints grouped separately from the column list.

Unique constraints

Composite uniqueness (multiple columns together must be unique) is also declared in constraints:

{
  "constraints": [
    {
      "type": "unique",
      "fields": ["organisation_id", "slug"]
    }
  ]
}

For a single-column unique constraint, set "unique": true directly on that column instead — see Field Types.

Fetching related data

The public API returns foreign key columns as their raw stored value (the referenced row's key) — it does not currently expand/populate the related record inline. If you need the related record, fetch it with a second request against that table's endpoint. See Endpoints.